@opengsd/get-shit-done-redux 1.0.0

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

@@ -0,0 +1,97 @@
+'use strict';
+
+const { PHASES_SUBCOMMANDS } = require('./command-aliases.generated.cjs');
+const { routeCjsCommandFamily } = require('./cjs-command-router-adapter.cjs');
+const { output } = require('./core.cjs');
+
+// ─── SDK bridge (Phase 6) — shared loader via cjs-sdk-bridge.cjs ──────────────
+const { tryLoadSdk, getExecuteForCjs } = require('./cjs-sdk-bridge.cjs');
+
+/**
+ * Manifest-backed phases subcommand router.
+ * Keeps gsd-tools.cjs thin while preserving current CJS semantics.
+ *
+ * Phase 6: phases.list and phases.clear 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).
+ *
+ * SDK-only (not in CJS router, treated as unknown):
+ * - archive: `phases archive` is SDK-only (`phases.archive` handler in SDK
+ *   query registry). CJS `gsd-tools phases` intentionally supports list/clear only.
+ *   `archive` is excluded from the subcommands list so it falls through to the
+ *   "unknown subcommand" error path (matching pre-Phase 6 behavior).
+ *
+ * CJS-only subcommands: none.
+ */
+function routePhasesCommand({ phase, milestone, args, cwd, raw, error }) {
+  const activeWorkstream = process.env.GSD_WORKSTREAM;
+  const sdkAvailable = !activeWorkstream && tryLoadSdk();
+
+  function sdkHandler(registryCommand, registryArgs, legacyArgs, cjsFallback) {
+    if (!sdkAvailable) return cjsFallback;
+    return () => {
+      const result = getExecuteForCjs()({
+        registryCommand,
+        registryArgs,
+        legacyCommand: 'phases',
+        legacyArgs,
+        // #3631: under --raw, request mode:'raw' so the bridge runs the SDK's
+        // raw projection (formatQueryRawOutput) and returns the scalar string
+        // CJS callers used to print. We then bypass output()'s JSON-stringify
+        // path by passing rawValue (the third positional). With mode:'json',
+        // output() emits the JSON IR as before.
+        mode: raw ? 'raw' : 'json',
+        projectDir: cwd,
+      });
+      if (!result.ok) {
+        error(result.errorDetails && result.errorDetails.message
+          ? result.errorDetails.message
+          : `phases ${registryCommand} failed (${result.errorKind})`);
+        return;
+      }
+      if (raw) {
+        output(null, true, typeof result.data === 'string' ? result.data : String(result.data ?? ''));
+      } else {
+        output(result.data);
+      }
+    };
+  }
+
+  routeCjsCommandFamily({
+    args,
+    // Exclude 'archive' — it's SDK-only and not supported in CJS. Excluding
+    // from this list causes it to hit the unknownMessage path, preserving the
+    // pre-Phase 6 error message for callers that pass 'archive'.
+    subcommands: PHASES_SUBCOMMANDS.filter((s) => s !== 'archive'),
+    error,
+    unknownMessage: (_subcommand, available) => `Unknown phases subcommand. Available: ${available.join(', ')}`,
+    handlers: {
+      list: sdkHandler(
+        'phases.list',
+        args.slice(2),
+        args.slice(1),
+        () => {
+          const typeIndex = args.indexOf('--type');
+          const phaseIndex = args.indexOf('--phase');
+          const options = {
+            type: typeIndex !== -1 ? args[typeIndex + 1] : null,
+            phase: phaseIndex !== -1 ? args[phaseIndex + 1] : null,
+            includeArchived: args.includes('--include-archived'),
+          };
+          phase.cmdPhasesList(cwd, options, raw);
+        },
+      ),
+      clear: sdkHandler(
+        'phases.clear',
+        args.slice(2),
+        args.slice(1),
+        () => milestone.cmdPhasesClear(cwd, raw, args.slice(2)),
+      ),
+    },
+  });
+}
+
+module.exports = {
+  routePhasesCommand,
+};

package/get-shit-done/bin/lib/plan-scan.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * Plan Scan Module — CJS adapter.
+ *
+ * The implementation is generated from sdk/src/query/plan-scan.ts and
+ * lives in plan-scan.generated.cjs. This file is a thin re-export so
+ * that existing call sites (state.cjs, roadmap.cjs, init.cjs,
+ * workstream-inventory.cjs, and tests) can continue to require('./plan-scan')
+ * unchanged.
+ *
+ * Exports (from generated file):
+ *   - scanPhasePlans(phaseDir) — canonical phase-plan scanner
+ *   - isRootPlanFile(fileName) — extended filter including /PLAN/i slug layouts
+ *   - isNestedPlanFile(fileName) — nested plans/ subdir filter
+ *   - isRootSummaryFile(fileName) — flat summary file filter
+ *   - isNestedSummaryFile(fileName) — nested summary file filter
+ *
+ * The isRootPlanFile helper uses /PLAN/i to match the extended slug layout
+ * (e.g. 5-PLAN-01-setup-database.md) in addition to bare and canonical forms.
+ * This was the fix for bug #3128 (roadmap.cjs plan-count regression).
+ *
+ * Regenerate: cd sdk && npm run gen:plan-scan
+ */
+
+module.exports = require('./plan-scan.generated.cjs');

package/get-shit-done/bin/lib/plan-scan.generated.cjs

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ *
+ * Source: sdk/src/query/plan-scan.ts
+ * Regenerate: cd sdk && npm run gen:plan-scan
+ *
+ * Plan Scan Module — detects plan and summary files in a phase directory.
+ * Supports both flat (pre-#3139) and nested (post-#3139) layouts.
+ */
+
+const { existsSync, readdirSync } = require('node:fs');
+const { join } = require('node:path');
+
+// Excluded derivative files
+const PLAN_OUTLINE_RE = /-OUTLINE\.md$/i;
+const PLAN_PRE_BOUNCE_RE = /\.pre-bounce\.md$/i;
+
+function isRootPlanFile(fileName) {
+    if (PLAN_OUTLINE_RE.test(fileName))
+        return false;
+    if (PLAN_PRE_BOUNCE_RE.test(fileName))
+        return false;
+    if (fileName.endsWith('-PLAN.md') || fileName === 'PLAN.md')
+        return true;
+    return /\.md$/i.test(fileName) && /PLAN/i.test(fileName);
+}
+
+function isNestedPlanFile(fileName) {
+    if (PLAN_OUTLINE_RE.test(fileName))
+        return false;
+    if (PLAN_PRE_BOUNCE_RE.test(fileName))
+        return false;
+    return /^PLAN-\d+.*\.md$/i.test(fileName) || /-PLAN-\d+.*\.md$/i.test(fileName);
+}
+
+function isRootSummaryFile(fileName) {
+    return fileName.endsWith('-SUMMARY.md') || fileName === 'SUMMARY.md';
+}
+
+function isNestedSummaryFile(fileName) {
+    return /^SUMMARY-\d+.*\.md$/i.test(fileName) || /-SUMMARY-\d+.*\.md$/i.test(fileName);
+}
+
+function scanPhasePlans(phaseDir) {
+    let rootFiles;
+    try {
+        rootFiles = readdirSync(phaseDir);
+    }
+    catch {
+        return {
+            planCount: 0,
+            summaryCount: 0,
+            completed: false,
+            hasNestedPlans: false,
+            planFiles: [],
+            summaryFiles: [],
+        };
+    }
+    const rootPlanFiles = rootFiles.filter(isRootPlanFile);
+    const rootSummaryFiles = rootFiles.filter(isRootSummaryFile);
+    let nestedPlanFiles = [];
+    let nestedSummaryFiles = [];
+    let hasNestedPlans = false;
+    const nestedDir = join(phaseDir, 'plans');
+    if (existsSync(nestedDir)) {
+        try {
+            const nestedFiles = readdirSync(nestedDir);
+            nestedPlanFiles = nestedFiles.filter(isNestedPlanFile);
+            nestedSummaryFiles = nestedFiles.filter(isNestedSummaryFile);
+            hasNestedPlans = nestedPlanFiles.length > 0;
+        }
+        catch { /* ignore unreadable nested layout */ }
+    }
+    const planFiles = rootPlanFiles.concat(nestedPlanFiles);
+    const summaryFiles = rootSummaryFiles.concat(nestedSummaryFiles);
+    const planCount = planFiles.length;
+    const summaryCount = summaryFiles.length;
+    return {
+        planCount,
+        summaryCount,
+        completed: planCount > 0 && summaryCount >= planCount,
+        hasNestedPlans,
+        planFiles,
+        summaryFiles,
+    };
+}
+
+// CJS callers do: const scanPhasePlans = require('./plan-scan.cjs')
+// and also destructure named exports — support both call styles.
+module.exports = scanPhasePlans;
+module.exports.scanPhasePlans = scanPhasePlans;
+module.exports.isRootPlanFile = isRootPlanFile;
+module.exports.isNestedPlanFile = isNestedPlanFile;
+module.exports.isRootSummaryFile = isRootSummaryFile;
+module.exports.isNestedSummaryFile = isNestedSummaryFile;

package/get-shit-done/bin/lib/planning-workspace.cjs

@@ -0,0 +1,415 @@
+/**
+ * Planning Workspace — .planning path resolution + active workstream routing.
+ *
+ * This module owns the planning workspace seam:
+ * - planningDir/planningRoot/planningPaths
+ * - active workstream pointer policy (session-scoped > shared)
+ * - pointer storage adapters (session/shared/memory)
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { probeTty, platformWriteSync, platformReadSync, platformEnsureDir } = require('./shell-command-projection.cjs');
+const { isValidActiveWorkstreamName } = require('./workstream-name-policy.cjs');
+
+const WORKSTREAM_SESSION_ENV_KEYS = [
+  'GSD_SESSION_KEY',
+  'CODEX_THREAD_ID',
+  'CLAUDE_SESSION_ID',
+  'CLAUDE_CODE_SSE_PORT',
+  'OPENCODE_SESSION_ID',
+  'GEMINI_SESSION_ID',
+  'CURSOR_SESSION_ID',
+  'WINDSURF_SESSION_ID',
+  'TERM_SESSION_ID',
+  'WT_SESSION',
+  'TMUX_PANE',
+  'ZELLIJ_SESSION_NAME',
+];
+
+let cachedControllingTtyToken = null;
+let didProbeControllingTtyToken = false;
+
+// Track .planning/.lock files held by this process so they can be removed on exit.
+const _heldPlanningLocks = new Set();
+process.on('exit', () => {
+  for (const lockPath of _heldPlanningLocks) {
+    try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
+  }
+});
+
+// Transient errno codes that indicate a temporary filesystem condition under
+// concurrent O_EXCL races — Docker overlay-fs (ENOENT/EINVAL/EIO), NFS
+// (ESTALE), and OS-level interrupt/retry signals (EAGAIN/EINTR).  These are
+// recoverable; withPlanningLock retries instead of propagating them.
+// Truly fatal codes (EMFILE, ENOSPC, EROFS, EACCES) are NOT in this set and
+// will still throw immediately.
+const PLANNING_LOCK_RETRY_ERRNOS = new Set([
+  'EPERM',   // Windows / macOS AV scanner holds the file open during delete
+  'EBUSY',   // Windows: file in use by another process
+  'EAGAIN',  // POSIX: resource temporarily unavailable
+  'EINTR',   // POSIX: syscall interrupted by signal
+  'EINVAL',  // Docker overlay-fs: transient during concurrent O_EXCL creation
+  'EIO',     // Docker overlay-fs / NFS: transient I/O error
+  'ENOENT',  // Docker overlay-fs: parent dir transiently missing during race
+  'ESTALE',  // NFS: stale file handle (self-resolves on retry)
+]);
+
+function planningDir(cwd, ws, project) {
+  if (project === undefined) project = process.env.GSD_PROJECT || null;
+  if (ws === undefined) ws = process.env.GSD_WORKSTREAM || null;
+
+  // Reject path separators and traversal components in project/workstream names
+  const BAD_SEGMENT = /[/\\]|\.\./;
+  if (project && BAD_SEGMENT.test(project)) {
+    throw new Error(`GSD_PROJECT contains invalid path characters: ${project}`);
+  }
+  if (ws && BAD_SEGMENT.test(ws)) {
+    throw new Error(`GSD_WORKSTREAM contains invalid path characters: ${ws}`);
+  }
+
+  let base = path.join(cwd, '.planning');
+  if (project) base = path.join(base, project);
+  if (ws) base = path.join(base, 'workstreams', ws);
+  return base;
+}
+
+function planningRoot(cwd) {
+  return path.join(cwd, '.planning');
+}
+
+function planningPaths(cwd, ws) {
+  const base = planningDir(cwd, ws);
+  return {
+    planning: base,
+    state: path.join(base, 'STATE.md'),
+    roadmap: path.join(base, 'ROADMAP.md'),
+    project: path.join(base, 'PROJECT.md'),
+    config: path.join(base, 'config.json'),
+    phases: path.join(base, 'phases'),
+    requirements: path.join(base, 'REQUIREMENTS.md'),
+  };
+}
+
+function sanitizeWorkstreamSessionToken(value) {
+  if (value === null || value === undefined) return null;
+  const token = String(value).trim().replace(/[^a-zA-Z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
+  return token ? token.slice(0, 160) : null;
+}
+
+function probeControllingTtyToken() {
+  if (didProbeControllingTtyToken) return cachedControllingTtyToken;
+  didProbeControllingTtyToken = true;
+
+  // `tty` reads stdin. When stdin is already non-interactive, spawning it only
+  // adds avoidable failures on the routing hot path and cannot reveal a stable token.
+  if (!(process.stdin && process.stdin.isTTY)) {
+    return cachedControllingTtyToken;
+  }
+
+  const ttyPath = probeTty();
+  if (ttyPath) {
+    const token = sanitizeWorkstreamSessionToken(ttyPath.replace(/^\/dev\//, ''));
+    if (token) cachedControllingTtyToken = `tty-${token}`;
+  }
+
+  return cachedControllingTtyToken;
+}
+
+function getControllingTtyToken() {
+  for (const envKey of ['TTY', 'SSH_TTY']) {
+    const token = sanitizeWorkstreamSessionToken(process.env[envKey]);
+    if (token) return `tty-${token.replace(/^dev_/, '')}`;
+  }
+
+  return probeControllingTtyToken();
+}
+
+function getWorkstreamSessionKey() {
+  for (const envKey of WORKSTREAM_SESSION_ENV_KEYS) {
+    const raw = process.env[envKey];
+    const token = sanitizeWorkstreamSessionToken(raw);
+    if (token) return `${envKey.toLowerCase().replace(/[^a-z0-9]+/g, '-')}-${token}`;
+  }
+
+  return getControllingTtyToken();
+}
+
+function getSessionScopedWorkstreamFile(cwd, fixedSessionKey) {
+  const sessionKey = fixedSessionKey || getWorkstreamSessionKey();
+  if (!sessionKey) return null;
+
+  // Use realpathSync.native so the hash is derived from the canonical filesystem
+  // path. On Windows, path.resolve returns whatever case the caller supplied,
+  // while realpathSync.native returns the case the OS recorded — they differ on
+  // case-insensitive NTFS, producing different hashes and different tmpdir slots.
+  // Fall back to path.resolve when the directory does not yet exist.
+  let planningAbs;
+  try {
+    planningAbs = fs.realpathSync.native(planningRoot(cwd));
+  } catch {
+    planningAbs = path.resolve(planningRoot(cwd));
+  }
+  const projectId = crypto
+    .createHash('sha1')
+    .update(planningAbs)
+    .digest('hex')
+    .slice(0, 16);
+
+  const dirPath = path.join(os.tmpdir(), 'gsd-workstream-sessions', projectId);
+  return {
+    sessionKey,
+    dirPath,
+    filePath: path.join(dirPath, sessionKey),
+  };
+}
+
+function createSharedPointerAdapter(cwd) {
+  const filePath = path.join(planningRoot(cwd), 'active-workstream');
+  return {
+    read() {
+      const raw = platformReadSync(filePath);
+      return raw ? raw.trim() || null : null;
+    },
+    write(name) {
+      platformWriteSync(filePath, name + '\n');
+    },
+    clear() {
+      try { fs.unlinkSync(filePath); } catch {}
+    },
+  };
+}
+
+function createSessionScopedPointerAdapter(cwd, fixedSessionKey) {
+  const scoped = getSessionScopedWorkstreamFile(cwd, fixedSessionKey);
+  if (!scoped) return null;
+
+  return {
+    read() {
+      const raw = platformReadSync(scoped.filePath);
+      return raw ? raw.trim() || null : null;
+    },
+    write(name) {
+      platformEnsureDir(scoped.dirPath);
+      platformWriteSync(scoped.filePath, name + '\n');
+    },
+    clear() {
+      try { fs.unlinkSync(scoped.filePath); } catch {}
+      try {
+        const remaining = fs.readdirSync(scoped.dirPath);
+        if (remaining.length === 0) {
+          fs.rmdirSync(scoped.dirPath);
+        }
+      } catch {}
+    },
+  };
+}
+
+function createMemoryPointerAdapter(initialName = null) {
+  let value = initialName;
+  return {
+    read() {
+      return value;
+    },
+    write(name) {
+      value = name;
+    },
+    clear() {
+      value = null;
+    },
+  };
+}
+
+function pickActiveWorkstreamAdapter(cwd, opts = {}) {
+  if (opts.activeWorkstreamAdapter) {
+    return opts.activeWorkstreamAdapter;
+  }
+
+  const sessionKey = getWorkstreamSessionKey();
+  if (sessionKey) {
+    if (opts.activeWorkstreamAdapters && opts.activeWorkstreamAdapters.session) {
+      return opts.activeWorkstreamAdapters.session;
+    }
+    return createSessionScopedPointerAdapter(cwd, sessionKey);
+  }
+
+  if (opts.activeWorkstreamAdapters && opts.activeWorkstreamAdapters.shared) {
+    return opts.activeWorkstreamAdapters.shared;
+  }
+  return createSharedPointerAdapter(cwd);
+}
+
+function validateWorkstreamName(name) {
+  return isValidActiveWorkstreamName(name);
+}
+
+function withPlanningLock(cwd, fn) {
+  const lockPath = path.join(planningDir(cwd), '.lock');
+  const lockTimeout = 10000; // 10 seconds
+  const start = Date.now();
+
+  // Ensure .planning/ exists
+  try { platformEnsureDir(planningDir(cwd)); } catch { /* ok */ }
+
+  function runWithHeldLock() {
+    // Atomic create — fails if file exists
+    fs.writeFileSync(lockPath, JSON.stringify({
+      pid: process.pid,
+      cwd,
+      acquired: new Date().toISOString(),
+    }), { flag: 'wx' });
+
+    _heldPlanningLocks.add(lockPath);
+
+    // Lock acquired — run the function
+    try {
+      return fn();
+    } finally {
+      _heldPlanningLocks.delete(lockPath);
+      try { fs.unlinkSync(lockPath); } catch { /* already released */ }
+    }
+  }
+
+  while (Date.now() - start < lockTimeout) {
+    try {
+      return runWithHeldLock();
+    } catch (err) {
+      // Transient filesystem errors (Docker overlay-fs, NFS, OS signals, AV scanners)
+      // are recoverable — wait and retry rather than propagating.
+      // See PLANNING_LOCK_RETRY_ERRNOS for the full list and rationale.
+      if (PLANNING_LOCK_RETRY_ERRNOS.has(err.code)) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+        continue;
+      }
+      if (err.code === 'EEXIST') {
+        // Lock exists — check if stale (>30s old)
+        try {
+          const stat = fs.statSync(lockPath);
+          if (Date.now() - stat.mtimeMs > 30000) {
+            fs.unlinkSync(lockPath);
+            continue; // retry
+          }
+        } catch { continue; }
+
+        // Wait and retry (cross-platform, no shell dependency)
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  // Timeout — stale-lock recovery, then re-acquire atomically before entering critical section.
+  try { fs.unlinkSync(lockPath); } catch { /* ok */ }
+  return runWithHeldLock();
+}
+
+function createPlanningWorkspace(cwd, opts = {}) {
+  return {
+    paths: {
+      dir(ws, project) {
+        return planningDir(cwd, ws, project);
+      },
+      root() {
+        return planningRoot(cwd);
+      },
+      all(ws) {
+        return planningPaths(cwd, ws);
+      },
+    },
+    activeWorkstream: {
+      get() {
+        const adapter = pickActiveWorkstreamAdapter(cwd, opts);
+        if (!adapter) return null;
+
+        const name = adapter.read();
+        if (!name || !validateWorkstreamName(name)) {
+          adapter.clear();
+          return null;
+        }
+
+        const wsDir = path.join(planningRoot(cwd), 'workstreams', name);
+        if (!fs.existsSync(wsDir)) {
+          adapter.clear();
+          return null;
+        }
+
+        return name;
+      },
+      set(name) {
+        const adapter = pickActiveWorkstreamAdapter(cwd, opts);
+        if (!adapter) return;
+
+        if (!name) {
+          adapter.clear();
+          return;
+        }
+        if (!validateWorkstreamName(name)) {
+          throw new Error('Invalid workstream name: must be alphanumeric, hyphens, underscores, or dots');
+        }
+
+        const wsDir = path.join(planningRoot(cwd), 'workstreams', name);
+        platformEnsureDir(wsDir);
+        adapter.write(name);
+      },
+      clear() {
+        const adapter = pickActiveWorkstreamAdapter(cwd, opts);
+        if (!adapter) return;
+        adapter.clear();
+      },
+    },
+  };
+}
+
+function getActiveWorkstream(cwd) {
+  return createPlanningWorkspace(cwd).activeWorkstream.get();
+}
+
+function setActiveWorkstream(cwd, name) {
+  createPlanningWorkspace(cwd).activeWorkstream.set(name);
+}
+
+/**
+ * Locate the CONTEXT.md file in a phase directory, handling both the bare
+ * form (`CONTEXT.md`) and the padded-prefix convention (`NN-CONTEXT.md`,
+ * `NN.N-CONTEXT.md`, etc.) used by gsd-discuss-phase output.
+ *
+ * Returns the filename (not the full path) of the first match, or null if
+ * no CONTEXT.md exists in the directory.
+ *
+ * Canonical dual-form predicate extracted here to eliminate the 5-site
+ * duplication that previously existed across init.cjs, roadmap.cjs,
+ * core.cjs, gap-checker.cjs (#3739).
+ *
+ * @param {string|string[]} absDirOrFiles - Absolute path to the phase directory,
+ *   OR an already-read files array (avoids a redundant readdirSync at call sites
+ *   that already hold a directory listing).
+ * @returns {string|null}
+ */
+function findContextMdIn(absDirOrFiles) {
+  try {
+    const files = Array.isArray(absDirOrFiles)
+      ? absDirOrFiles
+      : fs.readdirSync(absDirOrFiles);
+    if (files.includes('CONTEXT.md')) return 'CONTEXT.md';
+    return files.find(f => f.endsWith('-CONTEXT.md')) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  createPlanningWorkspace,
+  createSharedPointerAdapter,
+  createSessionScopedPointerAdapter,
+  createMemoryPointerAdapter,
+  planningDir,
+  planningRoot,
+  planningPaths,
+  withPlanningLock,
+  getActiveWorkstream,
+  setActiveWorkstream,
+  findContextMdIn,
+};