create-quiver 0.6.0 → 0.8.0

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

@@ -0,0 +1,9 @@
+const { runAnalyze } = require('../index');
+
+function analyzeProject(targetDir) {
+  return runAnalyze(targetDir);
+}
+
+module.exports = {
+  analyzeProject,
+};

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

@@ -0,0 +1,212 @@
+const fs = require('fs');
+const path = require('path');
+const { worktreeList } = require('./git');
+
+function readTextIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function countNonEmptyLines(text) {
+  return String(text || '')
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .length;
+}
+
+function hasFrontMatter(text) {
+  const value = String(text || '');
+  if (!value.startsWith('---\n')) {
+    return false;
+  }
+
+  return value.indexOf('\n---\n', 4) !== -1;
+}
+
+function normalizeRelativePath(root, absolutePath) {
+  return path.relative(root, absolutePath).split(path.sep).join('/');
+}
+
+function collectAiMarkdownFiles(projectRoot) {
+  const aiDir = path.join(projectRoot, 'docs', 'ai');
+  if (!fs.existsSync(aiDir)) {
+    return [];
+  }
+
+  const 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(aiDir);
+
+  return files;
+}
+
+function countDocsAiFrontMatterIssues(projectRoot) {
+  const files = collectAiMarkdownFiles(projectRoot);
+  const missing = [];
+
+  for (const filePath of files) {
+    const text = readTextIfExists(filePath);
+    if (!text || !hasFrontMatter(text)) {
+      missing.push(normalizeRelativePath(projectRoot, filePath));
+    }
+  }
+
+  return missing;
+}
+
+function countAgentsSections(projectRoot) {
+  const agentsPath = path.join(projectRoot, 'AGENTS.md');
+  const text = readTextIfExists(agentsPath);
+  if (!text) {
+    return ['AGENTS.md'];
+  }
+
+  const requiredSections = [
+    [/^Purpose$/m, 'Purpose'],
+    [/^## Reading Budget$/m, 'Reading Budget'],
+    [/^## Reading Order$/m, 'Reading Order'],
+    [/^## Output Policy$/m, 'Output Policy'],
+    [/^## Slice Execution Rules$/m, 'Slice Execution Rules'],
+    [/^## Links$/m, 'Links'],
+  ];
+
+  const missing = requiredSections
+    .filter(([pattern]) => !pattern.test(text))
+    .map(([, label]) => label);
+  return missing;
+}
+
+function countTieredPackSizeWarnings(projectRoot) {
+  const warnings = [];
+
+  const quickPath = path.join(projectRoot, 'docs', 'ai', 'QUICK.md');
+  const quickText = readTextIfExists(quickPath);
+  if (quickText && countNonEmptyLines(quickText) > 50) {
+    warnings.push(`docs/ai/QUICK.md exceeds the 50 non-empty line budget (${countNonEmptyLines(quickText)})`);
+  }
+
+  const standardPath = path.join(projectRoot, 'docs', 'ai', 'STANDARD.md');
+  const standardText = readTextIfExists(standardPath);
+  if (standardText && countNonEmptyLines(standardText) > 300) {
+    warnings.push(`docs/ai/STANDARD.md exceeds the 300 non-empty line budget (${countNonEmptyLines(standardText)})`);
+  }
+
+  return warnings;
+}
+
+function countActiveSliceOrphans(projectRoot) {
+  const activeSlicePath = path.join(projectRoot, 'docs', 'ai', 'ACTIVE_SLICE.md');
+  if (!fs.existsSync(activeSlicePath)) {
+    return [];
+  }
+
+  const activeWorktrees = worktreeList(projectRoot).filter((entry) => {
+    const worktreePath = entry.worktree || '';
+    if (!worktreePath || worktreePath === projectRoot) {
+      return false;
+    }
+
+    return fs.existsSync(path.join(worktreePath, 'WORKTREE_CONTEXT.md'));
+  });
+
+  if (activeWorktrees.length === 0) {
+    return ['docs/ai/ACTIVE_SLICE.md exists without an active slice worktree'];
+  }
+
+  return [];
+}
+
+function countStackInfoLeaks(projectRoot) {
+  const leakPatterns = [
+    /Package manager:/i,
+    /Detected package manager:/i,
+    /Detected primary stack:/i,
+    /Primary install:/i,
+    /Primary test:/i,
+    /Stack summary:/i,
+  ];
+
+  const generatedFiles = [];
+  const docsDir = path.join(projectRoot, 'docs');
+
+  if (fs.existsSync(docsDir)) {
+    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') && path.relative(docsDir, fullPath) !== 'PROJECT_MAP.md') {
+          generatedFiles.push(fullPath);
+        }
+      }
+    };
+
+    walk(docsDir);
+  }
+
+  const leaks = [];
+
+  for (const filePath of generatedFiles) {
+    const text = readTextIfExists(filePath);
+    if (!text) {
+      continue;
+    }
+
+    if (leakPatterns.some((pattern) => pattern.test(text))) {
+      leaks.push(normalizeRelativePath(projectRoot, filePath));
+    }
+  }
+
+  return leaks;
+}
+
+function collectDoctorWarnings(projectRoot) {
+  const warnings = [];
+
+  const agentsMissing = countAgentsSections(projectRoot);
+  if (agentsMissing.length > 0) {
+    if (agentsMissing.includes('AGENTS.md')) {
+      warnings.push('missing AGENTS.md');
+    } else {
+      warnings.push(`AGENTS.md is missing required sections: ${agentsMissing.join(', ')}`);
+    }
+  }
+
+  for (const issue of countTieredPackSizeWarnings(projectRoot)) {
+    warnings.push(issue);
+  }
+
+  const frontMatterIssues = countDocsAiFrontMatterIssues(projectRoot);
+  for (const issue of frontMatterIssues) {
+    warnings.push(`${issue} is missing YAML front matter`);
+  }
+
+  for (const issue of countActiveSliceOrphans(projectRoot)) {
+    warnings.push(issue);
+  }
+
+  const leakIssues = countStackInfoLeaks(projectRoot);
+  if (leakIssues.length > 0) {
+    warnings.push(`stack information appears outside docs/PROJECT_MAP.md: ${leakIssues.join(', ')}`);
+  }
+
+  return warnings;
+}
+
+module.exports = {
+  collectDoctorWarnings,
+};

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

@@ -0,0 +1,154 @@
+const cp = require('child_process');
+
+function runGit(args, cwd, options = {}) {
+  return cp.execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    ...options,
+  }).trim();
+}
+
+function tryGit(args, cwd, options = {}) {
+  try {
+    return runGit(args, cwd, options);
+  } catch {
+    return '';
+  }
+}
+
+function hasRef(repoRoot, ref) {
+  try {
+    runGit(['show-ref', '--verify', '--quiet', ref], repoRoot);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function hasLocalBranch(repoRoot, branchName) {
+  return hasRef(repoRoot, `refs/heads/${branchName}`);
+}
+
+function hasRemoteBranch(repoRoot, branchName, remote = 'origin') {
+  return hasRef(repoRoot, `refs/remotes/${remote}/${branchName}`);
+}
+
+function fetchBranch(repoRoot, branchName, remote = 'origin') {
+  return runGit(['fetch', remote, `${branchName}:${branchName}`], repoRoot);
+}
+
+function fetchRemote(repoRoot, remote = 'origin', args = ['--prune']) {
+  return runGit(['fetch', remote, ...args], repoRoot);
+}
+
+function worktreePrune(repoRoot) {
+  tryGit(['worktree', 'prune'], repoRoot);
+}
+
+function worktreeList(repoRoot) {
+  const text = tryGit(['worktree', 'list', '--porcelain'], repoRoot);
+  const entries = [];
+  const chunks = text.trim().split('\n\n').filter(Boolean);
+
+  for (const chunk of chunks) {
+    const entry = {};
+    for (const line of chunk.split('\n')) {
+      const idx = line.indexOf(' ');
+      if (idx === -1) {
+        continue;
+      }
+      entry[line.slice(0, idx)] = line.slice(idx + 1);
+    }
+    if (entry.worktree) {
+      entries.push(entry);
+    }
+  }
+
+  return entries;
+}
+
+function worktreeAdd(repoRoot, worktreePath, ref, options = {}) {
+  const args = ['worktree', 'add'];
+  if (options.branch) {
+    args.push('-b', options.branch);
+  }
+  if (options.force) {
+    args.push('--force');
+  }
+  args.push(worktreePath, ref);
+  return runGit(args, repoRoot);
+}
+
+function worktreeRemove(repoRoot, worktreePath, force = false) {
+  const args = ['worktree', 'remove'];
+  if (force) {
+    args.push('--force');
+  }
+  args.push(worktreePath);
+  return runGit(args, repoRoot);
+}
+
+function branchDelete(repoRoot, branchName, force = false) {
+  return runGit(['branch', force ? '-D' : '-d', branchName], repoRoot);
+}
+
+function currentBranch(repoRoot) {
+  return tryGit(['branch', '--show-current'], repoRoot);
+}
+
+function statusPorcelain(repoRoot) {
+  return tryGit(['status', '--porcelain'], repoRoot);
+}
+
+function revListCount(repoRoot, range) {
+  const output = tryGit(['rev-list', '--count', range], repoRoot);
+  return Number(output || '0');
+}
+
+function mergeBaseIsAncestor(repoRoot, maybeAncestor, ref) {
+  try {
+    runGit(['merge-base', '--is-ancestor', maybeAncestor, ref], repoRoot);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function lsRemoteHeads(repoRoot, branchName, remote = 'origin') {
+  try {
+    runGit(['ls-remote', '--exit-code', '--heads', remote, branchName], repoRoot);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function catFileExists(repoRoot, specRef) {
+  try {
+    runGit(['cat-file', '-e', specRef], repoRoot);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  branchDelete,
+  catFileExists,
+  currentBranch,
+  fetchBranch,
+  fetchRemote,
+  hasLocalBranch,
+  hasRemoteBranch,
+  lsRemoteHeads,
+  mergeBaseIsAncestor,
+  revListCount,
+  runGit,
+  statusPorcelain,
+  tryGit,
+  worktreeAdd,
+  worktreeList,
+  worktreePrune,
+  worktreeRemove,
+};

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

@@ -0,0 +1,104 @@
+const fs = require('fs');
+const path = require('path');
+
+const REQUIRED_HEADINGS = [
+  '## Background',
+  '## What you will change',
+  '## Validation checklist',
+  '## Out of scope',
+  '## Expected deliverable',
+  '## Constraints',
+];
+
+const HANDOFF_TEMPLATE_PATH = path.resolve(__dirname, '..', '..', '..', 'specs', '[project-name]', 'HANDOFF.md.template');
+
+function normalizePosixPath(filePath, pathLib = path) {
+  return filePath.split(pathLib.sep).join('/');
+}
+
+function resolveHandoffPath(repoRoot, handoffInput, pathLib = path) {
+  const absolutePath = pathLib.resolve(repoRoot, handoffInput);
+  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)})`);
+  }
+
+  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})`);
+  }
+
+  return {
+    absolutePath,
+    relativePath,
+    specSlug: match[1],
+  };
+}
+
+function readHandoffSections(text) {
+  return String(text || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('## '))
+    .map((line) => line.replace(/\s+$/, ''));
+}
+
+function validateHandoffSections(text) {
+  const sections = new Set(readHandoffSections(text));
+  return REQUIRED_HEADINGS.filter((heading) => !sections.has(heading));
+}
+
+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}`);
+  }
+
+  const text = fs.readFileSync(resolved.absolutePath, 'utf8');
+  const missingSections = validateHandoffSections(text);
+  if (missingSections.length > 0) {
+    throw new Error(`create-quiver: handoff is missing required sections: ${missingSections.join(', ')}`);
+  }
+
+  return resolved;
+}
+
+function scaffoldHandoff(specSlug, repoRoot = process.cwd()) {
+  const trimmedSlug = String(specSlug || '').trim();
+  if (!trimmedSlug) {
+    throw new Error('create-quiver: missing handoff slug. Use: npx create-quiver new-handoff <spec-slug>');
+  }
+
+  if (!fs.existsSync(HANDOFF_TEMPLATE_PATH)) {
+    throw new Error('create-quiver: missing handoff template at specs/[project-name]/HANDOFF.md.template');
+  }
+
+  const resolved = resolveHandoffPath(repoRoot, path.join('specs', trimmedSlug, 'HANDOFF.md'));
+  if (fs.existsSync(resolved.absolutePath)) {
+    throw new Error(`create-quiver: handoff already exists at ${resolved.relativePath}`);
+  }
+
+  const templateText = fs.readFileSync(HANDOFF_TEMPLATE_PATH, 'utf8');
+  const projectName = trimmedSlug.replace(/-/g, ' ');
+  const currentDate = new Date().toISOString().slice(0, 10);
+  const renderedText = templateText
+    .replace(/{{PROJECT_NAME}}/g, projectName)
+    .replace(/{{PROJECT_SLUG}}/g, trimmedSlug)
+    .replace(/{{FECHA}}/g, currentDate);
+
+  fs.mkdirSync(path.dirname(resolved.absolutePath), { recursive: true });
+  fs.writeFileSync(resolved.absolutePath, renderedText);
+
+  return checkHandoff(resolved.relativePath, repoRoot);
+}
+
+module.exports = {
+  REQUIRED_HEADINGS,
+  checkHandoff,
+  readHandoffSections,
+  scaffoldHandoff,
+  resolveHandoffPath,
+  validateHandoffSections,
+};