gsd-opencode 1.22.1 → 1.33.0

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

@@ -0,0 +1,267 @@
+/**
+ * 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');
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const GSD_MARKER = '<!-- generated-by: gsd-doc-writer -->';
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.planning', '.OpenCode', '__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; }
+  };
+
+  // has_cli_bin: package.json has a `bin` field
+  let has_cli_bin = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+    has_cli_bin = !!(pkg.bin && (typeof pkg.bin === 'string' || Object.keys(pkg.bin).length > 0));
+  } catch { /* no package.json or invalid JSON */ }
+
+  // is_monorepo: pnpm-workspace.yaml, lerna.json, or package.json workspaces
+  let is_monorepo = exists('pnpm-workspace.yaml') || exists('lerna.json');
+  if (!is_monorepo) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+      is_monorepo = Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0;
+    } catch { /* ignore */ }
+  }
+
+  // has_tests: common test directories or test frameworks in devDependencies
+  let has_tests = exists('test') || exists('tests') || exists('__tests__') || exists('spec');
+  if (!has_tests) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+      const devDeps = Object.keys(pkg.devDependencies || {});
+      has_tests = devDeps.some(d => ['vitest', 'jest', 'mocha', 'jasmine', 'ava'].includes(d));
+    } catch { /* ignore */ }
+  }
+
+  // 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
+  try {
+    const content = fs.readFileSync(path.join(cwd, 'pnpm-workspace.yaml'), 'utf-8');
+    const lines = content.split('\n');
+    const workspaces = [];
+    for (const line of lines) {
+      const m = line.match(/^\s*-\s+['"]?(.+?)['"]?\s*$/);
+      if (m) workspaces.push(m[1].trim());
+    }
+    if (workspaces.length > 0) return workspaces;
+  } catch { /* not present */ }
+
+  // package.json workspaces
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+    if (Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0) {
+      return pkg.workspaces;
+    }
+  } catch { /* not present or invalid */ }
+
+  // lerna.json
+  try {
+    const lerna = JSON.parse(fs.readFileSync(path.join(cwd, 'lerna.json'), 'utf-8'));
+    if (Array.isArray(lerna.packages) && lerna.packages.length > 0) {
+      return lerna.packages;
+    }
+  } catch { /* not present or invalid */ }
+
+  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 };

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

@@ -4,17 +4,53 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, output, error } = require('./core.cjs');
+const { safeReadFile, normalizeMd, output, error } = require('./core.cjs');
 
 // ─── Parsing engine ───────────────────────────────────────────────────────────
 
+/**
+ * Split a YAML inline array body on commas, respecting quoted strings.
+ * e.g. '"a, b", c' → ['a, b', 'c']
+ */
+function splitInlineArray(body) {
+  const items = [];
+  let current = '';
+  let inQuote = null; // null | '"' | "'"
+
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === ',') {
+      const trimmed = current.trim();
+      if (trimmed) items.push(trimmed);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  const trimmed = current.trim();
+  if (trimmed) items.push(trimmed);
+  return items;
+}
+
 function extractFrontmatter(content) {
   const frontmatter = {};
-  const match = content.match(/^---\n([\s\S]+?)\n---/);
+  // Find ALL frontmatter blocks at the start of the file.
+  // If multiple blocks exist (corruption from CRLF mismatch), use the LAST one
+  // since it represents the most recent state sync.
+  const allBlocks = [...content.matchAll(/(?:^|\n)\s*---\r?\n([\s\S]+?)\r?\n---/g)];
+  const match = allBlocks.length > 0 ? allBlocks[allBlocks.length - 1] : null;
   if (!match) return frontmatter;
 
   const yaml = match[1];
-  const lines = yaml.split('\n');
+  const lines = yaml.split(/\r?\n/);
 
   // Stack to track nested objects: [{obj, key, indent}]
   // obj = object to write to, key = current key collecting array items, indent = indentation level
@@ -49,8 +85,8 @@ function extractFrontmatter(content) {
         // Push new context for potential nested content
         stack.push({ obj: current.obj[key], key: null, indent });
       } else if (value.startsWith('[') && value.endsWith(']')) {
-        // Inline array: key: [a, b, c]
-        current.obj[key] = value.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+        // Inline array: key: [a, b, c] — quote-aware split (REG-04 fix)
+        current.obj[key] = splitInlineArray(value.slice(1, -1));
         current.key = null;
       } else {
         // Simple key: value
@@ -149,7 +185,7 @@ function reconstructFrontmatter(obj) {
 
 function spliceFrontmatter(content, newObj) {
   const yamlStr = reconstructFrontmatter(newObj);
-  const match = content.match(/^---\n[\s\S]+?\n---/);
+  const match = content.match(/^---\r?\n[\s\S]+?\r?\n---/);
   if (match) {
     return `---\n${yamlStr}\n---` + content.slice(match[0].length);
   }
@@ -159,66 +195,108 @@ function spliceFrontmatter(content, newObj) {
 function parseMustHavesBlock(content, blockName) {
   // Extract a specific block from must_haves in raw frontmatter YAML
   // Handles 3-level nesting: must_haves > artifacts/key_links > [{path, provides, ...}]
-  const fmMatch = content.match(/^---\n([\s\S]+?)\n---/);
+  const fmMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
   if (!fmMatch) return [];
 
   const yaml = fmMatch[1];
-  // Find the block (e.g., "truths:", "artifacts:", "key_links:")
-  const blockPattern = new RegExp(`^\\s{4}${blockName}:\\s*$`, 'm');
-  const blockStart = yaml.search(blockPattern);
+
+  // Find must_haves: first to detect its indentation level
+  const mustHavesMatch = yaml.match(/^(\s*)must_haves:\s*$/m);
+  if (!mustHavesMatch) return [];
+  const mustHavesIndent = mustHavesMatch[1].length;
+
+  // Find the block (e.g., "truths:", "artifacts:", "key_links:") under must_haves
+  // It must be indented more than must_haves but we detect the actual indent dynamically
+  const blockPattern = new RegExp(`^(\\s+)${blockName}:\\s*$`, 'm');
+  const blockMatch = yaml.match(blockPattern);
+  if (!blockMatch) return [];
+
+  const blockIndent = blockMatch[1].length;
+  // The block must be nested under must_haves (more indented)
+  if (blockIndent <= mustHavesIndent) return [];
+
+  // Find where the block starts in the yaml string
+  const blockStart = yaml.indexOf(blockMatch[0]);
   if (blockStart === -1) return [];
 
   const afterBlock = yaml.slice(blockStart);
-  const blockLines = afterBlock.split('\n').slice(1); // skip the header line
+  const blockLines = afterBlock.split(/\r?\n/).slice(1); // skip the header line
 
+  // List items are indented one level deeper than blockIndent
+  // Continuation KVs are indented one level deeper than list items
   const items = [];
   let current = null;
+  let listItemIndent = -1; // detected from first "- " line
 
   for (const line of blockLines) {
-    // Stop at same or lower indent level (non-continuation)
+    // Skip empty lines
     if (line.trim() === '') continue;
     const indent = line.match(/^(\s*)/)[1].length;
-    if (indent <= 4 && line.trim() !== '') break; // back to must_haves level or higher
-
-    if (line.match(/^\s{6}-\s+/)) {
-      // New list item at 6-space indent
-      if (current) items.push(current);
-      current = {};
-      // Check if it's a simple string item
-      const simpleMatch = line.match(/^\s{6}-\s+"?([^"]+)"?\s*$/);
-      if (simpleMatch && !line.includes(':')) {
-        current = simpleMatch[1];
-      } else {
-        // Key-value on same line as dash: "- path: value"
-        const kvMatch = line.match(/^\s{6}-\s+(\w+):\s*"?([^"]*)"?\s*$/);
-        if (kvMatch) {
-          current = {};
-          current[kvMatch[1]] = kvMatch[2];
+    // Stop at same or lower indent level than the block header
+    if (indent <= blockIndent && line.trim() !== '') break;
+
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith('- ')) {
+      // Detect list item indent from the first occurrence
+      if (listItemIndent === -1) listItemIndent = indent;
+
+      // Only treat as a top-level list item if at the expected indent
+      if (indent === listItemIndent) {
+        if (current) items.push(current);
+        current = {};
+        const afterDash = trimmed.slice(2);
+        // Check if it's a simple string item (no colon means not a key-value)
+        if (!afterDash.includes(':')) {
+          current = afterDash.replace(/^["']|["']$/g, '');
+        } else {
+          // Key-value on same line as dash: "- path: value"
+          const kvMatch = afterDash.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
+          if (kvMatch) {
+            current = {};
+            current[kvMatch[1]] = kvMatch[2];
+          }
         }
+        continue;
       }
-    } else if (current && typeof current === 'object') {
-      // Continuation key-value at 8+ space indent
-      const kvMatch = line.match(/^\s{8,}(\w+):\s*"?([^"]*)"?\s*$/);
-      if (kvMatch) {
-        const val = kvMatch[2];
-        // Try to parse as number
-        current[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
-      }
-      // Array items under a key
-      const arrMatch = line.match(/^\s{10,}-\s+"?([^"]+)"?\s*$/);
-      if (arrMatch) {
-        // Find the last key added and convert to array
+    }
+
+    if (current && typeof current === 'object' && indent > listItemIndent) {
+      // Continuation key-value or nested array item
+      if (trimmed.startsWith('- ')) {
+        // Array item under a key
+        const arrVal = trimmed.slice(2).replace(/^["']|["']$/g, '');
         const keys = Object.keys(current);
         const lastKey = keys[keys.length - 1];
         if (lastKey && !Array.isArray(current[lastKey])) {
           current[lastKey] = current[lastKey] ? [current[lastKey]] : [];
         }
-        if (lastKey) current[lastKey].push(arrMatch[1]);
+        if (lastKey) current[lastKey].push(arrVal);
+      } else {
+        const kvMatch = trimmed.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
+        if (kvMatch) {
+          const val = kvMatch[2];
+          // Try to parse as number
+          current[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
+        }
       }
     }
   }
   if (current) items.push(current);
 
+  // Warn when must_haves block exists but parsed as empty -- likely YAML formatting issue.
+  // This is a critical diagnostic: empty must_haves causes verification to silently degrade
+  // to Option C (LLM-derived truths) instead of checking documented contracts.
+  if (items.length === 0 && blockLines.length > 0) {
+    const nonEmptyLines = blockLines.filter(l => l.trim() !== '').length;
+    if (nonEmptyLines > 0) {
+      process.stderr.write(
+        `[gsd-tools] WARNING: must_haves.${blockName} block has ${nonEmptyLines} content lines but parsed 0 items. ` +
+        `Possible YAML formatting issue — verification will fall back to LLM-derived truths.\n`
+      );
+    }
+  }
+
   return items;
 }
 
@@ -232,6 +310,8 @@ const FRONTMATTER_SCHEMAS = {
 
 function cmdFrontmatterGet(cwd, filePath, field, raw) {
   if (!filePath) { error('file path required'); }
+  // Path traversal guard: reject null bytes
+  if (filePath.includes('\0')) { error('file path contains null bytes'); }
   const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
   const content = safeReadFile(fullPath);
   if (!content) { output({ error: 'File not found', path: filePath }, raw); return; }
@@ -247,6 +327,8 @@ function cmdFrontmatterGet(cwd, filePath, field, raw) {
 
 function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
   if (!filePath || !field || value === undefined) { error('file, field, and value required'); }
+  // Path traversal guard: reject null bytes
+  if (filePath.includes('\0')) { error('file path contains null bytes'); }
   const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
   if (!fs.existsSync(fullPath)) { output({ error: 'File not found', path: filePath }, raw); return; }
   const content = fs.readFileSync(fullPath, 'utf-8');
@@ -255,7 +337,7 @@ function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
   try { parsedValue = JSON.parse(value); } catch { parsedValue = value; }
   fm[field] = parsedValue;
   const newContent = spliceFrontmatter(content, fm);
-  fs.writeFileSync(fullPath, newContent, 'utf-8');
+  fs.writeFileSync(fullPath, normalizeMd(newContent), 'utf-8');
   output({ updated: true, field, value: parsedValue }, raw, 'true');
 }
 
@@ -269,7 +351,7 @@ function cmdFrontmatterMerge(cwd, filePath, data, raw) {
   try { mergeData = JSON.parse(data); } catch { error('Invalid JSON for --data'); return; }
   Object.assign(fm, mergeData);
   const newContent = spliceFrontmatter(content, fm);
-  fs.writeFileSync(fullPath, newContent, 'utf-8');
+  fs.writeFileSync(fullPath, normalizeMd(newContent), 'utf-8');
   output({ merged: true, fields: Object.keys(mergeData) }, raw, 'true');
 }