IF Commons GitHub

repoctl for the tier public

The operations program of a repository, driven by its repoctl.config.ts: it makes the generated files, merges, checks, commits and says what is wrong with a checkout, and where the configuration turns them on tells the versions, releases, scaffolds a library, proves a change and builds the documentation.

Verbs

VerbWhat it doesEffectDrawn asNot drawn
checkRun every check of the repository (generated files, specifications, rules, versions) and say what is wrong in one report.readcli, mcprest: its reach policy does not name the rest channel
syncMake every generated file, in dependency order, rerunning only the generators whose output is stale.mutatenonecli: sync is for the tier contributor; this caller holds public; mcp: sync is for the tier contributor; this caller holds public; rest: sync is for the tier contributor; this caller holds public
mergeMerge a reference, regenerate the generated files that conflict and report the conflicts in files a person wrote.mutatenonecli: merge is for the tier contributor; this caller holds public; mcp: merge is for the tier contributor; this caller holds public; rest: merge is for the tier contributor; this caller holds public
statusTell, for each library, its version in the repository, on npm and in its tag.readcli, mcprest: its reach policy does not name the rest channel
hygieneSay whether this repository consumes commons as published packages: no Git or path dependency, no vendored copy, one copy of each library, exact versions.readcli, mcprest: its reach policy does not name the rest channel
release planSay what a release would do, library by library and why; writes nothing.readcli, mcprest: its reach policy does not name the rest channel
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.mutatenonecli: release apply is for the tier contributor; this caller holds public; mcp: release apply is for the tier contributor; this caller holds public; rest: release apply is for the tier contributor; this caller holds public
release publishPublish the packed libraries of the release record to npm, behind the releaser tier and a typed confirmation.destructivenonecli: release publish is for the tier releaser; this caller holds public; mcp: release publish is for the tier releaser; this caller holds public; rest: release publish is for the tier releaser; this caller holds public
new libraryScaffold a library of commons: its folder, manifest, about.ts, specification kit, tools, tsconfig and LICENSE, and make what needs it again.mutatenonecli: new library is for the tier contributor; this caller holds public; mcp: new library is for the tier contributor; this caller holds public; rest: new library is for the tier contributor; this caller holds public
commitMake the commit with the repository's identity and trailers, refusing what must not be committed, after the generated files are checked.mutatenonecli: commit is for the tier contributor; this caller holds public; mcp: commit is for the tier contributor; this caller holds public; rest: commit is for the tier contributor; this caller holds public
doctorSay what is wrong with this checkout (dependencies, links, Node, Bun, stale generated files) and what to do about it.readcli, mcprest: its reach policy does not name the rest channel
proveCompute the proof a change needs from its blast radius (the tiers, the tests and why each skipped proof is safe) and run it.readcli, mcprest: its reach policy does not name the rest channel
queryAsk the libraries, their specifications and their requirements in SQL: one read-only SELECT over the relations libraries, specs and requirements.readcli, mcprest: its reach policy does not name the rest channel
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.readcli, mcprest: its reach policy does not name the rest channel
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).mutatenonecli: ci step is for the tier contributor; this caller holds public; mcp: ci step is for the tier contributor; this caller holds public; rest: ci step is for the tier contributor; this caller holds public
docs buildBuild the documentation site of this repository with the documentation generator, into the folder its configuration names.mutatenonecli: docs build is for the tier contributor; this caller holds public; mcp: docs build is for the tier contributor; this caller holds public; rest: docs build is for the tier contributor; this caller holds public
docs checkBuild the documentation site into a temporary folder and say every finding, writing nothing in the repository.readcli, mcprest: its reach policy does not name the rest channel
docs serveBuild the documentation site and serve it on a loopback port of this computer until the run is stopped; nothing is uploaded.mutatenonecli: docs serve is for the tier contributor; this caller holds public; mcp: docs serve is for the tier contributor; this caller holds public; rest: docs serve is for the tier contributor; this caller holds public
mcpServe the verbs the held tier sees as tools of a tool server on standard input and output.readclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel

Problem codes

CodeMeaning
E-ACCEPTANCEAn accepted risk is wrong: A typed file of accepted findings (commons/spec-kit/accepted-findings) has no reason, an end that is not a day or is more than 366 days ahead, an approver who is not on the list, a name that is not its finding's id, or accepts a finding twice.
E-CHECK-FAILEDA check of the repository found something: A named check of the repository's configuration ended with 1 and said what is wrong, line by line.
E-COMMIT-FAILEDGit did not make the commit: Git refused the commit.
E-COMMIT-FORBIDDENA file that must not be committed is staged: A path under .claude/, under node_modules or one that looks like a secret is among the files to commit.
E-COMMIT-IMPACTThe impact is not valid: `--impact` is not major, minor or patch, or the repository's commits carry no `Impact:` line.
E-COMMIT-NOTHINGThere is nothing to commit: Nothing is staged and no path was given.
E-COMMIT-REFSThe issue number is not valid: `--refs` is not an issue number.
E-COMMIT-SESSIONThe session address is missing or not valid: The trailer Claude-Session needs an https address, from --session or CLAUDE_SESSION_URL.
E-COMMIT-SUBJECTThe commit subject is not valid: The subject is empty, has more than one line, is longer than 100 characters or ends with a full stop.
E-CONFIG-INVALIDThe configuration is not valid: `repoctl.config.ts` was loaded and says something that cannot be: an id used twice, a generator that waits for one that is not there, a capability that needs `libraries`, a variable that is not a name.
E-CONFIG-LOADThe configuration could not be loaded: `repoctl.config.ts` could not be imported, or it exports no configuration (its default export or `config`).
E-CONFIG-MISSINGThis repository has no repoctl.config.ts: No `repoctl.config.ts` is in this folder or above it, and `--config` did not name one.
E-DOCS-FAILEDThe documentation generator reported a failure: The generator ended with a status that is not 0, or could not be served.
E-DOCS-GENERATOR-MISSINGThe documentation generator is not installed: The generator `ifc-docs` cannot be imported from this repository: neither the entry `./docs` of the one package `@intellectual-frontiers/commons` (`single` mode) nor the package `@intellectual-frontiers/docs` (`per-library` mode) is installed.
E-DOCTOR-BUNBun is not the pinned version: The version of Bun is not the one the repository pins (the file the doctor policy names).
E-DOCTOR-GITGit is not available or this is not a checkout: `git` does not run here, or the folder is not a Git working tree with an origin.
E-DOCTOR-INSTALLThe dependencies are not installed: The root has no node_modules, so no program can import a library.
E-DOCTOR-LINKSThe libraries are not linked: The folder under which the configuration's doctor policy says the libraries are linked does not link every library.
E-DOCTOR-NODENode 26 is missing: The program `node` is older than the least version the configuration's doctor policy names, or is not there.
E-ENVIRONMENTThis checkout cannot do it: Something the run needs is not there: a program, a folder, a file or the network.
E-GENERATOR-FAILEDA generator could not run: A generator ended with a status that is neither success nor staleness, so what it makes is not known.
E-HYGIENE-DUPLICATETwo installed copies of one library: The lockfile or node_modules holds one package of the policy's scope at two versions.
E-HYGIENE-GITA dependency by Git on the repository of commons: A package.json depends on the family's own repository by Git (github:, git+https:, git: or ssh:, at a commit or not).
E-HYGIENE-IDENTITYA merge commit was not made by the repository's identity: A merge commit of the history has an author or a committer that is not the identity `commit.identity` of the configuration, and the configuration does not hold it in `commit.heldMerges`; or a held hash matches no merge of the history.
E-HYGIENE-IMPORTA relative import into a copy of commons: A source imports a relative path that goes through the folder the hygiene policy names.
E-HYGIENE-PATHA path dependency into a checkout of commons: A package.json has a file: or link: dependency whose path goes through the folder the hygiene policy names.
E-HYGIENE-RANGEA dependency that is not an exact version: A dependency of the policy's scope is a range, a tag or latest.
E-HYGIENE-VENDOREDA vendored copy of a library of commons: A folder of the repository, outside node_modules, carries a package of the policy's scope and is not the root package or a workspace the root declares.
E-LIBRARY-CHECKThe check of a library's own rules finds something: A library's manifest or its folder breaks a rule that the register of libraries holds.
E-LIBRARY-EXISTSThe library exists: A folder with this name is already in commons/.
E-LIBRARY-NAMEThe library name is not valid: The name is not lower-case letters, digits and hyphens starting with a letter.
E-LIBRARY-RESERVEDThe library name is held for a family: The name is one that commons/libraries/src/family.ts holds for the library of a family.
E-MERGE-CONFLICTA file a person wrote conflicts: The merge conflicts in a file that is not generated; it is left as Git left it, for a person.
E-MERGE-FAILEDThe merge could not be made: Git refused the merge for a reason that is not a conflict.
E-MIZAN-RULEA rule of Mizan finds something: The rules Mizan adds to the format found a finding that its baseline does not hold, or a line of the baseline that no longer occurs.
E-NO-TARBALLA package was not packed: The tarball of a library of the record is not under dist/.
E-NO-TOKENThere is no npm credential: The variable INFRO_NPMJS_TOKEN is not set, so nothing can be sent to npm by hand.
E-NPM-UNREACHABLEnpm could not be asked: The registry of npm did not answer for a library, so its version there is not known.
E-PROVE-FAILEDA proof of the plan failed: A proof that `repoctl prove` ran (a type check, a check of the specifications, a suite, a packing) ended with a failure.
E-PROVE-QUARANTINEA quarantined test is past its expiry, or the record is wrong: The quarantine record names a test whose expiry day has passed (it runs again), or the record is not a list of entries with a test, an owner, an expiry and a reason.
E-PUBLISH-FAILEDnpm did not take a package: npm refused a package or the run could not start it; nothing was tagged.
E-PUBLISH-REFUSEDThe publication was refused: `release publish` needs the releaser tier and a typed confirmation, and one of them is missing.
E-REGENERATE-FAILEDA conflicted generated file could not be made again: A generated file conflicted and its generator could not make it, so it stays unresolved.
E-RELEASE-FAILEDThe release could not be made: The release stopped before it was made: a version that went back, a registry that could not be compared, a generator or a test that failed.
E-RELEASE-RECORDThe release record is missing: `release publish` reads commons/generated/release.auto.json and it is not there or does not decode.
E-SPEC-KITA specification kit breaks the format: The check of the specification format found a finding in a specification kit.
E-STALE-GENERATEDA generated file is stale: A generator's own check says its files are not what it makes now from their sources.
E-TYPESTypeScript 7 finds a type error: The type check of the tests of the root, or of commons' tools, which no library's own check covers, found an error.
E-UNDECLARED-DEPENDENCYA library imports a package its manifest does not declare: A source, a test or a tool of a library imports a package by name (or a `node:` built-in, which needs `@types/node`) that its package.json declares neither in dependencies nor in devDependencies.
E-USAGEThe command line does not fit: The words after `repoctl` do not name a verb, an option or an operand it takes.
E-USAGE-UNKNOWNA library the package does not hold is imported: A file of the repository imports `@intellectual-frontiers/commons/<library>` and the installed package has no library of that name; it is not counted.
E-VERSION-CONSTANTA constant of the sources disagrees with its library's version: A constant named for a library (`ERGONEX_VERSION`) or named by its manifest in `versionConstants` does not say the version of its package.
E-VERSIONSA version record is wrong: The check of versions found a record that is wrong, an identity that changed, or a version that went back since the base.
E000-FAILEDThe code a problem of the level fail carries when its raiser gave none.
E000-WARNINGThe code a problem of the level warn carries when its raiser gave none.
E000-YOURSThe code a problem of the level action carries when its raiser gave none.
P000-WAITINGThe code a problem of the level pending carries when its raiser gave none.

Exit statuses

OutcomeMeaning
okStatus 0: it did what it was asked, and nothing needs attention.
findingsStatus 1: it ran, and found something wrong (a failed check, a drift, a failure).
usageStatus 2: the command line was wrong, or the action was refused (a missing confirmation, a human-only option).
environmentStatus 3: something the run needs is missing or unreachable (a tool, a file, a network).
pendingStatus 4: nothing failed, but something is not set up yet and waits on time or on someone else.
startup-usageStatus 64: the program could not start: it was started wrongly (EX_USAGE).
startup-unavailableStatus 69: the program could not start: a service it needs is not available (EX_UNAVAILABLE).
startup-softwareStatus 70: the program could not start: an internal error (EX_SOFTWARE).
startup-osfileStatus 72: the program could not start: a file it needs is missing or unreadable (EX_OSFILE).
startup-configStatus 78: the program could not start: its configuration is wrong (EX_CONFIG).
interruptedStatus 130: it was stopped by the person (SIGINT).
terminatedStatus 143: it was stopped by the system (SIGTERM).

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