refactor(agent-surface): split CLI god file#15
Merged
Conversation
…rving) First strangler step on the agent-surface.mjs god file. Move the three god-file-global-free primitives (fail, sha256, exists) into scripts/agent-surface/util.mjs so later extractions can import the shared root without a circular dep back into the god file. Drop the now-unused createHash import. Acceptance: check + test green; `build --target all` byte-identical to pre-extraction (dist sha 7a249680…); god file 4610 -> 4592 lines. Extract -> verify -> commit; more to follow.
…ntmatter guard) New scripts/agent-surface/postprocess.mjs seam, wired into externalSkillOutputs. Strips a leading UTF-8 BOM and synthesizes minimal frontmatter for a SKILL.md that lost it — applied at emit time, re-run on every build from current upstream (no fork, no cherry-pick), separate from the emit that decides which files go where. Fixes the Zed 'must start with YAML frontmatter' failure for red-team-command-doctrine (it had frontmatter behind a BOM). Verified: its SKILL.md now begins '---'; 0 BOM'd SKILL.md in a full build; check + test green. (Intentional output change — not byte-identical — for the BOM/FM fix.)
…r-preserving) Move the pure MCP config render + non-destructive merge transforms (renderMcpConfig, the JSON/JSONC/Codex-TOML/YAML mergers + helpers, optionalServiceMcpServers) into scripts/agent-surface/merge.mjs, importing fail (util), tomlString (format), and the jsonc helpers. The install planner keeps prepareMcpConfigMerge/mcpConfigMerge and calls these. Acceptance: `build --target all` byte-identical (dist sha e17ba0a…); check + test green; god file 4592 -> 4408 lines.
…ng discipline) Replace the invisible literal U+FEFF with the explicit escape — same value (length 1), so BOM-strip behavior is unchanged; build stays byte-identical. Safer in review/editors.
…behavior-preserving) Move repo root and the cached readSourceKinds/readOptionalServices loaders into scripts/agent-surface/registry.mjs (sole reader of the raw registry JSON). root recomputes two levels up from the new location; drop the now-unused fileURLToPath import. Acceptance: build --target all byte-identical (e17ba0a…); check + test green; 4408 -> 4393.
…reserving) Move commandVersion + git query helpers (gitSubmoduleStatusMap, gitStagedGitlinkMap, gitValue, gitOutput, gitLines) into scripts/agent-surface/proc.mjs, importing root (registry) + fail (util). Thin spawnSync wrappers, no god-file coupling. Acceptance: build --target all byte-identical (e17ba0a…); check + test green; 4393 -> 4342.
…reserving) Move files/filesUnder/directories/directDirectories into scripts/agent-surface/fs-tree.mjs (deps: root, exists, readdir). Drop the now-unused readdir import from the god file. Acceptance: build --target all byte-identical (e17ba0a…); check + test green; 4342 -> 4294.
…e->registry readCommands/parseCommand/parseSimpleFrontmatter/parseFrontmatterScalar/commandPhaseFromName -> commands.mjs (parsing only; metadata validation stays in the check layer). Move relative() next to root in registry.mjs. Acceptance: build byte-identical (e17ba0a…); check+test green; 4294->4183.
…erving) readRules/parseRule -> rules.mjs (parsing only; reference validation + rendering stay). Acceptance: build byte-identical (e17ba0a…); check+test green.
…s (byte-identical) Move the pure per-target installRoot*/*Root/*Path/*OutputName helpers (via codemod) into scripts/agent-surface/roots.mjs (deps: os/path/process/root/fail). Path-safety helpers and the rule-reading kilo helper stay. Acceptance: build --target all byte-identical (e17ba0a…); check+test green; god 4122 -> 3851.
…cal) Move all render* (subagents/commands/skills/workflows/recipes/instructions/rules) + their support helpers (firstHeading, stripFrontmatter, yamlLiteralBlock, 7 *SubagentAccess) into render.mjs (imports commands/format/registry/rules/util). Pure text transforms; no producers/fs. Acceptance: build byte-identical (e17ba0a…); check+test green; god 3851 -> 3440.
…rs + install) Prep for targets.mjs: the path-safety helper is used by both the producer side (safeExternalPath) and install. Also drop the now-unused toml/yaml format re-exports from the god file (moved to render.mjs). Acceptance: build byte-identical; check+test green.
…byte-identical) The compiler engine: move the per-target adapter table + all producers/static-outputs (targetProducers/targetOutputs/produceCommandOutputs/externalSkillOutputs/optionalMcpOutputs/ selectedMcpServiceEntries/*StaticOutputs + externalSkillRoots/expandSkillRoot/safeExternalPath/ outputRootFor/outputAppliesTo*/scopedRuleReferenceOutputs/kiloRuleInstructionPaths/sourceKindPolicy + MAX_EXTERNAL*/generatedOutputMinimums) into targets.mjs, importing render/roots/merge/postprocess/ source-primitives. check + install import targets/targetOutputs/producers from here. Acceptance: build --target all byte-identical (e17ba0a…, isolating uncommitted source edits); check + test green.
Move all check/validate functions + workflow/registry schema validators into scripts/agent-surface/check.mjs. Move CLI-arg helpers (argValue etc.) to util.mjs and packageVersion to registry.mjs so check/install/workflow can share them. Build --target all byte-identical (dist sha256 e17ba0a…).
collectCommandReferenceFindings referenced lineNumberAt which lived only in the god file; check.mjs could not see it and threw ReferenceError whenever a command or rule reference matched. Move the helper into check.mjs; drop the dead god copy.
Add io.mjs (removeTree + readFileIfExists/readJsonIfExists/readJsoncIfExists + parseJsonc) and move exportableCommands + readWorkflowJson into check.mjs, where their only callers live. The prior check.mjs extraction left these in the god file, so check generated / workflow validate / generated checks threw ReferenceError once their paths ran (test suite now exercises them). check.mjs also now imports readFileIfExists. Build --target all byte-identical.
Move build (dist render) and the install subsystem — planner, strict-sync apply, backups, and MCP/Kilo config merges — into scripts/agent-surface/install.mjs. Prune the god file's now-dead render/roots/merge imports left over from the targets/check extractions. Build --target all byte-identical; god file 1550→831.
Move the workflow command tree (run-ledger doctor/apply, events chain, git-tree patch capture/verify) into workflow.mjs, the `run` evidence capture (redaction + class approval) into evidence.mjs, and the `doctor` health report into doctor.mjs. The god file is now a 176-line CLI dispatcher (main + inventory + commands + registry). Build --target all byte-identical.
Lyther
added a commit
that referenced
this pull request
Jul 2, 2026
The god-file decomposition (merged in #15) split scripts/agent-surface.mjs into a CLI entry + 20 focused modules under scripts/agent-surface/. Reconcile the stale docs: rewrite the architecture Source Tree to the real module map, update the scope/'single script' claims, refresh the modularity decision, drop the resolved 'one ~4k-line file' risk, and repoint the CONTRIBUTING 'add a target/MCP' steps at targets.mjs/render.mjs/roots.mjs/merge.mjs. by mass-energy equivalence
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
scripts/agent-surface.mjsinto focused modules underscripts/agent-surface/.Review
$qa-reviewaccepted the refactor surface with no blocking findings.Checks Run
npm run check-> passednpm run check:generated-> passednpm run check:commands-> passednpm run check:rules-> passednpm test-> passednpm run check:subagents-> passednode --check scripts/agent-surface.mjs-> passedfor f in scripts/agent-surface/*.mjs; do node --check "$f"; done-> passednode scripts/agent-surface.mjs check ignores-> passednpm run build -- --target all-> passedgit diff --check-> passednpm audit --omit=dev-> passednpm audit-> passednpm pack --dry-run --json-> passed