refactor(#1646): route capability routers through Command Routing Hub per ADR-959 (#1647)

* 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)
This commit is contained in:
Tom Boucher
2026-06-23 23:21:06 -04:00
committed by GitHub
parent 6214039358
commit 35478b615e
6 changed files with 212 additions and 103 deletions

View File

@@ -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)

View File

@@ -1517,7 +1517,7 @@ When `/gsd-new-project` creates a new `config.json`, it reads global defaults an
## Observability ## 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 ### Stderr error format

View File

@@ -26,6 +26,11 @@
// eslint-disable-next-line @typescript-eslint/no-require-imports // eslint-disable-next-line @typescript-eslint/no-require-imports
import io = require('./io.cjs'); 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 ──────────────────────────────────────────────────────────────────── // ─── Types ────────────────────────────────────────────────────────────────────
@@ -71,28 +76,67 @@ function routeAuditUat({ args, cwd, raw, error, _uat }: RouteAuditUatOptions): v
void error; void error;
// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
const u: UatModule = _uat ?? require('./uat.cjs'); 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 ────────────────────────────────────────────────────────── // ─── routeAuditOpen ──────────────────────────────────────────────────────────
function routeAuditOpen({ args, cwd, raw, error, _audit, _core }: RouteAuditOpenOptions): void { 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 // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
const a: AuditModule = _audit ?? require('./audit.cjs'); const a: AuditModule = _audit ?? require('./audit.cjs');
const c: CoreModule = _core ?? io; 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 wantJson = args.includes('--json');
const result = a.auditOpenArtifacts(cwd); const hubArgs = wantJson ? args.filter((arg) => arg !== '--json') : args;
if (wantJson) {
// io.output JSON-stringifies its first arg; pass the object directly. routeHubCommandFamily({
c.output(result, raw); family: 'audit-open',
} else { args: hubArgs,
// Human-readable report must bypass JSON encoding — use the rawValue subcommands: ['run'],
// form (third arg) which io.output emits verbatim. defaultSubcommand: 'run',
c.output(null, true, a.formatAuditReport(result)); 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 = { export = {

View File

@@ -13,6 +13,12 @@
// eslint-disable-next-line @typescript-eslint/no-require-imports // eslint-disable-next-line @typescript-eslint/no-require-imports
import commandRoutingHub = require('./command-routing-hub.cjs'); import commandRoutingHub = require('./command-routing-hub.cjs');
const { createHub, ERROR_KINDS } = commandRoutingHub; 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 ──────────────────────────────────────────────────────────────────── // ─── Types ────────────────────────────────────────────────────────────────────
@@ -140,7 +146,12 @@ function routeHubCommandFamily({
if (result.ok) return; if (result.ok) return;
if (result.kind === ERROR_KINDS.UnknownCommand) { 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; return;
} }
if (result.kind === ERROR_KINDS.InvalidArgs) { if (result.kind === ERROR_KINDS.InvalidArgs) {

View File

@@ -27,8 +27,15 @@
import graphify = require('./graphify.cjs'); import graphify = require('./graphify.cjs');
// eslint-disable-next-line @typescript-eslint/no-require-imports // eslint-disable-next-line @typescript-eslint/no-require-imports
import io = require('./io.cjs'); 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 { output, ERROR_REASON } = io;
const { makeInvalidArgs } = commandRoutingHub;
const { routeHubCommandFamily } = cjsCommandRouterAdapter;
// ─── Types ──────────────────────────────────────────────────────────────────── // ─── Types ────────────────────────────────────────────────────────────────────
@@ -52,42 +59,58 @@ interface RouteGraphifyCommandOptions {
// ─── Implementation ─────────────────────────────────────────────────────────── // ─── Implementation ───────────────────────────────────────────────────────────
function routeGraphifyCommand({ args, cwd, raw, error, _graphify }: RouteGraphifyCommandOptions): void { function routeGraphifyCommand({ args, cwd, raw, error, _graphify }: RouteGraphifyCommandOptions): void {
const subcommand = args[1];
const g: GraphifyModule = _graphify ?? graphify; const g: GraphifyModule = _graphify ?? graphify;
if (subcommand === 'query') { // Phase 2 (#1646): routes through the Command Routing Hub per ADR-959 §III(B)
const term = args[2]; // line 75. Validation handlers return `makeInvalidArgs(...)` Results (Q2=C,
if (!term) { // Q4=ii); the Hub → adapter translation preserves ERROR_REASON granularity
error('Usage: gsd-tools graphify query <term>', ERROR_REASON.USAGE); // via the exitReason field (Phase 1, #1644). Success handlers keep direct
return; // `output()` calls (audit's formatAuditReport quirk sets this precedent).
} // The unknown-subcommand path is owned by the Hub's manifest check; the
const budgetIdx = args.indexOf('--budget'); // adapter passes SDK_UNKNOWN_COMMAND for UnknownCommand Results.
let budget: number | null = null; routeHubCommandFamily({
if (budgetIdx !== -1) { family: 'graphify',
const rawBudget = args[budgetIdx + 1]; args,
if (rawBudget === undefined || Number.isNaN(parseInt(rawBudget, 10))) { // Alphabetical order produces a stable, byte-identical `Available:` list
error('Usage: gsd-tools graphify query <term> [--budget <N>]', ERROR_REASON.USAGE); // in the unknown-subcommand message (matches the pre-conversion text).
return; subcommands: ['build', 'diff', 'query', 'status'],
} handlers: {
budget = parseInt(rawBudget, 10); query: () => {
} const term = args[2];
output(g.graphifyQuery(cwd, term, { budget }), raw); if (!term) {
} else if (subcommand === 'status') { return makeInvalidArgs('term', 'Usage: gsd-tools graphify query <term>', ERROR_REASON.USAGE);
output(g.graphifyStatus(cwd), raw); }
} else if (subcommand === 'diff') { const budgetIdx = args.indexOf('--budget');
output(g.graphifyDiff(cwd), raw); let budget: number | null = null;
} else if (subcommand === 'build') { if (budgetIdx !== -1) {
if (args[2] === 'snapshot') { const rawBudget = args[budgetIdx + 1];
output(g.writeSnapshot(cwd), raw); if (rawBudget === undefined || Number.isNaN(parseInt(rawBudget, 10))) {
} else { return makeInvalidArgs(
output(g.graphifyBuild(cwd), raw); '--budget',
} 'Usage: gsd-tools graphify query <term> [--budget <N>]',
} else { ERROR_REASON.USAGE,
error( );
'Unknown graphify subcommand. Available: build, query, status, diff', }
ERROR_REASON.SDK_UNKNOWN_COMMAND, 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 = { export = {

View File

@@ -44,8 +44,15 @@ import io = require('./io.cjs');
import coreUtils = require('./core-utils.cjs'); import coreUtils = require('./core-utils.cjs');
// eslint-disable-next-line @typescript-eslint/no-require-imports // eslint-disable-next-line @typescript-eslint/no-require-imports
import path = require('path'); 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 { ERROR_REASON } = io;
const { makeInvalidArgs } = commandRoutingHub;
const { routeHubCommandFamily } = cjsCommandRouterAdapter;
// Default CoreModule implementation assembled from leaf modules. // Default CoreModule implementation assembled from leaf modules.
// _core seam overrides this entirely for test injection. // _core seam overrides this entirely for test injection.
const _defaultCore = { output: io.output, timeAgo: coreUtils.timeAgo }; 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 // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
const intel: IntelModule = _intel ?? require('./intel.cjs'); const intel: IntelModule = _intel ?? require('./intel.cjs');
const c: CoreModule = _core ?? _defaultCore; const c: CoreModule = _core ?? _defaultCore;
const subcommand = args[1];
if (subcommand === 'query') { // Phase 2 (#1646): routes through the Command Routing Hub per ADR-959 §III(B)
const term = args[2]; // line 75. Validation handlers return `makeInvalidArgs(...)` Results; the
if (!term) { // Hub → adapter translation preserves ERROR_REASON granularity via the
error('Usage: gsd-tools intel query <term>', ERROR_REASON.USAGE); // exitReason field (Phase 1, #1644). Success handlers keep direct `c.output()`
return; // calls. The timeAgo mutation in non-raw `status` is preserved. Lazy require
} // of intel.cjs inside the function is preserved (loads only when dispatched).
const planningDir = path.join(cwd, '.planning'); routeHubCommandFamily({
c.output(intel.intelQuery(term, planningDir), raw); family: 'intel',
} else if (subcommand === 'status') { args,
const planningDir = path.join(cwd, '.planning'); // Alphabetical for stable unknownMessage text; the integration test asserts
const status = intel.intelStatus(planningDir); // inclusion of all 9 subcommands, not order.
if (!raw && status.files) { subcommands: ['api-surface', 'diff', 'extract-exports', 'patch-meta', 'query', 'snapshot', 'status', 'update', 'validate'],
for (const file of Object.values(status.files)) { handlers: {
if (file.updated_at) { query: () => {
file.updated_at = c.timeAgo(new Date(file.updated_at)); const term = args[2];
if (!term) {
return makeInvalidArgs('term', 'Usage: gsd-tools intel query <term>', ERROR_REASON.USAGE);
} }
} const planningDir = path.join(cwd, '.planning');
} c.output(intel.intelQuery(term, planningDir), raw);
c.output(status, raw); },
} else if (subcommand === 'diff') { status: () => {
const planningDir = path.join(cwd, '.planning'); const planningDir = path.join(cwd, '.planning');
c.output(intel.intelDiff(planningDir), raw); const status = intel.intelStatus(planningDir);
} else if (subcommand === 'snapshot') { if (!raw && status.files) {
const planningDir = path.join(cwd, '.planning'); for (const file of Object.values(status.files)) {
c.output(intel.intelSnapshot(planningDir), raw); if (file.updated_at) {
} else if (subcommand === 'patch-meta') { file.updated_at = c.timeAgo(new Date(file.updated_at));
const filePath = args[2]; }
if (!filePath) { }
error('Usage: gsd-tools intel patch-meta <file-path>', ERROR_REASON.USAGE); }
return; c.output(status, raw);
} },
c.output(intel.intelPatchMeta(path.resolve(cwd, filePath)), raw); diff: () => {
} else if (subcommand === 'validate') { const planningDir = path.join(cwd, '.planning');
const planningDir = path.join(cwd, '.planning'); c.output(intel.intelDiff(planningDir), raw);
c.output(intel.intelValidate(planningDir), raw); },
} else if (subcommand === 'extract-exports') { snapshot: () => {
const filePath = args[2]; const planningDir = path.join(cwd, '.planning');
if (!filePath) { c.output(intel.intelSnapshot(planningDir), raw);
error('Usage: gsd-tools intel extract-exports <file-path>', ERROR_REASON.USAGE); },
return; 'patch-meta': () => {
} const filePath = args[2];
c.output(intel.intelExtractExports(path.resolve(cwd, filePath)), raw); if (!filePath) {
} else if (subcommand === 'update') { return makeInvalidArgs('file-path', 'Usage: gsd-tools intel patch-meta <file-path>', ERROR_REASON.USAGE);
const planningDir = path.join(cwd, '.planning'); }
c.output(intel.intelUpdate(planningDir), raw); c.output(intel.intelPatchMeta(path.resolve(cwd, filePath)), raw);
} else if (subcommand === 'api-surface') { },
const planningDir = path.join(cwd, '.planning'); validate: () => {
c.output(intel.intelApiSurface(planningDir), raw); const planningDir = path.join(cwd, '.planning');
} else { c.output(intel.intelValidate(planningDir), raw);
error( },
'Unknown intel subcommand. Available: query, status, update, diff, snapshot, patch-meta, validate, extract-exports, api-surface', 'extract-exports': () => {
ERROR_REASON.SDK_UNKNOWN_COMMAND, const filePath = args[2];
); if (!filePath) {
} return makeInvalidArgs('file-path', 'Usage: gsd-tools intel extract-exports <file-path>', 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 = { export = {