create-quiver 0.10.0 → 0.12.1

package/src/create-quiver/lib/doctor.js

@@ -1,8 +1,14 @@
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 const { readAllSlices } = require('./slice-graph');
 const { hasGeneratedProjectSpec, hasInitializedStateMetadata, readState } = require('./state');
 const { worktreeList } = require('./git');
+const {
+  buildQuiverConfig,
+  buildQuiverInternalGitignore,
+  resolveInitPackageScripts,
+} = require('./init-layout');
 
 const NEW_LAYOUT_REQUIRED_PATHS = [
   'README.md',
@@ -26,6 +32,13 @@ const LEGACY_LAYOUT_PROBES = [
   'docs/PROJECT_SCAN.json',
 ];
 
+const ROOT_GITIGNORE_DEFAULTS = [
+  'node_modules/',
+  '.DS_Store',
+  'dist/',
+  'coverage/',
+];
+
 function readTextIfExists(filePath) {
   if (!fs.existsSync(filePath)) {
     return null;
@@ -34,6 +47,34 @@ function readTextIfExists(filePath) {
   return fs.readFileSync(filePath, 'utf8');
 }
 
+function normalizeIgnorePattern(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) {
+    return trimmed;
+  }
+
+  return trimmed.replace(/\/+$/g, '');
+}
+
+function missingLineDefaults(existingText, defaults) {
+  const seen = new Set(
+    String(existingText || '')
+      .split(/\r?\n/)
+      .map(normalizeIgnorePattern)
+      .filter(Boolean),
+  );
+
+  return defaults.filter((line) => !seen.has(normalizeIgnorePattern(line)));
+}
+
+function appendMissingLines(filePath, lines) {
+  const existingText = readTextIfExists(filePath) || '';
+  const trimmed = existingText.replace(/\s+$/g, '');
+  const prefix = trimmed.length > 0 ? `${trimmed}\n` : '';
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${prefix}${lines.join('\n')}\n`);
+}
+
 function countNonEmptyLines(text) {
   return String(text || '')
     .split(/\r?\n/)
@@ -210,6 +251,82 @@ function countStackInfoLeaks(projectRoot) {
   return leaks;
 }
 
+function collectGeneratedMarkdownFiles(projectRoot) {
+  const files = [];
+  const rootFiles = ['README.md', 'AGENTS.md'];
+
+  for (const file of rootFiles) {
+    const absolutePath = path.join(projectRoot, file);
+    if (fs.existsSync(absolutePath)) {
+      files.push(absolutePath);
+    }
+  }
+
+  const docsDir = path.join(projectRoot, 'docs');
+  if (!fs.existsSync(docsDir)) {
+    return files;
+  }
+
+  const walk = (dirPath) => {
+    for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        files.push(fullPath);
+      }
+    }
+  };
+
+  walk(docsDir);
+
+  return files;
+}
+
+function isExternalLink(target) {
+  return /^(?:[a-z][a-z0-9+.-]*:|#)/i.test(target);
+}
+
+function normalizeMarkdownLinkTarget(target) {
+  return target
+    .trim()
+    .replace(/^<|>$/g, '')
+    .split('#')[0]
+    .trim();
+}
+
+function collectMissingMarkdownLinks(projectRoot) {
+  const missing = [];
+  const linkPattern = /!?\[[^\]]*]\(([^)]+)\)/g;
+
+  for (const filePath of collectGeneratedMarkdownFiles(projectRoot)) {
+    const text = readTextIfExists(filePath);
+    if (!text) {
+      continue;
+    }
+
+    let match;
+    while ((match = linkPattern.exec(text)) !== null) {
+      const target = normalizeMarkdownLinkTarget(match[1]);
+      if (!target || isExternalLink(target)) {
+        continue;
+      }
+
+      const resolved = path.resolve(path.dirname(filePath), target);
+      const relativeToRoot = path.relative(projectRoot, resolved);
+      if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
+        continue;
+      }
+
+      if (!fs.existsSync(resolved)) {
+        missing.push(`${normalizeRelativePath(projectRoot, filePath)} -> ${target}`);
+      }
+    }
+  }
+
+  return missing;
+}
+
 function collectLayoutReport(projectRoot) {
   const hasStateMetadata = hasInitializedStateMetadata(readState(projectRoot));
   const realSlices = readAllSlices(projectRoot);
@@ -276,6 +393,116 @@ function collectLayoutReport(projectRoot) {
   };
 }
 
+function buildDoctorFixPlan(projectRoot) {
+  const fixes = [];
+  const rootGitignorePath = path.join(projectRoot, '.gitignore');
+  const rootGitignoreText = readTextIfExists(rootGitignorePath) || '';
+  const missingRootGitignoreLines = missingLineDefaults(rootGitignoreText, ROOT_GITIGNORE_DEFAULTS);
+  if (!fs.existsSync(rootGitignorePath)) {
+    fixes.push({
+      type: 'append-lines',
+      path: '.gitignore',
+      description: 'Create root .gitignore with safe Quiver defaults.',
+      lines: ROOT_GITIGNORE_DEFAULTS,
+    });
+  } else if (missingRootGitignoreLines.length > 0) {
+    fixes.push({
+      type: 'append-lines',
+      path: '.gitignore',
+      description: `Merge missing root .gitignore defaults: ${missingRootGitignoreLines.join(', ')}.`,
+      lines: missingRootGitignoreLines,
+    });
+  }
+
+  const quiverGitignorePath = path.join(projectRoot, '.quiver', '.gitignore');
+  const quiverGitignoreText = readTextIfExists(quiverGitignorePath) || '';
+  const quiverDefaults = buildQuiverInternalGitignore().split(/\r?\n/).filter(Boolean);
+  const missingQuiverLines = missingLineDefaults(quiverGitignoreText, quiverDefaults);
+  if (!fs.existsSync(quiverGitignorePath)) {
+    fixes.push({
+      type: 'write-json-or-text',
+      path: '.quiver/.gitignore',
+      description: 'Create internal .quiver/.gitignore for local AI state.',
+      content: buildQuiverInternalGitignore(),
+    });
+  } else if (missingQuiverLines.length > 0) {
+    fixes.push({
+      type: 'append-lines',
+      path: '.quiver/.gitignore',
+      description: `Merge missing .quiver/.gitignore defaults: ${missingQuiverLines.join(', ')}.`,
+      lines: missingQuiverLines,
+    });
+  }
+
+  const configPath = path.join(projectRoot, '.quiver', 'config.json');
+  if (!fs.existsSync(configPath)) {
+    fixes.push({
+      type: 'write-json-or-text',
+      path: '.quiver/config.json',
+      description: 'Create missing Quiver config metadata.',
+      content: `${JSON.stringify(buildQuiverConfig(), null, 2)}\n`,
+    });
+  }
+
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(packageJsonPath)) {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    const scripts = packageJson.scripts && typeof packageJson.scripts === 'object' ? packageJson.scripts : {};
+    const expectedScripts = resolveInitPackageScripts('default');
+    const missingScripts = Object.entries(expectedScripts)
+      .filter(([name]) => (name.startsWith('quiver:') || name === 'check-handoff') && typeof scripts[name] !== 'string');
+
+    if (missingScripts.length > 0) {
+      fixes.push({
+        type: 'merge-package-scripts',
+        path: 'package.json',
+        description: `Add missing package scripts: ${missingScripts.map(([name]) => name).join(', ')}.`,
+        scripts: Object.fromEntries(missingScripts),
+      });
+    }
+  }
+
+  return fixes;
+}
+
+function applyDoctorFixPlan(projectRoot, fixes) {
+  for (const fix of fixes) {
+    const targetPath = path.join(projectRoot, fix.path);
+    if (fix.type === 'append-lines') {
+      appendMissingLines(targetPath, fix.lines);
+      continue;
+    }
+
+    if (fix.type === 'write-json-or-text') {
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.writeFileSync(targetPath, fix.content);
+      continue;
+    }
+
+    if (fix.type === 'merge-package-scripts') {
+      const packageJson = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+      packageJson.scripts = {
+        ...(packageJson.scripts || {}),
+        ...fix.scripts,
+      };
+      fs.writeFileSync(targetPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+    }
+  }
+}
+
+function formatDoctorFixPlan(fixes, { dryRun = false } = {}) {
+  const lines = [dryRun ? 'Quiver doctor fix dry-run' : 'Quiver doctor fix'];
+  if (fixes.length === 0) {
+    lines.push('- No safe fixes to apply.');
+  } else {
+    for (const fix of fixes) {
+      lines.push(`- ${dryRun ? 'Would update' : 'Updated'} ${fix.path}: ${fix.description}`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
 function collectDoctorReport(projectRoot) {
   const layout = collectLayoutReport(projectRoot);
   const warnings = collectDoctorWarnings(projectRoot);
@@ -286,6 +513,75 @@ function collectDoctorReport(projectRoot) {
   };
 }
 
+function runEnvironmentProbe(command, args = [], options = {}) {
+  const runner = options.runner || spawnSync;
+  return runner(command, args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    shell: false,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: options.timeout || 3000,
+  });
+}
+
+function probeOk(command, args, options = {}) {
+  const result = runEnvironmentProbe(command, args, options);
+  if (result && result.error && result.error.code === 'ENOENT') {
+    return {
+      ok: false,
+      reason: 'missing',
+    };
+  }
+  return {
+    ok: Boolean(result && result.status === 0),
+    reason: result && result.error ? result.error.message : result && result.stderr ? String(result.stderr).trim() : '',
+  };
+}
+
+function collectEnvironmentWarnings(projectRoot, options = {}) {
+  const warnings = [];
+  const cwd = projectRoot;
+
+  const checks = [
+    ['node', ['--version'], 'Node.js is required to run create-quiver. Install Node 20+ and retry.'],
+    ['npm', ['--version'], 'npm is required for generated npm scripts and package smokes. Install npm or use a Node distribution that includes it.'],
+    ['git', ['--version'], 'git is required for specs, slices, worktrees, commits, and PR flow. Install git and retry.'],
+  ];
+
+  for (const [command, args, message] of checks) {
+    const check = probeOk(command, args, { ...options, cwd });
+    if (!check.ok) {
+      warnings.push(`${command} check failed: ${message}`);
+    }
+  }
+
+  const ghCheck = probeOk('gh', ['--version'], { ...options, cwd });
+  if (!ghCheck.ok) {
+    warnings.push('gh check failed: GitHub CLI is required for `ai pr` and `ai doctor`. macOS: brew install gh. Linux: use your distro package manager. Windows: winget install GitHub.cli.');
+  } else {
+    const authCheck = probeOk('gh', ['auth', 'status'], { ...options, cwd });
+    if (!authCheck.ok) {
+      warnings.push('gh auth check failed: run `gh auth login` before using `ai pr --create`.');
+    }
+  }
+
+  if (!process.env.SHELL && !process.env.ComSpec) {
+    warnings.push('shell check failed: no SHELL or ComSpec environment variable was detected.');
+  }
+
+  if (projectRoot.includes(' ')) {
+    warnings.push('path contains spaces: use quoted paths when copying manual commands.');
+  }
+
+  try {
+    fs.accessSync(projectRoot, fs.constants.W_OK);
+  } catch {
+    warnings.push('permission check failed: current user cannot write to the project root.');
+  }
+
+  return warnings;
+}
+
 function collectDoctorWarnings(projectRoot) {
   const warnings = [];
 
@@ -316,11 +612,24 @@ function collectDoctorWarnings(projectRoot) {
     warnings.push(`stack information appears outside docs/PROJECT_MAP.md: ${leakIssues.join(', ')}`);
   }
 
+  const missingLinks = collectMissingMarkdownLinks(projectRoot);
+  for (const issue of missingLinks) {
+    warnings.push(`missing local docs link: ${issue}`);
+  }
+
+  for (const issue of collectEnvironmentWarnings(projectRoot)) {
+    warnings.push(issue);
+  }
+
   return warnings;
 }
 
 module.exports = {
+  applyDoctorFixPlan,
+  buildDoctorFixPlan,
   collectDoctorReport,
+  collectEnvironmentWarnings,
   collectDoctorWarnings,
   collectLayoutReport,
+  formatDoctorFixPlan,
 };

package/src/create-quiver/lib/evidence.js

@@ -0,0 +1,115 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('node:child_process');
+
+const DEFAULT_OUTPUT_LIMIT = 4000;
+
+function redactSecrets(text) {
+  return String(text || '')
+    .replace(/(authorization:\s*bearer\s+)[^\s`'"]+/gi, '$1[REDACTED]')
+    .replace(/\b((?:api[_-]?key|token|secret|password|passwd|pwd)[A-Z0-9_-]*\s*[:=]\s*)[^\s`'"]+/gi, '$1[REDACTED]')
+    .replace(/\b(npm_[A-Za-z0-9]{20,})\b/g, '[REDACTED_NPM_TOKEN]');
+}
+
+function truncateText(text, maxLength = DEFAULT_OUTPUT_LIMIT) {
+  const value = String(text || '');
+  if (value.length <= maxLength) {
+    return {
+      text: value,
+      truncated: false,
+    };
+  }
+
+  return {
+    text: `${value.slice(0, maxLength)}\n[... truncated ${value.length - maxLength} chars ...]`,
+    truncated: true,
+  };
+}
+
+function quoteCommandPart(value) {
+  const part = String(value || '');
+  return /\s/.test(part) ? JSON.stringify(part) : part;
+}
+
+function formatCommand(commandArgs) {
+  return commandArgs.map(quoteCommandPart).join(' ');
+}
+
+function defaultEvidencePath(repoRoot, startedAt = new Date()) {
+  const stamp = startedAt.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+  return path.join(repoRoot, '.quiver', 'evidence', `evidence-${stamp}.md`);
+}
+
+function renderEvidenceMarkdown(record) {
+  return `# Quiver Evidence
+
+- Command: \`${record.command}\`
+- Exit code: ${record.exit_code}
+- Duration ms: ${record.duration_ms}
+- Started at: ${record.started_at}
+- Finished at: ${record.finished_at}
+- Output truncated: ${record.output_truncated ? 'yes' : 'no'}
+
+## Stdout
+
+\`\`\`\`text
+${record.stdout || ''}
+\`\`\`\`
+
+## Stderr
+
+\`\`\`\`text
+${record.stderr || ''}
+\`\`\`\`
+`;
+}
+
+function runEvidenceCommand(repoRoot, commandArgs, options = {}) {
+  if (!Array.isArray(commandArgs) || commandArgs.length === 0) {
+    throw new Error('create-quiver: evidence run requires a command after --');
+  }
+
+  const startedAtDate = new Date();
+  const started = Date.now();
+  const result = (options.spawnSync || spawnSync)(commandArgs[0], commandArgs.slice(1), {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    shell: false,
+  });
+  const finishedAtDate = new Date();
+  const duration = Date.now() - started;
+  const exitCode = typeof result.status === 'number' ? result.status : 1;
+  const stdout = truncateText(redactSecrets(result.stdout || ''), options.maxOutput || DEFAULT_OUTPUT_LIMIT);
+  const stderr = truncateText(redactSecrets(result.stderr || result.error?.message || ''), options.maxOutput || DEFAULT_OUTPUT_LIMIT);
+  const record = {
+    command: redactSecrets(formatCommand(commandArgs)),
+    duration_ms: duration,
+    exit_code: exitCode,
+    finished_at: finishedAtDate.toISOString(),
+    output_truncated: stdout.truncated || stderr.truncated,
+    stderr: stderr.text,
+    stdout: stdout.text,
+    started_at: startedAtDate.toISOString(),
+  };
+  const outputPath = options.outputPath
+    ? path.resolve(repoRoot, options.outputPath)
+    : defaultEvidencePath(repoRoot, startedAtDate);
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, renderEvidenceMarkdown(record));
+
+  return {
+    exitCode,
+    outputPath,
+    record,
+  };
+}
+
+module.exports = {
+  DEFAULT_OUTPUT_LIMIT,
+  defaultEvidencePath,
+  redactSecrets,
+  renderEvidenceMarkdown,
+  runEvidenceCommand,
+  truncateText,
+};

package/src/create-quiver/lib/handoff.js

@@ -10,6 +10,36 @@ const REQUIRED_HEADINGS = [
   '## Constraints',
 ];
 
+const EXECUTION_BRIEF_REQUIRED_HEADINGS = [
+  {
+    label: 'context',
+    alternatives: ['## Context', '## Contexto'],
+  },
+  {
+    label: 'objective',
+    alternatives: ['## Objective', '## Objetivo'],
+  },
+  {
+    label: 'acceptance criteria',
+    alternatives: ['## Acceptance Criteria', '## Criterios de aceptacion', '## Criterios de aceptación'],
+  },
+  {
+    label: 'completion checklist',
+    alternatives: ['## Completion Checklist', '## Checklist de finalizacion', '## Checklist de finalización'],
+  },
+];
+
+const CLOSURE_BRIEF_REQUIRED_HEADINGS = [
+  {
+    label: 'summary',
+    alternatives: ['## Summary', '## Summary of Work', '## Resumen de lo realizado'],
+  },
+  {
+    label: 'validation',
+    alternatives: ['## Validation', '## Validation Against Acceptance Criteria', '## Validacion contra criterios de aceptacion', '## Validación contra criterios de aceptación'],
+  },
+];
+
 const HANDOFF_TEMPLATE_PATH = path.resolve(__dirname, '..', '..', '..', 'specs', '[project-name]', 'HANDOFF.md.template');
 
 function normalizePosixPath(filePath, pathLib = path) {
@@ -21,19 +51,36 @@ function resolveHandoffPath(repoRoot, handoffInput, pathLib = path) {
   const relativePath = normalizePosixPath(pathLib.relative(repoRoot, absolutePath), pathLib);
 
   if (relativePath.startsWith('..') || pathLib.isAbsolute(relativePath)) {
-    throw new Error(`create-quiver: handoff must live at specs/<spec-slug>/HANDOFF.md (got ${normalizePosixPath(handoffInput, pathLib)})`);
+    throw new Error(`create-quiver: handoff or brief must live under specs/<spec-slug>/ (got ${normalizePosixPath(handoffInput, pathLib)})`);
+  }
+
+  const handoffMatch = relativePath.match(/^(specs|specs-fix)\/([^/]+)\/HANDOFF\.md$/);
+  if (handoffMatch) {
+    return {
+      absolutePath,
+      relativePath,
+      specFamily: handoffMatch[1],
+      specSlug: handoffMatch[2],
+      kind: 'handoff',
+      label: 'Handoff',
+    };
   }
 
-  const match = relativePath.match(/^specs\/([^/]+)\/HANDOFF\.md$/);
-  if (!match) {
-    throw new Error(`create-quiver: handoff must live at specs/<spec-slug>/HANDOFF.md (got ${relativePath})`);
+  const briefMatch = relativePath.match(/^(specs|specs-fix)\/([^/]+)\/slices\/([^/]+)\/(EXECUTION_BRIEF|CLOSURE_BRIEF)\.md$/);
+  if (briefMatch) {
+    const briefName = briefMatch[4];
+    return {
+      absolutePath,
+      relativePath,
+      specFamily: briefMatch[1],
+      specSlug: briefMatch[2],
+      sliceId: briefMatch[3],
+      kind: briefName === 'EXECUTION_BRIEF' ? 'execution-brief' : 'closure-brief',
+      label: briefName === 'EXECUTION_BRIEF' ? 'Execution brief' : 'Closure brief',
+    };
   }
 
-  return {
-    absolutePath,
-    relativePath,
-    specSlug: match[1],
-  };
+  throw new Error(`create-quiver: handoff or brief must live at specs/<spec-slug>/HANDOFF.md or specs/<spec-slug>/slices/<slice-id>/EXECUTION_BRIEF.md|CLOSURE_BRIEF.md (got ${relativePath})`);
 }
 
 function readHandoffSections(text) {
@@ -49,17 +96,36 @@ function validateHandoffSections(text) {
   return REQUIRED_HEADINGS.filter((heading) => !sections.has(heading));
 }
 
+function normalizeHeading(heading) {
+  return String(heading || '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .trim()
+    .toLowerCase();
+}
+
+function validateBriefSections(text, kind) {
+  const sections = new Set(readHandoffSections(text).map(normalizeHeading));
+  const requiredGroups = kind === 'closure-brief' ? CLOSURE_BRIEF_REQUIRED_HEADINGS : EXECUTION_BRIEF_REQUIRED_HEADINGS;
+
+  return requiredGroups
+    .filter((group) => !group.alternatives.some((heading) => sections.has(normalizeHeading(heading))))
+    .map((group) => group.label);
+}
+
 function checkHandoff(handoffInput, repoRoot = process.cwd()) {
   const resolved = resolveHandoffPath(repoRoot, handoffInput);
 
   if (!fs.existsSync(resolved.absolutePath)) {
-    throw new Error(`create-quiver: missing handoff file: ${resolved.relativePath}`);
+    throw new Error(`create-quiver: missing ${resolved.label.toLowerCase()} file: ${resolved.relativePath}`);
   }
 
   const text = fs.readFileSync(resolved.absolutePath, 'utf8');
-  const missingSections = validateHandoffSections(text);
+  const missingSections = resolved.kind === 'handoff'
+    ? validateHandoffSections(text)
+    : validateBriefSections(text, resolved.kind);
   if (missingSections.length > 0) {
-    throw new Error(`create-quiver: handoff is missing required sections: ${missingSections.join(', ')}`);
+    throw new Error(`create-quiver: ${resolved.label.toLowerCase()} is missing required sections: ${missingSections.join(', ')}`);
   }
 
   return resolved;
@@ -95,10 +161,13 @@ function scaffoldHandoff(specSlug, repoRoot = process.cwd()) {
 }
 
 module.exports = {
+  CLOSURE_BRIEF_REQUIRED_HEADINGS,
+  EXECUTION_BRIEF_REQUIRED_HEADINGS,
   REQUIRED_HEADINGS,
   checkHandoff,
   readHandoffSections,
   scaffoldHandoff,
   resolveHandoffPath,
+  validateBriefSections,
   validateHandoffSections,
 };