@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/bin/lib/observability/logger.cjs

@@ -0,0 +1,174 @@
+'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.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { redactEvent, shouldIncludeArgs } = 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.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function _safeStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return JSON.stringify({ _serializationError: true });
+  }
+}
+
+/**
+ * Determine whether the audit file should be written to.
+ *
+ * @param {{ audit?: { enabled?: boolean } } | undefined} config
+ * @returns {boolean}
+ */
+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.
+ *
+ * @param {object} event - DispatchEvent
+ * @returns {object}
+ */
+function _toAuditRecord(event) {
+  return 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.
+ *
+ * @param {object} event - DispatchEvent with an error result
+ * @returns {object}
+ */
+function _toStderrRecord(event) {
+  const redacted = redactEvent(event);
+  const { result, ...eventWithoutResult } = redacted;
+  // Flatten: top-level gets kind + typed payload fields from result
+  const { kind, ...typedPayload } = result;
+  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).
+ *
+ * @param {string} cwd - Project root directory.
+ * @param {object} event - Redacted DispatchEvent.
+ */
+function _appendAuditLine(cwd, event) {
+  const planningDir = path.join(cwd, PLANNING_DIR);
+  // Ensure the directory exists
+  if (!fs.existsSync(planningDir)) {
+    fs.mkdirSync(planningDir, { recursive: true });
+  }
+  const auditPath = path.join(planningDir, AUDIT_FILE_NAME);
+  fs.appendFileSync(auditPath, _safeStringify(event) + '\n', 'utf8');
+}
+
+// ─── Public factories ─────────────────────────────────────────────────────────
+
+/**
+ * Create a no-op logger. All events are silently dropped.
+ * This is the Hub's default when no logger is injected by the caller.
+ *
+ * @returns {{ onEvent(event: object): void }}
+ */
+function createNoOpLogger() {
+  return {
+    onEvent(_event) {
+      // intentionally empty
+    },
+  };
+}
+
+/**
+ * Create the default DispatchLogger.
+ *
+ * @param {object} [opts]
+ * @param {string}  [opts.cwd=process.cwd()] - Project root; audit file is written relative to this.
+ * @param {object}  [opts.config]             - GSD config object. config.audit.enabled triggers audit.
+ * @returns {{ onEvent(event: object): void }}
+ */
+function createDefaultLogger({ cwd = process.cwd(), config } = {}) {
+  return {
+    /**
+     * @param {object} event - A DispatchEvent from the Hub.
+     */
+    onEvent(event) {
+      const isOk = event && event.result && event.result.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 && 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 && stderrErr.message || stderrErr),
+            }) + '\n'
+          );
+        }
+      }
+      // ── Silent on success (no else branch needed) ─────────────────────────
+    },
+  };
+}
+
+module.exports = { createDefaultLogger, createNoOpLogger };

package/get-shit-done/bin/lib/observability/redaction.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+/**
+ * Arg redaction policy — issue #177 (ADR-0174 P1.3).
+ *
+ * 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.
+ *
+ * This module is deliberately simple and has no side effects — redaction
+ * decisions are stateless reads of process.env at call time so that tests
+ * can toggle the env var without module-level caching issues.
+ */
+
+/**
+ * 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 a redacted copy of a DispatchEvent.
+ *
+ * If args should be omitted (default), strips the `args` field entirely.
+ * If args should be included (GSD_AUDIT_ARGS=1), passes the event through
+ * unchanged (args were already set by makeDispatchEvent with includeArgs:true,
+ * or absent — in which case they stay absent).
+ *
+ * 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.
+ */
+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;
+}
+
+module.exports = { shouldIncludeArgs, redactEvent };

package/get-shit-done/bin/lib/package-identity.cjs

@@ -0,0 +1,31 @@
+// @generated by scripts/generate-package-identity.cjs from package.json — DO NOT EDIT.
+// Single source for GSD package coordinates (issue #498). Regenerate with:
+//   node scripts/generate-package-identity.cjs
+'use strict';
+
+const packageName = "@opengsd/gsd-core";
+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";
+
+function formatManualInstall({ packageName, binName, scope, runtime } = {}) {
+  const runtimeFlag = runtime ? ` --${runtime}` : '';
+  return `npx -y --package=${packageName}@latest -- ${binName}${runtimeFlag} --${scope}`;
+}
+
+function manualInstallCommand(opts = {}) {
+  return formatManualInstall({ packageName, binName, scope: opts.scope, runtime: opts.runtime });
+}
+
+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).
+  PACKAGE_NAME: packageName,
+  binName,
+  repoSlug,
+  repoUrl,
+  changelogRawUrl,
+  manualInstallCommand,
+});

package/get-shit-done/bin/lib/phase-command-router.cjs

@@ -0,0 +1,191 @@
+'use strict';
+
+const { PHASE_SUBCOMMANDS } = require('./command-aliases.cjs');
+
+// ─── CommandRoutingHub (issue #3788, simplified in #175, typed in #176) ───────
+const { createHub, ERROR_KINDS, makeInvalidArgs } = require('./command-routing-hub.cjs');
+
+/**
+ * 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.
+ */
+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 = 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 = 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/get-shit-done/bin/lib/phase-lifecycle.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * Phase Lifecycle Pure Helpers — pure-computation functions extracted from
+ * the phase-lifecycle SDK handler.
+ *
+ * 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)
+ */
+
+/**
+ * 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;
+    // eslint-disable-next-line no-cond-assign
+    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));
+}
+
+module.exports = {
+  deriveProgressFromRoadmap,
+  clampPercent,
+};