IF Commons GitHub

ergonex for the tier administrator

The workspaces management of Intellectual Frontiers: it sets up and operates a team's repositories, tools and shell. It manages only Intellectual Frontiers Workspaces; it is not a general IFC or Mizan controller and does not front ifc.

Verbs

VerbWhat it doesEffectDrawn asNot drawn
startSay what to do next, from whether there is a workspace yet.readcli, mcprest: its reach policy does not name the rest channel
initMake the root and the workspace's own area, write a starter manifest where there is none, and put ergonex on your path.mutateclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
repos addAdd repositories to the list of the workspace: `ergonex repos add github.com/owner/repo`; `ergonex apply` clones them.mutateclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
repos removeTake repositories off the list; their folders stay on disk and become unmanaged.mutateclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
repos deleteTake repositories off the list and delete their folders, only where a folder is clean, fully pushed and has no worktree.destructiveclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
repos adoptFind the repositories under the root that the manifest does not name, and add those that are where their remote puts them.mutateclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
planShow the plan the manifest and what is on disk make, and change nothing.readcli, mcprest: its reach policy does not name the rest channel
applyCarry out the plan: clone, fast-forward, configure and write generated files; never delete work, never change the host.mutateclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
statusList every repository of the manifest with its state, how far it is ahead and behind, its stashes, untracked files and lock.readcli, mcprest: its reach policy does not name the rest channel
doctorCheck the runtime and tools, the layout, the file system, the hooks and the generated files, and say what to do about each.readcli, mcprest: its reach policy does not name the rest channel
verifyCompare the generated files with the state record and with what the templates give now; change nothing.readcli, mcprest: its reach policy does not name the rest channel
renderWrite the generated files from the manifest; --dry-run shows each difference as a diff, --check ends with findings where a file would change.mutateclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
worktree createMake a worktree for an issue's branch, only where someone else or uncommitted work is on the repository.mutateclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
worktree listList the worktrees of the managed repositories.readcli, mcprest: its reach policy does not name the rest channel
worktree pruneRemove the worktrees that have no uncommitted change and no unpushed commit; --dry-run names them.destructiveclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
shell printPrint the snippet for a shell (bash, zsh, fish, pwsh, nu) on standard output; it writes nothing.readcli, mcprest: its reach policy does not name the rest channel
shell installWrite one marked block of the snippet into the shell's start-up file; --dry-run shows the diff of it and writes nothing.mutateclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
shell uninstallRemove exactly the block `install` wrote; --dry-run shows the diff of it and writes nothing.mutateclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
pathsSay where ergonex keeps its files: the workspace, its state, its data, the tools it installs and their shims.readcli, mcprest: its reach policy does not name the rest channel
setupMake the root, install the pinned tools and set what the host needs; --dry-run shows the plan and changes nothing.mutateclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
toolsList the tool catalog and what is installed, verify the installed tools, or export the catalog (oscal, spdx, cyclonedx); installs nothing.readcli, mcprest: its reach policy does not name the rest channel
modulesList every module with its source and summary; --probe asks the modules on the PATH for their manifest.readclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel
hookThe checker the generated Git hooks run (pre-commit, commit-msg, pre-push); it only reads.readclimcp: its reach policy does not name the mcp channel; rest: its reach policy does not name the rest channel

Problem codes

CodeMeaning
E-APPLY-FAILEDAn action failed: `apply` tried an action and Git or the file system refused it.
E-APPLY-REFUSEDAn action was refused: `apply` did not carry out an action, to protect work that exists nowhere else.
E-CATALOG-SHAPEThe tool catalog does not decode: The tool catalog in the manifest is not the shape of a catalog.
E-CATALOG-TOOLA tool of the catalog is not valid: A tool is pinned to something that is not a version, or has no artifact for a system.
E-CHANGES-COMMIT-NAMES-NO-ISSUEA commit names no issue: The message has no `Refs #N` line.
E-CHANGES-WRONG-CLOSING-WORDA commit uses a closing word a host reads: A word like `Fixes` closes an issue on a host that reads it.
E-COMMIT-NOT-SIGNEDA commit is not signed: A local commit is not signed and verified.
E-COMMIT-SIGNING-WAIVEDSigning is waived for a repository: The repository's own record waives the signed-commit rule for a bot account.
E-ENVIRONMENTThis computer cannot do it: Something the run needs is not there: a program, the root, a file, or a place to write.
E-ENXAnother program is named enx: A program named enx is on the PATH, so the short name enx of `ergonex shell` is not defined (it is defined only where none is found); ergonex always works.
E-EVIDENCEThe evidence record could not be written: Every run leaves one record under the workspace's state folder, and this run could not write it.
E-FILESYSTEMThe file system of the root is not suitable: The root is on a file system that is case-insensitive or does not keep Git's files safe.
E-GENERATEDThe generated files are as they should be: Every generated file is as written and as the templates give it now.
E-GENERATED-DRIFTThe templates give something else now: A generated file is as it was written, but the templates now make different text.
E-GENERATED-EDITEDA generated file was edited by hand: A generated file is not as it was written, so ergonex will not overwrite it.
E-GENERATED-MISSINGA generated file is missing: A file that was written is not on disk.
E-GENERATED-PATHA template made a file that is refused: A generated file would be at a path that is not valid on every system.
E-GENERATED-UNRECORDEDA generated file is not in the state record: A generated file is on disk but the state record does not name it.
E-HOOKSA repository's hooks are not the generated ones: The repository does not use the hooks folder that ergonex generates.
E-HOST-NOT-ALLOWEDThe Git host is not allowed: A repository is on a host that the manifest's policy does not allow.
E-LOOPBACK-HTTPhttp to the loopback interface is accepted: ERGONEX_ALLOW_LOOPBACK_HTTP is set, so a pinned artifact may be fetched over http from this computer.
E-MANIFEST-BRANCHA branch is not valid: A branch in the manifest is not a branch name Git accepts.
E-MANIFEST-HOSTA Git host is not valid: A host in the manifest is not a host name.
E-MANIFEST-MODULEA registered module is not valid: A module the manifest registers has no valid name or program.
E-MANIFEST-PATHA repository's path is not portable: The path a remote makes is not valid on Linux, macOS and Windows alike.
E-MANIFEST-REMOTEA repository's remote is not valid: A remote in the manifest is not a repository on a Git host.
E-MANIFEST-SHAPEThe manifest does not decode: `.ergonex/workspace.ts` is not the shape of a manifest, or could not be loaded.
E-MANIFEST-SIGNINGThe signing policy is not valid: The manifest's signing policy names something the policy does not know.
E-MODULE-HIDDENA module is hidden by another: A module of a later source has the name of one found first.
E-MODULE-NAMEA program is not named as a module: An `ergonex-*` program on the PATH has a name a module may not have.
E-MODULE-OUTSIDE-CATALOGA module is outside the catalog: An `ergonex-*` program is on the PATH or registered, and the tool catalog does not list it.
E-MODULE-PROBE-TIMEOUTA module did not answer in time: `modules --probe` waited for the manifest of a module and none came.
E-MODULES-FILEThe registered modules file cannot be read: `.ergonex/modules.auto.json` does not decode.
E-NOT-A-REPOSITORYA folder is not a Git repository: Something is at the path of a repository that is not a clone.
E-PATH-COLLISIONTwo repositories make the same path: Two repositories of the manifest would be the same folder on a system that ignores the case of names.
E-PATH-LENGTHPaths of the workspace are near the limit: A path of the workspace is near the length Windows allows.
E-PATH-TOO-LONGA path is too long for Windows: A path of the workspace is longer than Windows allows while long paths are off.
E-PLAINTEXT-TOKENA token is written in a file: A file of the workspace holds text of the shape of a credential.
E-RENDER-WOULD-CHANGEA generated file would change: `render --check` found a generated file that differs from what the templates give now.
E-REPO-PATH-ROOMA repository's path leaves little room: A repository's own path leaves little room for the files inside it on Windows.
E-REPO-PATH-TOO-LONGA repository's path is too long: A repository's own path is too long for the system.
E-REPOSITORY-DIVERGEDA repository has diverged from its remote: It has commits its remote does not have, and the remote has commits it does not have.
E-REPOSITORY-LOCKEDA repository has a Git lock file: Another process may be working in it, and ergonex never removes a lock.
E-RUNTIMEThe runtime is not the one expected: ergonex runs on Bun by default and Node 26 as the backup.
E-SCAN-REFUSEDA file was not scanned: A file was left out of the scan of plaintext tokens, and the finding says why.
E-SETUP-APPLYSetup could not carry out a step: A step of the plan failed.
E-SETUP-GIT-INCLUDEThe global Git include was not added: The include of the generated Git configuration was not written.
E-SETUP-INSTALLA tool could not be installed: The artifact could not be fetched or its SHA-256 differs from the pin.
E-SETUP-LONGPATHSWindows long paths need an administrator: Long paths are off and this run is not elevated.
E-SETUP-MANIFESTSetup could not read the manifest: `setup` stopped before it changed anything.
E-SIGNING-WAIVER-UNREADA waiver could not be read: A repository's record of decisions could not be read, so no waiver of it holds.
E-STATE-RECORDThe state record is damaged: The state record in ergonex's state folder cannot be read.
E-TOKENThe token for reading packages is not ready: ERGONEX_GITHUB_TOKEN is not set, or GitHub CLI is not there to provide it.
E-TOOLA tool that ergonex needs is not usable: Git, Bun or Node is missing or too old.
E-TOOL-DRIFTAn installed tool is not as pinned: An installed tool's files differ from the install record.
E-TOOL-MISSINGA tool is missing: The tool is not on the PATH.
E-TOOL-OKA tool is as expected: The tool is installed at a version that is enough.
E-TOOL-OUTSIDE-CATALOGA tool is outside the catalog: A tool is in ergonex's tools folder and the catalog does not list it.
E-TOOL-TOO-OLDA tool is too old: The tool is installed, but older than the minimum.
E-TOOL-UNREADABLEA tool's version cannot be read: `<tool> --version` printed nothing that is a version.
E-UNKNOWN-MODULEA module is not known: No module has that name.
E-UNMANAGED-REPOSITORYA repository is under the root but not in the manifest: A clone is in the workspace that the manifest does not name.
E-UNSIGNED-COMMITA pushed commit is not signed: A commit that is being pushed is not signed and verified.
E-USAGEThe command line does not fit: The words after `ergonex` do not name a command, an option or an argument it takes.
E-WINDOWS-LONG-PATHSWindows long paths are not enabled: Long paths are off, and a path of the workspace may be longer than 259 characters.
E-WORKTREE-BASEA worktree cannot be made here: The repository is missing, locked, a clone of another repository or not a repository.
E-WRONG-REMOTEA folder is a clone of another repository: The folder is a repository, but its origin is not the one the manifest names.
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.