@therocketcode/gsd-core 1.4.0

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

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * Manifest-backed phase subcommand router.
+ * Keeps gsd-tools.cjs thin while preserving existing command semantics.
+ *
+ * Unsupported in this router:
+ * - scaffold: routed through top-level scaffold command.
+ *
+ * CJS-only subcommands: mvp-mode (dispatched directly, before hub).
+ *
+ * #3788: dispatch is mediated by CommandRoutingHub. The public entry point
+ * and observable CLI behaviour are unchanged.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/phase-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");
+// ─── CommandRoutingHub (issue #3788, simplified in #175, typed in #176) ───────
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const commandRoutingHub = require("./command-routing-hub.cjs");
+const { createHub, ERROR_KINDS, makeInvalidArgs } = commandRoutingHub;
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routePhaseCommand({ phase, args, cwd, raw, error }) {
+    // ── Unsupported subcommands ─────────────────────────────────────────────────
+    // Resolved before dispatch so the error message stays deterministic.
+    const UNSUPPORTED = {
+        scaffold: 'phase scaffold is routed through the top-level scaffold command.',
+    };
+    const subcommand = args[1];
+    if (subcommand && UNSUPPORTED[subcommand]) {
+        error(UNSUPPORTED[subcommand]);
+        return;
+    }
+    // ── No subcommand → reject early with helpful error ────────────────────────
+    // Pre-#3788 code resolved unknown subcommands via routeCjsCommandFamily which
+    // fell through to error() when no handler matched (including undefined).
+    // Post-#3788 the hub's manifest check is skipped for falsy subcommand, so we
+    // must guard here to preserve the deterministic "Available: ..." error message.
+    if (!subcommand) {
+        const available = command_aliases_cjs_1.PHASE_SUBCOMMANDS.filter(s => !UNSUPPORTED[s]).join(', ');
+        error(`Unknown phase subcommand. Available: ${available}`);
+        return;
+    }
+    // ── 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 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;
+    }
+    // ── Build the CJS registry ──────────────────────────────────────────────────
+    // Each handler receives a ctx object from the hub and must return a HubResult.
+    const cjsRegistry = {
+        phase: {
+            'next-decimal': (_ctx) => {
+                phase.cmdPhaseNextDecimal(cwd, args[2], raw);
+                return { ok: true, data: null };
+            },
+            add: (_ctx) => {
+                let customId = null;
+                const descArgs = [];
+                for (let i = 2; i < args.length; i++) {
+                    const token = args[i];
+                    if (token === '--raw') {
+                        continue;
+                    }
+                    if (token === '--id') {
+                        const id = args[i + 1];
+                        if (!id || id.startsWith('--')) {
+                            return makeInvalidArgs('--id', '--id requires a value');
+                        }
+                        customId = id;
+                        i++;
+                    }
+                    else if (token.startsWith('--')) {
+                        return makeInvalidArgs(token, `phase add does not support ${token}`);
+                    }
+                    else {
+                        descArgs.push(token);
+                    }
+                }
+                phase.cmdPhaseAdd(cwd, descArgs.join(' '), raw, customId);
+                return { ok: true, data: null };
+            },
+            'add-batch': (_ctx) => {
+                const descFlagIdx = args.indexOf('--descriptions');
+                let descriptions;
+                if (descFlagIdx !== -1) {
+                    const rawDescriptions = args[descFlagIdx + 1];
+                    if (!rawDescriptions || rawDescriptions.startsWith('--')) {
+                        return makeInvalidArgs('--descriptions', '--descriptions must be a JSON array');
+                    }
+                    try {
+                        descriptions = JSON.parse(rawDescriptions);
+                    }
+                    catch {
+                        return makeInvalidArgs('--descriptions', '--descriptions must be a JSON array');
+                    }
+                    if (!Array.isArray(descriptions)) {
+                        return makeInvalidArgs('--descriptions', '--descriptions must be a JSON array');
+                    }
+                }
+                else {
+                    descriptions = args.slice(2).filter(a => a !== '--raw');
+                }
+                phase.cmdPhaseAddBatch(cwd, descriptions, raw);
+                return { ok: true, data: null };
+            },
+            insert: (_ctx) => {
+                if (args.includes('--dry-run')) {
+                    return makeInvalidArgs('--dry-run', 'phase insert does not support --dry-run');
+                }
+                phase.cmdPhaseInsert(cwd, args[2], args.slice(3).join(' '), raw);
+                return { ok: true, data: null };
+            },
+            remove: (_ctx) => {
+                const removeArgs = args.slice(2).filter(token => token !== '--raw');
+                let forceFlag = false;
+                const positional = [];
+                for (const token of removeArgs) {
+                    if (token === '--force') {
+                        forceFlag = true;
+                        continue;
+                    }
+                    if (token.startsWith('--')) {
+                        return makeInvalidArgs(token, `phase remove does not support ${token}`);
+                    }
+                    positional.push(token);
+                }
+                if (positional.length !== 1) {
+                    return makeInvalidArgs('<phase-number>', 'phase remove accepts exactly one phase number');
+                }
+                phase.cmdPhaseRemove(cwd, positional[0], { force: forceFlag }, raw);
+                return { ok: true, data: null };
+            },
+            complete: (_ctx) => {
+                phase.cmdPhaseComplete(cwd, args[2], raw);
+                return { ok: true, data: null };
+            },
+        },
+    };
+    // ── Build manifest (available subcommands for UnknownCommand detection) ─────
+    // `availableSubcommands` is what the error message shows. It excludes
+    // unsupported commands (already handled above) but does NOT include 'mvp-mode'
+    // because it was absent from PHASE_SUBCOMMANDS in the original and was not
+    // shown in the "Available:" list there either.
+    //
+    // `manifestSubcommands` is the full routing set for the hub — it includes
+    // 'mvp-mode' (which the original code routed via a handler even without a
+    // manifest entry) so the hub's UnknownCommand check passes for it.
+    const availableSubcommands = command_aliases_cjs_1.PHASE_SUBCOMMANDS.filter(s => !UNSUPPORTED[s]);
+    const manifestSubcommands = ['mvp-mode', ...availableSubcommands];
+    const manifest = { phase: manifestSubcommands };
+    // ── Construct hub ──────────────────────────────────────────────────────────
+    // #175: Hub is CJS-only — no mode param, no sdkLoader.
+    const hub = createHub({ cjsRegistry, manifest });
+    // ── Dispatch ────────────────────────────────────────────────────────────────
+    const result = hub.dispatch({
+        family: 'phase',
+        subcommand,
+        args: args.slice(2),
+        cwd,
+        raw,
+    });
+    // ── 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.kind === ERROR_KINDS.UnknownCommand) {
+            const available = availableSubcommands.join(', ');
+            error(`Unknown phase subcommand. Available: ${available}`);
+            return;
+        }
+        if (result.kind === ERROR_KINDS.InvalidArgs || result.kind === ERROR_KINDS.HandlerRefusal) {
+            // #176: typed payload — reason holds the human-readable message
+            error(result.reason);
+            return;
+        }
+        // HandlerFailure: message field
+        error(result.message);
+        return;
+    }
+}
+module.exports = {
+    routePhaseCommand,
+};

package/gsd-core/bin/lib/phase-lifecycle.cjs

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Phase Lifecycle Pure Helpers — pure-computation functions extracted from
+ * the phase-lifecycle SDK handler (ADR-457 build-at-publish: the hand-written
+ * bin/lib/phase-lifecycle.cjs collapsed to a TypeScript source of truth).
+ * Behaviour is preserved byte-for-behaviour from the prior hand-written .cjs;
+ * only types are added.
+ *
+ * I/O adapter pattern (ADR-3524 Section 4): each side supplies its own I/O
+ * (sync readFileSync for CJS, async readFile for SDK); the pure computation
+ * logic is shared via this generated artifact.
+ *
+ * Scope:
+ *   - deriveProgressFromRoadmap(roadmapContent): count Complete rows => idempotent
+ *   - clampPercent(completed, total): percent with 100 ceiling
+ *
+ * These two functions are the root-cause fix for issue #4.
+ *
+ * References:
+ *   - ADR-3524 (docs/adr/3524-cjs-sdk-hard-seam.md)
+ *   - Issue #4 (TheRocketCodeMX/gsd-core)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveProgressFromRoadmap = deriveProgressFromRoadmap;
+exports.clampPercent = clampPercent;
+/**
+ * Derive completed_phases, total_phases, and total_plans from ROADMAP content.
+ * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ */
+function deriveProgressFromRoadmap(roadmapContent) {
+    let completedPhases = null;
+    let totalPhases = null;
+    let totalPlans = null;
+    try {
+        // Count Complete rows in the progress table (Status column = "Complete").
+        // Pattern: row where the phase cell starts with a digit (data row, not header),
+        // followed by any cell content, then a "Complete" status cell.
+        // Handles both short form ("| 4. |") and long form ("| 01. Foundation |").
+        // See phase-lifecycle.ts ~line 1655 for the original SDK pattern.
+        const tableCompletePattern = /\|\s*\d+[^|]*\|\s*[^|]*\|\s*Complete\s*\|/gi;
+        const completeMatches = roadmapContent.match(tableCompletePattern);
+        completedPhases = completeMatches ? completeMatches.length : null;
+        // Count total phase rows in the progress table.
+        // Identify the table by looking for Phase|...|Status|...|Completed header.
+        const progressTableMatch = roadmapContent.match(/\|\s*Phase\s*\|[^|]*\|[^|]*Status[^|]*\|[^|]*Completed[^|]*\|[\s\S]*?(?=\n\n|\n##|$)/i);
+        if (progressTableMatch) {
+            const tableText = progressTableMatch[0];
+            // Count data rows (rows starting with pipe then a phase number)
+            const dataRowPattern = /^\|\s*\d+/gm;
+            const dataRows = tableText.match(dataRowPattern);
+            totalPhases = dataRows ? dataRows.length : null;
+        }
+        // Sum plan counts from M/N columns in progress table
+        let totalPlansSum = 0;
+        const planCellPattern = /\|\s*\d+[^|]*\|\s*(\d+)\/(\d+)\s*\|/gi;
+        let pm;
+        while ((pm = planCellPattern.exec(roadmapContent)) !== null) {
+            totalPlansSum += parseInt(pm[2], 10);
+        }
+        if (totalPlansSum > 0)
+            totalPlans = totalPlansSum;
+    }
+    catch { /* intentionally empty — fall through to existing values */ }
+    return { completedPhases, totalPhases, totalPlans };
+}
+/**
+ * Compute progress percent clamped to 100.
+ * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ */
+function clampPercent(completed, total) {
+    if (!total || total <= 0)
+        return 0;
+    return Math.min(100, Math.round((completed / total) * 100));
+}