From 35478b615ee581f59e502799cace91cbfd0d3d2e Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Tue, 23 Jun 2026 23:21:06 -0400 Subject: [PATCH] refactor(#1646): route capability routers through Command Routing Hub per ADR-959 (#1647) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * refactor(#1646): route capability routers through Command Routing Hub per ADR-959 Phase 2 of parent #1641. Converts graphify, intel, and audit command routers from hand-rolled if/else dispatch to routeHubCommandFamily, implementing the ADR-959 §III(B) line 75 mandate. The three routers now share the uniform dispatch shape with the 14 host routers. src/cjs-command-router-adapter.cts * Imported ERROR_REASON from io.cjs. * UnknownCommand translation now passes ERROR_REASON.SDK_UNKNOWN_COMMAND as the second arg to error() — additive for host routers (their existing one-arg error callbacks ignore the second arg), required for capability routers whose tests assert reason === 'sdk_unknown_command' on the JSON-error envelope. src/graphify-command-router.cts * Replaced 4-branch if/else with routeHubCommandFamily + handlers map. * Validation handlers (missing term, missing/invalid --budget) now return makeInvalidArgs(arg, reason, ERROR_REASON.USAGE) Results instead of calling error() directly (Q2=C, Q4=ii from grilling). * Success handlers keep direct output() calls. * Subcommands array is alphabetical for byte-identical 'Available:' text in the unknown-subcommand message. * The unknown-subcommand path is now owned by the Hub's manifest check (the adapter passes SDK_UNKNOWN_COMMAND). src/intel-command-router.cts * Replaced 9-branch if/else with routeHubCommandFamily + handlers map. * Validation handlers (missing term, missing filePath for patch-meta and extract-exports) return makeInvalidArgs Results. * Preserved the timeAgo mutation in the non-raw status handler. * Preserved the lazy require('./intel.cjs') inside the route function. src/audit-command-router.cts * routeAuditUat: routes through the Hub with a synthetic 'run' defaultSubcommand (no real subcommands). Gives uniform observability. * routeAuditOpen: captures --json in a closure, strips it from args before Hub dispatch (so it isn't mistaken for a subcommand by the manifest check), then branches on wantJson inside the handler to preserve the formatAuditReport success-path quirk. docs/CONFIGURATION.md * Observability section: noted capability commands (graphify, intel, audit-uat, audit-open) now emit DispatchEvent records since #1646. .changeset/capability-routers-via-hub.md * Changed fragment describing the user-visible audit-trail expansion. pr:0 placeholder will be backfilled after gh pr create returns the real PR number (DEFECT.CHANGESET-PR-FIELD-DRIFT). Verification * graphify cutover tests: 119/119 pass (all unit, dispatch, behavior, error path, JSON-errors, and registry assertions) * intel cutover tests: 39/39 pass * audit cutover tests: 24/24 pass * bug-974-graphify-budget-missing-value regression test: pass * npm run test:unit (full suite): 2384 tests, 0 fail * gsd-test-summary on docker: outcome=passed, 0 failures (RULESET.PR-FLOW.docker-before-push) JSON-error envelope parity verified byte-identical: reason values ('usage', 'sdk_unknown_command') and message texts are preserved across all three routers' error paths. * chore(#1646): backfill changeset pr: 1647 (DEFECT.CHANGESET-PR-FIELD-DRIFT) --- .changeset/capability-routers-via-hub.md | 5 + docs/CONFIGURATION.md | 2 +- src/audit-command-router.cts | 70 +++++++++--- src/cjs-command-router-adapter.cts | 13 ++- src/graphify-command-router.cts | 91 +++++++++------ src/intel-command-router.cts | 134 ++++++++++++++--------- 6 files changed, 212 insertions(+), 103 deletions(-) create mode 100644 .changeset/capability-routers-via-hub.md diff --git a/.changeset/capability-routers-via-hub.md b/.changeset/capability-routers-via-hub.md new file mode 100644 index 000000000..35987dee1 --- /dev/null +++ b/.changeset/capability-routers-via-hub.md @@ -0,0 +1,5 @@ +--- +type: Changed +pr: 1647 +--- +**Capability commands now emit dispatch audit records** — `graphify`, `intel`, `audit-uat`, and `audit-open` now route through the Command Routing Hub per ADR-959 §III(B), so `GSD_AUDIT=1` traces, the structured stderr JSON error envelope, and the typed Result contract cover them uniformly with all other command families. JSON-error `reason` values (`usage`, `sdk_unknown_command`) are preserved byte-identical. (#1646) diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index fde6876df..437d922d6 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -1517,7 +1517,7 @@ When `/gsd-new-project` creates a new `config.json`, it reads global defaults an ## Observability -The Command Routing Hub emits a structured `DispatchEvent` after every dispatch. Default behaviour is **silent on success** and **one structured JSON line to stderr on error**. +The Command Routing Hub emits a structured `DispatchEvent` after every dispatch — including capability commands (`graphify`, `intel`, `audit-uat`, `audit-open`) since #1646. Default behaviour is **silent on success** and **one structured JSON line to stderr on error**. ### Stderr error format diff --git a/src/audit-command-router.cts b/src/audit-command-router.cts index 7b1bbcb37..fb82b7665 100644 --- a/src/audit-command-router.cts +++ b/src/audit-command-router.cts @@ -26,6 +26,11 @@ // eslint-disable-next-line @typescript-eslint/no-require-imports import io = require('./io.cjs'); +// Phase 2 (#1646): route through the Hub per ADR-959 §III(B) line 75. +// eslint-disable-next-line @typescript-eslint/no-require-imports +import cjsCommandRouterAdapter = require('./cjs-command-router-adapter.cjs'); + +const { routeHubCommandFamily } = cjsCommandRouterAdapter; // ─── Types ──────────────────────────────────────────────────────────────────── @@ -71,28 +76,67 @@ function routeAuditUat({ args, cwd, raw, error, _uat }: RouteAuditUatOptions): v void error; // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment const u: UatModule = _uat ?? require('./uat.cjs'); - u.cmdAuditUat(cwd, raw); + + // Phase 2 (#1646): routes through the Hub for uniform observability and + // HandlerFailure taxonomy. audit-uat has no subcommands — a synthetic 'run' + // defaultSubcommand gives the Hub a single-handler manifest. The dispatch is + // trivial but the observability seam (DispatchEvent, GSD_AUDIT=1 trace) is + // now consistent with graphify/intel/host routers. + routeHubCommandFamily({ + family: 'audit-uat', + args, + subcommands: ['run'], + defaultSubcommand: 'run', + handlers: { + run: () => u.cmdAuditUat(cwd, raw), + }, + unknownMessage: (subcommand: string) => + `Unknown audit-uat subcommand: "${subcommand}". audit-uat takes no subcommands.`, + error, + cwd, + raw, + }); } // ─── routeAuditOpen ────────────────────────────────────────────────────────── function routeAuditOpen({ args, cwd, raw, error, _audit, _core }: RouteAuditOpenOptions): void { - // Suppress unused-variable warning for error — audit-open has no subcommand - // dispatch that would call error(); only flag parsing occurs here. - void error; // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment const a: AuditModule = _audit ?? require('./audit.cjs'); const c: CoreModule = _core ?? io; + + // Phase 2 (#1646): routes through the Hub for uniform observability. + // `--json` is a flag, not a subcommand — capture it in the closure and strip + // it from args before Hub dispatch so it isn't mistaken for a subcommand by + // the manifest check. The handler then branches on wantJson for the two + // output shapes (JSON object vs human-readable formatted report). const wantJson = args.includes('--json'); - const result = a.auditOpenArtifacts(cwd); - if (wantJson) { - // io.output JSON-stringifies its first arg; pass the object directly. - c.output(result, raw); - } else { - // Human-readable report must bypass JSON encoding — use the rawValue - // form (third arg) which io.output emits verbatim. - c.output(null, true, a.formatAuditReport(result)); - } + const hubArgs = wantJson ? args.filter((arg) => arg !== '--json') : args; + + routeHubCommandFamily({ + family: 'audit-open', + args: hubArgs, + subcommands: ['run'], + defaultSubcommand: 'run', + handlers: { + run: () => { + const result = a.auditOpenArtifacts(cwd); + if (wantJson) { + // io.output JSON-stringifies its first arg; pass the object directly. + c.output(result, raw); + } else { + // Human-readable report must bypass JSON encoding — use the rawValue + // form (third arg) which io.output emits verbatim. + c.output(null, true, a.formatAuditReport(result)); + } + }, + }, + unknownMessage: (subcommand: string) => + `Unknown audit-open subcommand: "${subcommand}". audit-open takes no subcommands (use --json for JSON output).`, + error, + cwd, + raw, + }); } export = { diff --git a/src/cjs-command-router-adapter.cts b/src/cjs-command-router-adapter.cts index a8e6642e1..ddaed40c9 100644 --- a/src/cjs-command-router-adapter.cts +++ b/src/cjs-command-router-adapter.cts @@ -13,6 +13,12 @@ // eslint-disable-next-line @typescript-eslint/no-require-imports import commandRoutingHub = require('./command-routing-hub.cjs'); const { createHub, ERROR_KINDS } = commandRoutingHub; +// Phase 2 (#1646): import ERROR_REASON so the UnknownCommand translation can +// pass `sdk_unknown_command` as the second arg to error(), preserving the +// JSON-error envelope contract that capability routers' tests assert on. +// eslint-disable-next-line @typescript-eslint/no-require-imports +import io = require('./io.cjs'); +const { ERROR_REASON } = io; // ─── Types ──────────────────────────────────────────────────────────────────── @@ -140,7 +146,12 @@ function routeHubCommandFamily({ if (result.ok) return; if (result.kind === ERROR_KINDS.UnknownCommand) { - error(unknownMessage(subcommand ?? '', available)); + // Phase 2 (#1646): pass SDK_UNKNOWN_COMMAND as the second arg so the + // JSON-error envelope (GSD_JSON_ERRORS=1) preserves the typed reason + // for downstream consumers. Additive for host routers (their existing + // one-arg `error` callbacks ignore the second arg); required for + // capability routers whose tests assert on `reason === 'sdk_unknown_command'`. + error(unknownMessage(subcommand ?? '', available), ERROR_REASON.SDK_UNKNOWN_COMMAND); return; } if (result.kind === ERROR_KINDS.InvalidArgs) { diff --git a/src/graphify-command-router.cts b/src/graphify-command-router.cts index 0cea739d2..666ca9f11 100644 --- a/src/graphify-command-router.cts +++ b/src/graphify-command-router.cts @@ -27,8 +27,15 @@ import graphify = require('./graphify.cjs'); // eslint-disable-next-line @typescript-eslint/no-require-imports import io = require('./io.cjs'); +// Phase 2 (#1646): route through the Hub per ADR-959 §III(B) line 75. +// eslint-disable-next-line @typescript-eslint/no-require-imports +import commandRoutingHub = require('./command-routing-hub.cjs'); +// eslint-disable-next-line @typescript-eslint/no-require-imports +import cjsCommandRouterAdapter = require('./cjs-command-router-adapter.cjs'); const { output, ERROR_REASON } = io; +const { makeInvalidArgs } = commandRoutingHub; +const { routeHubCommandFamily } = cjsCommandRouterAdapter; // ─── Types ──────────────────────────────────────────────────────────────────── @@ -52,42 +59,58 @@ interface RouteGraphifyCommandOptions { // ─── Implementation ─────────────────────────────────────────────────────────── function routeGraphifyCommand({ args, cwd, raw, error, _graphify }: RouteGraphifyCommandOptions): void { - const subcommand = args[1]; const g: GraphifyModule = _graphify ?? graphify; - if (subcommand === 'query') { - const term = args[2]; - if (!term) { - error('Usage: gsd-tools graphify query ', ERROR_REASON.USAGE); - return; - } - const budgetIdx = args.indexOf('--budget'); - let budget: number | null = null; - if (budgetIdx !== -1) { - const rawBudget = args[budgetIdx + 1]; - if (rawBudget === undefined || Number.isNaN(parseInt(rawBudget, 10))) { - error('Usage: gsd-tools graphify query [--budget ]', ERROR_REASON.USAGE); - return; - } - budget = parseInt(rawBudget, 10); - } - output(g.graphifyQuery(cwd, term, { budget }), raw); - } else if (subcommand === 'status') { - output(g.graphifyStatus(cwd), raw); - } else if (subcommand === 'diff') { - output(g.graphifyDiff(cwd), raw); - } else if (subcommand === 'build') { - if (args[2] === 'snapshot') { - output(g.writeSnapshot(cwd), raw); - } else { - output(g.graphifyBuild(cwd), raw); - } - } else { - error( - 'Unknown graphify subcommand. Available: build, query, status, diff', - ERROR_REASON.SDK_UNKNOWN_COMMAND, - ); - } + // Phase 2 (#1646): routes through the Command Routing Hub per ADR-959 §III(B) + // line 75. Validation handlers return `makeInvalidArgs(...)` Results (Q2=C, + // Q4=ii); the Hub → adapter translation preserves ERROR_REASON granularity + // via the exitReason field (Phase 1, #1644). Success handlers keep direct + // `output()` calls (audit's formatAuditReport quirk sets this precedent). + // The unknown-subcommand path is owned by the Hub's manifest check; the + // adapter passes SDK_UNKNOWN_COMMAND for UnknownCommand Results. + routeHubCommandFamily({ + family: 'graphify', + args, + // Alphabetical order produces a stable, byte-identical `Available:` list + // in the unknown-subcommand message (matches the pre-conversion text). + subcommands: ['build', 'diff', 'query', 'status'], + handlers: { + query: () => { + const term = args[2]; + if (!term) { + return makeInvalidArgs('term', 'Usage: gsd-tools graphify query ', ERROR_REASON.USAGE); + } + const budgetIdx = args.indexOf('--budget'); + let budget: number | null = null; + if (budgetIdx !== -1) { + const rawBudget = args[budgetIdx + 1]; + if (rawBudget === undefined || Number.isNaN(parseInt(rawBudget, 10))) { + return makeInvalidArgs( + '--budget', + 'Usage: gsd-tools graphify query [--budget ]', + ERROR_REASON.USAGE, + ); + } + budget = parseInt(rawBudget, 10); + } + output(g.graphifyQuery(cwd, term, { budget }), raw); + }, + status: () => output(g.graphifyStatus(cwd), raw), + diff: () => output(g.graphifyDiff(cwd), raw), + build: () => { + if (args[2] === 'snapshot') { + output(g.writeSnapshot(cwd), raw); + } else { + output(g.graphifyBuild(cwd), raw); + } + }, + }, + unknownMessage: (subcommand: string, available: string[]) => + `Unknown graphify subcommand. Available: ${available.join(', ')}`, + error, + cwd, + raw, + }); } export = { diff --git a/src/intel-command-router.cts b/src/intel-command-router.cts index ab00f8d16..6809d84cf 100644 --- a/src/intel-command-router.cts +++ b/src/intel-command-router.cts @@ -44,8 +44,15 @@ import io = require('./io.cjs'); import coreUtils = require('./core-utils.cjs'); // eslint-disable-next-line @typescript-eslint/no-require-imports import path = require('path'); +// Phase 2 (#1646): route through the Hub per ADR-959 §III(B) line 75. +// eslint-disable-next-line @typescript-eslint/no-require-imports +import commandRoutingHub = require('./command-routing-hub.cjs'); +// eslint-disable-next-line @typescript-eslint/no-require-imports +import cjsCommandRouterAdapter = require('./cjs-command-router-adapter.cjs'); const { ERROR_REASON } = io; +const { makeInvalidArgs } = commandRoutingHub; +const { routeHubCommandFamily } = cjsCommandRouterAdapter; // Default CoreModule implementation assembled from leaf modules. // _core seam overrides this entirely for test injection. const _defaultCore = { output: io.output, timeAgo: coreUtils.timeAgo }; @@ -87,62 +94,81 @@ function routeIntelCommand({ args, cwd, raw, error, _intel, _core }: RouteIntelC // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment const intel: IntelModule = _intel ?? require('./intel.cjs'); const c: CoreModule = _core ?? _defaultCore; - const subcommand = args[1]; - if (subcommand === 'query') { - const term = args[2]; - if (!term) { - error('Usage: gsd-tools intel query ', ERROR_REASON.USAGE); - return; - } - const planningDir = path.join(cwd, '.planning'); - c.output(intel.intelQuery(term, planningDir), raw); - } else if (subcommand === 'status') { - const planningDir = path.join(cwd, '.planning'); - const status = intel.intelStatus(planningDir); - if (!raw && status.files) { - for (const file of Object.values(status.files)) { - if (file.updated_at) { - file.updated_at = c.timeAgo(new Date(file.updated_at)); + // Phase 2 (#1646): routes through the Command Routing Hub per ADR-959 §III(B) + // line 75. Validation handlers return `makeInvalidArgs(...)` Results; the + // Hub → adapter translation preserves ERROR_REASON granularity via the + // exitReason field (Phase 1, #1644). Success handlers keep direct `c.output()` + // calls. The timeAgo mutation in non-raw `status` is preserved. Lazy require + // of intel.cjs inside the function is preserved (loads only when dispatched). + routeHubCommandFamily({ + family: 'intel', + args, + // Alphabetical for stable unknownMessage text; the integration test asserts + // inclusion of all 9 subcommands, not order. + subcommands: ['api-surface', 'diff', 'extract-exports', 'patch-meta', 'query', 'snapshot', 'status', 'update', 'validate'], + handlers: { + query: () => { + const term = args[2]; + if (!term) { + return makeInvalidArgs('term', 'Usage: gsd-tools intel query ', ERROR_REASON.USAGE); } - } - } - c.output(status, raw); - } else if (subcommand === 'diff') { - const planningDir = path.join(cwd, '.planning'); - c.output(intel.intelDiff(planningDir), raw); - } else if (subcommand === 'snapshot') { - const planningDir = path.join(cwd, '.planning'); - c.output(intel.intelSnapshot(planningDir), raw); - } else if (subcommand === 'patch-meta') { - const filePath = args[2]; - if (!filePath) { - error('Usage: gsd-tools intel patch-meta ', ERROR_REASON.USAGE); - return; - } - c.output(intel.intelPatchMeta(path.resolve(cwd, filePath)), raw); - } else if (subcommand === 'validate') { - const planningDir = path.join(cwd, '.planning'); - c.output(intel.intelValidate(planningDir), raw); - } else if (subcommand === 'extract-exports') { - const filePath = args[2]; - if (!filePath) { - error('Usage: gsd-tools intel extract-exports ', ERROR_REASON.USAGE); - return; - } - c.output(intel.intelExtractExports(path.resolve(cwd, filePath)), raw); - } else if (subcommand === 'update') { - const planningDir = path.join(cwd, '.planning'); - c.output(intel.intelUpdate(planningDir), raw); - } else if (subcommand === 'api-surface') { - const planningDir = path.join(cwd, '.planning'); - c.output(intel.intelApiSurface(planningDir), raw); - } else { - error( - 'Unknown intel subcommand. Available: query, status, update, diff, snapshot, patch-meta, validate, extract-exports, api-surface', - ERROR_REASON.SDK_UNKNOWN_COMMAND, - ); - } + const planningDir = path.join(cwd, '.planning'); + c.output(intel.intelQuery(term, planningDir), raw); + }, + status: () => { + const planningDir = path.join(cwd, '.planning'); + const status = intel.intelStatus(planningDir); + if (!raw && status.files) { + for (const file of Object.values(status.files)) { + if (file.updated_at) { + file.updated_at = c.timeAgo(new Date(file.updated_at)); + } + } + } + c.output(status, raw); + }, + diff: () => { + const planningDir = path.join(cwd, '.planning'); + c.output(intel.intelDiff(planningDir), raw); + }, + snapshot: () => { + const planningDir = path.join(cwd, '.planning'); + c.output(intel.intelSnapshot(planningDir), raw); + }, + 'patch-meta': () => { + const filePath = args[2]; + if (!filePath) { + return makeInvalidArgs('file-path', 'Usage: gsd-tools intel patch-meta ', ERROR_REASON.USAGE); + } + c.output(intel.intelPatchMeta(path.resolve(cwd, filePath)), raw); + }, + validate: () => { + const planningDir = path.join(cwd, '.planning'); + c.output(intel.intelValidate(planningDir), raw); + }, + 'extract-exports': () => { + const filePath = args[2]; + if (!filePath) { + return makeInvalidArgs('file-path', 'Usage: gsd-tools intel extract-exports ', ERROR_REASON.USAGE); + } + c.output(intel.intelExtractExports(path.resolve(cwd, filePath)), raw); + }, + update: () => { + const planningDir = path.join(cwd, '.planning'); + c.output(intel.intelUpdate(planningDir), raw); + }, + 'api-surface': () => { + const planningDir = path.join(cwd, '.planning'); + c.output(intel.intelApiSurface(planningDir), raw); + }, + }, + unknownMessage: (subcommand: string, available: string[]) => + `Unknown intel subcommand. Available: ${available.join(', ')}`, + error, + cwd, + raw, + }); } export = {