@opengsd/gsd-core 1.2.0-rc.1

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

@@ -0,0 +1,252 @@
+'use strict';
+
+const { STATE_SUBCOMMANDS } = require('./command-aliases.cjs');
+const { routeHubCommandFamily, cjsFallbackHandler } = require('./cjs-command-router-adapter.cjs');
+const { parseNamedArgs } = require('./command-arg-projection.cjs');
+
+/**
+ * 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).
+ */
+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', ...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: cjsFallbackHandler(
+        'state.load',
+        [],
+        args.slice(1),
+        null,
+        () => state.cmdStateLoad(cwd, raw),
+      ),
+      json: cjsFallbackHandler(
+        'state.json',
+        [],
+        args.slice(1),
+        null,
+        () => state.cmdStateJson(cwd, raw),
+      ),
+      get: cjsFallbackHandler(
+        'state.get',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => state.cmdStateGet(cwd, args[2], raw),
+      ),
+      update: cjsFallbackHandler(
+        'state.update',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => state.cmdStateUpdate(cwd, args[2], args[3]),
+      ),
+      patch: cjsFallbackHandler(
+        'state.patch',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          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}`);
+            }
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+              error('state patch: JSON input must be an object of field/value pairs.');
+            }
+            for (const [key, value] of Object.entries(parsed)) {
+              if (key && value !== undefined) {
+                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': cjsFallbackHandler(
+        'state.advance-plan',
+        [],
+        args.slice(1),
+        null,
+        () => state.cmdStateAdvancePlan(cwd, raw),
+      ),
+      'record-metric': cjsFallbackHandler(
+        'state.record-metric',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          const { phase: p, plan, duration, tasks, files } = parseNamedArgs(args, ['phase', 'plan', 'duration', 'tasks', 'files']);
+          state.cmdStateRecordMetric(cwd, { phase: p, plan, duration, tasks, files }, raw);
+        },
+      ),
+      'update-progress': cjsFallbackHandler(
+        'state.update-progress',
+        [],
+        args.slice(1),
+        null,
+        () => state.cmdStateUpdateProgress(cwd, raw),
+      ),
+      'add-decision': cjsFallbackHandler(
+        'state.add-decision',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          const { phase: p, summary, 'summary-file': summary_file, rationale, 'rationale-file': rationale_file } = parseNamedArgs(args, ['phase', 'summary', 'summary-file', 'rationale', 'rationale-file']);
+          state.cmdStateAddDecision(cwd, { phase: p, summary, summary_file, rationale: rationale || '', rationale_file }, raw);
+        },
+      ),
+      'add-blocker': cjsFallbackHandler(
+        'state.add-blocker',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          const { text, 'text-file': text_file } = parseNamedArgs(args, ['text', 'text-file']);
+          state.cmdStateAddBlocker(cwd, { text, text_file }, raw);
+        },
+      ),
+      'resolve-blocker': cjsFallbackHandler(
+        'state.resolve-blocker',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => state.cmdStateResolveBlocker(cwd, parseNamedArgs(args, ['text']).text, raw),
+      ),
+      'record-session': cjsFallbackHandler(
+        'state.record-session',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          const { 'stopped-at': stopped_at, 'resume-file': resume_file } = 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, resume_file }, raw);
+        },
+      ),
+      'begin-phase': cjsFallbackHandler(
+        'state.begin-phase',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          const { phase: p, name, plans } = parseNamedArgs(args, ['phase', 'name', 'plans']);
+          state.cmdStateBeginPhase(cwd, p, name, parsePlans(plans), raw);
+        },
+      ),
+      'signal-waiting': cjsFallbackHandler(
+        'state.signal-waiting',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          const { type, question, options, phase: p } = parseNamedArgs(args, ['type', 'question', 'options', 'phase']);
+          state.cmdSignalWaiting(cwd, type, question, options, p, raw);
+        },
+      ),
+      'signal-resume': cjsFallbackHandler(
+        'state.signal-resume',
+        [],
+        args.slice(1),
+        null,
+        () => state.cmdSignalResume(cwd, raw),
+      ),
+      'planned-phase': cjsFallbackHandler(
+        'state.planned-phase',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          const { phase: p, plans } = parseNamedArgs(args, ['phase', 'name', 'plans']);
+          state.cmdStatePlannedPhase(cwd, p, parsePlans(plans), raw);
+        },
+      ),
+      validate: cjsFallbackHandler(
+        'state.validate',
+        [],
+        args.slice(1),
+        null,
+        () => state.cmdStateValidate(cwd, raw),
+      ),
+      sync: cjsFallbackHandler(
+        'state.sync',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          const { verify } = parseNamedArgs(args, [], ['verify']);
+          state.cmdStateSync(cwd, { verify }, raw);
+        },
+      ),
+      prune: cjsFallbackHandler(
+        'state.prune',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          const { 'keep-recent': keepRecent, 'dry-run': dryRun } = parseNamedArgs(args, ['keep-recent'], ['dry-run']);
+          state.cmdStatePrune(cwd, { keepRecent: keepRecent || '3', dryRun: !!dryRun }, raw);
+        },
+      ),
+      // complete-phase: CJS-only — no SDK counterpart.
+      'complete-phase': () => {
+        const { phase: p } = parseNamedArgs(args, ['phase']);
+        state.cmdStateCompletePhase(cwd, raw, p || args[2]);
+      },
+      'milestone-switch': cjsFallbackHandler(
+        'state.milestone-switch',
+        args.slice(2),
+        args.slice(1),
+        null,
+        () => {
+          const { milestone, name } = parseNamedArgs(args, ['milestone', 'name']);
+          state.cmdStateMilestoneSwitch(cwd, milestone, name, raw);
+        },
+      ),
+    },
+  });
+}
+
+module.exports = {
+  routeStateCommand,
+};

package/get-shit-done/bin/lib/state-document.cjs

@@ -0,0 +1,263 @@
+'use strict';
+
+/**
+ * STATE.md Document Module — pure transforms for STATE.md text.
+ * This module does not read the filesystem and does not own persistence or locking.
+ */
+
+// Internal helpers
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function toFiniteNumber(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
+}
+
+function existingProgressExceedsDerived(existingProgress, derivedProgress, key) {
+    const existing = toFiniteNumber(existingProgress[key]);
+    const derived = toFiniteNumber(derivedProgress[key]);
+    return existing !== null && derived !== null && existing > derived;
+}
+
+function stateExtractField(content, fieldName) {
+    const escaped = escapeRegex(fieldName);
+    const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i');
+    const boldMatch = content.match(boldPattern);
+    if (boldMatch)
+        return boldMatch[1].trim();
+    const plainPattern = new RegExp(`^${escaped}:[ \\t]*(.+)`, 'im');
+    const plainMatch = content.match(plainPattern);
+    return plainMatch ? plainMatch[1].trim() : null;
+}
+
+function stateReplaceField(content, fieldName, newValue) {
+    const escaped = escapeRegex(fieldName);
+    const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
+    if (boldPattern.test(content)) {
+        return content.replace(boldPattern, (_match, prefix) => `${prefix}${newValue}`);
+    }
+    const plainPattern = new RegExp(`(^${escaped}:\\s*)(.*)`, 'im');
+    if (plainPattern.test(content)) {
+        return content.replace(plainPattern, (_match, prefix) => `${prefix}${newValue}`);
+    }
+    return null;
+}
+
+function stateReplaceFieldWithFallback(content, primary, fallback, value) {
+    let result = stateReplaceField(content, primary, value);
+    if (result)
+        return result;
+    if (fallback) {
+        result = stateReplaceField(content, fallback, value);
+        if (result)
+            return result;
+    }
+    return content;
+}
+
+function normalizeStateStatus(status, pausedAt) {
+    let normalizedStatus = status || 'unknown';
+    const statusLower = (status || '').toLowerCase();
+    if (statusLower.includes('paused') || statusLower.includes('stopped') || pausedAt) {
+        normalizedStatus = 'paused';
+    }
+    else if (statusLower.includes('executing') || statusLower.includes('in progress')) {
+        normalizedStatus = 'executing';
+    }
+    else if (statusLower.includes('planning') || statusLower.includes('ready to plan')) {
+        normalizedStatus = 'planning';
+    }
+    else if (statusLower.includes('discussing')) {
+        normalizedStatus = 'discussing';
+    }
+    else if (statusLower.includes('verif')) {
+        normalizedStatus = 'verifying';
+    }
+    else if (statusLower.includes('complete') || statusLower.includes('done')) {
+        normalizedStatus = 'completed';
+    }
+    else if (statusLower.includes('ready to execute')) {
+        normalizedStatus = 'executing';
+    }
+    return normalizedStatus;
+}
+
+function computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases) {
+    const hasPlanData = totalPlans !== null && totalPlans > 0 && completedPlans !== null;
+    const hasPhaseData = totalPhases !== null && totalPhases > 0 && completedPhases !== null;
+    if (!hasPlanData && !hasPhaseData)
+        return null;
+    const planFraction = hasPlanData ? completedPlans / totalPlans : 1;
+    const phaseFraction = hasPhaseData ? completedPhases / totalPhases : 1;
+    return Math.min(100, Math.round(Math.min(planFraction, phaseFraction) * 100));
+}
+
+function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
+    if (!existingProgress || typeof existingProgress !== 'object')
+        return false;
+    if (!derivedProgress || typeof derivedProgress !== 'object')
+        return false;
+    const existing = existingProgress;
+    const derived = derivedProgress;
+    return (existingProgressExceedsDerived(existing, derived, 'total_phases') ||
+        existingProgressExceedsDerived(existing, derived, 'completed_phases') ||
+        existingProgressExceedsDerived(existing, derived, 'total_plans') ||
+        existingProgressExceedsDerived(existing, derived, 'completed_plans'));
+}
+
+function normalizeProgressNumbers(progress) {
+    if (!progress || typeof progress !== 'object')
+        return progress;
+    const normalized = { ...progress };
+    for (const key of ['total_phases', 'completed_phases', 'total_plans', 'completed_plans', 'percent']) {
+        const number = toFiniteNumber(normalized[key]);
+        if (number !== null)
+            normalized[key] = number;
+    }
+    return normalized;
+}
+
+/**
+ * KNOWN_TEMPLATE_DEFAULTS — per-field table of string values that were written
+ * by a GSD handler (not by an executor / human).  A value that appears in this
+ * list is safe to overwrite on the next handler call.  Any other value was
+ * authored by the executor and must be preserved (Knuth invariant:
+ * handler-owns-transition-between-known-template-defaults).
+ *
+ * Keys must match the canonical field name as it appears in STATE.md.
+ * Comparison is case-insensitive so "None" and "none" both match.
+ *
+ * For Status, exact strings are supplemented by a pattern list
+ * (KNOWN_STATUS_PATTERNS) that matches handler-generated values whose exact
+ * text is variable (e.g. "Executing Phase 5").
+ */
+const KNOWN_TEMPLATE_DEFAULTS = {
+  'Resume File': ['None'],
+  'Status': [
+    'Ready to execute',
+    'Phase complete — ready for verification',
+    'Ready to plan',
+    'Defining requirements',
+    'Planning complete',
+    // Legacy / abbreviated handler values present in older STATE.md files
+    'Executing',
+    'In progress',
+    'Planning',
+    'Verifying',
+    'Completed',
+    'Done',
+    'Active',
+    'Paused',
+    'unknown',
+  ],
+  // Last Activity is a date field; ISO date-only strings (YYYY-MM-DD) are the
+  // handler-generated form.  We detect them by shape rather than an exhaustive
+  // list because the date changes every day.
+  // NOTE: entries here are matched by isStateTemplateDefault using the date regex
+  // in addition to exact string equality.
+  'Last Activity': [],
+  'Last activity': [],
+};
+
+/**
+ * Regex patterns that match handler-generated Status values whose text includes
+ * a variable component (e.g. phase number).  Checked after the KNOWN_TEMPLATE_DEFAULTS
+ * exact-match list in isStateTemplateDefault.
+ */
+const KNOWN_STATUS_PATTERNS = [
+  /^Executing Phase\s+\d+/i,
+  /^Planning Phase\s+\d+/i,
+  /^Phase\s+\d+\s+complete/i,
+  /^Verifying Phase\s+\d+/i,
+  /^Phase complete/i,
+];
+
+/**
+ * Returns true when the given value is a known template default for the field,
+ * meaning a GSD handler wrote it and a subsequent handler may replace it.
+ *
+ * A value is considered a template default when:
+ *   (a) it appears in KNOWN_TEMPLATE_DEFAULTS[field] (exact, case-insensitive), OR
+ *   (b) it matches the ISO date-only shape (YYYY-MM-DD) for Last Activity fields
+ *       (handlers always write bare dates; executors write narrative prose).
+ *
+ * @param {string} field  - Canonical field name (case-sensitive key lookup attempted
+ *                          first, then case-insensitive fallback).
+ * @param {string} value  - The current value extracted from STATE.md.
+ * @returns {boolean}
+ */
+function isStateTemplateDefault(field, value) {
+    if (value === null || value === undefined) return true; // absent → initial write
+    const v = String(value).trim();
+    if (v === '') return true; // blank → treat as absent
+
+    // Look up the defaults list, trying exact key first then case-insensitive.
+    let defaults = KNOWN_TEMPLATE_DEFAULTS[field];
+    if (!defaults) {
+        const fieldLower = field.toLowerCase();
+        const matchKey = Object.keys(KNOWN_TEMPLATE_DEFAULTS).find(k => k.toLowerCase() === fieldLower);
+        defaults = matchKey ? KNOWN_TEMPLATE_DEFAULTS[matchKey] : null;
+    }
+
+    if (defaults && defaults.some(d => d.toLowerCase() === v.toLowerCase())) {
+        return true;
+    }
+
+    const fieldLower = field.toLowerCase();
+
+    // Status: also check pattern list for variable handler-generated values
+    // (e.g. "Executing Phase 5", "Planning Phase 3").
+    if (fieldLower === 'status') {
+        if (KNOWN_STATUS_PATTERNS.some(p => p.test(v))) return true;
+    }
+
+    // Last Activity / Last activity: bare ISO date (YYYY-MM-DD) is handler-generated.
+    if (fieldLower === 'last activity') {
+        if (/^\d{4}-\d{2}-\d{2}$/.test(v)) return true;
+    }
+
+    return false;
+}
+
+/**
+ * Replaces a field in STATE.md content only when the existing value is a known
+ * template default (or the field is absent).  If the existing value is
+ * executor-authored, the content is returned unchanged.
+ *
+ * When `newValue` is null or undefined the function is a no-op (returns content).
+ *
+ * @param {string} content       - Full STATE.md text.
+ * @param {string} field         - Field name as it appears in STATE.md.
+ * @param {string[]} knownDefaults - The defaults list to check against (typically
+ *                                   KNOWN_TEMPLATE_DEFAULTS[field]).
+ * @param {string} newValue      - Value to write when replacement is permitted.
+ * @returns {string}             - Updated content (or original if skipped).
+ */
+function stateReplaceFieldIfTemplate(content, field, knownDefaults, newValue) {
+    if (newValue === null || newValue === undefined) return content;
+    const existing = stateExtractField(content, field);
+    // Build a temporary KNOWN_TEMPLATE_DEFAULTS-compatible lookup so we can reuse
+    // the isStateTemplateDefault logic for the provided knownDefaults array.
+    const tempField = '__tmp__';
+    const tempDefaults = { [tempField]: knownDefaults || [] };
+    // Inline check: absent/blank → always write; in list → write; else → skip.
+    if (existing === null || existing === undefined || existing.trim() === '') {
+        return stateReplaceField(content, field, newValue) || content;
+    }
+    const v = existing.trim();
+    const inList = (knownDefaults || []).some(d => d.toLowerCase() === v.toLowerCase());
+    const fieldLower = field.toLowerCase();
+    // Special-case: Status pattern list for variable handler-generated values.
+    const matchesStatusPattern = (fieldLower === 'status') && KNOWN_STATUS_PATTERNS.some(p => p.test(v));
+    // Special-case: Last Activity bare ISO date (YYYY-MM-DD) is handler-generated.
+    const isDateShape = (fieldLower === 'last activity') && /^\d{4}-\d{2}-\d{2}$/.test(v);
+    if (inList || matchesStatusPattern || isDateShape) {
+        return stateReplaceField(content, field, newValue) || content;
+    }
+    // Executor-authored — preserve.
+    return content;
+}
+
+module.exports = { stateExtractField, stateReplaceField, stateReplaceFieldWithFallback, normalizeStateStatus, computeProgressPercent, shouldPreserveExistingProgress, normalizeProgressNumbers, KNOWN_TEMPLATE_DEFAULTS, KNOWN_STATUS_PATTERNS, isStateTemplateDefault, stateReplaceFieldIfTemplate };