IF Commons GitHub

The `repoctl` command

repoctl is the operations program of this repository: a headless program in the layers of Kanon, run as bun run repoctl <verb> at the root, or as repoctl where installed from the package, and served as tools by repoctl mcp so that an AI agent runs the same deterministic operations as a person. Every fact it knows of the repository (the generators of its generated files, its checks, the commit identity and trailers, the hygiene policy) is in repoctl.config.ts at the root; a generator or a check is added there and nowhere else. See use repoctl in your own repository and add a verb.

A verb is a governance action with an effect (read, mutate or destructive), a tier that may see it (public, contributor, releaser; the host fixes it with REPOCTL_TIER, contributor where it says nothing) and a reach policy. The verbs share --json (one JSON document), --quiet and --verbose (and most --sarif and --color); those with a preview take --dry-run and those that check take --check. Findings come with a code that repoctl explain <code> explains, and repoctl help lists the verbs. The same descriptions are drawn in full in Programs.

Which verb for which job

  • Make the generated files: sync (sync --check in CI and hooks).
  • Bring in main: merge origin/main.
  • Say what is wrong: check (the report), doctor (the checkout), explain <code> (a finding's meaning), hygiene (the consumption rule), status (versions).
  • Prove a change: prove.
  • Commit: commit -m "Subject" --refs N.
  • Release: release plan, release apply, release publish (the release).
  • Add a library: new library <name> --summary "...".
  • Documentation: docs build, docs check, docs serve.
  • Ask in SQL: query "SELECT ..." over the relations libraries, specs and requirements.

explain

repoctl explain <code> says what a finding's problem code means and what to do about it; it runs where there is no configuration. It is part of the program and not a verb of the table below, so it is written here: repoctl explain with no code lists the codes.

repoctl explain          # the codes it can explain
repoctl explain <code>   # what one finding means, and the command that fixes it

The commands

Read from the program's own typed verb definitions: each is declared once, and the command line, the tool server and these pages read that one table.

CommandWhat it doesEffectTierPreviewCheckSafe to repeat
repoctl syncMake every generated file, in dependency order, rerunning only the generators whose output is stale.mutatecontributoryesyesyes
repoctl mergeMerge a reference, regenerate the generated files that conflict and report the conflicts in files a person wrote.mutatecontributornonono
repoctl checkRun every check of the repository (generated files, specifications, rules, versions) and say what is wrong in one report.readpublicnonoyes
repoctl statusTell, for each library, its version in the repository, on npm and in its tag.readpublicnonoyes
repoctl hygieneSay whether this repository consumes commons as published packages: no Git or path dependency, no vendored copy, one copy of each library, exact versions.readpublicnonoyes
repoctl queryAsk the libraries, their specifications and their requirements in SQL: one read-only SELECT over the relations libraries, specs and requirements.readpublicnonoyes
repoctl usageSay what this repository uses of the package @intellectual-frontiers/commons: the libraries it imports, those reached through them and those never touched, with their sizes.readpublicnonoyes
repoctl ci stepRun one step of a pipeline under the build policy: run the command given after --, keep what it prints, read it into findings with the parser of its tool, write the step's findings file and end 0 whatever the command's status was (commons 0038-build-policy FR-013).mutatecontributornonono
repoctl release planSay what a release would do, library by library and why; writes nothing.readpublicnonoyes
repoctl release applyMake a release: raise the versions the plan says, make the generated files, run the tests that pack and write the record; commits nothing.mutatecontributoryesnono
repoctl release publishPublish the packed libraries of the release record to npm, behind the releaser tier and a typed confirmation.destructivereleaseryesnono
repoctl new libraryScaffold a library of commons: its folder, manifest, about.ts, specification kit, tools, tsconfig and LICENSE, and make what needs it again.mutatecontributoryesnono
repoctl commitMake the commit with the repository's identity and trailers, refusing what must not be committed, after the generated files are checked.mutatecontributoryesnono
repoctl doctorSay what is wrong with this checkout (dependencies, links, Node, Bun, stale generated files) and what to do about it.readpublicnonoyes
repoctl proveCompute the proof a change needs from its blast radius (the tiers, the tests and why each skipped proof is safe) and run it.readpublicnonoyes
repoctl docs buildBuild the documentation site of this repository with the documentation generator, into the folder its configuration names.mutatecontributoryesnoyes
repoctl docs serveBuild the documentation site and serve it on a loopback port of this computer until the run is stopped; nothing is uploaded.mutatecontributoryesnoyes
repoctl docs checkBuild the documentation site into a temporary folder and say every finding, writing nothing in the repository.readpublicnonoyes
repoctl mcpServe the verbs the held tier sees as tools of a tool server on standard input and output.readpublicnonoyes

repoctl sync

Make every generated file, in dependency order, rerunning only the generators whose output is stale.

OptionMeaning
--onlyOnly these generators, as ids separated by commas (those of the configuration).
--dry-runShow what would change and change nothing.
--checkChange nothing; end with findings where something would change.
repoctl sync  # Make every generated file that is stale, in dependency order.
repoctl sync --check  # Write nothing; exit 1 naming each stale generator and the command that fixes it (what CI and the hooks run).
repoctl sync --dry-run  # Say which generators would be run.
repoctl sync --only readme,license  # Only the generators of the README and the licenses.

The full page of this verb: repoctl sync.

repoctl merge

Merge a reference, regenerate the generated files that conflict and report the conflicts in files a person wrote.

repoctl merge origin/main  # Merge main; a generated file that conflicts is made again, never resolved by hand.
repoctl merge some-branch  # Merge a branch; a conflict in a file a person wrote is reported and left as Git left it.

The full page of this verb: repoctl merge.

repoctl check

Run every check of the repository (generated files, specifications, rules, versions) and say what is wrong in one report.

repoctl check  # Run every check: the generated files, the specification kits, the rules of Mizan, the versions and the constants that say a version.
repoctl check --json  # The same, as one JSON document: each section with its findings, their codes and their fixes.

The full page of this verb: repoctl check.

repoctl status

Tell, for each library, its version in the repository, on npm and in its tag.

OptionMeaning
--offlineAsk no network: npm is not asked, and the tags are those of the local clone.
repoctl status  # The version of each library in the repository, on npm and in its tag.
repoctl status --offline  # The same without the network: npm is not asked and the tags are the local ones.
repoctl status --json  # The rows as one JSON document.

The full page of this verb: repoctl status.

repoctl hygiene

Say whether this repository consumes commons as published packages: no Git or path dependency, no vendored copy, one copy of each library, exact versions.

repoctl hygiene  # Say whether this repository consumes the family's packages only as published packages: findings with their code and path, and the exit status 1 where one fails.
repoctl hygiene --json  # The same as one JSON document: the repository, the findings with their code, level, path, message and fix, and the counts.

The full page of this verb: repoctl hygiene.

repoctl query

Ask the libraries, their specifications and their requirements in SQL: one read-only SELECT over the relations libraries, specs and requirements.

OptionMeaning
--limitThe most rows of the answer.
repoctl query SELECT library, count(*) AS n FROM requirements WHERE mechanism = 'none' GROUP BY library  # Count the requirements that nothing verifies, library by library.
repoctl query SELECT name, version FROM libraries ORDER BY name --json  # The libraries with their versions, as one JSON document.

The full page of this verb: repoctl query.

repoctl usage

Say what this repository uses of the package @intellectual-frontiers/commons: the libraries it imports, those reached through them and those never touched, with their sizes.

OptionMeaning
--rootThe repository to read (the repository repoctl runs in by default).
--packageThe folder of the installed package (node_modules/@intellectual-frontiers/commons of the repository by default).
repoctl usage  # What this repository uses of the package: the libraries imported, those reached through them and those never touched.
repoctl usage --root ../erga --package ../erga/node_modules/@intellectual-frontiers/commons --json  # The same for another repository, as one JSON document.

The full page of this verb: repoctl usage.

repoctl ci step

Run one step of a pipeline under the build policy: run the command given after --, keep what it prints, read it into findings with the parser of its tool, write the step's findings file and end 0 whatever the command's status was (commons 0038-build-policy FR-013).

OptionMeaning
--idThe step's id: letters, digits, dots, hyphens and underscores.
--jobThe job the step is in.
--moduleThe module (library) its findings are of.
--toolThe tool whose output is read: tsc, bun-test, lint, format, repoctl-check, mizan-check, kanon-check, generated-files, verify, checks, exit-status, install.
--timeoutThe minutes after which the command is stopped.
--outThe folder the step's findings file is written to.
repoctl ci step --id tests --tool bun-test -- bun test  # Run the tests and keep the failing ones as findings.

The full page of this verb: repoctl ci step.

repoctl release plan

Say what a release would do, library by library and why; writes nothing.

OptionMeaning
--offlineDo not ask npm what it holds: a version with no tag is then raised only where its files changed since it was raised.
--distributionThe distribution mode for this run: per-library or single (the mode of the repository, or IFC_DISTRIBUTION, where it is not given).
--raiseRaise a library whatever its state says: NAME, or NAME=major|minor|patch.
repoctl release plan  # What a release would do, library by library and why; nothing is written.
repoctl release plan --offline  # The same without asking npm.
repoctl release plan --raise headless=minor  # Plan the release with headless raised by a minor.

The full page of this verb: repoctl release plan.

repoctl release apply

Make a release: raise the versions the plan says, make the generated files, run the tests that pack and write the record; commits nothing.

OptionMeaning
--offlineDo not ask npm what it holds: a version with no tag is then raised only where its files changed since it was raised.
--distributionThe distribution mode for this run: per-library or single (the mode of the repository, or IFC_DISTRIBUTION, where it is not given).
--raiseRaise a library whatever its state says: NAME, or NAME=major|minor|patch.
--testsRun the tests that pack, install and type-check every library (on by default).
--dry-runShow what would change and change nothing.
repoctl release apply --dry-run  # The plan, with nothing written.
repoctl release apply  # Raise the versions the plan says, make every generated file, run the tests that pack and write the record.
repoctl release apply --no-tests  # The same without the tests that pack: for trying the command, never for a release.

The full page of this verb: repoctl release apply.

repoctl release publish

Publish the packed libraries of the release record to npm, behind the releaser tier and a typed confirmation.

OptionMeaning
--confirmThe confirmation the preview printed (`publish <n> <digest>`), typed by the person who publishes.
--dry-runShow what would change and change nothing.
--yesConfirm the destruction without asking.
repoctl release publish --dry-run  # The releases that would be sent, and the confirmation to type.
repoctl release publish --yes --confirm 'publish 3 1a2b3c4d'  # Send them to npm, with the confirmation the preview printed (the releaser tier, INFRO_NPMJS_TOKEN in the environment).

The full page of this verb: repoctl release publish.

repoctl new library

Scaffold a library of commons: its folder, manifest, about.ts, specification kit, tools, tsconfig and LICENSE, and make what needs it again.

OptionMeaning
--summaryWhat the library is, in a sentence or two: its first sentence is its row in the README.
--roleWhere the README puts it: foundation, pattern, program or standard.
--dry-runShow what would change and change nothing.
repoctl new library widget --summary Widgets, made by the book.  # Scaffold the library widget in the libraries' folder with its manifest, spec kit, tools and LICENSE.
repoctl new library widget --summary Widgets. --dry-run  # List the files that would be made, and write nothing.

The full page of this verb: repoctl new library.

repoctl commit

Make the commit with the repository's identity and trailers, refusing what must not be committed, after the generated files are checked.

OptionMeaning
--messageThe subject of the commit: one line of at most 100 characters, with no full stop at its end.
--refsThe issue the commit refers to: its number, written as the line `Refs #N`.
--impactHow much the release raises the version of a library this commit changes: major (a breaking change; a minor while the major version is 0), minor (a feature) or patch (a fix), written as the line `Impact:`.
--sessionThe address of the session, written as the line `Claude-Session` (else the variable CLAUDE_SESSION_URL).
--co-authorThe line that credits the agent (else the variable REPOCTL_CO_AUTHOR, else the configuration's).
--dry-runShow what would change and change nothing.
repoctl commit -m Add the doctor --refs 10  # Commit what is staged, as the repository's identity, with the trailers its configuration lists (`Refs #10`, the co-author, the session).
repoctl commit -m Fix the merge --dry-run commons/repoctl/src  # Show the message and the files, and commit nothing.

The full page of this verb: repoctl commit.

repoctl doctor

Say what is wrong with this checkout (dependencies, links, Node, Bun, stale generated files) and what to do about it.

repoctl doctor  # What is wrong with this checkout, in the order to fix it, and the command for each.

The full page of this verb: repoctl doctor.

repoctl prove

Compute the proof a change needs from its blast radius (the tiers, the tests and why each skipped proof is safe) and run it.

OptionMeaning
--baseThe revision the change starts at (origin/main, else main, else HEAD).
--planPrint the plan as one JSON document and run nothing.
--whySay, for every proof and every proof left out, why.
--tierRun only this tier (0 to 6 or T0 to T6).
--allPlan every proof of every tier, whatever changed.
--no-cacheRun every selected test, whatever the cache holds.
repoctl prove  # Prove what the working tree changes since origin/main: the tiers T0 to T3 that apply, and only those.
repoctl prove --why  # The same, with the sentence that says why each proof runs and why each skipped proof is safe to skip.
repoctl prove --plan  # The plan as JSON, run nothing: what CI and the development loop read.
repoctl prove --tier 0  # Only the static proofs of the plan.
repoctl prove --all --plan  # Every proof of every tier, as the nightly run and the release plan it.

The full page of this verb: repoctl prove.

repoctl docs build

Build the documentation site of this repository with the documentation generator, into the folder its configuration names.

OptionMeaning
--outThe folder to build into (the configuration's docs.out by default).
--dry-runShow what would change and change nothing.
repoctl docs build  # Build the site into the folder the configuration names.
repoctl docs build --dry-run  # Say what the generator would be asked, and build nothing.

The full page of this verb: repoctl docs build.

repoctl docs serve

Build the documentation site and serve it on a loopback port of this computer until the run is stopped; nothing is uploaded.

OptionMeaning
--portThe loopback port to serve on (0 lets the system choose).
--forStop after this many seconds (else it serves until it is interrupted).
--dry-runShow what would change and change nothing.
repoctl docs serve  # Build the site and serve it on http://127.0.0.1:4173/ until Ctrl-C.
repoctl docs serve --port 0 --for 30  # Serve on a port the system chooses, and stop after 30 seconds.

The full page of this verb: repoctl docs serve.

repoctl docs check

Build the documentation site into a temporary folder and say every finding, writing nothing in the repository.

repoctl docs check  # Build the site into a temporary folder and say every finding; nothing is written in the repository.

The full page of this verb: repoctl docs check.

repoctl mcp

Serve the verbs the held tier sees as tools of a tool server on standard input and output.

repoctl mcp  # Serve the tools of the tier the host holds (REPOCTL_TIER; REPOCTL_READ_ONLY=1 serves only what reads).

The full page of this verb: repoctl mcp.

Titles, headings, exports, tables, columns and requirements. Esc closes.