* 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
5
.changeset/capability-routers-via-hub.md
Normal file
5
.changeset/capability-routers-via-hub.md
Normal 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)
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 = {
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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 <term>', 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 <term> [--budget <N>]', 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 <term>', 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 <term> [--budget <N>]',
|
||||
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 = {
|
||||
|
||||
@@ -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 <term>', 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 <term>', 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 <file-path>', 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 <file-path>', 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 <file-path>', 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 <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 = {
|
||||
|
||||
Reference in New Issue
Block a user