feat(hub): drop mode/sdkLoader/SdkDispatchFailed (#175) (#220)

* feat(hub): drop mode/sdkLoader/SdkDispatchFailed (#175)

The Command Routing Hub no longer carries dual-runtime selection.
Removes `mode` and `sdkLoader` constructor parameters and the
`SdkDispatchFailed` and `SdkLoadFailed` errorKind values. The Hub
now routes exclusively through the CJS registry / handler resolution
path. ERROR_KINDS enum shrinks from 6 to 4 values.

phase-command-router.cjs updated to construct the Hub without the
removed params (removes tryLoadSdk, getExecuteForCjs, sdkLoader fn,
mode variable, and the post-dispatch SDK output branch). The 7
remaining family routers (init, phases, roadmap, state, validate,
verify, cjs-command-router-adapter) do not use createHub directly
and require no changes.

The CJS↔SDK bridge (bin/lib/cjs-sdk-bridge.cjs) is unchanged and
remains separately invokable; its removal is tracked in Phase 4 (#190).

ADR-0012 is no longer amended in this PR — the decision is captured
in ADR-0174 (which supersedes ADR-0012 entirely as part of the
SDK-retirement migration). Amending a superseded ADR would be
redundant noise.

Tests:
- Added assertions that Hub rejects/ignores `mode` and `sdkLoader`
- Removed obsolete mode-selection branching tests
- 57/57 local tests pass

Closes #175.
Part of #174 (ADR-0174).

* chore(changeset): add docs-exempt marker (#175)

P1.1's CommandRoutingHub work has no docs/ touchpoints — the
architectural decision is captured in ADR-0174 (merged via PR #198).
Per-phase ADR amendments would create noise; the SDK-retirement
migration's docs land in Phase 6 PRs (#193-#196) once the relevant
state is removed.

Adds the standard <!-- docs-exempt: <reason> --> marker inside the
changeset fragment so lint:docs accepts the PR without forcing a
docs/ touch that would be redundant.

Refs #175. Part of #174 (ADR-0174).
This commit is contained in:
Tom Boucher
2026-05-24 13:04:11 -04:00
committed by GitHub
parent 6fc46db49a
commit 21e3ce53c0
4 changed files with 156 additions and 398 deletions

View File

@@ -1,27 +1,24 @@
'use strict';
/**
* Command Routing Hub — issue #3788.
* Command Routing Hub — issue #3788, simplified in #175.
*
* A pure-result dispatch hub that centralizes the mode decision (SDK vs CJS),
* A pure-result dispatch hub that centralizes CJS routing,
* the error taxonomy, and the no-throw contract that all command-family routers
* currently duplicate independently.
*
* Design:
* createHub({ mode, sdkLoader, cjsRegistry, manifest }) -> hub
* createHub({ cjsRegistry, manifest }) -> hub
* hub.dispatch({ family, subcommand, args, cwd, raw }) -> Result
*
* Result = { ok: true, data }
* | { ok: false, errorKind, message, details? }
*
* Invariants:
* - `mode` is fixed at construction; never re-evaluated per dispatch.
* - Hub always routes through CJS handlers. There is no SDK path (#175).
* - Hub never prints to stdout/stderr, never calls process.exit.
* - Hub never throws — all internal throws are caught and converted to
* { ok: false, errorKind: 'HandlerFailure', message, details }.
* - No transparent fallback: an SDK-mode hub that encounters an SDK crash
* returns { ok: false, errorKind: 'SdkDispatchFailed' }; it does NOT
* silently retry via the CJS registry.
* - The errorKind taxonomy is closed. Callers switch on ERROR_KINDS values.
*/
@@ -29,6 +26,8 @@
* Closed errorKind enum. Export as a frozen object so callers can switch on
* ERROR_KINDS.UnknownCommand etc. without relying on bare string literals.
*
* #175: SdkLoadFailed and SdkDispatchFailed removed — Hub is CJS-only.
*
* @readonly
*/
const ERROR_KINDS = Object.freeze({
@@ -40,10 +39,6 @@ const ERROR_KINDS = Object.freeze({
HandlerRefusal: 'HandlerRefusal',
/** A handler threw an unexpected exception. */
HandlerFailure: 'HandlerFailure',
/** The sdkLoader function threw or returned a falsy value at dispatch time. */
SdkLoadFailed: 'SdkLoadFailed',
/** The SDK was loaded but threw or returned ok:false during execution. */
SdkDispatchFailed: 'SdkDispatchFailed',
});
/**
@@ -54,13 +49,10 @@ const ERROR_KINDS = Object.freeze({
/**
* @typedef {object} HubOptions
* @property {'sdk' | 'cjs'} mode - Dispatch mode, fixed at construction.
* @property {() => unknown} [sdkLoader] - Callable that returns the SDK execute
* function (or throws). Only used when mode === 'sdk'.
* @property {Record<string, Record<string, (ctx: object) => HubResult>>} [cjsRegistry] -
* Nested map of family -> subcommand -> handler. Only used when mode === 'cjs'.
* Nested map of family -> subcommand -> handler.
* @property {Record<string, string[]>} [manifest] - Map of family -> known subcommands.
* Used for UnknownCommand detection regardless of mode.
* Used for UnknownCommand detection.
*/
/**
@@ -69,14 +61,7 @@ const ERROR_KINDS = Object.freeze({
* @param {HubOptions} options
* @returns {{ dispatch: (req: object) => HubResult }}
*/
function createHub({ mode, sdkLoader, cjsRegistry, manifest }) {
if (mode !== 'sdk' && mode !== 'cjs') {
throw new TypeError(`CommandRoutingHub: mode must be 'sdk' or 'cjs', got ${JSON.stringify(mode)}`);
}
// Validate mode once at construction; never re-check per dispatch.
const _mode = mode;
const _sdkLoader = sdkLoader;
function createHub({ cjsRegistry, manifest } = {}) {
const _cjsRegistry = cjsRegistry;
const _manifest = manifest;
@@ -102,7 +87,7 @@ function createHub({ mode, sdkLoader, cjsRegistry, manifest }) {
function _dispatch(req) {
const { family, subcommand, args = [], cwd, raw } = req;
// ── manifest check (applies to both modes) ──────────────────────────────
// ── manifest check ────────────────────────────────────────────────────────
if (_manifest) {
const knownSubcommands = _manifest[family];
if (!knownSubcommands) {
@@ -121,70 +106,9 @@ function createHub({ mode, sdkLoader, cjsRegistry, manifest }) {
}
}
if (_mode === 'sdk') {
return _dispatchSdk({ family, subcommand, args, cwd, raw });
}
return _dispatchCjs({ family, subcommand, args, cwd, raw });
}
function _dispatchSdk({ family, subcommand, args, cwd, raw }) {
// Load the SDK execute function (or return SdkLoadFailed).
let executeForCjs;
try {
executeForCjs = _sdkLoader ? _sdkLoader() : null;
} catch (err) {
return {
ok: false,
errorKind: ERROR_KINDS.SdkLoadFailed,
message: `SDK load failed: ${err instanceof Error ? err.message : String(err)}`,
details: { originalError: err },
};
}
if (!executeForCjs || typeof executeForCjs !== 'function') {
return {
ok: false,
errorKind: ERROR_KINDS.SdkLoadFailed,
message: 'SDK loader did not return a callable execute function',
};
}
// Call the SDK. No transparent fallback — any error becomes SdkDispatchFailed.
let result;
try {
result = executeForCjs({
registryCommand: subcommand ? `${family}.${subcommand}` : family,
registryArgs: args,
legacyCommand: family,
legacyArgs: [subcommand, ...args].filter(Boolean),
mode: raw ? 'raw' : 'json',
projectDir: cwd,
});
} catch (err) {
return {
ok: false,
errorKind: ERROR_KINDS.SdkDispatchFailed,
message: err instanceof Error ? err.message : String(err),
details: { originalError: err },
};
}
if (!result || !result.ok) {
const message = (result && result.errorDetails && result.errorDetails.message)
? result.errorDetails.message
: `${family}${subcommand ? ' ' + subcommand : ''} failed (${result && result.errorKind})`;
return {
ok: false,
errorKind: ERROR_KINDS.SdkDispatchFailed,
message,
details: result || {},
};
}
return { ok: true, data: result.data };
}
function _dispatchCjs({ family, subcommand, args, cwd, raw }) {
if (!_cjsRegistry) {
return {

View File

@@ -1,37 +1,28 @@
'use strict';
const { PHASE_SUBCOMMANDS } = require('./command-aliases.generated.cjs');
const { output } = require('./core.cjs');
// ─── SDK bridge (Phase 6) — shared loader via cjs-sdk-bridge.cjs ──────────────
const { tryLoadSdk, getExecuteForCjs } = require('./cjs-sdk-bridge.cjs');
// ─── CommandRoutingHub (issue #3788) ──────────────────────────────────────────
// ─── CommandRoutingHub (issue #3788, simplified in #175) ──────────────────────
const { createHub, ERROR_KINDS } = require('./command-routing-hub.cjs');
/**
* Manifest-backed phase subcommand router.
* Keeps gsd-tools.cjs thin while preserving existing command semantics.
*
* Phase 6: all CJS-handled phase subcommands are dispatched via executeForCjs
* when the SDK is available. CJS fallback retained when:
* - GSD_WORKSTREAM is active (workstream-scoped requests fall through to CJS).
* - SDK is unavailable (build not present).
* #175: Hub is CJS-only. The SDK bridge is still separately invokable via
* bin/lib/cjs-sdk-bridge.cjs, but the Hub no longer routes to it.
*
* SDK-only (unsupported in CJS router):
* SDK-only (unsupported in CJS router — error returned before dispatch):
* - list-plans: SDK-only.
* - list-artifacts: SDK-only.
* - scaffold: routed through top-level scaffold command.
*
* CJS-only subcommands: none.
* CJS-only subcommands: mvp-mode (dispatched directly, before hub).
*
* #3788: dispatch is now mediated by CommandRoutingHub. The public entry point
* #3788: dispatch is mediated by CommandRoutingHub. The public entry point
* and observable CLI behaviour are unchanged.
*/
function routePhaseCommand({ phase, args, cwd, raw, error }) {
const activeWorkstream = process.env.GSD_WORKSTREAM;
const sdkAvailable = !activeWorkstream && tryLoadSdk();
// ── Unsupported / SDK-only subcommands ─────────────────────────────────────
// Resolved before dispatch so the error message matches the pre-#3788 text.
const UNSUPPORTED = {
@@ -58,12 +49,11 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
return;
}
// ── CJS-only subcommands (always bypass SDK path) ──────────────────────────
// ── CJS-only subcommands (dispatched directly, before hub) ─────────────────
// `mvp-mode` has a CJS-native implementation in phase.cmdPhaseMvpMode that
// differs from the SDK query layer (different ROADMAP scan + error codes).
// Dispatch it early so the SDK hub path is never reached for this subcommand,
// preserving the pre-migration observable behaviour (correct exit code,
// correct JSON error reason code, correct ROADMAP scan).
// Dispatch it early to preserve pre-migration observable behaviour (correct
// exit code, correct JSON error reason code, correct ROADMAP scan).
if (subcommand === 'mvp-mode') {
phase.cmdPhaseMvpMode(cwd, args.slice(2), raw);
return;
@@ -157,15 +147,6 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
},
};
// ── Build the SDK loader ────────────────────────────────────────────────────
function sdkLoader() {
const execute = getExecuteForCjs();
if (!execute) return null;
// Wrap executeForCjs to match the hub's sdkLoader contract:
// hub calls sdkLoader() -> returns the execute function itself.
return execute;
}
// ── Build manifest (available subcommands for UnknownCommand detection) ─────
// `availableSubcommands` is what the error message shows. It excludes
// SDK-only unsupported commands (already handled above) but does NOT include
@@ -179,14 +160,9 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
const manifestSubcommands = ['mvp-mode', ...availableSubcommands];
const manifest = { phase: manifestSubcommands };
// ── Construct hub (mode fixed at call time based on env + SDK availability) ─
const mode = sdkAvailable ? 'sdk' : 'cjs';
const hub = createHub({
mode,
sdkLoader: mode === 'sdk' ? sdkLoader : undefined,
cjsRegistry: mode === 'cjs' ? cjsRegistry : undefined,
manifest,
});
// ── Construct hub ──────────────────────────────────────────────────────────
// #175: Hub is CJS-only — no mode param, no sdkLoader.
const hub = createHub({ cjsRegistry, manifest });
// ── Dispatch ────────────────────────────────────────────────────────────────
const result = hub.dispatch({
@@ -198,27 +174,18 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
});
// ── Translate result → CLI output / error (adapter responsibility) ──────────
// CJS handlers call output() themselves (inside phase.cmdPhase*()).
// No further output call is needed here.
if (!result.ok) {
if (result.errorKind === ERROR_KINDS.UnknownCommand) {
const available = availableSubcommands.join(', ');
error(`Unknown phase subcommand. Available: ${available}`);
return;
}
// InvalidArgs, HandlerRefusal, HandlerFailure, SdkLoadFailed, SdkDispatchFailed
// InvalidArgs, HandlerRefusal, HandlerFailure
error(result.message);
return;
}
// SDK path: the hub wraps executeForCjs; data projection is the adapter's job.
// CJS handlers call output() themselves (inside phase.cmdPhase*()), so no
// further output call is needed for cjs mode.
if (mode === 'sdk') {
if (raw) {
output(null, true, typeof result.data === 'string' ? result.data : String(result.data ?? ''));
} else {
output(result.data);
}
}
}
module.exports = {