@opengsd/gsd-core 1.2.0 → 1.3.0

package/gsd-core/bin/lib/observability/logger.cjs

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * DispatchLogger interface + default implementation — issue #177 (ADR-0174 P1.3).
+ *
+ * Interface:
+ *   { onEvent(event: DispatchEvent): void }
+ *
+ * Default behaviour (createDefaultLogger):
+ *   1. Silent on success — no stdout/stderr when result.kind === 'ok'.
+ *   2. Structured JSON to stderr on error — one line per dispatch error.
+ *   3. Opt-in audit file — when GSD_AUDIT=1 OR config.audit.enabled===true,
+ *      appends every event (success + error) as one JSON line to
+ *      .planning/.gsd-trace.jsonl relative to `cwd`. Creates .planning/ if absent.
+ *   4. Args redaction — args omitted by default; included when GSD_AUDIT_ARGS=1.
+ *
+ * No-op logger (createNoOpLogger):
+ *   Silent on all events. Used as the Hub default when no logger is injected.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/observability/logger.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 };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const redaction_cjs_1 = require("./redaction.cjs");
+const AUDIT_FILE_NAME = '.gsd-trace.jsonl';
+const PLANNING_DIR = '.planning';
+// ─── helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Safely serialise a value to JSON, falling back to a placeholder on circular refs.
+ */
+function _safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return JSON.stringify({ _serializationError: true });
+    }
+}
+/**
+ * Determine whether the audit file should be written to.
+ */
+function _isAuditEnabled(config) {
+    if (process.env['GSD_AUDIT'] === '1')
+        return true;
+    if (config && config.audit && config.audit.enabled === true)
+        return true;
+    return false;
+}
+/**
+ * Build the redacted plain object for the audit file.
+ * Preserves the full DispatchEvent structure.
+ */
+function _toAuditRecord(event) {
+    return (0, redaction_cjs_1.redactEvent)(event);
+}
+/**
+ * Build the flattened stderr error line.
+ *
+ * Per ADR-0174 P1.3 contract: { "kind": "<variant>", "traceId": "<uuid>", ...typedPayload }
+ * The result's kind is promoted to top-level and the typed payload fields are spread in.
+ * The `result` wrapper is removed.
+ */
+function _toStderrRecord(event) {
+    const redacted = (0, redaction_cjs_1.redactEvent)(event);
+    const { result, ...eventWithoutResult } = redacted;
+    // Flatten: top-level gets kind + typed payload fields from result
+    const resultObj = result;
+    const { kind, ...typedPayload } = resultObj;
+    return Object.assign({}, eventWithoutResult, { kind }, typedPayload);
+}
+/**
+ * Append one JSON line to the audit file.
+ * Creates .planning/ directory if it does not exist.
+ *
+ * Uses synchronous fs API (crash-safe for v1 — dispatch is synchronous).
+ */
+function _appendAuditLine(cwd, event) {
+    const planningDir = node_path_1.default.join(cwd, PLANNING_DIR);
+    // Ensure the directory exists
+    if (!node_fs_1.default.existsSync(planningDir)) {
+        node_fs_1.default.mkdirSync(planningDir, { recursive: true });
+    }
+    const auditPath = node_path_1.default.join(planningDir, AUDIT_FILE_NAME);
+    node_fs_1.default.appendFileSync(auditPath, _safeStringify(event) + '\n', 'utf8');
+}
+/**
+ * Create a no-op logger. All events are silently dropped.
+ * This is the Hub's default when no logger is injected by the caller.
+ */
+function createNoOpLogger() {
+    return {
+        onEvent(_event) {
+            // intentionally empty
+        },
+    };
+}
+/**
+ * Create the default DispatchLogger.
+ */
+function createDefaultLogger({ cwd = process.cwd(), config } = {}) {
+    return {
+        /**
+         * @param event - A DispatchEvent from the Hub.
+         */
+        onEvent(event) {
+            const resultObj = event && event['result'];
+            const isOk = resultObj && resultObj['kind'] === 'ok';
+            // ── Audit file (both ok and error) ────────────────────────────────────
+            if (_isAuditEnabled(config)) {
+                try {
+                    const auditRecord = _toAuditRecord(event);
+                    _appendAuditLine(cwd, auditRecord);
+                }
+                catch (auditErr) {
+                    // Audit errors must not surface to callers
+                    process.stderr.write(_safeStringify({
+                        level: 'warn',
+                        source: 'DispatchLogger',
+                        message: 'audit file write failed: ' + String(auditErr?.message ?? auditErr),
+                    }) + '\n');
+                }
+            }
+            // ── Stderr on error ───────────────────────────────────────────────────
+            if (!isOk) {
+                try {
+                    const stderrRecord = _toStderrRecord(event);
+                    process.stderr.write(_safeStringify(stderrRecord) + '\n');
+                }
+                catch (stderrErr) {
+                    // Last-resort: we cannot throw from the logger
+                    process.stderr.write(_safeStringify({
+                        level: 'warn',
+                        source: 'DispatchLogger',
+                        message: 'stderr emit failed: ' + String(stderrErr?.message ?? stderrErr),
+                    }) + '\n');
+                }
+            }
+            // ── Silent on success (no else branch needed) ─────────────────────────
+        },
+    };
+}
+module.exports = { createDefaultLogger, createNoOpLogger };

package/{get-shit-done → gsd-core}/bin/lib/observability/redaction.cjs

@@ -1,7 +1,9 @@
-'use strict';
-
+"use strict";
 /**
- * Arg redaction policy — issue #177 (ADR-0174 P1.3).
+ * Arg redaction policy — issue #177 (ADR-457 build-at-publish: the
+ * hand-written bin/lib/observability/redaction.cjs collapsed to a TypeScript
+ * source of truth). Behaviour is preserved byte-for-behaviour from the prior
+ * hand-written .cjs; only types are added.
  *
  * Privacy default: args are OMITTED from every emitted event (both stderr
  * and file audit). Opt-in: set GSD_AUDIT_ARGS=1 to include args verbatim.
@@ -10,18 +12,17 @@
  * decisions are stateless reads of process.env at call time so that tests
  * can toggle the env var without module-level caching issues.
  */
-
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldIncludeArgs = shouldIncludeArgs;
+exports.redactEvent = redactEvent;
 /**
  * Returns true when the caller has opted in to including args in events.
  * Only GSD_AUDIT_ARGS === '1' enables inclusion; any other value (including
  * empty string, 'true', 'yes') keeps the default of omitting args.
- *
- * @returns {boolean}
  */
 function shouldIncludeArgs() {
-  return process.env.GSD_AUDIT_ARGS === '1';
+    return process.env.GSD_AUDIT_ARGS === '1';
 }
-
 /**
  * Return a redacted copy of a DispatchEvent.
  *
@@ -32,19 +33,16 @@ function shouldIncludeArgs() {
  *
  * The original event object is never mutated (it is frozen by makeDispatchEvent).
  *
- * @param {object} event - A DispatchEvent (frozen or plain).
- * @returns {object} A new plain object with the same fields, minus args when redacted.
+ * @param event - A DispatchEvent (frozen or plain).
+ * @returns A new plain object with the same fields, minus args when redacted.
  */
 function redactEvent(event) {
-  if (shouldIncludeArgs()) {
-    // Include path: return a shallow copy with args preserved if present
-    const copy = Object.assign({}, event);
-    return copy;
-  }
-
-  // Exclude path: build a copy omitting `args`
-  const { args: _dropped, ...rest } = event;
-  return rest;
+    if (shouldIncludeArgs()) {
+        // Include path: return a shallow copy with args preserved if present
+        const copy = Object.assign({}, event);
+        return copy;
+    }
+    // Exclude path: build a copy omitting `args`
+    const { args: _dropped, ...rest } = event;
+    return rest;
 }
-
-module.exports = { shouldIncludeArgs, redactEvent };

package/{get-shit-done → gsd-core}/bin/lib/package-identity.cjs

@@ -8,6 +8,8 @@ const binName = "gsd-core";
 const repoSlug = "open-gsd/gsd-core";
 const repoUrl = "https://github.com/open-gsd/gsd-core";
 const changelogRawUrl = "https://raw.githubusercontent.com/open-gsd/gsd-core/main/CHANGELOG.md";
+const cacheSlug = "opengsd-gsd-core";
+const updateCacheFileName = "gsd-update-check-opengsd-gsd-core.json";
 
 function formatManualInstall({ packageName, binName, scope, runtime } = {}) {
   const runtimeFlag = runtime ? ` --${runtime}` : '';
@@ -21,11 +23,13 @@ function manualInstallCommand(opts = {}) {
 module.exports = Object.freeze({
   packageName,
   // PACKAGE_NAME: back-compat alias for #516-era consumers. Baked here, so it
-  // survives the installed tree’s synthetic package.json (fixes the #378 undefined).
+  // survives the installed tree's synthetic package.json (fixes the #378 undefined).
   PACKAGE_NAME: packageName,
   binName,
   repoSlug,
   repoUrl,
   changelogRawUrl,
+  cacheSlug,
+  updateCacheFileName,
   manualInstallCommand,
 });

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 (open-gsd/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));
+}