* 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:
@@ -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 {
|
||||
|
||||
@@ -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 = {
|
||||
|
||||
Reference in New Issue
Block a user