@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/bin/lib/update-context.cjs

@@ -0,0 +1,209 @@
+'use strict';
+
+/**
+ * Update-context resolver (issue #498, candidate 3).
+ *
+ * Faithful Node port of the ~280-line `get_installed_version` bash step in
+ * `workflows/update.md`. That logic resolved the installed GSD version, the
+ * install scope (LOCAL / GLOBAL / UNKNOWN), the target runtime, and the config
+ * dir — entirely as inline bash inside an LLM prompt, untestable through its
+ * interface. This module makes the same cascade a pure, injected-fs function so
+ * the workflow shrinks to: call → compare → confirm → install.
+ *
+ * The fs is injected ({ exists, readFile }) so every precedence branch is
+ * testable without a live multi-runtime install. `loadUpdateContext` wires the
+ * real fs for the CLI.
+ */
+
+const path = require('node:path');
+
+// Runtime -> candidate relative dir. Order matters: it is the probe order, and
+// mirrors the RUNTIME_DIRS array the bash used (a runtime may have several
+// candidate dirs). Kept here, not derived from the installer's getDirName,
+// because update detection probes ALL historical dirs per runtime.
+const RUNTIME_DIRS = [
+  ['claude', '.claude'],
+  ['opencode', '.config/opencode'],
+  ['opencode', '.opencode'],
+  ['antigravity', '.gemini/antigravity-ide'],
+  ['antigravity', '.gemini/antigravity-cli'],
+  ['antigravity', '.gemini/antigravity'],
+  ['antigravity', '.agent'], // local Antigravity install dir (#503; bin/install.js getDirName('antigravity'))
+  ['gemini', '.gemini'],
+  ['kilo', '.config/kilo'],
+  ['kilo', '.kilo'],
+  ['codex', '.codex'],
+];
+
+const SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
+
+function expandHome(p, home) {
+  if (!p) return '';
+  return p.startsWith('~/') ? path.join(home, p.slice(2)) : p;
+}
+
+function versionFile(dir) { return path.join(dir, 'get-shit-done', 'VERSION'); }
+function markerFile(dir) { return path.join(dir, 'get-shit-done', 'workflows', 'update.md'); }
+
+// Detection: a dir "has GSD" if it carries a VERSION file or the update.md
+// workflow marker.
+function hasInstall(fs, dir) {
+  return fs.exists(versionFile(dir)) || fs.exists(markerFile(dir));
+}
+
+// Read VERSION at dir; return a trimmed semver string, or null if missing/invalid.
+function validVersionAt(fs, dir) {
+  const raw = fs.readFile(versionFile(dir));
+  if (raw == null) return null;
+  const trimmed = String(raw).trim();
+  return SEMVER_PREFIX.test(trimmed) ? trimmed : null;
+}
+
+// A version is TRUSTED only when BOTH the VERSION file and the update.md marker
+// exist (and VERSION is valid semver) — the old inline cascade required both
+// (update.md ~lines 230/241). A VERSION-only or marker-only dir is a partial
+// install, so its version is not trusted (caller treats it as 0.0.0 = reinstall).
+// One rule, applied on every path (fast path + LOCAL/GLOBAL cascade).
+function trustedVersionAt(fs, dir) {
+  return dir && fs.exists(markerFile(dir)) ? validVersionAt(fs, dir) : null;
+}
+
+// Infer the preferred runtime from preferredConfigDir config files, then env.
+function inferPreferredRuntime({ fs, env, preferredConfigDir }) {
+  if (preferredConfigDir) {
+    if (fs.exists(path.join(preferredConfigDir, 'kilo.json')) ||
+        fs.exists(path.join(preferredConfigDir, 'kilo.jsonc'))) return 'kilo';
+    if (fs.exists(path.join(preferredConfigDir, 'opencode.json')) ||
+        fs.exists(path.join(preferredConfigDir, 'opencode.jsonc'))) return 'opencode';
+    if (fs.exists(path.join(preferredConfigDir, 'config.toml'))) return 'codex';
+  }
+  if (env.CODEX_HOME) return 'codex';
+  if (env.ANTIGRAVITY_CONFIG_DIR) return 'antigravity';
+  if (env.GEMINI_CONFIG_DIR) return 'gemini';
+  if (env.KILO_CONFIG_DIR || env.KILO_CONFIG) return 'kilo';
+  if (env.OPENCODE_CONFIG_DIR || env.OPENCODE_CONFIG) return 'opencode';
+  if (env.CLAUDE_CONFIG_DIR) return 'claude';
+  return 'claude';
+}
+
+// Absolute env-override candidates, mirroring the bash ENV_RUNTIME_DIRS block.
+function envRuntimeDirs({ env, home }) {
+  const out = [];
+  const ex = (v) => expandHome(v, home);
+  if (env.CLAUDE_CONFIG_DIR) out.push(['claude', ex(env.CLAUDE_CONFIG_DIR)]);
+  if (env.ANTIGRAVITY_CONFIG_DIR) out.push(['antigravity', ex(env.ANTIGRAVITY_CONFIG_DIR)]);
+  if (env.GEMINI_CONFIG_DIR) out.push(['gemini', ex(env.GEMINI_CONFIG_DIR)]);
+  if (env.KILO_CONFIG_DIR) out.push(['kilo', ex(env.KILO_CONFIG_DIR)]);
+  else if (env.KILO_CONFIG) out.push(['kilo', path.dirname(ex(env.KILO_CONFIG))]);
+  else if (env.XDG_CONFIG_HOME) out.push(['kilo', path.join(ex(env.XDG_CONFIG_HOME), 'kilo')]);
+  if (env.OPENCODE_CONFIG_DIR) out.push(['opencode', ex(env.OPENCODE_CONFIG_DIR)]);
+  else if (env.OPENCODE_CONFIG) out.push(['opencode', path.dirname(ex(env.OPENCODE_CONFIG))]);
+  else if (env.XDG_CONFIG_HOME) out.push(['opencode', path.join(ex(env.XDG_CONFIG_HOME), 'opencode')]);
+  if (env.CODEX_HOME) out.push(['codex', ex(env.CODEX_HOME)]);
+  return out;
+}
+
+// Stable reorder: entries whose runtime === preferred first, original order kept.
+function preferFirst(entries, preferred) {
+  const pref = entries.filter(([rt]) => rt === preferred);
+  const rest = entries.filter(([rt]) => rt !== preferred);
+  return [...pref, ...rest];
+}
+
+/**
+ * Pure resolver. Returns { installedVersion, scope, runtime, gsdDir }.
+ */
+function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = '', preferredRuntime = '' }) {
+  // Expand a leading `~/` before any probe — the old inline bash ran
+  // `expand_home "$PREFERRED_CONFIG_DIR"` first, and a quoted shell path never
+  // tilde-expands, so a custom --config-dir like `~/custom-gsd` must resolve
+  // here or the fast path below silently misses the install (#498 parity).
+  preferredConfigDir = expandHome(preferredConfigDir, home);
+  const preferred = preferredRuntime || inferPreferredRuntime({ fs, env, preferredConfigDir });
+
+  // Fast path: a validated preferredConfigDir (custom --config-dir install).
+  if (preferredConfigDir && hasInstall(fs, preferredConfigDir)) {
+    const resolvedPref = path.resolve(preferredConfigDir);
+    let scope = 'GLOBAL';
+    for (const [, reldir] of RUNTIME_DIRS) {
+      if (path.resolve(cwd, reldir) === resolvedPref) { scope = 'LOCAL'; break; }
+    }
+    return {
+      installedVersion: trustedVersionAt(fs, preferredConfigDir) || '0.0.0',
+      scope,
+      runtime: preferred,
+      gsdDir: preferredConfigDir,
+    };
+  }
+
+  const orderedEnv = preferFirst(envRuntimeDirs({ env, home }), preferred);
+  const orderedRuntime = preferFirst(RUNTIME_DIRS, preferred);
+
+  // LOCAL probe (relative to cwd).
+  let localRuntime = '', localDir = '';
+  for (const [rt, reldir] of orderedRuntime) {
+    const cand = path.resolve(cwd, reldir);
+    if (hasInstall(fs, cand)) { localRuntime = rt; localDir = cand; break; }
+  }
+
+  // GLOBAL probe: absolute env candidates first, then $HOME-relative.
+  let globalRuntime = '', globalDir = '';
+  for (const [rt, absdir] of orderedEnv) {
+    if (hasInstall(fs, absdir)) { globalRuntime = rt; globalDir = path.resolve(absdir); break; }
+  }
+  if (!globalRuntime) {
+    for (const [rt, reldir] of orderedRuntime) {
+      const cand = path.resolve(home, reldir);
+      if (hasInstall(fs, cand)) { globalRuntime = rt; globalDir = cand; break; }
+    }
+  }
+
+  const localValid = trustedVersionAt(fs, localDir);
+  const isLocal = !!localValid && (!globalDir || localDir !== globalDir);
+
+  if (isLocal) {
+    return { installedVersion: localValid, scope: 'LOCAL', runtime: localRuntime, gsdDir: localDir };
+  }
+  const globalValid = trustedVersionAt(fs, globalDir);
+  if (globalValid) {
+    return { installedVersion: globalValid, scope: 'GLOBAL', runtime: globalRuntime, gsdDir: globalDir };
+  }
+  // A runtime dir was detected (VERSION or marker present) but is not a
+  // complete, valid install: keep scope/runtime/dir and report 0.0.0 so the
+  // caller re-installs (old inline `elif [ -n "$LOCAL_DIR" ]`). Apply the same
+  // same-path dedup as the trusted path so cwd===home does not misdetect as LOCAL.
+  if (localRuntime && (!globalDir || localDir !== globalDir)) {
+    return { installedVersion: '0.0.0', scope: 'LOCAL', runtime: localRuntime, gsdDir: localDir };
+  }
+  if (globalRuntime) {
+    return { installedVersion: '0.0.0', scope: 'GLOBAL', runtime: globalRuntime, gsdDir: globalDir };
+  }
+  return { installedVersion: '0.0.0', scope: 'UNKNOWN', runtime: 'claude', gsdDir: '' };
+}
+
+/**
+ * CLI wiring: resolve against the real filesystem.
+ */
+function loadUpdateContext(opts = {}) {
+  const nodeFs = require('node:fs');
+  const fs = {
+    exists: (p) => nodeFs.existsSync(p),
+    readFile: (p) => { try { return nodeFs.readFileSync(p, 'utf8'); } catch (e) { return null; } },
+  };
+  return resolveUpdateContext({
+    home: opts.home || require('node:os').homedir(),
+    cwd: opts.cwd || process.cwd(),
+    env: opts.env || process.env,
+    fs,
+    preferredConfigDir: opts.preferredConfigDir || '',
+    preferredRuntime: opts.preferredRuntime || '',
+  });
+}
+
+module.exports = {
+  resolveUpdateContext,
+  loadUpdateContext,
+  RUNTIME_DIRS,
+  inferPreferredRuntime,
+  envRuntimeDirs,
+};

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

@@ -0,0 +1,83 @@
+'use strict';
+
+const { VALIDATE_SUBCOMMANDS } = require('./command-aliases.cjs');
+const { formatGsdSlash, resolveRuntime } = require('./runtime-slash.cjs');
+const { routeCjsCommandFamily } = require('./cjs-command-router-adapter.cjs');
+const { parseNamedArgs } = require('./command-arg-projection.cjs');
+
+/**
+ * Manifest-backed validate subcommand router.
+ * Keeps gsd-tools.cjs thin while preserving existing command semantics.
+ *
+ * Phase 6: validate.consistency, validate.health, validate.agents are
+ * dispatched via executeForCjs when the SDK is available. CJS fallback
+ * retained when:
+ * - GSD_WORKSTREAM is active (workstream-scoped requests fall through to CJS).
+ * - SDK is unavailable (build not present).
+ *
+ * CJS-only subcommands:
+ * - context: complex inline logic using classifyContextUtilization and
+ *   output formatting that has no direct SDK counterpart. Remains CJS-native.
+ *
+ * SDK-only (unsupported in CJS router): none.
+ */
+function routeValidateCommand({ verify, args, cwd, raw, output: outputFn, error }) {
+  routeCjsCommandFamily({
+    args,
+    subcommands: VALIDATE_SUBCOMMANDS,
+    unsupported: {},
+    error,
+    unknownMessage: (_subcommand, available) => `Unknown validate subcommand. Available: ${available.join(', ')}`,
+    handlers: {
+      consistency: () => verify.cmdValidateConsistency(cwd, raw),
+      // Keep health on CJS for now so fix hints are rendered via runtime-slash
+      // helpers (codex expects $gsd-* command shape).
+      health: () => {
+        const repairFlag = args.includes('--repair');
+        const backfillFlag = args.includes('--backfill');
+        verify.cmdValidateHealth(cwd, { repair: repairFlag, backfill: backfillFlag }, raw);
+      },
+      agents: () => verify.cmdValidateAgents(cwd, raw),
+      // context: CJS-only — complex inline logic using classifyContextUtilization
+      // with custom output formatting that has no direct SDK counterpart.
+      context: () => {
+        const opts = parseNamedArgs(args, ['tokens-used', 'context-window']);
+        if (opts['tokens-used'] === null) {
+          error('--tokens-used <integer> is required for `validate context`');
+          return;
+        }
+        if (opts['context-window'] === null) {
+          error('--context-window <integer> is required for `validate context`');
+          return;
+        }
+        const { classifyContextUtilization, STATES } = require('./context-utilization.cjs');
+        const threadCmd = formatGsdSlash('thread', resolveRuntime(cwd));
+        const RECOMMENDATIONS = {
+          [STATES.HEALTHY]: null,
+          [STATES.WARNING]: `Context is approaching the fracture zone — consider ${threadCmd} to continue in a fresh window.`,
+          [STATES.CRITICAL]: `Reasoning quality may degrade past 70% utilization (fracture point). Run ${threadCmd} now to preserve output quality.`,
+        };
+        let classified;
+        try {
+          classified = classifyContextUtilization(Number(opts['tokens-used']), Number(opts['context-window']));
+        } catch (e) {
+          const flag = /tokensUsed/.test(e.message) ? '--tokens-used' : '--context-window';
+          error(`${flag} must be a non-negative integer (window > 0), got the values supplied`);
+          return;
+        }
+        const result = { ...classified, recommendation: RECOMMENDATIONS[classified.state] };
+        if (args.includes('--json')) {
+          outputFn(result, raw);
+        } else {
+          const lines = [`Context utilization: ${result.percent}% (${result.state})`];
+          if (result.recommendation) lines.push(result.recommendation);
+          outputFn(result, true, lines.join('\n'));
+        }
+      },
+    },
+  });
+}
+
+module.exports = {
+  routeValidateCommand,
+};

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

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * Validate Helpers — pure computation helpers and regex constants extracted from
+ * sdk/src/query/validate.ts. No I/O. No async. No filesystem operations.
+ *
+ * Issue #6 drift items (three helpers):
+ *   1. phaseVariants() — replaces parseInt-based padded/unpadded check in verify.cjs
+ *      Check 8 (W006 disk-existence and W007 roadmap-membership checks).
+ *   2. buildRoadmapPhaseVariants() — replaces raw roadmapPhases set in W007 loop.
+ *   3. buildNotStartedPhaseVariants() — replaces raw+zero-padded notStartedPhases
+ *      in W006 skip logic.
+ *
+ * Issue #26 drift items (four constants/helpers):
+ *   4. phaseDirNameRe — W005 phase directory naming regex (was inline in verify.cjs Check 6).
+ *   5. PHASE_TOKEN_FROM_DIR_RE — extracts phase token from dir name (was inline in
+ *      verify.cjs forEachArchivedPhaseToken / collectDiskPhases).
+ *   6. MILESTONE_ARCHIVE_DIR_RE — identifies milestone archive directories (was inline).
+ *   7. canonicalPlanStem() — I001 PLAN/SUMMARY stem canonicalization (was inline in Check 7).
+ *
+ * I/O adapter pattern (ADR-3524 §4): pure transforms extracted from the SDK.
+ *
+ * References:
+ *   - ADR-3524 (docs/adr/3524-cjs-sdk-hard-seam.md)
+ *   - Issue #6 (open-gsd/gsd-core)
+ *   - Issue #26 (open-gsd/gsd-core)
+ *   - PR #154 (issue #4) — generator pattern precedent
+ *   - PR #156 (issue #6) — validate.ts generator that #26 extends
+ */
+
+// ── Issue #26: regex constants (W005, W006-archived) ────────────────────────
+const phaseDirNameRe = /^\d{2,}(?:\.\d+)*-[\w-]+$/;
+const PHASE_TOKEN_FROM_DIR_RE = /^(?:[A-Z]{1,6}-)?(\d+[A-Z]?(?:\.\d+)*)(?:-|$)/i;
+const MILESTONE_ARCHIVE_DIR_RE = /^v\d+.*-phases$/i;
+
+// ── Issue #26: I001 canonicalization ────────────────────────────────────────
+function canonicalPlanStem(stem) {
+    const m = stem.match(/^(\d+[A-Z]?(?:\.\d+)*-\d+)/i);
+    return m ? m[1] : stem;
+}
+
+// ── Issue #6: phase variant helpers (W006/W007) ──────────────────────────────
+function phaseVariants(phase) {
+
+                const variants = new Set([phase]);
+                const dotIdx = phase.indexOf('.');
+                const head = dotIdx === -1 ? phase : phase.slice(0, dotIdx);
+                const tail = dotIdx === -1 ? '' : phase.slice(dotIdx);
+                const headMatch = head.match(/^(\d+)([A-Z]?)$/i);
+                if (!headMatch)
+                    return variants;
+                const numericHead = headMatch[1];
+                const letterSuffix = headMatch[2] || '';
+                variants.add(`${String(parseInt(numericHead, 10))}${letterSuffix}${tail}`);
+                variants.add(`${numericHead.padStart(2, '0')}${letterSuffix}${tail}`);
+                return variants;
+            
+}
+
+function buildRoadmapPhaseVariants(roadmapContent) {
+  const roadmapPhases = new Set();
+  const roadmapPhaseVariants = new Set();
+  const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
+  let m;
+  while ((m = phasePattern.exec(roadmapContent)) !== null) {
+    roadmapPhases.add(m[1]);
+    for (const variant of phaseVariants(m[1])) roadmapPhaseVariants.add(variant);
+  }
+  return { roadmapPhases, roadmapPhaseVariants };
+}
+
+function buildNotStartedPhaseVariants(roadmapContent) {
+  const notStartedPhases = new Set();
+  const uncheckedPattern = /-\s*\[\s\]\s*\*{0,2}Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s*]/gi;
+  let um;
+  while ((um = uncheckedPattern.exec(roadmapContent)) !== null) {
+    for (const variant of phaseVariants(um[1])) notStartedPhases.add(variant);
+  }
+  return notStartedPhases;
+}
+
+module.exports = {
+  // Issue #26 exports (W005 regex, W006-archived regex constants, I001 helper)
+  phaseDirNameRe,
+  PHASE_TOKEN_FROM_DIR_RE,
+  MILESTONE_ARCHIVE_DIR_RE,
+  canonicalPlanStem,
+  // Issue #6 exports (W006/W007 phase variant helpers)
+  phaseVariants,
+  buildRoadmapPhaseVariants,
+  buildNotStartedPhaseVariants,
+};

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

@@ -0,0 +1,40 @@
+'use strict';
+
+const { VERIFY_SUBCOMMANDS } = require('./command-aliases.cjs');
+const { routeCjsCommandFamily } = require('./cjs-command-router-adapter.cjs');
+
+/**
+ * Manifest-backed verify subcommand router.
+ * Keeps gsd-tools.cjs thin while preserving existing command semantics.
+ */
+function routeVerifyCommand({ verify, args, cwd, raw, error }) {
+  routeCjsCommandFamily({
+    args,
+    subcommands: VERIFY_SUBCOMMANDS,
+    unsupported: {},
+    error,
+    unknownMessage: (_subcommand, available) => `Unknown verify subcommand. Available: ${available.join(', ')}`,
+    handlers: {
+      'plan-structure': () => verify.cmdVerifyPlanStructure(cwd, args[2], raw),
+      'phase-completeness': () => verify.cmdVerifyPhaseCompleteness(cwd, args[2], raw),
+      references: () => verify.cmdVerifyReferences(cwd, args[2], raw),
+      commits: () => verify.cmdVerifyCommits(cwd, args.slice(2), raw),
+      artifacts: () => verify.cmdVerifyArtifacts(cwd, args[2], raw),
+      'key-links': () => verify.cmdVerifyKeyLinks(cwd, args[2], raw),
+      'schema-drift': () => {
+        const rest = args.slice(2);
+        const skipFlag = rest.includes('--skip');
+        const phaseArg = rest.find((arg) => !arg.startsWith('-'));
+        verify.cmdVerifySchemaDrift(cwd, phaseArg, skipFlag, raw);
+      },
+      // verify codebase-drift dispatches direct to CJS — drift is out-of-seam
+      // per ADR/PRD 3524 §3 / L160 (CJS-only by design). Routing through
+      // recursive dispatch would re-enter this router path.
+      'codebase-drift': () => verify.cmdVerifyCodebaseDrift(cwd, raw),
+    },
+  });
+}
+
+module.exports = {
+  routeVerifyCommand,
+};