create-quiver 0.9.1 → 0.12.0

package/src/create-quiver/commands/next.js

@@ -12,12 +12,23 @@ function collectNext(repoRoot, options = {}) {
     onlyReady: true,
     specSlug: options.specSlug,
   });
+  const historyReport = options.includeCompleted
+    ? collectPlan(repoRoot, {
+        includeCompleted: true,
+        specSlug: options.specSlug,
+      })
+    : null;
 
   const allReady = report.plan.filter((item) => String(item.status || '').toLowerCase() !== 'blocked');
   const next = allReady.length > 0 ? allReady[0] : null;
+  const history = historyReport
+    ? historyReport.plan.filter((item) => String(item.status || '').toLowerCase() === 'completed')
+    : [];
 
   return {
     all_ready: allReady,
+    history,
+    include_completed: options.includeCompleted === true,
     next,
   };
 }
@@ -27,6 +38,13 @@ function formatHumanNext(report, options = {}) {
 
   if (!report.next) {
     lines.push('No ready slices found.');
+    if (report.include_completed && report.history.length > 0) {
+      lines.push('');
+      lines.push('Historical slices included by --include-completed:');
+      for (const item of report.history) {
+        lines.push(`- ${item.ref} (${item.status})`);
+      }
+    }
     return `${lines.join('\n')}\n`;
   }
 
@@ -51,6 +69,14 @@ function formatHumanNext(report, options = {}) {
     }
   }
 
+  if (report.include_completed && report.history.length > 0) {
+    lines.push('');
+    lines.push('Historical slices included by --include-completed:');
+    for (const item of report.history) {
+      lines.push(`- ${item.ref} (${item.status})`);
+    }
+  }
+
   return `${lines.join('\n')}\n`;
 }
 
@@ -110,6 +136,8 @@ async function runNext(repoRoot, options = {}) {
         ...item,
         start_slice_command: toStartSliceCommand(item.slice_path),
       })),
+      history: report.history,
+      include_completed: report.include_completed,
       next: report.next
         ? {
             ...report.next,

package/src/create-quiver/commands/plan.js

@@ -4,6 +4,7 @@ const { relativePosixPath } = require('../lib/paths');
 const { buildGraph, readAllSlices, topoSort } = require('../lib/slice-graph');
 
 const EXCLUDED_STATUSES = new Set(['completed', 'skipped', 'cancelled']);
+const HISTORY_EXCLUDED_STATUSES = new Set(['skipped', 'cancelled']);
 
 function toHourCount(value) {
   const parsed = Number(value);
@@ -118,7 +119,8 @@ function collectPlan(repoRoot, options = {}) {
   const allSlices = readAllSlices(repoRoot);
   const graph = buildGraph(allSlices);
   const topo = topoSort(graph);
-  const excluded = EXCLUDED_STATUSES;
+  const includeCompleted = options.includeCompleted === true;
+  const excluded = includeCompleted ? HISTORY_EXCLUDED_STATUSES : EXCLUDED_STATUSES;
   const specSlug = options.specSlug ? String(options.specSlug).trim() : '';
 
   const pendingRefs = new Set(
@@ -147,6 +149,7 @@ function collectPlan(repoRoot, options = {}) {
 
   return {
     critical_path: criticalPath,
+    include_completed: includeCompleted,
     plan,
     total_hours: totalHours,
   };
@@ -154,12 +157,12 @@ function collectPlan(repoRoot, options = {}) {
 
 function formatHumanPlan(report, options = {}) {
   const unicode = Boolean(options.unicode) || /UTF-8/i.test(process.env.LANG || '');
-  const title = options.onlyReady ? 'Ready slices' : 'Quiver plan';
+  const title = options.onlyReady ? 'Ready slices' : (report.include_completed ? 'Quiver plan (including completed)' : 'Quiver plan');
   const pathSeparator = unicode ? ' → ' : ' -> ';
   const lines = [title, `Total hours: ${report.total_hours}`, `Critical path: ${report.critical_path.length > 0 ? report.critical_path.join(pathSeparator) : '-'}`, ''];
 
   if (report.plan.length === 0) {
-    lines.push('No pending slices found.');
+    lines.push(report.include_completed ? 'No slices found for the selected filters.' : 'No pending slices found.');
     return `${lines.join('\n')}\n`;
   }
 

package/src/create-quiver/commands/prepare.js

@@ -0,0 +1,236 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { collectDoctorReport } = require('../lib/doctor');
+const { ensureGhAuthenticated, ensureGhInstalled, ensureIdentityFile } = require('../lib/ai/github');
+const { collectOnboardingContextPlan } = require('../lib/ai/onboarding-template');
+const { preflightProvider } = require('../lib/ai/preflight');
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function summarizeError(error) {
+  return {
+    code: error && error.code ? error.code : 'UNKNOWN_ERROR',
+    message: error && error.message ? error.message : String(error),
+    details: error && error.details ? error.details : undefined,
+  };
+}
+
+function collectCheckStatus(label, runner, sink) {
+  try {
+    const value = runner();
+    sink.status = 'ok';
+    sink.value = value;
+    return value;
+  } catch (error) {
+    sink.status = 'missing';
+    sink.error = summarizeError(error);
+    return null;
+  }
+}
+
+function buildNextSteps(report) {
+  const nextSteps = [];
+
+  if (report.gh.status !== 'ok') {
+    nextSteps.push('Install GitHub CLI, then rerun `npx create-quiver prepare`.');
+  }
+
+  if (report.ssh.identityFileStatus === 'missing') {
+    nextSteps.push('Fix the SSH identity file path, then rerun `npx create-quiver prepare`.');
+  }
+
+  if (report.ssh.authStatus === 'missing') {
+    nextSteps.push('Run `gh auth login`, then rerun `npx create-quiver prepare`.');
+  }
+
+  if (report.provider.status === 'missing') {
+    nextSteps.push('Install the ' + report.provider.name + ' CLI, then rerun `npx create-quiver prepare --provider ' + report.provider.name + '`.');
+  }
+
+  if (nextSteps.length === 0) {
+    nextSteps.push('Run `npx create-quiver doctor` for the layout contract, then `npx create-quiver ai prepare-context --dry-run` to preview the context drafts.');
+  }
+
+  return nextSteps;
+}
+
+function formatListLine(label, value) {
+  if (Array.isArray(value)) {
+    return `${label}: ${value.length > 0 ? value.join(', ') : 'none'}`;
+  }
+
+  return `${label}: ${value}`;
+}
+
+function formatPrepareReport(report) {
+  const lines = [
+    'Quiver prepare report',
+    `Mode: ${report.dryRun ? 'dry-run' : 'live'}`,
+    `Project: ${report.projectRoot}`,
+    'Framework guidance: packaged README_FOR_AI.md template',
+    `Project docs copy: ${report.workflowSource.exists ? 'present' : 'absent (not counted as debt)'}`,
+    `Layout: ${report.doctor.layout}`,
+    formatListLine('Specs', report.doctor.specSlugs),
+  ];
+
+  if (report.doctor.warnings.length > 0) {
+    lines.push(`Doctor warnings: ${report.doctor.warnings.join(' | ')}`);
+  }
+
+  lines.push('Checks: project docs, GitHub CLI, GitHub auth when SSH inputs are provided, SSH identity file when passed, provider CLI when passed');
+
+  lines.push('Onboarding context:');
+  lines.push(`- prompt source: ${report.onboarding.promptSource}`);
+  lines.push(`- selected docs: ${report.onboarding.selectedDocs.length > 0 ? report.onboarding.selectedDocs.map((item) => item.path).join(', ') : 'none'}`);
+  lines.push(`- documentation debt: ${report.onboarding.missingDocs.length > 0 ? report.onboarding.missingDocs.map((item) => item.path).join(', ') : 'none'}`);
+  lines.push(`- omitted by default: ${report.onboarding.omittedByDefault.join(' | ')}`);
+
+  if (report.onboarding.risks.length > 0) {
+    lines.push(`- onboarding risks: ${report.onboarding.risks.join(' | ')}`);
+  }
+
+  lines.push('GitHub CLI:');
+  if (report.gh.status === 'ok') {
+    lines.push(`- available (${report.gh.value.command})`);
+  } else {
+    lines.push(`- missing`);
+    lines.push(`- ${report.gh.error.message}`);
+  }
+
+  lines.push('SSH:');
+  lines.push(`- host alias: ${report.ssh.hostAlias || 'not provided'}`);
+  if (report.ssh.identityFile) {
+    lines.push(`- identity file: ${report.ssh.identityFile}`);
+  } else if (report.ssh.identityFileStatus === 'skipped') {
+    lines.push('- identity file: not requested');
+  } else if (report.ssh.identityFileStatus === 'missing') {
+    lines.push(`- identity file: missing (${report.ssh.identityError.message})`);
+  }
+  if (report.ssh.authStatus === 'ok') {
+    lines.push('- auth: ok');
+  } else if (report.ssh.authStatus === 'missing') {
+    lines.push(`- auth: missing (${report.ssh.authError.message})`);
+  } else {
+    lines.push('- auth: not requested');
+  }
+
+  if (report.provider.name) {
+    lines.push(`Provider CLI (${report.provider.name}):`);
+    if (report.provider.status === 'ok') {
+      lines.push(`- available (${report.provider.value.command})`);
+    } else {
+      lines.push(`- missing (${report.provider.error.message})`);
+    }
+  } else {
+    lines.push('Provider CLI: not requested');
+  }
+
+  lines.push('Next safe commands:');
+  for (const step of report.nextSteps) {
+    lines.push(`- ${step}`);
+  }
+
+  if (report.dryRun) {
+    lines.push('Dry-run note: this command does not write files.');
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+async function runPrepare(repoRoot, options = {}) {
+  const doctorReport = collectDoctorReport(repoRoot);
+  const workflowSourcePath = path.join(repoRoot, 'README_FOR_AI.md');
+  const onboarding = collectOnboardingContextPlan(repoRoot);
+  const report = {
+    dryRun: options.dryRun === true,
+    doctor: doctorReport,
+    gh: { status: 'skipped', value: null, error: null },
+    nextSteps: [],
+    onboarding,
+    projectRoot: repoRoot,
+    provider: { name: '', status: 'skipped', value: null, error: null },
+    ssh: {
+      authError: null,
+      authStatus: 'skipped',
+      hostAlias: String(options.sshHostAlias || '').trim(),
+      identityError: null,
+      identityFile: '',
+      identityFileStatus: 'skipped',
+      status: 'skipped',
+    },
+    workflowSource: {
+      exists: fs.existsSync(workflowSourcePath),
+      path: workflowSourcePath,
+    },
+  };
+
+  collectCheckStatus(
+    'gh',
+    () => ensureGhInstalled({
+      cwd: repoRoot,
+      ghCommand: options.ghCommand,
+      ghProbe: options.ghProbe,
+      ghProbeArgs: options.ghProbeArgs,
+    }),
+    report.gh,
+  );
+
+  if (report.ssh.hostAlias || options.identityFile) {
+    report.ssh.status = 'requested';
+
+    if (options.identityFile) {
+      try {
+        report.ssh.identityFile = ensureIdentityFile(repoRoot, options.identityFile);
+        report.ssh.identityFileStatus = 'ok';
+      } catch (error) {
+        report.ssh.identityFileStatus = 'missing';
+        report.ssh.identityError = summarizeError(error);
+      }
+    }
+
+    if (report.gh.status === 'ok') {
+      try {
+        const auth = ensureGhAuthenticated({
+          cwd: repoRoot,
+          ghAuthArgs: options.ghAuthArgs,
+          ghAuthProbe: options.ghAuthProbe,
+          ghCommand: options.ghCommand,
+          ghProbe: options.ghProbe,
+        });
+        report.ssh.authStatus = 'ok';
+        report.ssh.auth = auth;
+      } catch (error) {
+        report.ssh.authStatus = 'missing';
+        report.ssh.authError = summarizeError(error);
+      }
+    } else {
+      report.ssh.authStatus = 'skipped';
+    }
+  }
+
+  if (options.provider) {
+    report.provider.name = String(options.provider).trim().toLowerCase();
+    collectCheckStatus(
+      'provider',
+      () => preflightProvider(report.provider.name, {
+        cwd: repoRoot,
+        probe: options.providerProbe,
+        probeArgs: options.providerProbeArgs,
+      }),
+      report.provider,
+    );
+  }
+
+  report.nextSteps = buildNextSteps(report);
+
+  process.stdout.write(formatPrepareReport(report));
+  return report;
+}
+
+module.exports = {
+  formatPrepareReport,
+  runPrepare,
+};

package/src/create-quiver/commands/spec.js

@@ -0,0 +1,133 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { resolveReviewedTechnicalPlanInput } = require('../lib/ai/plan-review');
+const {
+  buildSpecGenerationManifest,
+  describeSpecGeneration,
+  generateSpecArtifacts,
+} = require('../lib/ai/spec-generator');
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function toRelativePosix(root, filePath) {
+  return path.relative(root, filePath).split(path.sep).join('/');
+}
+
+function readInputText(repoRoot, inputPath) {
+  const resolved = path.resolve(repoRoot, inputPath || '');
+  if (!inputPath || !fs.existsSync(resolved)) {
+    throw new Error(formatError(`missing reviewed and approved plan input: ${inputPath || '<default>'}`));
+  }
+  return fs.readFileSync(resolved, 'utf8');
+}
+
+function buildSpecCreatePreview(repoRoot, options = {}) {
+  const resolved = resolveReviewedTechnicalPlanInput(repoRoot, options.input || undefined);
+  const inputPath = resolved.inputPath;
+  const inputText = readInputText(repoRoot, inputPath);
+  const manifest = buildSpecGenerationManifest({
+    inputPath,
+    inputText,
+    repoRoot,
+    specSlug: options.specSlug,
+  });
+  const preview = describeSpecGeneration(manifest, repoRoot);
+  const relativeSpecDir = toRelativePosix(repoRoot, preview.specDir);
+
+  if (fs.existsSync(preview.specDir)) {
+    throw new Error(formatError(`spec directory already exists: ${relativeSpecDir}`));
+  }
+
+  return {
+    inputPath,
+    manifest,
+    preview,
+    relativeSpecDir,
+  };
+}
+
+function formatNextCommands(specDir) {
+  return [
+    'Next safe commands:',
+    `- npx create-quiver spec start ${specDir}`,
+    `- npx create-quiver spec status ${specDir}`,
+    '- npx create-quiver next',
+    '- npx create-quiver ai execute-plan --dry-run --commit',
+  ];
+}
+
+function formatSpecCreateDryRun(preview) {
+  const lines = [
+    'Quiver spec create dry-run',
+    `Spec slug: ${preview.manifest.slug}`,
+    `Title: ${preview.manifest.title}`,
+    `Input file: ${preview.inputPath}`,
+    `Target: ${preview.relativeSpecDir}`,
+    `Planned files: ${preview.preview.files.length}`,
+  ];
+
+  for (const file of preview.preview.files) {
+    lines.push(`- ${file}`);
+  }
+
+  lines.push(...formatNextCommands(preview.relativeSpecDir));
+  lines.push('No files will be written in dry-run mode.');
+  return `${lines.join('\n')}\n`;
+}
+
+function formatSpecCreateResult(result, repoRoot) {
+  const relativeSpecDir = toRelativePosix(repoRoot, result.specDir);
+  const lines = [
+    'Quiver spec created',
+    `Spec slug: ${result.manifest.slug}`,
+    `Target: ${relativeSpecDir}`,
+    `Files written: ${result.files.length}`,
+  ];
+
+  for (const filePath of result.files) {
+    lines.push(`- ${toRelativePosix(repoRoot, filePath)}`);
+  }
+
+  lines.push(...formatNextCommands(relativeSpecDir));
+  return `${lines.join('\n')}\n`;
+}
+
+function runCreateSpec(repoRoot, options = {}) {
+  const preview = buildSpecCreatePreview(repoRoot, options);
+
+  if (options.dryRun) {
+    process.stdout.write(formatSpecCreateDryRun(preview));
+    return {
+      task: 'spec-create',
+      dryRun: true,
+      manifest: preview.manifest,
+      specDir: preview.relativeSpecDir,
+      files: preview.preview.files,
+    };
+  }
+
+  const result = generateSpecArtifacts(repoRoot, {
+    input: preview.inputPath,
+    specSlug: options.specSlug,
+  });
+  process.stdout.write(formatSpecCreateResult(result, repoRoot));
+
+  return {
+    task: 'spec-create',
+    dryRun: false,
+    specSlug: result.manifest.slug,
+    specDir: toRelativePosix(repoRoot, result.specDir),
+    files: result.files.map((filePath) => toRelativePosix(repoRoot, filePath)),
+    manifest: result.manifest,
+  };
+}
+
+module.exports = {
+  buildSpecCreatePreview,
+  formatSpecCreateDryRun,
+  formatSpecCreateResult,
+  runCreateSpec,
+};