Ergonex (1 of 2)
5 specifications, 128 requirements. All libraries
0001 The ergonex command
| Requirement | Mechanism | Who | Note |
|---|---|---|---|
FR-001 | check | bun test suite/ | ergonex-command.test.ts, ergonex-boundaries.test.ts: the controller is workspaces/ergonex.ts, the commands are in commands/, the contract in modules/, and the package's bin names ergonex through node/ergonex.mjs |
FR-002 | check | bun test suite/ | ergonex-command.test.ts: ergonex --help says in these words that ergonex manages only Intellectual Frontiers Workspaces, is not a general IFC or Mizan controller and does not front ifc |
FR-003 | check | bun test suite/ | ergonex-command.test.ts: ergonex <name> runs the module, ergonex help describes the command, and ergonex modules names every module with its name, its source (ergonex:BuiltIn, ergonex:Registered or ergonex:Path) and its summary |
FR-004 | check | bun test suite/ | ergonex-modules.test.ts, ergonex-command.test.ts: a module is found built-in, then registered, then on the PATH, the first runs and the one it hides is an informational finding; the order is the ontology's |
FR-005 | check | bun test suite/ | ergonex-modules.test.ts, ergonex-command.test.ts: a name that is not lower-case letters, digits and hyphens from a letter, or longer than 32, is refused with exit status 2 and never run |
FR-006 | check | bun test suite/ | ergonex-modules.test.ts, ergonex-command.test.ts: an unknown name is exit status 2 with up to three modules within an edit distance of two, or that none is near |
FR-007 | check | bun test suite/ | ergonex-modules.test.ts: ErgonexModule and Command are typed, defineCommand parses the options once into a typed value, and a switch over a union of sources or statuses is exhaustive (the compiler and the linter) |
FR-008 | check | bun test suite/ | ergonex-modules.test.ts, ergonex-command.test.ts: an external module's --ergonex-manifest answer is checked by a typed decoder and its JSON Schema is made from the same fields; a module that does not answer or whose answer does not decode is opaque, runs, and its exit status is passed on and recorded |
FR-009 | check | bun test suite/ | ergonex-command.test.ts: ergonex modules and ergonex help run nothing found on the PATH; --probe runs each only to ask for --ergonex-manifest |
FR-010 | check | bun test suite/ | ergonex-modules.test.ts, ergonex-command.test.ts, ergonex-apply.test.ts: exit status 0 ok, 1 findings (a warning or an error; an informational one alone is 0), 2 usage, 3 environment, with the numbers of the ontology |
FR-011 | check | bun test suite/ | ergonex-command.test.ts: a registered module of modules.auto.json is found before the PATH and its program is refused with exit status 3 where its SHA-256 differs from the pin; the finding for a module the catalog does not list is in ergonex doctor (ergonex-wiring.test.ts) |
FR-012 | check | bun test suite/ | ergonex-apply.test.ts: plan shows the typed plan and changes nothing, apply carries it out with no action that changes the host and no destructive action without --allow-destructive |
FR-013 | check | bun test suite/ | ergonex-apply.test.ts: status lists every repository in the order of its path with its state, ahead and behind, stashes, untracked files and lock, uses no network without --fetch, and ends with findings for a diverged, locked, wrong-remote or not-a-repository one |
FR-014 | check | bun test suite/ | ergonex-render.test.ts, ergonex-record.test.ts: doctor checks the runtime and tools, the layout and portability, the file system, the hooks and the generated files, each ok, suggest, warn or error with what to do; the plaintext-token scan, signed commits and the catalog are wired in at commands/doctor.ts DOCTOR_CHECKS and proved in ergonex-wiring.test.ts |
FR-015 | check | bun test suite/ | ergonex-render.test.ts: verify and render as 0003-host FR-010 and FR-012 say; ergonex-wiring.test.ts: ergonex tools (run as a real program) lists the catalog of the manifest, verifies the installed tools against their records and the probes, exports OSCAL, SPDX and CycloneDX, and installs nothing |
FR-016 | check | bun test suite/ | ergonex-apply.test.ts: worktree create makes a worktree at .worktrees/<host>/<path>/<repo>/<branch-slug> on an issue-named branch only where someone else or uncommitted work is on the repository (else it says the checkout is the place, unless --always), list shows them, prune removes only one with no uncommitted change and no unpushed commit, and only with --allow-destructive |
FR-017 | check | bun test suite/ | ergonex-setup.test.ts: --dry-run shows the plan and changes nothing, setup carries the plan out, and the run is recorded with ergonex:applied and a not_run for a dry run; only setup carries out an InstallTool or a ConfigureHost; ergonex-wiring.test.ts: the same through the command, and setup takes the workspace's one lock file (<home>/.ergonex/ergonex.lock), the one apply takes, so that setup --apply and apply refuse while another run holds it |
FR-018 | check | bun test suite/ | ergonex-setup.test.ts: setup creates the root and a starter manifest (never over one), installs only the pinned artifacts of the catalog for this system into .ergonex/tools/, and only probes git, bun and node, naming how to install one that is missing or old |
FR-019 | check | bun test suite/ | ergonex-setup.test.ts: on Windows setup sets core.longpaths in each cloned repository with real git, turns the system setting on only where elevated (the function that stands for reg add is given by the test), and where not elevated prints the exact steps and ends with findings; a path over 259 is an error |
FR-020 | check | bun test suite/ | ergonex-wiring.test.ts: ergonex setup --git-include shows the exact change and writes the one marked include of the generated git.auto.conf only after --yes or a yes (a usage failure with no terminal and none; nothing on a dry run), twice leaves one; ergonex-command.test.ts, ergonex-shell.test.ts: ergonex shell --install and --uninstall are the setup restricted to the shell block, with a diff, a question and the same evidence |
FR-021 | check | bun test suite/ | ergonex-command.test.ts: ergonex shell print <shell> prints the snippet on standard output and writes nothing |
FR-022 | check | bun test suite/ | ergonex-modules.test.ts, ergonex-command.test.ts: options are parsed once into a typed value, every command accepts --home, --json, --sarif, --no-color and --help, and an option a command does not know is exit status 2 |
FR-023 | check | bun test suite/ | ergonex-apply.test.ts: every command is idempotent (a second apply and a second render change nothing); ergonex-command.test.ts: every run writes its evidence record, a usage run as not_run with its reason |
FR-024 | check | bun test suite/ | ergonex-command.test.ts: the same report from Bun and from Node 26, through the controller and the launcher with the loader hook of ifc; the library has no any, no non-null !, errors as values and exhaustive switches (tsc and the linter in CI); Deno is not run, tested or documented |
FR-025 | check | bun test suite/ | ergonex-command.test.ts: ergonex init makes the root and the area and writes the starter manifest once, and run again changes nothing |
FR-026 | check | bun test suite/ | ergonex-command.test.ts, ergonex-render.test.ts: ergonex shell print <shell> and a hook write no evidence record; every other run does |
FR-027 | check | bun test suite/ | ergonex-render.test.ts: the commit-msg, pre-push and pre-commit hooks run ergonex hook, which only reads and ends 0 or 1 where it ran its checker, and the script turns any other status into cannot-run |
FR-028 | check | bun test suite/ | ergonex-probe.test.ts: modules --probe asks about each module found on the PATH (the question says it is not sandboxed) and runs only those the person says yes to, or all with --yes; with no terminal and no --yes it is a usage failure (status 2) that runs nothing; a module registered by the workspace is not asked about; ergonex-command.test.ts: the PATH modules probed with --yes |
FR-029 | check | bun test suite/ | ergonex-probe.test.ts: the wait is 5000 ms by default and --probe-timeout SECONDS sets another (a value that is not a whole number of at least 1 is a usage failure); a module that does not answer in time is an informational finding naming it and the wait, listed as opaque, the other modules are listed and the status stays 0; a longer wait lets a slow module answer |
FR-030 | check | bun test suite/ | ergonex-headless.test.ts: the tree is a Headless model with no problem and a reach policy for every action, the reports only read and are safe to repeat, the previewing actions say so, and the destructive ones preview and are confirmed |
FR-031 | check | bun test suite/ | ergonex-boundaries.test.ts, ergonex-headless.test.ts: the domain logic is the pure core and the surface is commands/ and ergonex.ts; ergonex-headless.test.ts runs the program through Headless (log, hints, explain, envelope) and ergonex-command.test.ts proves the old words are not commands |
0002 Intellectual Frontiers Workspaces
| Requirement | Mechanism | Who | Note |
|---|---|---|---|
FR-001 | check | bun test suite/ | ergonex-command.test.ts: the root of a run is --home, else $ERGONEX_HOME, else $HOME/workspaces, as a real program on Bun and Node (the pure resolution is proved in ergonex-layout.test.ts) |
FR-002 | check | bun test suite/ | ergonex-apply.test.ts: after init and apply the root holds the repositories' hosts, the generated files and the workspace's own area (the manifest, the state record, the generated files, hooks/, evidence/); the area's tools/ is made by ergonex setup --apply (ergonex-wiring.test.ts) |
FR-003 | check | bun test suite/ | ergonex-scan.test.ts: resolveInside, readInside and forbiddenRead refuse an absolute path, .., a drive, a backslash, the home folder, NUL, a link that leads out of the root and any file of ~/.ssh or a credential store, and a hostile manifest is refused as a manifest; that every writer calls them is the controller's (M5) |
FR-004 | check | bun test suite/ | ergonex-command.test.ts: ergonex --help says in these words that it manages only Intellectual Frontiers Workspaces and does not front ifc; ergonex-apply.test.ts and ergonex-boundaries.test.ts: no file of a user's profile is read or written |
FR-005 | none | Planned, M4 of issue #10: commons/ergonex/ exists and no rung below imports it (ergonex-boundaries.test.ts proves it); the command and the templates are M5's, and rung 10 as an instance of the ladder is the lead's amendment of 0016-ladder | |
FR-006 | check | bun test suite/ | ergonex-layout.test.ts: a repository is at the lower-case host then the remote's path as the host writes it (GitHub owner and repository, GitLab groups to any depth), whichever spelling the remote has, and the path maps back to its remote |
FR-007 | check | bun test suite/ | ergonex-layout.test.ts, ergonex-plan.test.ts: a worktree is at .worktrees/<host>/<path...>/<repo>/<branch-slug>, with the slug free of what Windows refuses, and the plan holds a CreateWorktree only where another worker or uncommitted work is on the repository |
FR-008 | check | bun test suite/ | ergonex-layout.test.ts, ergonex-manifest.test.ts: a host or a segment named .worktrees, .ergonex or .git, in any case, is refused and named |
FR-009 | check | bun test suite/ | ergonex-portable.test.ts: the fixture of hostile names (empty, dot, forbidden and control characters, trailing dot or space, every device name in any case with any extension and the superscript digits, over 255 bytes, non-NFC), pure so that it runs on every system |
FR-010 | check | bun test suite/ | ergonex-portable.test.ts: a path of the workspace is made only from portable segments with / between them, never absolute, never holding .. or a drive, and given the native separator only by nativePath |
FR-011 | check | bun test suite/ | ergonex-portable.test.ts, ergonex-manifest.test.ts: paths equal after NFC and case folding collide, and the manifest refuses both and names each other, on every file system |
FR-012 | check | bun test suite/ | ergonex-portable.test.ts: 259 characters is accepted and 260 is a path-too-long error naming the path, unless long paths are enabled (the doctor message and the ergonex:Error severity are the command's, M5) |
FR-013 | check | bun test suite/ | ergonex-render.test.ts: a manifest of two groups gives two *.auto.code-workspace files with relative paths and no symbolic link anywhere in the root; ergonex-templates.test.ts: the template makes no symbolic link |
FR-014 | check | bun test suite/ | ergonex-record.test.ts: FAT, exFAT, a network share and a Windows drive under WSL are each classified from the type a probe reports (never from the path) and are warnings, and a probe not made is said; ergonex-render.test.ts: doctor runs the probe (stat -f on Linux, the table of mounts on macOS); the probe on Windows is not built and says so |
FR-015 | check | bun test suite/ | githost-adapters.test.ts, githost-live.test.ts: GitHub, GitLab and plain Git pass the same conformance function (tests/githost-conformance.ts) over recorded exchanges, a loopback server and a real repository |
FR-016 | check | bun test suite/ | ergonex-ontology.test.ts: the kinds Github, Gitlab and Git each support the four common capabilities, and GitHub and GitLab protected branches, issues and change requests |
FR-017 | check | bun test suite/ | githost-adapters.test.ts, githost-remote.test.ts: a capability a kind lacks is a typed unsupported result naming the host and the capability (GitHub nested groups, plain Git protected branches, issues and change requests), and the table is the ontology's |
FR-018 | none | Planned, M4 of issue #10: the adapters read a token only from the environment they are handed, send it to the one host they serve, and hold it in no result, URL or file (githost-live.test.ts, githost-remote.test.ts, ergonex-boundaries.test.ts); the host's own command-line tools (gh, glab) and the evidence's lack of a credential are not wired | |
FR-019 | check | bun test suite/ | githost-remote.test.ts, ergonex-manifest.test.ts: GitHub for github.com, GitLab for gitlab.com and the hosts the manifest names, plain Git for every other, and a self-hosted GitLab is never guessed from a URL |
FR-020 | check | bun test suite/ | ergonex-layout.test.ts, ergonex-manifest.test.ts: a path of more than two segments on a host without nested groups is refused naming the manager and the path, and GitLab takes any depth |
FR-021 | check | bun test suite/ | ergonex-plan.test.ts, ergonex-boundaries.test.ts: plan(desired, observed) is a pure function (arguments frozen, same plan and digest, the pure core imports no clock, environment or file) |
FR-022 | check | bun test suite/ | ergonex-plan.test.ts, ergonex-state.test.ts: each of the ten states is observed in a real repository and the plan's action for it is the state's defaultAction in the ontology |
FR-023 | check | bun test suite/ | ergonex-ontology.test.ts: the ten action kinds are the code list the specification names; the exhaustive switch over them is the compiler's |
FR-024 | check | bun test suite/ | ergonex-apply.test.ts: apply observes each repository again before each action and reports as skipped an action whose state changed; the plan changes nothing |
FR-025 | check | bun test suite/ | ergonex-apply.test.ts: after apply the next plan holds only skips and a second apply changes no file, configuration or state record |
FR-026 | check | bun test suite/ | ergonex-plan.test.ts, ergonex-state.test.ts: a FastForward is planned for Behind and for no other state (a property over every state), and a dirty repository behind its remote is skipped |
FR-027 | check | bun test suite/ | ergonex-apply.test.ts: a dirty, ahead, diverged or locked repository is never touched, a non-repository folder and another remote's clone are never overwritten, a generated file edited by hand is never removed, and a worktree with work is never pruned |
FR-028 | check | bun test suite/ | ergonex-apply.test.ts: a Git lock file makes the repository Locked, which apply does not act on and whose lock it does not remove; a second run refuses with the first named, and a lock whose holder is gone is taken over |
FR-029 | check | bun test suite/ | ergonex-apply.test.ts: RemoveGenerated is in the plan and is carried out only with --allow-destructive and only while the file is as written |
FR-030 | check | bun test suite/ | ergonex-setup.test.ts: stepChangesHost is true for exactly InstallTool, SetSystemLongPaths and AddGitInclude, setup carries them out only where --apply is given (a dry run, with --git-include too, changes nothing), and ergonex tools has no install argument (ergonex-tools.test.ts); the plan of every other command holds none by plan.ts (ergonex-plan.test.ts); ergonex-wiring.test.ts: run as a real program, no plan of plan or apply holds an install, a dry run of setup fetches and writes nothing, and only setup --apply installs |
FR-031 | check | bun test suite/ | ergonex-scan.test.ts: tokens of GitHub and GitLab, private key blocks, a credential in a URL and authorization headers are errors naming the file and the line and never the secret, placeholders are not secrets, and the generated files, the manifest and each repository's local Git configuration are scanned inside the root; running the scan in every command is the controller's (M5); ergonex-wiring.test.ts: ergonex doctor finds a token in a repository's local Git configuration and in the manifest, naming the file and line and never printing it (nor holding it in a record), and the pre-commit hook stops a commit that stages one |
FR-032 | check | bun test suite/ | ergonex-scan.test.ts: signedCommitFindings is an error where a regulated domain is named and a warning elsewhere, over the signature letters of real commits from real git (N unsigned, G signed with an SSH key made by ssh-keygen); the Git hooks that fail where they cannot check are M5's templates; ergonex-wiring.test.ts: ergonex doctor reports an unsigned commit of a managed repository as a warning, and as an error once the manifest names a regulated domain |
FR-033 | check | bun test suite/ | ergonex-tools.test.ts, ergonex-scan.test.ts: a tool or an ergonex-* module outside the catalog is informational through day 90 and a warning from day 91, the day first seen kept by firstSeen; writing the day into the state record is the controller's (M5); ergonex-wiring.test.ts: ergonex doctor, with a real ergonex-* executable on the PATH, reports it informational from the first day and at 89 days and a warning at 91, writes the first-seen day to state.auto.json and never restarts it, and a catalog tool that provides it ends the finding; ergonex tools does the same for a folder of tools the catalog does not list |
FR-034 | check | bun test suite/ | ergonex-render.test.ts: the commit-msg hook, run by Git through core.hooksPath, applies the commit rules of 0020-ifccm (mizan/changes/commit-message.ts); ergonex-apply.test.ts: ergonex worktree create names the issue in the branch (branchNamesIssue is the one place that says how, until 0020-ifccm does) |
FR-035 | check | bun test suite/ | ergonex-findings.test.ts: the finding type, its severities and their SARIF levels (the ontology's), the SARIF 2.1.0 log of findings and the exit status they give |
FR-036 | check | bun test suite/ | ergonex-record.test.ts: a path of 270 characters is an error naming it with ergonex setup as the way, and that Windows long paths are not enabled is informational while none exceeds the limit; ergonex-render.test.ts: each doctor check is ok, suggest, warn or error with what to do |
FR-037 | check | bun test suite/ | ergonex-tools.test.ts: decodeCatalog holds name, one pinned version, provides and per system and architecture an https URL and a SHA-256, and refuses latest, a range, http, a credential in a URL, a bad hash and a path that leaves the folder; adding the field to the manifest decoder is the lead's; ergonex-wiring.test.ts: the catalog is the manifest's optional tools field, decoded with the manifest, and its tools are in tools.auto.json; ergonex-loopback.test.ts: while ERGONEX_ALLOW_LOOPBACK_HTTP is set ergonex writes the one line on standard error and the report holds the informational finding ergonex/loopback-http, on Bun and Node 26, with the same exit status |
FR-038 | check | bun test suite/ | ergonex-tools.test.ts: the probes of git, bun and node judge the version the real program says (missing, too old, unreadable, ok), the catalog refuses them as tools, and setup only probes |
FR-039 | check | bun test suite/ | ergonex-tools.test.ts, ergonex-setup.test.ts: the pinned artifact is fetched through the transport from a real loopback server (tar.gz, zip, bare file) and from a recorded exchange, the SHA-256 is checked before anything is written, a hash that differs writes nothing, latest and http pins are refused, and an installed tool is verified against its install record; ergonex-wiring.test.ts: setup --apply, run as a real program, fetches the pinned artifact from a loopback server and installs it, and with a hash that differs writes nothing |
FR-040 | check | bun test suite/ | ergonex-tools.test.ts: the catalog as OSCAL inventory-items and what is installed as SPDX 2.3 and CycloneDX 1.6, deterministic, each with the pinned SHA-256 |
FR-041 | check | bun test suite/ | ergonex-setup.test.ts: writeRunEvidence writes one record in the IFQS test-record shape named by the UTC time and run id under .ergonex/evidence/, never overwriting, with not_run and its reason for a check that did not run; calling it at the end of every command is the controller's (M5) |
FR-042 | check | bun test suite/ | ergonex-setup.test.ts: the record names the command and only the names of its options, the plan hash, the state hash, the tool versions, the findings and the exit, and a record that would hold a credential is redacted or refused |
FR-043 | check | bun test suite/ | ergonex-setup.test.ts: the tool versions of the run are cases of the record and missingToolVersions names what a regulated run still lacks; passing every tool used is the controller's (M5) |
FR-044 | check | bun test suite/ | ergonex-ontology.test.ts: every class and code-list class has one audit record and the audit's rules find nothing; the three specifications name only terms the ontology defines |
FR-045 | review | 0002-workspace-model FR-045 | A reviewer checks that each control of the section Standards and controls names a requirement that supports it; the OSCAL slice of NIST SP 800-53 will make the mapping data |
FR-046 | review | 0002-workspace-model FR-046 | A reviewer checks that the workspace's documentation carries the credits (the author of the earlier tools, chezmoi, Git); CREDITS.md is in commons/ergonex/ |
FR-047 | check | bun test suite/ | githost-remote.test.ts, ergonex-state.test.ts: https, ssh, scp-like and git forms of one remote are one repository, and a credential in a remote URL is dropped and in no result, error, state or finding |
FR-048 | check | bun test suite/ | ergonex-path-room.test.ts: a repository's path (the root and its path, as the system writes it) of up to 150 characters has no finding, over 150 is informational (ergonex/repo-path-room) and over 259 an error (ergonex/repo-path-too-long) on Windows and elsewhere whatever the long-path setting; ergonex doctor run as a program reports both and says nothing of a short path |
FR-049 | check | bun test suite/ | ergonex-signing-waiver.test.ts: a Decision of the repository's record (signing-waiver ACCOUNT KEY in covers) clears the unsigned-commit finding only for that committer with that key, as an informational finding that names the Decision, the account and the key; another account, another key, no signature, a bad or revoked one, another repository, no regulated domain and a record that cannot be read waive nothing; facts read from real SSH-signed commits and ergonex doctor run as a program |
0003 Ergonex host: typed templates, generated files and what is managed
| Requirement | Mechanism | Who | Note |
|---|---|---|---|
FR-001 | check | bun test suite/ | ergonex-command.test.ts: the manifest is loaded from workspace.ts and decoded once, and one that does not decode is reported as ergonex:Error findings naming each field and stops the run before anything is changed (ergonex-manifest.test.ts proves the decoder) |
FR-002 | check | bun test suite/ | ergonex-command.test.ts: ergonex init writes the starter manifest once and never rewrites it; ergonex setup (M6) may call the same function |
FR-003 | check | bun test suite/ | ergonex-templates.test.ts: a template is a TypeScript function from data to files, and no code of the templates or the generator evaluates text or names a dotfiles manager |
FR-004 | check | bun test suite/ | ergonex-templates.test.ts, ergonex-render.test.ts: a generated file's path is refused where it holds .., is absolute, names a drive or lacks .auto. (a hook in .ergonex/hooks/ excepted), and a collision after case folding refuses both; its header names its generator |
FR-005 | check | bun test suite/ | ergonex-templates.test.ts, ergonex-render.test.ts: the templates make a code-workspace file for each group, AGENTS.auto.md, tools.auto.json, modules.auto.json, the hooks and .envrc.auto where allowed; tools.auto.json lists the catalog of the manifest |
FR-006 | check | bun test suite/ | ergonex-templates.test.ts, ergonex-render.test.ts: each folder of a group is listed by a path relative to the file with / between segments |
FR-007 | check | bun test suite/ | ergonex-templates.test.ts: the same data gives the same bytes (UTF-8, no byte-order mark, LF, one final newline, no time, host or user name); ergonex-render.test.ts: Bun and Node 26 make the same bytes |
FR-008 | check | bun test suite/ | ergonex-templates.test.ts: a file inside a repository's working tree is refused; ergonex-render.test.ts: a group whose name would make such a path or one outside the root is refused and nothing is written |
FR-009 | check | bun test suite/ | ergonex-record.test.ts: the state record holds the hash and generator of each file, the plan's hash, the version and the first-seen days, and reads back the same bytes; ergonex-render.test.ts: render writes it; ergonex doctor and ergonex tools fill the first-seen days and never restart them (ergonex-wiring.test.ts) |
FR-010 | check | bun test suite/ | ergonex-record.test.ts, ergonex-render.test.ts: verify reports a hand edit as an error and a missing, an unrecorded and a drifted file as warnings, and changes nothing |
FR-011 | check | bun test suite/ | ergonex-render.test.ts: render and apply leave a hand-edited generated file as it is and say so, and render --force replaces it |
FR-012 | check | bun test suite/ | ergonex-render.test.ts: render --check writes nothing, names each file that would change and ends with findings; --diff shows a unified diff and writes nothing |
FR-013 | check | bun test suite/ | ergonex-apply.test.ts: apply sets core.hooksPath, the signing settings, user.name, user.email and, on Windows, core.longpaths in the repository's own configuration, replaces another hooks path, and writes nothing to the user's global configuration (the Windows setting is not run here: Windows is the CI's) |
FR-014 | check | bun test suite/ | ergonex-templates.test.ts: the three hooks are POSIX sh scripts of mode 0755 accepted by sh -n; ergonex-render.test.ts: Git runs them through core.hooksPath and the commit-msg hook stops a commit that names no issue; the pre-commit hook's scan is wired in at commands/hook.ts CHECKERS; ergonex-wiring.test.ts: the pre-commit hook runs the plaintext-token scan of the staged changes (host/staged.ts, scan/secrets.ts) |
FR-015 | check | bun test suite/ | ergonex-templates.test.ts, ergonex-render.test.ts: a hook only reads; with no checker it exits non-zero with the reason where a regulated domain is named and exits zero with the same message elsewhere, run by Git with no bun, node or ergonex on the PATH |
FR-016 | check | bun test suite/ | ergonex-setup.test.ts: setup --git-include shows the exact change and asks, writes only after a yes (no terminal and no --yes is a usage error before any change), leaves one marked block where run twice and the block comes out exactly; the file is a real configuration that real git config reads back; ergonex-wiring.test.ts: through ergonex as a real program |
FR-017 | check | bun test suite/ | ergonex-command.test.ts: ergonex shell <bash|zsh|fish|pwsh|nu> prints the snippet on standard output and writes no file, and another shell is exit status 2 |
FR-018 | check | bun test suite/ | ergonex-shell.test.ts: the snippet of each shell does the four things and defines one function; sourced by a real bash it sets the root once, puts the tools folder on the PATH once and wcd changes to a repository by name (zsh, fish, PowerShell and Nushell are read as text: they are not installed here) |
FR-019 | check | bun test suite/ | ergonex-shell.test.ts, ergonex-command.test.ts: --install shows a unified diff of one marked block and writes only after a yes or --yes (a usage failure with no terminal and no --yes), twice leaves one block, --uninstall removes exactly it and leaves a file with other text, CRLF or no final newline as it was |
FR-020 | check | bun test suite/ | ergonex-boundaries.test.ts, ergonex-apply.test.ts: nothing of the global or system Git configuration, ~/.ssh, a credential store or a user's file is read or written but the one marked block of a start-up file on request |
FR-021 | check | bun test suite/ | ergonex-templates.test.ts: no code under workspaces/ imports, runs or names a dotfiles manager |
FR-022 | check | bun test suite/ | ergonex-templates.test.ts: AGENTS.auto.md tells an agent the layout, the rules and the commands from the manifest, with no secret and no absolute path of the computer |
FR-023 | check | bun test suite/ | ergonex-templates.test.ts, ergonex-render.test.ts: .envrc.auto only where direnv is wanted and found, and it only adds the tools folder to the PATH by a relative path |
FR-024 | check | bun test suite/ | ergonex-templates.test.ts: lefthook.auto.yml calls the three generated hooks by their relative path and holds no checker |
FR-025 | check | bun test suite/ | ergonex-templates.test.ts, ergonex-render.test.ts: a hook finds the root from its own place, holds no absolute path, sends the checker's output to standard error and reads its status as go on, stop or cannot run |
FR-026 | check | bun test suite/ | ergonex-shell.test.ts: installBlock refuses a file that is not there (absent) and takes an empty one, and the command that creates a start-up file is said for each shell with a path quoted for it; ergonex-command.test.ts: ergonex shell --install, run as a program, never creates the start-up file or its folder (exit status 3, the path and the command named, the user's home as it was, with --yes or without), --uninstall creates none, and a file the person made takes the block |
FR-027 | check | bun test suite/ | ergonex-enx.test.ts: the snippet of each shell, sourced by the real shell, defines enx as ergonex only where no other enx is found, with its completions, and is safe to repeat; zsh, fish, PowerShell and Nushell where installed |
FR-028 | check | bun test suite/ | ergonex-enx.test.ts: doctor names each program called enx on the PATH as a warning and says the short name is free where there is none |
0004 Onboarding
| Requirement | Mechanism | Who | Note |
|---|---|---|---|
FR-001 | check | bun test suite/ | ergonex-package.test.ts: the bundled file runs from an empty folder on Bun and Node 26 with nothing beside it; the published package.json has no dependency, the library's version, one bin and public access; the publish workflow sends it to npm with provenance and to GitHub (commons 0030-generated-workflows FR-009) |
FR-002 | check | bun test suite/ | ergonex-onboarding.test.ts: already on the path, then the runtime's global install and no file of ours, a failed install says the command and bunx, a checkout is not installed; ergonex-locations.test.ts: init in a world makes no folder or command file |
FR-003 | check | bun test suite/ | ergonex-onboarding.test.ts: the words for no root, no workspace and a workspace, and the program run with no command exits 0 and says what to do next |
FR-004 | check | bun test suite/ | ergonex-shell.test.ts: each of the five snippets sets ERGONEX_GITHUB_TOKEN from gh auth token and never GITHUB_TOKEN or GH_TOKEN; the real bash sets it from a gh that gives a token, leaves it unset where gh fails or is not there, and keeps one that is set |
FR-005 | check | bun test suite/ | ergonex-boundaries.test.ts: no code of the library writes a package manager's configuration or holds a token; the token is named, never held |
FR-006 | check | bun test suite/ | ergonex-onboarding.test.ts: the token's check for each case (not set with and without GitHub CLI, set and not asked, set with and without the scope, no answer) and the scopes read from GitHub's header |
FR-007 | check | bun test suite/ | ergonex-onboarding.test.ts: init on a home with a space and a letter outside ASCII, and a command file that passes such arguments on; ergonex-install.test.ts: the installers' scripts parse; the Windows, macOS and Linux runs of the library's workflow (0004-onboarding FR-009) |
FR-008 | check | bun test suite/ | ergonex-install.test.ts: the installers are what the generator makes; the Windows script installs with winget by identifier, downloads nothing, is ASCII with a byte order mark and parses; the sh script runs ergonex with the Bun there and asks Bun's own installer for the pinned version where there is none |
FR-009 | gate | .github/workflows/ergonex.auto.yml | the workflow runs the library's verify and its tests on Node on windows-latest, macos-latest and ubuntu-latest |
FR-010 | check | bun test suite/ | ergonex-locations.test.ts: ergonex paths names the workspace, .ergonex/, the state, data and tools folders and the shims |
0005 Repositories
| Requirement | Mechanism | Who | Note |
|---|---|---|---|
FR-001 | check | bun test suite/ | ergonex-repositories.test.ts: the manifest reads the entries of repositories.ts and workspace.ts as one list, and a repeated path is a collision |
FR-002 | check | bun test suite/ | ergonex-repositories.test.ts: a command writes the file whole and leaves workspace.ts as it was |
FR-003 | check | bun test suite/ | ergonex-repositories.test.ts: add reads the forms a person writes, records the https address and the branch, and reports a repository already held |
FR-004 | check | bun test suite/ | ergonex-repositories.test.ts: add decodes the manifest with its change first and writes nothing the manifest would refuse |
FR-005 | check | bun test suite/ | ergonex-repositories.test.ts: add --apply clones |
FR-006 | check | bun test suite/ | ergonex-repositories.test.ts: remove takes an entry out of the list, leaves the folder, and refuses one named in workspace.ts |
FR-007 | check | bun test suite/ | ergonex-repositories.test.ts: remove --delete deletes a clean folder and refuses, changing nothing, where there is work |
FR-008 | check | bun test suite/ | ergonex-repositories.test.ts: adopt lists adoptable, misplaced and remoteless repositories and changes nothing |
FR-009 | check | bun test suite/ | ergonex-repositories.test.ts: adopt --apply adds the adoptable ones only |
FR-010 | check | bun test suite/ | ergonex-repositories.test.ts: status notes each unmanaged repository |