@opengsd/gsd-core 1.3.0-rc.1 → 1.3.1

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

@@ -1,82 +0,0 @@
-'use strict';
-
-/**
- * DispatchEvent shape factory — issue #177 (ADR-0174 P1.3), extended in #178 (P1.4).
- *
- * Creates a structured event record for every Hub dispatch, used by
- * DispatchLogger to emit stderr errors and opt-in file audit trails.
- *
- * Shape:
- *   traceId:       string           — UUID v4, generated per dispatch
- *   parentTraceId: string|undefined — propagated from the caller when it is a canonical UUID v4
- *                                     (RFC 4122); invalid values are silently coerced to undefined.
- *                                     Enables a future init-composer (Phase 2) to correlate child
- *                                     dispatches to their parent via the audit file.
- *   command:       string  — the dispatched verb
- *   args?:         unknown — only present when includeArgs === true
- *   result:        { kind: 'ok' | 'UnknownCommand' | 'InvalidArgs' | 'HandlerRefusal' | 'HandlerFailure', ...payload }
- *   timestamp:     string  — ISO 8601
- */
-
-const { randomUUID } = require('crypto');
-
-/**
- * Canonical UUID v4 regex (RFC 4122).
- * - 36 characters total (32 hex + 4 hyphens)
- * - Version nibble: 4
- * - Variant bits: [89ab]
- * - Case-insensitive: accepts both upper- and lowercase hex
- *
- * Used to validate parentTraceId before propagation. traceId is always
- * generated internally by crypto.randomUUID() and is guaranteed valid.
- */
-const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-
-/**
- * Returns true only when value is a canonical UUID v4 string.
- * Any other value (non-string, wrong format, wrong version/variant) → false.
- *
- * @param {unknown} value
- * @returns {boolean}
- */
-function isValidParentTraceId(value) {
-  return typeof value === 'string' && UUID_V4_REGEX.test(value);
-}
-
-/**
- * Create a DispatchEvent.
- *
- * @param {object} opts
- * @param {string}   opts.command     - The dispatched command verb.
- * @param {unknown}  [opts.args]      - Raw args passed to the hub.
- * @param {object}   opts.result      - The HubResult returned by the hub.
- * @param {boolean}  [opts.includeArgs=false] - When true, include args in the event.
- * @param {string}   [opts.parentTraceId]     - Must be a canonical UUID v4 (RFC 4122).
- *   Invalid values (non-string, wrong format, wrong version/variant) are silently coerced
- *   to undefined — no stderr warn is emitted. This prevents correlation poisoning from
- *   unvalidated caller input while keeping the factory pure and side-effect-free.
- * @returns {object} Immutable DispatchEvent record.
- */
-function makeDispatchEvent({ command, args, result, includeArgs = false, parentTraceId }) {
-  // Validate parentTraceId against UUID v4 format before propagation.
-  // Invalid inputs (empty string, non-UUID, UUID v1, oversized, etc.) are silently
-  // coerced to undefined. Silent coercion keeps the factory pure — no side effects,
-  // no log spam on bad input, consistent with how non-string values already collapse.
-  const resolvedParentTraceId = isValidParentTraceId(parentTraceId) ? parentTraceId : undefined;
-
-  const event = {
-    traceId: randomUUID(),
-    parentTraceId: resolvedParentTraceId,
-    command: String(command),
-    result,
-    timestamp: new Date().toISOString(),
-  };
-
-  if (includeArgs && args !== undefined) {
-    event.args = args;
-  }
-
-  return Object.freeze(event);
-}
-
-module.exports = { makeDispatchEvent };

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

@@ -1,174 +0,0 @@
-'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/phase-command-router.cjs

@@ -1,191 +0,0 @@
-'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

@@ -1,79 +0,0 @@
-'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;
-    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,
-};