@opengsd/gsd-core 1.2.0 → 1.3.0

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -0,0 +1,524 @@
+"use strict";
+/**
+ * Shell Command Projection Module
+ *
+ * Tracer-bullet seam for runtime-aware projection of serialized command text
+ * that GSD writes into runtime config or prints for copy/paste. This module
+ * does NOT execute commands; it only renders command text for external shells
+ * and runtimes.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/shell-command-projection.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hookCommandNeedsPowerShellCallOperator = hookCommandNeedsPowerShellCallOperator;
+exports.formatHookCommandForRuntime = formatHookCommandForRuntime;
+exports.shellHookOmitsBashRunner = shellHookOmitsBashRunner;
+exports.buildLocalShellHookCommand = buildLocalShellHookCommand;
+exports.formatManagedHookScriptToken = formatManagedHookScriptToken;
+exports.projectLocalHookPrefix = projectLocalHookPrefix;
+exports.projectPortableHookBaseDir = projectPortableHookBaseDir;
+exports.projectShellCommandText = projectShellCommandText;
+exports.projectManagedHookCommand = projectManagedHookCommand;
+exports.isManagedHookBasename = isManagedHookBasename;
+exports.isManagedHookCommand = isManagedHookCommand;
+exports.projectLegacySettingsHookCommand = projectLegacySettingsHookCommand;
+exports.escapeTomlDoubleQuotedString = escapeTomlDoubleQuotedString;
+exports.projectCodexHookTomlCommand = projectCodexHookTomlCommand;
+exports.escapePowerShellSingleQuoted = escapePowerShellSingleQuoted;
+exports.escapePosixDoubleQuoted = escapePosixDoubleQuoted;
+exports.escapeSingleQuotedShellLiteral = escapeSingleQuotedShellLiteral;
+exports.renderShellActionLines = renderShellActionLines;
+exports.projectPathActionProjection = projectPathActionProjection;
+exports.projectPersistentPathExportActions = projectPersistentPathExportActions;
+exports.execGit = execGit;
+exports.execNpm = execNpm;
+exports.execTool = execTool;
+exports.probeTty = probeTty;
+exports.normalizeContent = normalizeContent;
+exports.platformWriteSync = platformWriteSync;
+exports.platformReadSync = platformReadSync;
+exports.platformEnsureDir = platformEnsureDir;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+// Use non-destructured namespace import so test-time mock.method(childProcess, 'spawnSync')
+// can intercept calls from this seam — destructured imports capture references
+// at load time and become un-mockable.
+const node_child_process_1 = __importDefault(require("node:child_process"));
+/**
+ * Return true when a managed hook command must be prefixed with PowerShell's
+ * call operator so a quoted executable token is invokable by the target
+ * runtime/shell combination.
+ *
+ * Current evidence-backed policy:
+ * - Gemini on Windows requires `& ` for quoted node/bash runners.
+ * - Claude Code on Windows does NOT: its hook commands execute under bash/Git
+ *   Bash and `& ` breaks there (#3413).
+ *
+ * Keep the policy conservative until another runtime has a verified need.
+ */
+function hookCommandNeedsPowerShellCallOperator(opts = {}) {
+    const platform = opts.platform || process.platform;
+    const runtime = opts.runtime || 'generic';
+    return platform === 'win32' && runtime === 'gemini';
+}
+/**
+ * Project a fully-assembled hook command string for the target runtime.
+ */
+function formatHookCommandForRuntime(command, opts = {}) {
+    return hookCommandNeedsPowerShellCallOperator(opts) ? `& ${command}` : command;
+}
+// #166/#580: Claude Code on Windows executes hook command strings inside Git
+// Bash. A `.sh` hook wrapped with an explicit bash.exe path makes bash try to
+// exec bash itself ("C:/.../bash.exe: cannot execute binary file"). Both install
+// paths — global (buildHookCommand) and local (buildLocalShellHookCommand) — must
+// drop the bash runner in this case and emit only the anchored script path.
+// Centralized here so the two paths cannot silently drift apart again: the local
+// path missed this guard and reintroduced the #166/#377 failure (#580).
+function shellHookOmitsBashRunner({ platform, runtime = 'generic', isShellHook = false } = {}) {
+    const p = platform ?? process.platform;
+    return p === 'win32' && runtime === 'claude' && isShellHook;
+}
+// Builds the command string for a local-install managed `.sh` hook. Mirrors the
+// global buildHookCommand path but uses the $CLAUDE_PROJECT_DIR-anchored prefix
+// instead of an absolute configDir. On Claude/Windows the bash runner is dropped
+// (see shellHookOmitsBashRunner) and the anchored script path is emitted alone —
+// matching the global path. Elsewhere the resolved bash runner is required; a
+// null runner yields null so callers skip registration instead of emitting a
+// broken hook (#3393).
+function buildLocalShellHookCommand({ localPrefix, hookFile, bashRunner, runtime = 'generic', platform = process.platform }) {
+    if (!localPrefix || !hookFile)
+        return null;
+    const scriptPath = `${localPrefix}/hooks/${hookFile}`;
+    if (shellHookOmitsBashRunner({ platform, runtime, isShellHook: true })) {
+        return formatHookCommandForRuntime(scriptPath, { platform, runtime });
+    }
+    if (!bashRunner)
+        return null;
+    return projectShellCommandText({
+        runnerToken: bashRunner,
+        argTokens: [scriptPath],
+        runtime,
+        platform,
+    });
+}
+/**
+ * Project a managed hook script path token for serialized shell commands.
+ * Windows managed hook commands normalize to forward slashes so the same path
+ * survives JSON/TOML/config surfaces consistently.
+ */
+function formatManagedHookScriptToken(scriptPath, opts = {}) {
+    const platform = opts.platform || process.platform;
+    if (platform !== 'win32')
+        return null;
+    return JSON.stringify(scriptPath.replace(/\\/g, '/'));
+}
+function projectLocalHookPrefix({ runtime = 'claude', dirName }) {
+    if (!dirName)
+        return dirName;
+    return (runtime === 'gemini' || runtime === 'antigravity')
+        ? dirName
+        : `"$CLAUDE_PROJECT_DIR"/${dirName}`;
+}
+function projectPortableHookBaseDir({ configDir, homeDir }) {
+    const normalizedConfigDir = String(configDir || '').replace(/\\/g, '/');
+    const normalizedHome = String(homeDir || '').replace(/\\/g, '/');
+    if (!normalizedConfigDir || !normalizedHome)
+        return normalizedConfigDir;
+    return normalizedConfigDir.startsWith(normalizedHome)
+        ? '$HOME' + normalizedConfigDir.slice(normalizedHome.length)
+        : normalizedConfigDir;
+}
+function projectShellCommandText({ runnerToken, argTokens = [], runtime = 'generic', platform = process.platform, }) {
+    if (!runnerToken)
+        return null;
+    const parts = [runnerToken, ...argTokens.filter(Boolean)];
+    return formatHookCommandForRuntime(parts.join(' '), { platform, runtime });
+}
+function projectManagedHookCommand({ absoluteRunner, scriptPath, runtime = 'generic', platform = process.platform }) {
+    if (!absoluteRunner || !scriptPath)
+        return null;
+    const normalizedScriptPath = platform === 'win32' ? scriptPath.replace(/\\/g, '/') : scriptPath;
+    return projectShellCommandText({
+        runnerToken: absoluteRunner,
+        argTokens: [JSON.stringify(normalizedScriptPath)],
+        runtime,
+        platform,
+    });
+}
+const MANAGED_HOOK_BASENAMES_BY_SURFACE = {
+    'settings-json': new Set([
+        'gsd-check-update.js',
+        'gsd-statusline.js',
+        'gsd-context-monitor.js',
+        'gsd-prompt-guard.js',
+        'gsd-read-guard.js',
+        'gsd-read-injection-scanner.js',
+        'gsd-update-banner.js',
+        'gsd-workflow-guard.js',
+    ]),
+    'codex-toml': new Set([
+        'gsd-check-update.js',
+    ]),
+};
+const MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE = {
+    'settings-json': new Set([
+        'gsd-check-update.js',
+        'gsd-statusline.js',
+        'gsd-context-monitor.js',
+        'gsd-prompt-guard.js',
+        'gsd-read-guard.js',
+        'gsd-read-injection-scanner.js',
+        'gsd-update-banner.js',
+        'gsd-workflow-guard.js',
+        'gsd-session-state.sh',
+        'gsd-validate-commit.sh',
+        'gsd-phase-boundary.sh',
+    ]),
+    'codex-toml': new Set([
+        'gsd-check-update.js',
+    ]),
+    'codex-hooks-json': new Set([
+        'gsd-check-update.js',
+        // #3426: Windows .cmd shim for Codex hook — must be treated as managed so
+        // reconcileCodexHooksJsonSessionStart can replace stale node-runner commands
+        // with the .cmd shim on reinstall (and vice-versa on cross-platform moves).
+        'gsd-check-update.cmd',
+    ]),
+};
+const LEGACY_MANAGED_HOOK_ALIASES_BY_SURFACE = {
+    'codex-toml': new Set([
+        'gsd-update-check.js',
+    ]),
+    'codex-hooks-json': new Set([
+        'gsd-update-check.js',
+    ]),
+};
+function managedHookSurfaceSet(surface = 'settings-json') {
+    return MANAGED_HOOK_BASENAMES_BY_SURFACE[surface] || MANAGED_HOOK_BASENAMES_BY_SURFACE['settings-json'];
+}
+function isManagedHookBasename(scriptPathOrBasename, opts = {}) {
+    if (!scriptPathOrBasename)
+        return false;
+    const surface = opts.surface || 'settings-json';
+    const basename = String(scriptPathOrBasename).split(/[\\/]/).pop() || '';
+    return managedHookSurfaceSet(surface).has(basename);
+}
+function managedHookCommandSurfaceSet(surface = 'settings-json', includeLegacyAliases = false) {
+    const base = MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE[surface]
+        || MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE['settings-json'];
+    if (!includeLegacyAliases)
+        return base;
+    const aliases = LEGACY_MANAGED_HOOK_ALIASES_BY_SURFACE[surface];
+    if (!aliases || aliases.size === 0)
+        return base;
+    return new Set([...base, ...aliases]);
+}
+function isManagedHookCommand(commandText, opts = {}) {
+    if (typeof commandText !== 'string')
+        return false;
+    const surface = opts.surface || 'settings-json';
+    const includeLegacyAliases = opts.includeLegacyAliases === true;
+    const managedBasenames = managedHookCommandSurfaceSet(surface, includeLegacyAliases);
+    if (!managedBasenames || managedBasenames.size === 0)
+        return false;
+    const normalizedCommand = commandText.replace(/\\/g, '/');
+    if (typeof opts.configDir === 'string' && opts.configDir.length > 0) {
+        const normalizedHooksDir = `${node_path_1.default.join(opts.configDir, 'hooks').replace(/\\/g, '/')}/`;
+        if (!normalizedCommand.includes(normalizedHooksDir))
+            return false;
+    }
+    for (const basename of managedBasenames) {
+        const escapedBasename = basename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const pattern = new RegExp(`(^|[\\\\/\\s"'` + '`' + `])${escapedBasename}(?=$|[\\s"'` + '`' + `])`);
+        if (pattern.test(normalizedCommand))
+            return true;
+    }
+    return false;
+}
+/**
+ * Projection helper for legacy settings.json hook rewrites.
+ *
+ * Non-Windows keeps the original script token shape when provided (single
+ * quote / bareword / quoted), while Windows normalizes to double-quoted
+ * forward-slash path tokens for stable cross-shell behavior.
+ */
+function projectLegacySettingsHookCommand({ absoluteRunner, scriptPath, scriptToken, runtime = 'generic', platform = process.platform, }) {
+    if (!absoluteRunner || !scriptPath)
+        return null;
+    const normalizedScriptPath = platform === 'win32' ? scriptPath.replace(/\\/g, '/') : scriptPath;
+    const commandScriptToken = platform === 'win32'
+        ? JSON.stringify(normalizedScriptPath)
+        : (scriptToken || JSON.stringify(normalizedScriptPath));
+    return projectShellCommandText({
+        runnerToken: absoluteRunner,
+        argTokens: [commandScriptToken],
+        runtime,
+        platform,
+    });
+}
+function escapeTomlDoubleQuotedString(value) {
+    return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function projectCodexHookTomlCommand({ absoluteRunner, scriptPath, platform = process.platform }) {
+    const command = projectManagedHookCommand({
+        absoluteRunner,
+        scriptPath,
+        runtime: 'codex',
+        platform,
+    });
+    return command === null ? null : escapeTomlDoubleQuotedString(command);
+}
+function escapePowerShellSingleQuoted(value) {
+    return String(value).replace(/'/g, "''");
+}
+function escapePosixDoubleQuoted(value) {
+    return String(value).replace(/[\\$"`]/g, '\\$&');
+}
+function escapeSingleQuotedShellLiteral(value) {
+    return String(value).replace(/'/g, "'\\''");
+}
+function renderShellActionLines(shellActions = []) {
+    return shellActions.map((action) => {
+        if (!action || !action.command)
+            return '';
+        return action.label ? `${action.label}: ${action.command}` : action.command;
+    }).filter(Boolean);
+}
+function projectPathActionProjection({ mode = 'repair', targetDir, platform = process.platform, }) {
+    if (!targetDir)
+        return { shellActions: [], actionLines: [] };
+    const isWin32 = platform === 'win32';
+    let shellActions;
+    if (isWin32) {
+        const psTargetDir = escapePowerShellSingleQuoted(targetDir);
+        const bashTargetDir = escapeSingleQuotedShellLiteral(String(targetDir).replace(/\\/g, '/'));
+        shellActions = [
+            {
+                label: 'PowerShell',
+                shell: 'powershell',
+                command: `[Environment]::SetEnvironmentVariable('PATH', '${psTargetDir};' + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')`,
+            },
+            {
+                label: 'cmd.exe',
+                shell: 'cmd',
+                command: `powershell -Command "[Environment]::SetEnvironmentVariable('PATH', '${psTargetDir};' + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')"`,
+            },
+            {
+                label: 'Git Bash',
+                shell: 'bash',
+                command: `echo 'export PATH="${bashTargetDir}:$PATH"' >> ~/.bashrc`,
+            },
+        ];
+    }
+    else if (mode === 'persist') {
+        const bashTargetDir = escapeSingleQuotedShellLiteral(String(targetDir));
+        shellActions = [
+            {
+                label: 'zsh',
+                shell: 'zsh',
+                command: `echo 'export PATH="${bashTargetDir}:$PATH"' >> ~/.zshrc`,
+            },
+            {
+                label: 'bash',
+                shell: 'bash',
+                command: `echo 'export PATH="${bashTargetDir}:$PATH"' >> ~/.bashrc`,
+            },
+        ];
+    }
+    else {
+        const posixTargetDir = escapePosixDoubleQuoted(targetDir);
+        shellActions = [
+            {
+                label: null,
+                shell: 'posix',
+                command: `export PATH="${posixTargetDir}:$PATH"`,
+            },
+        ];
+    }
+    return {
+        shellActions,
+        actionLines: renderShellActionLines(shellActions),
+    };
+}
+function projectPersistentPathExportActions({ targetDir, platform = process.platform }) {
+    const projected = projectPathActionProjection({
+        mode: 'persist',
+        targetDir,
+        platform,
+    });
+    return { shellActions: projected.shellActions };
+}
+function _spawnResult(result, program) {
+    if (result.error && result.error.code === 'ENOENT') {
+        return { exitCode: 127, stdout: '', stderr: `${program}: not found`, signal: null, error: result.error };
+    }
+    return {
+        exitCode: result.status ?? 1,
+        stdout: (result.stdout ?? '').toString().trim(),
+        stderr: (result.stderr ?? '').toString().trim(),
+        signal: result.signal ?? null,
+        error: result.error ?? null,
+    };
+}
+function execGit(args, opts = {}) {
+    // Non-interactive defaults: a hung credential prompt or terminal-input
+    // probe must surface as a timeout, not block the tool forever. Callers
+    // can override via opts.env.
+    const env = {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: '0',
+        GCM_INTERACTIVE: 'never',
+        ...(opts.env || {}),
+    };
+    const result = node_child_process_1.default.spawnSync('git', args, {
+        cwd: opts.cwd,
+        env,
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        timeout: opts.timeout ?? 10_000,
+    });
+    return _spawnResult(result, 'git');
+}
+function execNpm(args, opts = {}) {
+    const result = node_child_process_1.default.spawnSync('npm', args, {
+        cwd: opts.cwd,
+        shell: process.platform === 'win32',
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: opts.timeout ?? 15_000,
+    });
+    return _spawnResult(result, 'npm');
+}
+function execTool(program, args, opts = {}) {
+    const result = node_child_process_1.default.spawnSync(program, args, {
+        cwd: opts.cwd,
+        env: opts.env ? { ...process.env, ...opts.env } : undefined,
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        timeout: opts.timeout ?? 30_000,
+    });
+    return _spawnResult(result, program);
+}
+function probeTty(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    if (platform === 'win32')
+        return null;
+    try {
+        const ttyPath = node_child_process_1.default.execFileSync('tty', [], {
+            encoding: 'utf-8',
+            stdio: ['inherit', 'pipe', 'ignore'],
+        }).trim();
+        if (!ttyPath || ttyPath === 'not a tty')
+            return null;
+        return ttyPath;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Platform file I/O ────────────────────────────────────────────────────────
+function _normalizeMd(content) {
+    if (!content || typeof content !== 'string')
+        return content;
+    let text = content.replace(/\r\n/g, '\n');
+    const lines = text.split('\n');
+    const result = [];
+    const fenceRegex = /^```/;
+    const insideFence = new Array(lines.length);
+    let fenceOpen = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (fenceRegex.test(lines[i].trimEnd())) {
+            if (fenceOpen) {
+                insideFence[i] = false;
+                fenceOpen = false;
+            }
+            else {
+                insideFence[i] = false;
+                fenceOpen = true;
+            }
+        }
+        else {
+            insideFence[i] = fenceOpen;
+        }
+    }
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const prev = i > 0 ? lines[i - 1] : '';
+        const prevTrimmed = prev.trimEnd();
+        const trimmed = line.trimEnd();
+        const isFenceLine = fenceRegex.test(trimmed);
+        if (/^#{1,6}\s/.test(trimmed) && i > 0 && prevTrimmed !== '' && prevTrimmed !== '---')
+            result.push('');
+        if (isFenceLine && i > 0 && prevTrimmed !== '' && !insideFence[i] && (i === 0 || !insideFence[i - 1] || isFenceLine)) {
+            if (i === 0 || !insideFence[i - 1])
+                result.push('');
+        }
+        if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i > 0 && prevTrimmed !== '' && !/^(\s*[-*+]\s|\s*\d+\.\s)/.test(prev) && prevTrimmed !== '---')
+            result.push('');
+        result.push(line);
+        if (/^#{1,6}\s/.test(trimmed) && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '')
+            result.push('');
+        if (/^```\s*$/.test(trimmed) && i > 0 && insideFence[i - 1] && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '')
+            result.push('');
+        if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i < lines.length - 1) {
+            const next = lines[i + 1];
+            if (next !== undefined && next.trimEnd() !== '' && !/^(\s*[-*+]\s|\s*\d+\.\s)/.test(next) && !/^\s/.test(next))
+                result.push('');
+        }
+    }
+    text = result.join('\n');
+    text = text.replace(/\n{3,}/g, '\n\n');
+    text = text.replace(/\n*$/, '\n');
+    return text;
+}
+function normalizeContent(filePath, content, opts = {}) {
+    const encoding = opts.encoding ?? 'utf-8';
+    const isMd = node_path_1.default.extname(filePath).toLowerCase() === '.md';
+    let normalized;
+    if (isMd) {
+        normalized = _normalizeMd(content);
+    }
+    else {
+        normalized = (content ?? '').replace(/\r\n/g, '\n').replace(/\n*$/, '\n');
+    }
+    return { content: normalized, encoding };
+}
+function platformWriteSync(filePath, content, opts = {}) {
+    const { content: normalized, encoding } = normalizeContent(filePath, content, opts);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+    const tmpPath = filePath + '.tmp.' + process.pid;
+    try {
+        node_fs_1.default.writeFileSync(tmpPath, normalized, encoding);
+        node_fs_1.default.renameSync(tmpPath, filePath);
+    }
+    catch {
+        try {
+            node_fs_1.default.unlinkSync(tmpPath);
+        }
+        catch { /* already gone */ }
+        node_fs_1.default.writeFileSync(filePath, normalized, encoding);
+    }
+}
+function platformReadSync(filePath, opts = {}) {
+    const encoding = opts.encoding ?? 'utf-8';
+    try {
+        return node_fs_1.default.readFileSync(filePath, encoding);
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT') {
+            if (opts.required)
+                throw err;
+            return null;
+        }
+        throw err;
+    }
+}
+function platformEnsureDir(dirPath) {
+    node_fs_1.default.mkdirSync(dirPath, { recursive: true });
+}

package/gsd-core/bin/lib/state-command-router.cjs

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Manifest-backed state subcommand router.
+ * Keeps gsd-tools.cjs thin while preserving existing command semantics.
+ *
+ * Phase 5.1: handlers that have SDK equivalents are dispatched via
+ * executeForCjs (the sync bridge). CJS fallback is retained for:
+ * - complete-phase: no SDK counterpart.
+ * - Any command when GSD_WORKSTREAM is active (GSDTransport forces subprocess
+ *   for workstream requests; subprocess is disabled in the sync bridge worker).
+ * - Any command when the SDK is not available (build not present).
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/state-command-router.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+const command_aliases_cjs_1 = require("./command-aliases.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
+const { routeHubCommandFamily } = cjsCommandRouterAdapter;
+const command_arg_projection_cjs_1 = require("./command-arg-projection.cjs");
+// ─── Types ────────────────────────────────────────────────────────────────────
+// Helper: extract string-only named arg value (value flags never return boolean).
+function strArg(opts, key) {
+    const v = opts[key];
+    if (typeof v === 'boolean')
+        return undefined;
+    return v;
+}
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routeStateCommand({ state, args, cwd, raw, error }) {
+    const parsePlans = (plans) => {
+        const parsedPlans = plans == null ? null : Number.parseInt(plans, 10);
+        if (plans != null && Number.isNaN(parsedPlans)) {
+            error('Invalid --plans value. Expected an integer.');
+            return null;
+        }
+        return parsedPlans;
+    };
+    routeHubCommandFamily({
+        family: 'state',
+        args,
+        subcommands: ['load', 'complete-phase', ...command_aliases_cjs_1.STATE_SUBCOMMANDS.filter((s) => s !== 'load')],
+        defaultSubcommand: 'load',
+        unsupported: {
+            'add-roadmap-evolution': 'state add-roadmap-evolution is SDK-only. Use: gsd-tools query state.add-roadmap-evolution ...',
+        },
+        error,
+        cwd,
+        raw,
+        unknownMessage: (subcommand, available) => `Unknown state subcommand: "${subcommand}". Available: ${available.join(', ')}`,
+        handlers: {
+            load: () => state.cmdStateLoad(cwd, raw),
+            json: () => state.cmdStateJson(cwd, raw),
+            get: () => state.cmdStateGet(cwd, args[2], raw),
+            update: () => state.cmdStateUpdate(cwd, args[2], args[3]),
+            patch: () => {
+                const patches = {};
+                if (args.length === 3 && typeof args[2] === 'string' && args[2].trim().startsWith('{')) {
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(args[2]);
+                    }
+                    catch (err) {
+                        error(`state patch: invalid JSON object: ${err.message}`);
+                        return;
+                    }
+                    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                        error('state patch: JSON input must be an object of field/value pairs.');
+                        return;
+                    }
+                    for (const [key, value] of Object.entries(parsed)) {
+                        if (key && value !== undefined) {
+                            // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                            patches[key] = String(value);
+                        }
+                    }
+                }
+                else {
+                    for (let i = 2; i < args.length; i += 2) {
+                        const key = args[i].replace(/^--/, '');
+                        const value = args[i + 1];
+                        if (key && value !== undefined) {
+                            patches[key] = value;
+                        }
+                    }
+                }
+                state.cmdStatePatch(cwd, patches, raw);
+            },
+            'advance-plan': () => state.cmdStateAdvancePlan(cwd, raw),
+            'record-metric': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'plan', 'duration', 'tasks', 'files']);
+                state.cmdStateRecordMetric(cwd, {
+                    phase: strArg(a, 'phase'),
+                    plan: strArg(a, 'plan'),
+                    duration: strArg(a, 'duration'),
+                    tasks: strArg(a, 'tasks'),
+                    files: strArg(a, 'files'),
+                }, raw);
+            },
+            'update-progress': () => state.cmdStateUpdateProgress(cwd, raw),
+            'add-decision': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'summary', 'summary-file', 'rationale', 'rationale-file']);
+                state.cmdStateAddDecision(cwd, {
+                    phase: strArg(a, 'phase'),
+                    summary: strArg(a, 'summary'),
+                    summary_file: strArg(a, 'summary-file'),
+                    rationale: strArg(a, 'rationale') || '',
+                    rationale_file: strArg(a, 'rationale-file'),
+                }, raw);
+            },
+            'add-blocker': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['text', 'text-file']);
+                state.cmdStateAddBlocker(cwd, { text: strArg(a, 'text'), text_file: strArg(a, 'text-file') }, raw);
+            },
+            'resolve-blocker': () => state.cmdStateResolveBlocker(cwd, strArg((0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['text']), 'text'), raw),
+            'record-session': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['stopped-at', 'resume-file']);
+                // Pass resume_file as-is (undefined when --resume-file was not provided) so
+                // cmdStateRecordSession can distinguish "caller explicitly passed a value" from
+                // "option was not supplied" and apply the template-default-only replacement guard.
+                state.cmdStateRecordSession(cwd, { stopped_at: strArg(a, 'stopped-at'), resume_file: strArg(a, 'resume-file') }, raw);
+            },
+            'begin-phase': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'name', 'plans']);
+                state.cmdStateBeginPhase(cwd, strArg(a, 'phase'), strArg(a, 'name'), parsePlans(strArg(a, 'plans')), raw);
+            },
+            'signal-waiting': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['type', 'question', 'options', 'phase']);
+                state.cmdSignalWaiting(cwd, strArg(a, 'type'), strArg(a, 'question'), strArg(a, 'options'), strArg(a, 'phase'), raw);
+            },
+            'signal-resume': () => state.cmdSignalResume(cwd, raw),
+            'planned-phase': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'name', 'plans']);
+                state.cmdStatePlannedPhase(cwd, strArg(a, 'phase'), parsePlans(strArg(a, 'plans')), raw);
+            },
+            validate: () => state.cmdStateValidate(cwd, raw),
+            sync: () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, [], ['verify']);
+                state.cmdStateSync(cwd, { verify: a['verify'] }, raw);
+            },
+            prune: () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['keep-recent'], ['dry-run']);
+                state.cmdStatePrune(cwd, { keepRecent: strArg(a, 'keep-recent') || '3', dryRun: a['dry-run'] === true }, raw);
+            },
+            // complete-phase: CJS-only — no SDK counterpart.
+            'complete-phase': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase']);
+                state.cmdStateCompletePhase(cwd, raw, strArg(a, 'phase') || args[2]);
+            },
+            'milestone-switch': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['milestone', 'name']);
+                state.cmdStateMilestoneSwitch(cwd, strArg(a, 'milestone'), strArg(a, 'name'), raw);
+            },
+        },
+    });
+}
+module.exports = {
+    routeStateCommand,
+};