@opengsd/gsd-core 1.2.0-rc.1

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

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Shared parser for CONTEXT.md <decisions> blocks.
+ * Accepts both numeric (D-42) and alphanumeric (D-INFRA-01) IDs.
+ * Returns {id, text, category, tags, trackable} per decision.
+ * CJS callers that only use {id, text} safely ignore the extra fields.
+ */
+
+const DISCRETION_HEADINGS = new Set([
+    "claude's discretion",
+    'claudes discretion',
+    'claude discretion',
+]);
+const NON_TRACKABLE_TAGS = new Set(['informational', 'folded', 'deferred']);
+/**
+ * Strip fenced code blocks from `content` so example `<decisions>` snippets
+ * inside ```` ``` ```` do not pollute the parser (review F11).
+ */
+function stripFencedCode(content) {
+    return content.replace(/```[\s\S]*?```/g, ' ').replace(/~~~[\s\S]*?~~~/g, ' ');
+}
+/**
+ * Extract the inner text of EVERY `<decisions>...</decisions>` block in
+ * order, concatenated by `\n\n`. Returns null when no block is present.
+ *
+ * CONTEXT.md may legitimately contain more than one block (for example, a
+ * "current decisions" block plus a "carry-over from prior phase" block);
+ * dropping all-but-the-first silently lost the second batch (review F13).
+ */
+function extractDecisionsBlock(content) {
+    const cleaned = stripFencedCode(content);
+    const matches = [...cleaned.matchAll(/<decisions>([\s\S]*?)<\/decisions>/g)];
+    if (matches.length === 0)
+        return null;
+    return matches.map((m) => m[1]).join('\n\n');
+}
+/**
+ * Parse trackable decisions from CONTEXT.md content.
+ *
+ * Returns ALL D-NN decisions found inside `<decisions>` (including
+ * non-trackable ones, with `trackable: false`). Callers that only want the
+ * gate-enforced decisions should filter `.filter(d => d.trackable)`.
+ */
+function parseDecisions(content) {
+    if (!content || typeof content !== 'string')
+        return [];
+    const block = extractDecisionsBlock(content);
+    if (block === null)
+        return [];
+    const lines = block.split(/\r?\n/);
+    const out = [];
+    let category = '';
+    let inDiscretion = false;
+    // Bullet line: `- **D-NN[ [tags]]:** text`
+    // Phase 6 (#3575): aligned to CJS regex — accepts alphanumeric IDs (D-01, D-INFRA-01, D-FOO_BAR)
+    // in addition to numeric-only IDs (D-42). The first character after `D-` must
+    // be alphanumeric, so malformed shapes like `D--foo` or `D-_bar` are rejected.
+    // CJS callers consume {id, text} and ignore the optional extras.
+    const bulletRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)\])?\s*:\*\*\s*(.*)$/;
+    let current = null;
+    const flush = () => {
+        if (current) {
+            current.text = current.text.trim();
+            out.push(current);
+            current = null;
+        }
+    };
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Track category headings (`### Heading`)
+        const headingMatch = trimmed.match(/^###\s+(.+?)\s*$/);
+        if (headingMatch) {
+            flush();
+            category = headingMatch[1];
+            // Strip the full unicode-quote family so any rendering of "Claude's
+            // Discretion" (ASCII apostrophe, curly U+2019, U+2018, U+201A, U+201B,
+            // double-quote variants U+201C/D/E/F, etc.) collapses to the same key
+            // (review F20).
+            const normalized = category
+                .toLowerCase()
+                .replace(/[\u2018\u2019\u201A\u201B\u201C\u201D\u201E\u201F'"`]/g, '')
+                .trim();
+            inDiscretion = DISCRETION_HEADINGS.has(normalized);
+            continue;
+        }
+        const bulletMatch = line.match(bulletRe);
+        if (bulletMatch) {
+            flush();
+            const id = `D-${bulletMatch[1]}`;
+            const tags = bulletMatch[2]
+                ? bulletMatch[2]
+                    .split(',')
+                    .map((t) => t.trim().toLowerCase())
+                    .filter(Boolean)
+                : [];
+            const trackable = !inDiscretion && !tags.some((t) => NON_TRACKABLE_TAGS.has(t));
+            current = { id, text: bulletMatch[3], category, tags, trackable };
+            continue;
+        }
+        // Continuation line for current decision (indented with space OR tab,
+        // non-bullet, non-empty) — tab indentation must work too (review F12).
+        if (current && trimmed !== '' && !trimmed.startsWith('-') && /^[ \t]/.test(line)) {
+            current.text += ' ' + trimmed;
+            continue;
+        }
+        // Blank line or unrelated content terminates the current decision
+        if (trimmed === '') {
+            flush();
+        }
+    }
+    flush();
+    return out;
+}
+
+module.exports = { parseDecisions };

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

@@ -0,0 +1,270 @@
+/**
+ * Docs — Commands for the docs-update workflow
+ *
+ * Provides `cmdDocsInit` which returns project signals, existing doc inventory
+ * with GSD marker detection, doc tooling detection, monorepo awareness, and
+ * model resolution. Used by Phase 2 to route doc generation appropriately.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, loadConfig, resolveModelInternal, pathExistsInternal, toPosixPath, checkAgentsInstalled } = require('./core.cjs');
+const { platformReadSync } = require('./shell-command-projection.cjs');
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const GSD_MARKER = '<!-- generated-by: gsd-doc-writer -->';
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.planning', '.claude', '__pycache__',
+  'target', 'dist', 'build', '.next', '.nuxt', 'coverage',
+  '.vscode', '.idea',
+]);
+
+// ─── Private helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Check whether a file begins with the GSD doc writer marker.
+ * Reads the first 500 bytes only — avoids loading large files.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {boolean}
+ */
+function hasGsdMarker(filePath) {
+  try {
+    const buf = Buffer.alloc(500);
+    const fd = fs.openSync(filePath, 'r');
+    const bytesRead = fs.readSync(fd, buf, 0, 500, 0);
+    fs.closeSync(fd);
+    return buf.slice(0, bytesRead).toString('utf-8').includes(GSD_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Recursively scan the project root (immediate .md files) and docs/ directory
+ * (up to 4 levels deep) for Markdown files, excluding dirs in SKIP_DIRS.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Array<{path: string, has_gsd_marker: boolean}>}
+ */
+function scanExistingDocs(cwd) {
+  const MAX_DEPTH = 4;
+  const results = [];
+
+  /**
+   * Recursively walk a directory for .md files up to MAX_DEPTH levels.
+   * @param {string} dir - Directory to scan
+   * @param {number} depth - Current depth (1-based)
+   */
+  function walkDir(dir, depth) {
+    if (depth > MAX_DEPTH) return;
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walkDir(abs, depth + 1);
+        } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+          const rel = toPosixPath(path.relative(cwd, abs));
+          results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+        }
+      }
+    } catch { /* directory may not exist — best-effort */ }
+  }
+
+  // Scan root-level .md files (non-recursive)
+  try {
+    const entries = fs.readdirSync(cwd, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+        const abs = path.join(cwd, entry.name);
+        const rel = toPosixPath(path.relative(cwd, abs));
+        results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+      }
+    }
+  } catch { /* best-effort */ }
+
+  // Recursively scan docs/ directory
+  const docsDir = path.join(cwd, 'docs');
+  walkDir(docsDir, 1);
+
+  // Fallback: if docs/ does not exist, try documentation/ or doc/
+  try {
+    fs.statSync(docsDir);
+  } catch {
+    const alternatives = ['documentation', 'doc'];
+    for (const alt of alternatives) {
+      const altDir = path.join(cwd, alt);
+      try {
+        const stat = fs.statSync(altDir);
+        if (stat.isDirectory()) {
+          walkDir(altDir, 1);
+          break;
+        }
+      } catch { /* not present */ }
+    }
+  }
+
+  return results.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Detect project type signals from the filesystem and package.json.
+ * All checks are best-effort and never throw.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object} Boolean signal fields
+ */
+function detectProjectType(cwd) {
+  const exists = (rel) => {
+    try { return pathExistsInternal(cwd, rel); } catch { return false; }
+  };
+
+  // Read package.json once — used by has_cli_bin, is_monorepo, has_tests checks.
+  const pkgRaw = platformReadSync(path.join(cwd, 'package.json'));
+  let pkg = null;
+  if (pkgRaw) {
+    try { pkg = JSON.parse(pkgRaw); } catch { /* invalid JSON */ }
+  }
+
+  // has_cli_bin: package.json has a `bin` field
+  const has_cli_bin = !!(pkg && pkg.bin && (typeof pkg.bin === 'string' || Object.keys(pkg.bin).length > 0));
+
+  // is_monorepo: pnpm-workspace.yaml, lerna.json, or package.json workspaces
+  let is_monorepo = exists('pnpm-workspace.yaml') || exists('lerna.json');
+  if (!is_monorepo && pkg) {
+    is_monorepo = Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0;
+  }
+
+  // has_tests: common test directories or test frameworks in devDependencies
+  let has_tests = exists('test') || exists('tests') || exists('__tests__') || exists('spec');
+  if (!has_tests && pkg) {
+    const devDeps = Object.keys(pkg.devDependencies || {});
+    has_tests = devDeps.some(d => ['vitest', 'jest', 'mocha', 'jasmine', 'ava'].includes(d));
+  }
+
+  // has_deploy_config: various deployment config files
+  const deployFiles = [
+    'Dockerfile', 'docker-compose.yml', 'docker-compose.yaml',
+    'fly.toml', 'render.yaml', 'vercel.json', 'netlify.toml', 'railway.json',
+    '.github/workflows/deploy.yml', '.github/workflows/deploy.yaml',
+  ];
+  const has_deploy_config = deployFiles.some(f => exists(f));
+
+  return {
+    has_package_json: exists('package.json'),
+    has_api_routes: (
+      exists('src/app/api') || exists('routes') || exists('src/routes') ||
+      exists('api') || exists('server')
+    ),
+    has_cli_bin,
+    is_open_source: exists('LICENSE') || exists('LICENSE.md'),
+    has_deploy_config,
+    is_monorepo,
+    has_tests,
+  };
+}
+
+/**
+ * Detect known documentation tooling in the project.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object} Boolean detection fields
+ */
+function detectDocTooling(cwd) {
+  const exists = (rel) => {
+    try { return pathExistsInternal(cwd, rel); } catch { return false; }
+  };
+
+  return {
+    docusaurus: exists('docusaurus.config.js') || exists('docusaurus.config.ts'),
+    vitepress: (
+      exists('.vitepress/config.js') ||
+      exists('.vitepress/config.ts') ||
+      exists('.vitepress/config.mts')
+    ),
+    mkdocs: exists('mkdocs.yml'),
+    storybook: exists('.storybook'),
+  };
+}
+
+/**
+ * Extract monorepo workspace globs from pnpm-workspace.yaml, package.json
+ * workspaces, or lerna.json.
+ *
+ * @param {string} cwd - Project root
+ * @returns {string[]} Array of workspace glob patterns, or [] if not a monorepo
+ */
+function detectMonorepoWorkspaces(cwd) {
+  // pnpm-workspace.yaml
+  const pnpmRaw = platformReadSync(path.join(cwd, 'pnpm-workspace.yaml'));
+  if (pnpmRaw) {
+    const workspaces = [];
+    for (const line of pnpmRaw.split('\n')) {
+      const m = line.match(/^\s*-\s+['"]?(.+?)['"]?\s*$/);
+      if (m) workspaces.push(m[1].trim());
+    }
+    if (workspaces.length > 0) return workspaces;
+  }
+
+  // package.json workspaces
+  const pkgRaw = platformReadSync(path.join(cwd, 'package.json'));
+  if (pkgRaw) {
+    try {
+      const pkg = JSON.parse(pkgRaw);
+      if (Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0) {
+        return pkg.workspaces;
+      }
+    } catch { /* invalid JSON */ }
+  }
+
+  // lerna.json
+  const lernaRaw = platformReadSync(path.join(cwd, 'lerna.json'));
+  if (lernaRaw) {
+    try {
+      const lerna = JSON.parse(lernaRaw);
+      if (Array.isArray(lerna.packages) && lerna.packages.length > 0) {
+        return lerna.packages;
+      }
+    } catch { /* invalid JSON */ }
+  }
+
+  return [];
+}
+
+// ─── Public commands ──────────────────────────────────────────────────────────
+
+/**
+ * Return JSON context for the docs-update workflow: project signals, existing
+ * doc inventory, doc tooling detection, monorepo workspaces, and model
+ * resolution. Follows the cmdInitMapCodebase pattern.
+ *
+ * @example
+ * node gsd-tools.cjs docs-init --raw
+ *
+ * @param {string} cwd - Project root directory
+ * @param {boolean} raw - Pass raw JSON flag through to output()
+ */
+function cmdDocsInit(cwd, raw) {
+  const config = loadConfig(cwd);
+  const result = {
+    doc_writer_model: resolveModelInternal(cwd, 'gsd-doc-writer'),
+    commit_docs: config.commit_docs,
+    existing_docs: scanExistingDocs(cwd),
+    project_type: detectProjectType(cwd),
+    doc_tooling: detectDocTooling(cwd),
+    monorepo_workspaces: detectMonorepoWorkspaces(cwd),
+    planning_exists: pathExistsInternal(cwd, '.planning'),
+  };
+  // Inject project_root and agent installation status (mirrors withProjectRoot in init.cjs)
+  result.project_root = cwd;
+  const agentStatus = checkAgentsInstalled();
+  result.agents_installed = agentStatus.agents_installed;
+  result.missing_agents = agentStatus.missing_agents;
+  output(result, raw);
+}
+
+module.exports = { cmdDocsInit };