create-quiver 0.9.1 → 0.12.0

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

@@ -1,6 +1,42 @@
 const fs = require('fs');
 const path = require('path');
+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',
+  'AGENTS.md',
+  'package.json',
+  'docs/AI_CONTEXT.md',
+  'docs/AI_ONBOARDING_PROMPT.md',
+  'docs/COMMANDS.md',
+  'docs/WORKFLOW.md',
+  '.quiver/state.json',
+  '.quiver/config.json',
+  '.quiver/.gitignore',
+];
+
+const LEGACY_LAYOUT_PROBES = [
+  'docs-template/',
+  'tools/scripts/start-slice.sh',
+  'tools/scripts/check-slice-readiness.sh',
+  'tools/scripts/check-pr-readiness.sh',
+  '.github/pull_request_template.md',
+  'docs/PROJECT_SCAN.json',
+];
+
+const ROOT_GITIGNORE_DEFAULTS = [
+  'node_modules/',
+  '.DS_Store',
+  'dist/',
+  'coverage/',
+];
 
 function readTextIfExists(filePath) {
   if (!fs.existsSync(filePath)) {
@@ -10,6 +46,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/)
@@ -30,6 +94,18 @@ function normalizeRelativePath(root, absolutePath) {
   return path.relative(root, absolutePath).split(path.sep).join('/');
 }
 
+function hasPath(projectRoot, relativePath) {
+  return fs.existsSync(path.join(projectRoot, relativePath));
+}
+
+function collectPresentPaths(projectRoot, relativePaths) {
+  return relativePaths.filter((relativePath) => hasPath(projectRoot, relativePath));
+}
+
+function collectMissingPaths(projectRoot, relativePaths) {
+  return relativePaths.filter((relativePath) => !hasPath(projectRoot, relativePath));
+}
+
 function collectAiMarkdownFiles(projectRoot) {
   const aiDir = path.join(projectRoot, 'docs', 'ai');
   if (!fs.existsSync(aiDir)) {
@@ -174,6 +250,268 @@ 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);
+  const specSlugs = Array.from(new Set(realSlices.map((slice) => slice.specSlug))).sort((left, right) => left.localeCompare(right));
+  const newLayoutFiles = collectPresentPaths(projectRoot, NEW_LAYOUT_REQUIRED_PATHS);
+  const missingNewLayoutFiles = collectMissingPaths(projectRoot, NEW_LAYOUT_REQUIRED_PATHS);
+  const legacySignals = collectPresentPaths(projectRoot, LEGACY_LAYOUT_PROBES);
+  const hasLegacyProjectSpec = hasGeneratedProjectSpec(projectRoot);
+
+  if (hasLegacyProjectSpec) {
+    legacySignals.push('specs/<project-slug>/SPEC.md');
+  }
+
+  const hasNewLayout = missingNewLayoutFiles.length === 0;
+  const hasLegacyLayout = legacySignals.length > 0;
+
+  let layout = 'incomplete';
+  if (hasNewLayout && hasLegacyLayout) {
+    layout = 'hybrid';
+  } else if (hasNewLayout) {
+    layout = 'new';
+  } else if (hasLegacyLayout) {
+    layout = 'legacy';
+  }
+
+  const recommendations = [];
+
+  if (layout === 'new') {
+    if (specSlugs.length === 0) {
+      recommendations.push('No specs yet. That is valid after the AI-first init flow.');
+    } else {
+      recommendations.push(`Specs found: ${specSlugs.join(', ')}.`);
+    }
+
+    if (!hasPath(projectRoot, 'docs/PROJECT_MAP.md')) {
+      recommendations.push('Run `npx create-quiver analyze` to generate docs/PROJECT_MAP.md when you want the visible project map.');
+    }
+  } else if (layout === 'legacy') {
+    recommendations.push('Legacy layout detected. Run `npx create-quiver migrate` to add the modern .quiver/ contract and AI-first docs.');
+  } else if (layout === 'hybrid') {
+    recommendations.push('Hybrid layout detected. Keep the new .quiver/ contract as the source of truth and plan cleanup of legacy roots.');
+    recommendations.push('Review any remaining docs-template/, tools/scripts/, or docs/PROJECT_SCAN.json paths and migrate them only if they are still needed.');
+  } else {
+    recommendations.push('Incomplete layout detected. Restore the missing AI-first contract files before relying on this project for onboarding.');
+    if (missingNewLayoutFiles.length > 0) {
+      recommendations.push(`Missing files: ${missingNewLayoutFiles.join(', ')}.`);
+    }
+    if (!hasStateMetadata && !hasLegacyLayout) {
+      recommendations.push('Run `npx create-quiver --name "Project Name"` or `npx create-quiver init` to create the Quiver contract first.');
+    }
+  }
+
+  return {
+    hasLegacyLayout,
+    hasNewLayout,
+    hasStateMetadata,
+    layout,
+    legacySignals,
+    missingNewLayoutFiles,
+    newLayoutFiles,
+    recommendations,
+    realSlices,
+    specSlugs,
+  };
+}
+
+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);
+
+  return {
+    ...layout,
+    warnings,
+  };
+}
+
 function collectDoctorWarnings(projectRoot) {
   const warnings = [];
 
@@ -204,9 +542,19 @@ 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}`);
+  }
+
   return warnings;
 }
 
 module.exports = {
+  applyDoctorFixPlan,
+  buildDoctorFixPlan,
+  collectDoctorReport,
   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/git.js

@@ -101,6 +101,23 @@ function statusPorcelain(repoRoot) {
   return tryGit(['status', '--porcelain'], repoRoot);
 }
 
+function remoteList(repoRoot) {
+  const output = tryGit(['remote'], repoRoot);
+  return output ? output.split('\n').map((line) => line.trim()).filter(Boolean) : [];
+}
+
+function hasRemote(repoRoot, remoteName = 'origin') {
+  return remoteList(repoRoot).includes(remoteName);
+}
+
+function isCleanWorktree(repoRoot) {
+  return statusPorcelain(repoRoot) === '';
+}
+
+function isDetachedHead(repoRoot) {
+  return currentBranch(repoRoot) === '';
+}
+
 function revListCount(repoRoot, range) {
   const output = tryGit(['rev-list', '--count', range], repoRoot);
   return Number(output || '0');
@@ -143,7 +160,11 @@ module.exports = {
   hasRemoteBranch,
   lsRemoteHeads,
   mergeBaseIsAncestor,
+  hasRemote,
+  isCleanWorktree,
+  isDetachedHead,
   revListCount,
+  remoteList,
   runGit,
   statusPorcelain,
   tryGit,