create-quiver 0.12.0 → 0.12.1

package/src/create-quiver/lib/ai/export-state.js

@@ -0,0 +1,534 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { listAgentProfiles } = require('../agent-profiles');
+const { collectLayoutReport } = require('../doctor');
+const { buildGraph, computeLevels, detectFileConflicts, readAllSlices, SliceGraphError } = require('../slice-graph');
+const { listAiRuns, nextCommandForPhase } = require('./run-state');
+
+const EXPORT_SCHEMA_VERSION = 1;
+
+function toPosix(relativePath) {
+  return String(relativePath || '').split(path.sep).join('/');
+}
+
+function relativePath(projectRoot, filePath) {
+  return toPosix(path.relative(projectRoot, filePath));
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function readPackageSummary(projectRoot) {
+  const packageJson = readJsonIfExists(path.join(projectRoot, 'package.json'));
+
+  return {
+    name: packageJson?.name || path.basename(projectRoot) || 'project',
+    package_manager: fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))
+      ? 'pnpm'
+      : fs.existsSync(path.join(projectRoot, 'yarn.lock'))
+        ? 'yarn'
+        : 'npm',
+  };
+}
+
+function isCompletedStatus(status) {
+  return ['closed', 'completed', 'done'].includes(String(status || '').toLowerCase());
+}
+
+function isBlockedStatus(slice) {
+  return String(slice?.status || '').toLowerCase() === 'blocked' || Boolean(slice?.json?.blocked_reason);
+}
+
+function progressForSlice(slice) {
+  const explicit = Number(slice?.json?.progress);
+  if (Number.isFinite(explicit)) {
+    return Math.max(0, Math.min(100, explicit));
+  }
+
+  const status = String(slice?.status || '').toLowerCase();
+  if (isCompletedStatus(status)) {
+    return 100;
+  }
+  if (status === 'in-progress' || status === 'active' || status === 'review') {
+    return 50;
+  }
+  return 0;
+}
+
+function summarizeProgress(items) {
+  const total = items.length;
+  const completed = items.filter((item) => isCompletedStatus(item.status)).length;
+  const blocked = items.filter((item) => isBlockedStatus(item)).length;
+  const open = Math.max(0, total - completed);
+  const percent = total === 0 ? 0 : Math.round((completed / total) * 100);
+
+  return {
+    total,
+    completed,
+    open,
+    blocked,
+    percent,
+  };
+}
+
+function statusForSpec(specSlices) {
+  if (specSlices.length === 0) {
+    return 'empty';
+  }
+  if (specSlices.some((slice) => isBlockedStatus(slice))) {
+    return 'blocked';
+  }
+  if (specSlices.every((slice) => isCompletedStatus(slice.status))) {
+    return 'done';
+  }
+  if (specSlices.some((slice) => progressForSlice(slice) > 0)) {
+    return 'in-progress';
+  }
+  return 'planned';
+}
+
+function groupSlicesBySpec(slices) {
+  const groups = new Map();
+
+  for (const slice of slices) {
+    const key = `${slice.specFamily}/${slice.specSlug}`;
+    if (!groups.has(key)) {
+      groups.set(key, []);
+    }
+    groups.get(key).push(slice);
+  }
+
+  return Array.from(groups.entries())
+    .map(([key, specSlices]) => {
+      const [specFamily, specSlug] = key.split('/');
+      return { specFamily, specSlug, slices: specSlices };
+    })
+    .sort((left, right) => left.specSlug.localeCompare(right.specSlug));
+}
+
+function buildGraphSummary(slices) {
+  try {
+    const graph = buildGraph(slices);
+    const levels = computeLevels(graph).map((level, index) => ({
+      level: index,
+      slices: level.map((slice) => slice.ref),
+    }));
+
+    return {
+      ok: true,
+      edges: graph.edges.map((edge) => ({ from: edge.from, to: edge.to })),
+      levels,
+      conflicts: detectFileConflicts(graph.nodes).map((conflict) => ({
+        files: conflict.files,
+        slices: conflict.slices,
+      })),
+      error: null,
+      nodes: graph.nodes,
+    };
+  } catch (error) {
+    if (error instanceof SliceGraphError) {
+      return {
+        ok: false,
+        edges: [],
+        levels: [],
+        conflicts: [],
+        error: {
+          code: error.code,
+          message: error.message,
+        },
+        nodes: slices,
+      };
+    }
+    throw error;
+  }
+}
+
+function filterGraphSummary(graph, selectedRefs) {
+  if (!graph.ok) {
+    return graph;
+  }
+
+  const levels = graph.levels
+    .map((level) => ({
+      original_level: level.level,
+      slices: level.slices.filter((ref) => selectedRefs.has(ref)),
+    }))
+    .filter((level) => level.slices.length > 0)
+    .map((level, index) => ({
+      level: index,
+      original_level: level.original_level,
+      slices: level.slices,
+    }));
+
+  return {
+    ...graph,
+    edges: graph.edges.filter((edge) => selectedRefs.has(edge.to)),
+    levels,
+    conflicts: graph.conflicts
+      .map((conflict) => ({
+        files: conflict.files,
+        slices: conflict.slices.filter((ref) => selectedRefs.has(ref)),
+      }))
+      .filter((conflict) => conflict.slices.length > 1),
+  };
+}
+
+function normalizeSlice(projectRoot, slice, dependencyMap) {
+  const dependencies = dependencyMap.get(slice.ref) || slice.depends_on || slice.dependencies || [];
+
+  return {
+    ref: slice.ref,
+    id: slice.sliceId,
+    title: slice.title,
+    status: slice.status,
+    progress: progressForSlice(slice),
+    spec_slug: slice.specSlug,
+    spec_family: slice.specFamily,
+    path: relativePath(projectRoot, slice.sliceDir),
+    slice_json: toPosix(path.join(slice.specFamily, slice.specSlug, 'slices', path.basename(slice.sliceDir), 'slice.json')),
+    dependencies,
+    parallel_safe: slice.parallel_safe,
+    parallel_safe_reason: slice.parallel_safe_reason,
+    allowed_write_paths: slice.allowed_write_paths,
+    expected_read_paths: slice.expected_read_paths,
+    validation_hints: slice.validation_hints,
+    files: slice.files,
+    evidence: Array.isArray(slice.json?.evidence) ? slice.json.evidence : [],
+    tests: Array.isArray(slice.json?.tests) ? slice.json.tests : [],
+    blocked_reason: slice.json?.blocked_reason || null,
+  };
+}
+
+function normalizeRuns(projectRoot) {
+  return listAiRuns(projectRoot).map((run) => ({
+    run_id: run.run_id,
+    status: run.status,
+    phase: run.phase,
+    spec_slug: run.spec_slug || null,
+    requirement_path: run.requirement?.path || null,
+    approvals_path: run.approvals_path || null,
+    state_path: toPosix(path.join('.quiver', 'runs', run.run_id, 'state.json')),
+    next_command: nextCommandForPhase(run.phase),
+    updated_at: run.updated_at || run.created_at || null,
+  }));
+}
+
+function normalizeAgents(projectRoot) {
+  return listAgentProfiles(projectRoot).map((item) => ({
+    role: item.role,
+    configured: item.configured,
+    provider: item.profile?.provider || null,
+    model: item.profile?.model || null,
+    label: item.profile?.label || null,
+    context: item.profile?.context || null,
+    updated_at: item.profile?.updated_at || null,
+  }));
+}
+
+function collectLifecycleExport(projectRoot, options = {}) {
+  const allSlices = readAllSlices(projectRoot);
+  const slices = options.includeCompleted ? allSlices : allSlices.filter((slice) => !isCompletedStatus(slice.status));
+  const fullGraph = buildGraphSummary(allSlices);
+  const selectedRefs = new Set(slices.map((slice) => slice.ref));
+  const graph = filterGraphSummary(fullGraph, selectedRefs);
+  if (graph.ok) {
+    graph.conflicts = detectFileConflicts(slices).map((conflict) => ({
+      files: conflict.files,
+      slices: conflict.slices,
+    }));
+  }
+  const dependencyMap = new Map(fullGraph.nodes.map((node) => [node.ref, node.depends_on || node.dependencies || []]));
+  const normalizedSlices = slices.map((slice) => normalizeSlice(projectRoot, slice, dependencyMap));
+  const specs = groupSlicesBySpec(slices).map((spec) => {
+    const progress = summarizeProgress(spec.slices);
+    const specPath = path.join(spec.specFamily, spec.specSlug);
+    return {
+      slug: spec.specSlug,
+      family: spec.specFamily,
+      path: specPath,
+      spec_path: fs.existsSync(path.join(projectRoot, specPath, 'SPEC.md')) ? toPosix(path.join(specPath, 'SPEC.md')) : null,
+      status_path: fs.existsSync(path.join(projectRoot, specPath, 'STATUS.md')) ? toPosix(path.join(specPath, 'STATUS.md')) : null,
+      pr_path: fs.existsSync(path.join(projectRoot, specPath, 'pr.md')) ? toPosix(path.join(specPath, 'pr.md')) : null,
+      status: statusForSpec(spec.slices),
+      progress,
+      slices: spec.slices.map((slice) => slice.ref),
+      blockers: spec.slices.filter((slice) => isBlockedStatus(slice)).map((slice) => ({
+        ref: slice.ref,
+        reason: slice.json?.blocked_reason || 'blocked',
+      })),
+    };
+  });
+  const layout = collectLayoutReport(projectRoot);
+  const runs = normalizeRuns(projectRoot);
+  const agents = normalizeAgents(projectRoot);
+  const progress = summarizeProgress(slices);
+  const blockers = normalizedSlices
+    .filter((slice) => slice.blocked_reason || String(slice.status).toLowerCase() === 'blocked')
+    .map((slice) => ({ ref: slice.ref, reason: slice.blocked_reason || 'blocked' }));
+
+  if (!graph.ok) {
+    blockers.push({ ref: 'slice-graph', reason: graph.error.message });
+  }
+  if (layout.layout === 'legacy' || layout.layout === 'hybrid' || layout.layout === 'incomplete') {
+    blockers.push({ ref: 'migration', reason: layout.recommendations.join(' ') });
+  }
+
+  return {
+    schema_version: EXPORT_SCHEMA_VERSION,
+    generated_at: new Date().toISOString(),
+    project: readPackageSummary(projectRoot),
+    summary: {
+      specs: specs.length,
+      slices: progress.total,
+      completed_slices: progress.completed,
+      open_slices: progress.open,
+      blocked_slices: progress.blocked,
+      progress_percent: progress.percent,
+      runs: runs.length,
+      configured_agents: agents.filter((agent) => agent.configured).length,
+    },
+    agents,
+    runs,
+    specs,
+    slices: normalizedSlices,
+    graph: {
+      ok: graph.ok,
+      edges: graph.edges,
+      levels: graph.levels,
+      conflicts: graph.conflicts,
+      error: graph.error,
+    },
+    migration: {
+      layout: layout.layout,
+      has_new_layout: layout.hasNewLayout,
+      has_legacy_layout: layout.hasLegacyLayout,
+      legacy_signals: layout.legacySignals,
+      missing_new_layout_files: layout.missingNewLayoutFiles,
+      recommendations: layout.recommendations,
+      dry_run_command: 'npx create-quiver migrate --dry-run',
+    },
+    dashboard: {
+      progress,
+      blockers,
+      agents: agents.map((agent) => ({
+        id: agent.role,
+        role: agent.role,
+        configured: agent.configured,
+        provider: agent.provider,
+      })),
+      specs: specs.map((spec) => ({
+        id: spec.slug,
+        status: spec.status,
+        progress: spec.progress.percent,
+        slice_count: spec.progress.total,
+        blockers: spec.blockers,
+      })),
+      slices: normalizedSlices.map((slice) => ({
+        id: slice.ref,
+        status: slice.status,
+        progress: slice.progress,
+        dependencies: slice.dependencies,
+        blocker: slice.blocked_reason,
+      })),
+      dependencies: graph.edges,
+    },
+  };
+}
+
+function formatLifecycleInspect(data) {
+  const lines = [
+    'Quiver lifecycle inspect',
+    `Project: ${data.project.name}`,
+    `Specs: ${data.summary.specs}`,
+    `Slices: ${data.summary.slices} total, ${data.summary.open_slices} open, ${data.summary.blocked_slices} blocked, ${data.summary.progress_percent}% done`,
+    `Runs: ${data.summary.runs}`,
+    `Agents configured: ${data.summary.configured_agents}/${data.agents.length}`,
+    `Layout: ${data.migration.layout}`,
+    '',
+    'Next safe commands',
+  ];
+
+  const activeRun = [...data.runs].reverse().find((run) => run.status !== 'closed');
+  lines.push(`- ${activeRun ? activeRun.next_command : 'npx create-quiver ai run create --input <requirements.md>'}`);
+
+  if (data.summary.slices > 0) {
+    lines.push('- npx create-quiver ai slices list');
+    lines.push('- npx create-quiver ai export --format json');
+  } else {
+    lines.push('- npx create-quiver ai plan --phase acceptance --input <requirements.md> --dry-run');
+  }
+
+  if (data.migration.layout === 'legacy' || data.migration.layout === 'hybrid' || data.migration.layout === 'incomplete') {
+    lines.push('- npx create-quiver migrate --dry-run');
+  }
+
+  if (data.dashboard.blockers.length > 0) {
+    lines.push('', 'Blockers');
+    for (const blocker of data.dashboard.blockers) {
+      lines.push(`- ${blocker.ref}: ${blocker.reason}`);
+    }
+  }
+
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function formatSpecsList(data) {
+  const lines = ['Quiver specs list'];
+
+  if (data.specs.length === 0) {
+    lines.push('- No specs found. Next: npx create-quiver spec create --dry-run');
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+  }
+
+  for (const spec of data.specs) {
+    lines.push(`- ${spec.slug}: ${spec.status}, ${spec.progress.percent}% done, ${spec.progress.total} slices (${spec.path})`);
+  }
+
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function formatSlicesList(data) {
+  const lines = ['Quiver slices list'];
+
+  if (data.slices.length === 0) {
+    lines.push('- No slices found. Next: npx create-quiver spec create --dry-run');
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+  }
+
+  for (const slice of data.slices) {
+    const deps = slice.dependencies.length > 0 ? ` deps=${slice.dependencies.join(',')}` : '';
+    const blocked = slice.blocked_reason ? ` blocked=${slice.blocked_reason}` : '';
+    lines.push(`- ${slice.ref}: ${slice.status}, ${slice.progress}% done${deps}${blocked}`);
+  }
+
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function formatTraceReport(data) {
+  const lines = [
+    'Quiver trace report',
+    `Project: ${data.project.name}`,
+    `Schema: ${data.schema_version}`,
+    '',
+    'Runs',
+  ];
+
+  if (data.runs.length === 0) {
+    lines.push('- none');
+  } else {
+    for (const run of data.runs) {
+      lines.push(`- ${run.run_id}: ${run.phase} (${run.status}) -> ${run.next_command}`);
+    }
+  }
+
+  lines.push('', 'Execution waves');
+  if (!data.graph.ok) {
+    lines.push(`- graph error: ${data.graph.error.message}`);
+  } else if (data.graph.levels.length === 0) {
+    lines.push('- none');
+  } else {
+    for (const level of data.graph.levels) {
+      lines.push(`- wave ${level.level}: ${level.slices.join(', ')}`);
+    }
+  }
+
+  lines.push('', 'Migration');
+  lines.push(`- layout: ${data.migration.layout}`);
+  for (const recommendation of data.migration.recommendations) {
+    lines.push(`- ${recommendation}`);
+  }
+
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function formatLifecycleExportMarkdown(data) {
+  const lines = [
+    '# Quiver Lifecycle Export',
+    '',
+    `- Project: ${data.project.name}`,
+    `- Generated: ${data.generated_at}`,
+    `- Schema version: ${data.schema_version}`,
+    `- Specs: ${data.summary.specs}`,
+    `- Slices: ${data.summary.slices} total, ${data.summary.completed_slices} completed, ${data.summary.open_slices} open`,
+    `- Progress: ${data.summary.progress_percent}%`,
+    `- Layout: ${data.migration.layout}`,
+    '',
+    '## Specs',
+    '',
+  ];
+
+  if (data.specs.length === 0) {
+    lines.push('No specs found.');
+  } else {
+    lines.push('| Spec | Status | Progress | Slices | Path |');
+    lines.push('|---|---|---:|---:|---|');
+    for (const spec of data.specs) {
+      lines.push(`| ${spec.slug} | ${spec.status} | ${spec.progress.percent}% | ${spec.progress.total} | ${spec.path} |`);
+    }
+  }
+
+  lines.push('', '## Slices', '');
+  if (data.slices.length === 0) {
+    lines.push('No slices found.');
+  } else {
+    lines.push('| Slice | Status | Progress | Dependencies | Write Scope |');
+    lines.push('|---|---|---:|---|---|');
+    for (const slice of data.slices) {
+      lines.push(`| ${slice.ref} | ${slice.status} | ${slice.progress}% | ${slice.dependencies.join(', ') || '-'} | ${slice.allowed_write_paths.join(', ') || slice.files.join(', ') || '-'} |`);
+    }
+  }
+
+  lines.push('', '## Agents', '');
+  if (data.agents.length === 0) {
+    lines.push('No agent roles available.');
+  } else {
+    lines.push('| Role | Configured | Provider | Model |');
+    lines.push('|---|---|---|---|');
+    for (const agent of data.agents) {
+      lines.push(`| ${agent.role} | ${agent.configured ? 'yes' : 'no'} | ${agent.provider || '-'} | ${agent.model || '-'} |`);
+    }
+  }
+
+  lines.push('', '## Runs', '');
+  if (data.runs.length === 0) {
+    lines.push('No AI runs found.');
+  } else {
+    lines.push('| Run | Phase | Status | Next Command |');
+    lines.push('|---|---|---|---|');
+    for (const run of data.runs) {
+      lines.push(`| ${run.run_id} | ${run.phase} | ${run.status} | \`${run.next_command}\` |`);
+    }
+  }
+
+  lines.push('', '## Migration', '');
+  lines.push(`- Layout: ${data.migration.layout}`);
+  for (const recommendation of data.migration.recommendations) {
+    lines.push(`- ${recommendation}`);
+  }
+  lines.push(`- Dry-run: \`${data.migration.dry_run_command}\``);
+  lines.push('');
+
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = {
+  EXPORT_SCHEMA_VERSION,
+  collectLifecycleExport,
+  formatLifecycleExportMarkdown,
+  formatLifecycleInspect,
+  formatSlicesList,
+  formatSpecsList,
+  formatTraceReport,
+};

package/src/create-quiver/lib/ai/github.js

@@ -4,6 +4,8 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
 const { currentBranch, hasRemote, isCleanWorktree } = require('../git');
+const { parseJsonWithComments } = require('../json');
+const { formatActionableError } = require('../actionable-error');
 
 const DEFAULT_GH_COMMAND = 'gh';
 const DEFAULT_REMOTE = 'origin';
@@ -249,6 +251,82 @@ function ensureIdentityFile(repoRoot, identityFile) {
   return resolved;
 }
 
+function ensureSshHostAlias(sshHostAlias) {
+  const value = String(sshHostAlias || '').trim();
+  if (!value) {
+    throw createError(
+      'MISSING_SSH_HOST_ALIAS',
+      formatActionableError({
+        failure: 'missing SSH host alias. Pass --ssh-host-alias <alias> before opening the PR.',
+        impact: 'Quiver cannot verify which GitHub SSH identity should be used for this PR flow.',
+        fix: 'macOS/Linux: add a Host entry in ~/.ssh/config, for example `Host github-work`. Windows: add the Host entry in %USERPROFILE%\\.ssh\\config.',
+        nextCommand: 'ssh -T <alias>',
+      }),
+    );
+  }
+  return value;
+}
+
+function prBodySpecDir(repoRoot, prBodyPath) {
+  const relative = path.relative(repoRoot, prBodyPath).split(path.sep).join('/');
+  const parts = relative.split('/');
+  if (parts[0] !== 'specs' || parts.length !== 3 || parts[2] !== 'pr.md') {
+    return '';
+  }
+  return path.join(repoRoot, parts[0], parts[1]);
+}
+
+function listOpenSlicesForSpec(specDir) {
+  const slicesDir = path.join(specDir, 'slices');
+  if (!fs.existsSync(slicesDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(slicesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const slicePath = path.join(slicesDir, entry.name, 'slice.json');
+      if (!fs.existsSync(slicePath)) {
+        return null;
+      }
+      const json = parseJsonWithComments(fs.readFileSync(slicePath, 'utf8'));
+      const status = String(json.status || 'draft').trim() || 'draft';
+      return {
+        id: json.slice_id || entry.name,
+        status,
+      };
+    })
+    .filter(Boolean)
+    .filter((slice) => slice.status !== 'completed')
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function ensureNoOpenSlicesForPrBody(repoRoot, prBodyPath) {
+  const specDir = prBodySpecDir(repoRoot, prBodyPath);
+  if (!specDir) {
+    return [];
+  }
+
+  const openSlices = listOpenSlicesForSpec(specDir);
+  if (openSlices.length > 0) {
+    throw createError(
+      'OPEN_SLICES',
+      formatActionableError({
+        failure: `cannot create PR while spec slices are still open: ${openSlices.map((slice) => `${slice.id} (${slice.status})`).join(', ')}.`,
+        impact: 'The PR would not represent a closed spec and could miss required slice commits or evidence.',
+        fix: 'Finish, validate, and close every slice in the spec before creating the PR.',
+        nextCommand: 'npx create-quiver ai execute-plan --dry-run --commit',
+      }),
+      {
+        openSlices,
+        specDir,
+      },
+    );
+  }
+
+  return openSlices;
+}
+
 function findPrBodyCandidates(repoRoot) {
   const candidates = [];
   const rootPr = path.join(repoRoot, 'pr.md');
@@ -352,6 +430,7 @@ function buildPrCreateArgs(plan) {
 
 function buildPrCreatePlan(repoRoot, preflightReport, options = {}) {
   const prBody = readPrBody(repoRoot, options.prBodyPath || options.input);
+  ensureNoOpenSlicesForPrBody(repoRoot, prBody.path);
   const baseBranch = String(options.baseBranch || 'main').trim() || 'main';
   const title = String(options.title || '').trim() || extractPrTitle(prBody.body, preflightReport.branchName);
   const plan = {
@@ -420,6 +499,7 @@ function preflightGitHubPr(repoRoot, options = {}) {
   const guidePath = ensureGitFlowGuide(repoRoot, options.gitFlowGuidePath);
   const remote = ensureRemote(repoRoot, options.remote || DEFAULT_REMOTE);
   const branchName = ensureWorktreeReady(repoRoot, options);
+  const sshHostAlias = ensureSshHostAlias(options.sshHostAlias);
   const identityFile = ensureIdentityFile(repoRoot, options.identityFile);
 
   return buildPreflightReport(repoRoot, options, {
@@ -428,6 +508,7 @@ function preflightGitHubPr(repoRoot, options = {}) {
     guidePath,
     remote,
     branchName,
+    sshHostAlias,
     identityFile,
   });
 }
@@ -511,7 +592,9 @@ module.exports = {
   ensureGhInstalled,
   ensureGitFlowGuide,
   ensureIdentityFile,
+  ensureNoOpenSlicesForPrBody,
   ensureRemote,
+  ensureSshHostAlias,
   ensureWorktreeReady,
   findPrBodyCandidates,
   formatGhInstallGuidance,