@ai-is-gonna/get-tasks-done 0.2.0

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

@@ -0,0 +1,39 @@
+'use strict';
+
+const { PHASES_SUBCOMMANDS } = require('./command-aliases.generated.cjs');
+const { routeCjsCommandFamily } = require('./cjs-command-router-adapter.cjs');
+
+/**
+ * Manifest-backed phases subcommand router.
+ * Keeps gtd-tools.cjs thin while preserving current CJS semantics:
+ * - list
+ * - clear
+ *
+ * Note: `archive` is currently SDK-only (`phases.archive` handler in SDK query
+ * registry). CJS `gtd-tools phases` intentionally supports list/clear only.
+ */
+function routePhasesCommand({ phase, milestone, args, cwd, raw, error }) {
+  routeCjsCommandFamily({
+    args,
+    subcommands: PHASES_SUBCOMMANDS.filter((s) => s !== 'archive'),
+    error,
+    unknownMessage: (_subcommand, available) => `Unknown phases subcommand. Available: ${available.join(', ')}`,
+    handlers: {
+      list: () => {
+        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: () => milestone.cmdPhasesClear(cwd, raw, args.slice(2)),
+    },
+  });
+}
+
+module.exports = {
+  routePhasesCommand,
+};

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

@@ -0,0 +1,138 @@
+'use strict';
+/**
+ * plan-scan — canonical phase-plan scanner (k014)
+ *
+ * Single source of truth for detecting plan and summary files in a phase
+ * directory, replacing four divergent copies in state.cjs, roadmap.cjs,
+ * init.cjs, and phase.cjs (#3262).
+ *
+ * Layout support:
+ *   Flat  (pre-#3139): phases/<N>/*-PLAN.md, *-SUMMARY.md
+ *   Nested (post-#3139): phases/<N>/plans/PLAN-<NN>-*.md, SUMMARY-<NN>-*.md
+ *
+ * @module plan-scan
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Excluded derivative files — present alongside real plans but must not be
+// counted.  OUTLINE exclusion catches both flat (-PLAN-OUTLINE.md) and nested
+// (PLAN-NN-OUTLINE.md) forms via a broad -OUTLINE.md$ pattern.  The
+// pre-bounce pattern is intentionally broad (matches any *.pre-bounce.md) so
+// stale bounce files never inflate plan counts (#3257 regression root cause).
+const PLAN_OUTLINE_RE = /-OUTLINE\.md$/i;
+const PLAN_PRE_BOUNCE_RE = /\.pre-bounce\.md$/i;
+
+/**
+ * Determine whether a filename from the flat phase root is a plan file.
+ *
+ * Accepts:
+ *   - Bare            PLAN.md
+ *   - Canonical padded 01-01-PLAN.md
+ *   - Extended layout  5-PLAN-01-setup.md  (the format gtd-plan-phase writes;
+ *     looksLikePlanFile in phase.cjs / isPlanFile in roadmap.cjs)
+ *
+ * Rejects: -PLAN-OUTLINE.md, *.pre-bounce.md
+ */
+function isRootPlanFile(f) {
+  if (PLAN_OUTLINE_RE.test(f)) return false;
+  if (PLAN_PRE_BOUNCE_RE.test(f)) return false;
+  // Canonical suffix or bare name
+  if (f.endsWith('-PLAN.md') || f === 'PLAN.md') return true;
+  // Extended layout: any .md that contains PLAN (case-insensitive) in the name
+  return /\.md$/i.test(f) && /PLAN/i.test(f);
+}
+
+/**
+ * Determine whether a filename from the nested plans/ subdir is a plan file.
+ *
+ * Nested layout names: PLAN-NN-slug.md or N-PLAN-NN-slug.md.
+ * Excludes OUTLINE and pre-bounce suffixes.
+ */
+function isNestedPlanFile(f) {
+  if (PLAN_OUTLINE_RE.test(f)) return false;
+  if (PLAN_PRE_BOUNCE_RE.test(f)) return false;
+  return /^PLAN-\d+.*\.md$/i.test(f) || /-PLAN-\d+.*\.md$/i.test(f);
+}
+
+/**
+ * Determine whether a filename from the flat phase root is a summary file.
+ */
+function isRootSummaryFile(f) {
+  return f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md';
+}
+
+/**
+ * Determine whether a filename from the nested plans/ subdir is a summary.
+ */
+function isNestedSummaryFile(f) {
+  return /^SUMMARY-\d+.*\.md$/i.test(f) || /-SUMMARY-\d+.*\.md$/i.test(f);
+}
+
+/**
+ * Scan a single phase directory for plan and summary files.
+ *
+ * @param {string} phaseDir — absolute path to the phase directory
+ * @returns {{
+ *   planCount: number,
+ *   summaryCount: number,
+ *   completed: boolean,
+ *   hasNestedPlans: boolean,
+ *   planFiles: string[],
+ *   summaryFiles: string[],
+ * }}
+ */
+function scanPhasePlans(phaseDir) {
+  let rootFiles;
+  try {
+    rootFiles = fs.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 = path.join(phaseDir, 'plans');
+  if (fs.existsSync(nestedDir)) {
+    try {
+      const nested = fs.readdirSync(nestedDir);
+      nestedPlanFiles = nested.filter(isNestedPlanFile);
+      nestedSummaryFiles = nested.filter(isNestedSummaryFile);
+      hasNestedPlans = nestedPlanFiles.length > 0;
+    } catch { /* ignore if plans/ is not a readable directory */ }
+  }
+
+  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,
+  };
+}
+
+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-tasks-done/bin/lib/planning-workspace.cjs

@@ -0,0 +1,361 @@
+/**
+ * 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 = [
+  'GTD_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 */ }
+  }
+});
+
+function planningDir(cwd, ws, project) {
+  if (project === undefined) project = process.env.GTD_PROJECT || null;
+  if (ws === undefined) ws = process.env.GTD_WORKSTREAM || null;
+
+  // Reject path separators and traversal components in project/workstream names
+  const BAD_SEGMENT = /[/\\]|\.\./;
+  if (project && BAD_SEGMENT.test(project)) {
+    throw new Error(`GTD_PROJECT contains invalid path characters: ${project}`);
+  }
+  if (ws && BAD_SEGMENT.test(ws)) {
+    throw new Error(`GTD_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(), 'gtd-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) {
+      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);
+}
+
+module.exports = {
+  createPlanningWorkspace,
+  createSharedPointerAdapter,
+  createSessionScopedPointerAdapter,
+  createMemoryPointerAdapter,
+  planningDir,
+  planningRoot,
+  planningPaths,
+  withPlanningLock,
+  getActiveWorkstream,
+  setActiveWorkstream,
+};