refactor: extract shared utilities, externalize model data, add debug logging#23
Conversation
… logging Full-codebase modernization applying the code-modernizer ladder: Shared utilities (rung 2 — already solved in this codebase): - Extract slug(), clamp01(), epochDay(), hasBin(), contentHash(), IGNORE_DIRS, SRC_EXT, CODE_EXT into src/util.js - Replace 3 copies of slug (cortex, recall, cortex_hook) - Replace 2 copies of hasBin/have (doctor, harden) - Replace 2 copies of clamp01 (route, adjudicate) - Replace 2 copies of epoch-day math (cortex_hook_main, cortex_mcp) - Unify IGNORE_DIRS across atlas, scope (was inconsistent) - Unify CODE_EXT across preflight (was duplicated) Data externalization (rung 3 — use the platform): - Move model IDs, pricing, and tier config from source literals to src/model_tiers.json (rotation is now a config change) - Read MCP server version from package.json instead of hardcoding - Add exports field to package.json (modern Node.js convention) - Bump minimum Node to >=20 (reflects actual API usage) Error observability (production readiness): - Replace 7 silent catch-and-swallow sites with FORGE_DEBUG=1 stderr logging (adjudicate, verify, lean, lessons_store, skillgate, atlas, cortex_hook_main) — fail-safe semantics preserved, failures now diagnosable Hash upgrade (rung 3 — stdlib does it): - Replace djb2 (32-bit, collision-prone) with crypto.createHash in cortex_hook.js outputSignature — crypto already imported in atlas.js Cleanup: - Remove unused execFileSync imports from doctor.js and harden.js All 222 tests pass. No behavioral changes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YS8HJw5cwmAQyNQLxRmyYZ
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Line 13 in 2026653
Do not export the side-effectful CLI as the package root
Exporting . to ./src/cli.js makes any consumer import '@codewithjuber/forgekit' execute src/cli.js's top-level run(process.argv.slice(2)), so it prints CLI output or consumes the embedding process's argv and can set process.exitCode. Since this line creates a public module entry point, it should point to an import-safe module or the CLI should be guarded to run only when invoked as the bin.
Line 10 in 2026653
Do not drop Node 18 support in a refactor
This raises the published engine requirement to Node 20 even though the runtime still treats Node 18 as supported (doctor accepts major >= 18) and this refactor does not otherwise require Node 20. In environments that enforce engines, existing Node 18 users are blocked from installing or upgrading a release that otherwise still runs there; either keep the engine at >=18 or update the runtime checks/docs as an intentional breaking change.
Line 21 in 2026653
Keep hidden directories out of the scope graph
When a repo has hidden generated/config directories containing source files, such as .svelte-kit, .nuxt, or .cache, this now descends into them because the previous entry.name.startsWith('.') guard was removed and IGNORE_DIRS only names a few dot dirs. forge scope can then include generated hidden files as graph nodes and report spurious coupling for edits in real source files, so keep the generic dot-directory skip here.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
2 participants
What & why
Applies the code-modernizer skill (Full scope) across the forgekit codebase to eliminate duplication, externalize data, and improve debuggability — all without adding runtime dependencies.
Key changes (20 files, +161 / -123):
src/util.js— centralizes 7 utilities (slug,clamp01,epochDay,hasBin,contentHash,IGNORE_DIRS,SRC_EXT,CODE_EXT) that were duplicated across 10+ source filessrc/model_tiers.json— externalizes model pricing/tier data from hardcoded literals inmodel_tiers.js, making updates a data change instead of a code changecortex.js,recall.js,doctor.js,harden.js,route.js,adjudicate.js,cortex_hook.js,cortex_hook_main.js,cortex_mcp.js,scope.js,preflight.js,atlas.jsto use shared utilitiescortex_hook.jswith SHA-256 (already used elsewhere viacontentHash)FORGE_DEBUG=1stderr logging to 7 catch blocks that previously swallowed errors silently (adjudicate.js,atlas.js,cortex_hook_main.js,lean.js,lessons_store.js,skillgate.js,verify.js)cortex_mcp.jsreads server version frompackage.jsoninstead of hardcodingpackage.jsonaddsexportsfield and bumpsengines.nodefrom>=18to>=20Checklist
npm testpasses (Node 18/20/22) — 222 tests passnpm run checkpasses (Biome lint + format)util.jsexports are exercised transitively through existing testsfeat:/fix:/docs:…) —refactor:CHANGELOG.mdupdated under## [Unreleased]forge substrate,forge impact, router/gate, or MCP substrate toolsRisk & rollback
2026653Extra checks (tick if applicable)
Generated by Claude Code