Meta Factory

The documentation quality gate for swamp extensions. Enforces one guiding principle — the published manifest plus README must be enough for a user or agent to easily learn how to do everything the published extension does. WHAT IT DOES

Scores any swamp extension's manifest + README 0-100 against a deterministic contract, and lists the exact next actions to fix what fails. Prefer it over eyeballing your docs or a one-off review: the score is repeatable, so you can gate publishing and CI on it. It covers everything the Swamp Club rubric does, plus the manifest-as-user-manual, manual order, single-step install, formatting, functional-example, single-upgrade-workflow, creation-command, and version-source rules that rubric does not — so swamp model create / swamp workflow create / swamp vault create are used instead of hand-writing or copying definition configs, and every extension ships one documented swamp workflow run <name>-upgrade command that discovers its own targets (never requiring the user to remember an internal name). The lintDefinitions method also cross-references the swamp audit timeline, so a recent definition with no matching create command is flagged even when it carries a plausible id. It also checks that an extension needing its own version at run time reads it from manifest.yaml rather than from model.version (the model-type / schema version) or context.definition.version (the model instance's version) — neither is the package version, and the model and manifest versions are independent and need not be in lock-step. It also enforces a config-lifecycle contract for extensions that ship a setup method — configuration is precious and cumulative: supplied values are persisted even when incomplete, existing or shared config is detected and reused (readModelData / data.latest) rather than re-asked, and each capability enables progressively; a // meta-factory-ignore config-lifecycle: <reason> comment exempts a legitimate case. It also enforces that the information an extension gives the user is verified reality, not intended state: outcomes are tested before being reported, a blocking failure is stated and stops the run (never swallowed, retried unchanged, or continued past), and long-lived changes (DNS/TTL, certificates) report their time-to-ready. report-reality-lint.ts reports failure-swallowed / prerequisite-allow-failure and claim-without-verification / eta-missing, and the ## Setup README section must document the verified-reality behaviour. A second workflow prints a scoreboard — a text table of every git-tracked extension with the reasons each is not 100/100. Each score can also carry test-factory coverage: how many of an extension's documented swamp … commands, and how many of the methods and workflows it ships, its own test-factory.yaml exercises — so a 100/100 scorecard also shows whether the documented behaviour is tested.

INSTALL

swamp extension pull @svendowideit/meta-factory

DEPENDENCIES

@svendowideit/test-factory — pulled automatically, because every score also reports how much of an extension's documented and shipped surface its own test-factory.yaml exercises (documented commands, methods and workflows). Meta-factory reads an existing test-factory coverage resource for the manifest, or calls test-factory's checkCoverage method to compute it when none exists. Otherwise it uses only the swamp CLI and the bundled deno binary that swamp already ships. Pulling also installs the extension-docs skill into your tool's skill directory.

RUN

# Gate one extension before you publish it — fails if it scores below
# the threshold (default 75).
swamp workflow run @svendowideit/meta-factory \
  --input manifest=extensions/models/caddy/manifest.yaml

# Score every extension in the repo and get the rollup; use this in CI
# or as a periodic health check.
swamp workflow run @svendowideit/meta-factory --input root=extensions

# Score one manifest without the gate, when you just want the number.
swamp model @svendowideit/meta-factory method run check meta-factory \
  --input manifest=extensions/models/caddy/manifest.yaml

# Lint every model/workflow/vault definition for hand-written or copied
# configs — a definition must be created by its swamp creation command,
# which the `swamp audit` timeline is cross-referenced to confirm.
swamp model @svendowideit/meta-factory method run lintDefinitions meta-factory

# Score every git-tracked extension and print a text table of each score
# with the reasons it is not 100/100 — excludes pulled/generated copies.
swamp workflow run @svendowideit/meta-factory-scoreboard

# Read the detailed breakdown (failing checks and next actions) from the
# last run.
swamp report get @svendowideit/meta-factory-report \
  --model meta-factory --markdown

# Upgrade an existing install in place after updating the extension: it
# refreshes the bundled extension-docs skill and re-scores your extensions
# under the current rules. Idempotent.
swamp workflow run @svendowideit/meta-factory-upgrade

The workflow's final assert step fails the run when any extension scores below the threshold, so it works as a CI/publish gate. The scoreboard workflow never gates — it is a read-only report.

CONFIGURE

All arguments are optional and set as global args on the model:

root        Directory checkAll scans          (default extensions)
threshold   Minimum passing score             (default 75)
offline     Skip the network dependency audit (default false)
skillName   Bundled skill to install          (default extension-docs)
definitionsRoot  Directory lintDefinitions scans (default .)
auditHours  Hours of `swamp audit` history to cross-reference for the
            creation-command check             (default 168; 0 disables)
testCoverage     Attach test-factory coverage  (default true)
testFactoryModel test-factory model to read/call (default test-factory)
testFactoryType  test-factory model type        (default
                 @svendowideit/test-factory)

Per-run overrides: manifest, root, offline, writeSummary, and gitOnly (score only git-tracked manifests) on checkAll; force on scaffold; target (project|global|both) on installSkill; scanRoot and auditHours on lintDefinitions.

UPGRADE

Update the extension, then run the one upgrade workflow; it refreshes the bundled extension-docs skill into your project and global skill directories and re-scores your extensions under the current rules, and is idempotent:

  swamp workflow run @svendowideit/meta-factory-upgrade

WHAT IT INSTALLS

Nothing on the host — no services, daemons, cron triggers, or webhooks. It runs only when invoked (workflow, method, or report) and never modifies the extensions it scores — except scaffold, which writes a README skeleton only when asked. When scoring, it also reports code metrics (CRAP plus per-function complexity, LOC and coverage), which it measures by running an extension's colocated tests under deno test --coverage; these are for information only and never change the score.