create-quiver 0.13.0 → 0.14.1

package/src/create-quiver/lib/ai/context-proposal.js

@@ -0,0 +1,389 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { redactSensitiveLocalValues } = require('./artifacts');
+const { getPreparedContextDocPaths } = require('./context-packs');
+const { contextProposalSchema } = require('./context-proposal.schema');
+const { quiverInternalPaths } = require('../init-layout');
+const {
+  getProjectRelativePathIssue,
+  validateProjectRelativePath,
+} = require('../paths');
+
+const INVALID_PROPOSAL_ARTIFACT_SCHEMA_VERSION = 1;
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+class ContextProposalError extends Error {
+  constructor(message, issues = []) {
+    super(formatError(message));
+    this.name = 'ContextProposalError';
+    this.code = 'AI_CONTEXT_PROPOSAL_INVALID';
+    this.issues = issues;
+    this.safeNextSteps = [
+      'Run deterministic prepare-context without --with-planner if you need the safest fallback.',
+      'Rerun with --with-planner --print-prompt and ask the planner to return only valid JSON.',
+      'Review the blocked paths and keep proposal writes limited to approved docs-only context files.',
+    ];
+  }
+}
+
+function normalizeProposalShape(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return value;
+  }
+
+  const proposal = { ...value };
+  if (!proposal.docs && Array.isArray(proposal.files)) {
+    proposal.docs = proposal.files;
+    delete proposal.files;
+  }
+  if (proposal.schemaVersion && !proposal.schema_version) {
+    proposal.schema_version = proposal.schemaVersion;
+    delete proposal.schemaVersion;
+  }
+  if (proposal.nextSteps && !proposal.next_steps) {
+    proposal.next_steps = proposal.nextSteps;
+    delete proposal.nextSteps;
+  }
+  if (proposal.omittedPaths && !proposal.omitted_paths) {
+    proposal.omitted_paths = proposal.omittedPaths;
+    delete proposal.omittedPaths;
+  }
+
+  return proposal;
+}
+
+function getAllowedContextProposalPaths() {
+  return getPreparedContextDocPaths();
+}
+
+function classifyDisallowedContextPath(relativePath) {
+  const normalized = String(relativePath || '').replace(/\\/g, '/').toLowerCase();
+
+  if (/^(src|app|apps|packages|lib|server|client|web)\//.test(normalized)) {
+    return 'product-code';
+  }
+  if (/^(package(?:-lock)?|npm-shrinkwrap)\.json$/.test(normalized)
+    || /^pnpm-lock\.yaml$/.test(normalized)
+    || /^yarn\.lock$/.test(normalized)
+    || /^bun\.lockb?$/.test(normalized)) {
+    return 'dependency-or-lockfile';
+  }
+  if (/^(vite|next|webpack|rollup|tsconfig|jsconfig|babel|postcss|tailwind|eslint|prettier|turbo|vercel|netlify|dockerfile|compose)(\.|$)/i.test(normalized)) {
+    return 'build-or-runtime-config';
+  }
+  if (/^(dist|build|coverage|out|generated|gen|artifacts|reports)\//.test(normalized)) {
+    return 'generated-output';
+  }
+  if (/^\.quiver\//.test(normalized)) {
+    return 'quiver-internal-state';
+  }
+  if (!normalized.startsWith('docs/')) {
+    return 'not-a-context-doc';
+  }
+  return 'unapproved-context-doc';
+}
+
+function validateContextProposalPath(filePath, options = {}) {
+  const issue = getProjectRelativePathIssue(filePath, options.pathLib);
+  if (issue) {
+    return {
+      ok: false,
+      path: String(filePath || ''),
+      issue,
+      message: `path must be project-relative and stay inside the repository (issue=${issue})`,
+    };
+  }
+
+  let normalized;
+  try {
+    normalized = validateProjectRelativePath(filePath, 'planner proposal path', options.pathLib);
+  } catch (error) {
+    return {
+      ok: false,
+      path: String(filePath || ''),
+      issue: 'invalid-project-relative-path',
+      message: error.message,
+    };
+  }
+
+  const allowed = new Set(options.allowedPaths || getAllowedContextProposalPaths());
+  if (!allowed.has(normalized)) {
+    const issueName = classifyDisallowedContextPath(normalized);
+    return {
+      ok: false,
+      path: normalized,
+      issue: issueName,
+      message: `path is not approved for planner context writes (${issueName}). Allowed paths: ${Array.from(allowed).join(', ')}`,
+    };
+  }
+
+  return {
+    ok: true,
+    path: normalized,
+  };
+}
+
+function extractBalancedJsonObject(text) {
+  const input = String(text || '');
+  const start = input.indexOf('{');
+  if (start === -1) {
+    return null;
+  }
+
+  let depth = 0;
+  let quote = null;
+  let escaping = false;
+
+  for (let index = start; index < input.length; index += 1) {
+    const char = input[index];
+
+    if (escaping) {
+      escaping = false;
+      continue;
+    }
+    if (char === '\\') {
+      escaping = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === '{') {
+      depth += 1;
+    }
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        return input.slice(start, index + 1);
+      }
+    }
+  }
+
+  return null;
+}
+
+function parseJsonCandidate(jsonText, source) {
+  try {
+    return {
+      ok: true,
+      source,
+      value: JSON.parse(jsonText),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      source,
+      error,
+    };
+  }
+}
+
+function parsePlannerProposalJson(text) {
+  const input = String(text || '').trim();
+  if (!input) {
+    throw new ContextProposalError('planner proposal output is empty', [
+      { path: null, issue: 'empty-output', message: 'The planner returned no proposal JSON.' },
+    ]);
+  }
+
+  const direct = parseJsonCandidate(input, 'raw-json');
+  if (direct.ok) {
+    return direct;
+  }
+
+  const fencedMatches = Array.from(input.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi));
+  const parseFailures = [direct];
+  for (const match of fencedMatches) {
+    const parsed = parseJsonCandidate(match[1].trim(), 'fenced-json');
+    if (parsed.ok) {
+      return parsed;
+    }
+    parseFailures.push(parsed);
+  }
+
+  const balanced = extractBalancedJsonObject(input);
+  if (balanced) {
+    const parsed = parseJsonCandidate(balanced, 'embedded-json');
+    if (parsed.ok) {
+      return parsed;
+    }
+    parseFailures.push(parsed);
+  }
+
+  const firstError = parseFailures.find((item) => item.error)?.error;
+  throw new ContextProposalError('planner proposal output is not valid JSON', [
+    {
+      path: null,
+      issue: 'malformed-json',
+      message: firstError ? firstError.message : 'No JSON object or fenced JSON block could be parsed.',
+    },
+  ]);
+}
+
+function mapZodIssues(error) {
+  return error.issues.map((issue) => ({
+    path: issue.path.length > 0 ? issue.path.join('.') : null,
+    issue: issue.code,
+    message: issue.message,
+  }));
+}
+
+function normalizeStrings(values) {
+  return Array.from(new Set((Array.isArray(values) ? values : [])
+    .map((item) => String(item || '').trim())
+    .filter(Boolean)));
+}
+
+function normalizeContextProposal(value, options = {}) {
+  const proposal = normalizeProposalShape(value);
+  const parsed = contextProposalSchema.safeParse(proposal);
+  if (!parsed.success) {
+    throw new ContextProposalError('planner context proposal does not match the required schema', mapZodIssues(parsed.error));
+  }
+
+  const issues = [];
+  const seenPaths = new Set();
+  const docs = [];
+
+  for (const [index, doc] of parsed.data.docs.entries()) {
+    const pathResult = validateContextProposalPath(doc.path, options);
+    if (!pathResult.ok) {
+      issues.push({
+        index,
+        path: pathResult.path,
+        issue: pathResult.issue,
+        message: pathResult.message,
+      });
+      continue;
+    }
+
+    if (seenPaths.has(pathResult.path)) {
+      issues.push({
+        index,
+        path: pathResult.path,
+        issue: 'duplicate-path',
+        message: 'planner proposal contains multiple updates for the same context doc path',
+      });
+      continue;
+    }
+    seenPaths.add(pathResult.path);
+
+    if (doc.action !== 'skip' && !doc.content.trim()) {
+      issues.push({
+        index,
+        path: pathResult.path,
+        issue: 'missing-content',
+        message: 'create/update proposal entries require non-empty content',
+      });
+      continue;
+    }
+
+    docs.push({
+      path: pathResult.path,
+      action: doc.action,
+      content: doc.content,
+      reason: doc.reason,
+      assumptions: normalizeStrings(doc.assumptions),
+      risks: normalizeStrings(doc.risks),
+      source: 'planner-proposal',
+    });
+  }
+
+  if (issues.length > 0) {
+    throw new ContextProposalError('planner context proposal contains unsafe or ambiguous writes', issues);
+  }
+
+  return {
+    schemaVersion: parsed.data.schema_version,
+    kind: parsed.data.kind,
+    summary: parsed.data.summary,
+    assumptions: normalizeStrings(parsed.data.assumptions),
+    risks: normalizeStrings(parsed.data.risks),
+    omittedPaths: normalizeStrings(parsed.data.omitted_paths),
+    nextSteps: normalizeStrings(parsed.data.next_steps),
+    docs,
+    writePlan: docs
+      .filter((doc) => doc.action !== 'skip')
+      .map((doc) => ({
+        path: doc.path,
+        content: doc.content,
+        reason: doc.reason,
+        source: doc.source,
+      })),
+  };
+}
+
+function parseContextProposalOutput(text, options = {}) {
+  const parsed = parsePlannerProposalJson(text);
+  return {
+    ...normalizeContextProposal(parsed.value, options),
+    parseSource: parsed.source,
+  };
+}
+
+function safeArtifactName(now = new Date()) {
+  return `${now.toISOString()
+    .replace(/\.\d{3}Z$/, 'z')
+    .replace(/[^0-9a-z]+/gi, '-')
+    .toLowerCase()
+    .replace(/^-+|-+$/g, '')}-invalid-context-proposal.json`;
+}
+
+function writeInvalidContextProposalArtifact(projectRoot, runId, rawOutput, error, options = {}) {
+  if (!projectRoot) {
+    throw new Error(formatError('missing project root for invalid context proposal artifact'));
+  }
+  if (!runId) {
+    throw new Error(formatError('missing AI run id for invalid context proposal artifact'));
+  }
+
+  const now = options.now || new Date();
+  const artifactDir = path.join(quiverInternalPaths(projectRoot).runsDir, String(runId), 'raw');
+  const filePath = path.join(artifactDir, safeArtifactName(now));
+  const artifact = {
+    schema_version: INVALID_PROPOSAL_ARTIFACT_SCHEMA_VERSION,
+    kind: 'invalid-context-proposal',
+    created_at: now.toISOString(),
+    ok: false,
+    error: {
+      code: error?.code || 'AI_CONTEXT_PROPOSAL_INVALID',
+      message: error?.message || String(error || 'unknown error'),
+      issues: Array.isArray(error?.issues) ? error.issues : [],
+      safe_next_steps: Array.isArray(error?.safeNextSteps) ? error.safeNextSteps : [],
+    },
+    raw_output: redactSensitiveLocalValues(rawOutput, { projectRoot }),
+  };
+
+  fs.mkdirSync(artifactDir, { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(artifact, null, 2)}\n`);
+
+  return {
+    filePath,
+    path: path.relative(projectRoot, filePath).split(path.sep).join('/'),
+    artifact,
+  };
+}
+
+module.exports = {
+  INVALID_PROPOSAL_ARTIFACT_SCHEMA_VERSION,
+  ContextProposalError,
+  classifyDisallowedContextPath,
+  extractBalancedJsonObject,
+  getAllowedContextProposalPaths,
+  normalizeContextProposal,
+  parseContextProposalOutput,
+  parsePlannerProposalJson,
+  validateContextProposalPath,
+  writeInvalidContextProposalArtifact,
+};

package/src/create-quiver/lib/ai/context-proposal.schema.js

@@ -0,0 +1,31 @@
+const { z } = require('zod');
+
+const CONTEXT_PROPOSAL_SCHEMA_VERSION = 1;
+const MAX_DOC_CONTENT_LENGTH = 400_000;
+
+const contextProposalDocSchema = z.object({
+  path: z.string().trim().min(1, 'doc path is required'),
+  action: z.enum(['create', 'update', 'skip']).default('update'),
+  content: z.string().max(MAX_DOC_CONTENT_LENGTH).default(''),
+  reason: z.string().trim().max(2_000).default('Planner proposed this documentation update.'),
+  assumptions: z.array(z.string().trim().min(1)).default([]),
+  risks: z.array(z.string().trim().min(1)).default([]),
+});
+
+const contextProposalSchema = z.object({
+  schema_version: z.literal(CONTEXT_PROPOSAL_SCHEMA_VERSION).default(CONTEXT_PROPOSAL_SCHEMA_VERSION),
+  kind: z.literal('quiver-context-proposal').default('quiver-context-proposal'),
+  summary: z.string().trim().max(4_000).default(''),
+  assumptions: z.array(z.string().trim().min(1)).default([]),
+  risks: z.array(z.string().trim().min(1)).default([]),
+  docs: z.array(contextProposalDocSchema).min(1, 'at least one docs update is required'),
+  omitted_paths: z.array(z.string().trim().min(1)).default([]),
+  next_steps: z.array(z.string().trim().min(1)).default([]),
+}).strict();
+
+module.exports = {
+  CONTEXT_PROPOSAL_SCHEMA_VERSION,
+  MAX_DOC_CONTENT_LENGTH,
+  contextProposalDocSchema,
+  contextProposalSchema,
+};

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

@@ -5,6 +5,7 @@ const { listAgentProfiles } = require('../agent-profiles');
 const { PLANNER_APPROVAL_PHASES, readPhaseApproval } = require('../approvals');
 const { collectLayoutReport } = require('../doctor');
 const {
+  collectActiveSliceState,
   filterSlicesForExecution,
   groupSlicesBySpec: groupResolvedSlicesBySpec,
   isBlockedStatus: isCanonicalBlockedStatus,
@@ -296,14 +297,44 @@ function collectWarnings({ graph, layout, specs, slices }) {
 function collectNextSteps(data) {
   const activeRun = [...data.runs].reverse().find((run) => run.status !== 'closed');
   const commands = [];
+  const firstSpec = data.specs[0] || null;
+  const firstSlice = data.slices[0] || null;
+  const activeRunWantsSpecCreate = Boolean(activeRun?.next_command && activeRun.next_command.includes('spec create'));
 
-  commands.push({
-    id: activeRun ? 'continue-active-run' : 'create-ai-run',
-    command: activeRun ? activeRun.next_command : 'npx create-quiver ai run create --input <requirements.md>',
-    reason: activeRun ? `Continue AI run ${activeRun.run_id}.` : 'Start a new AI lifecycle run.',
-  });
+  if (activeRun && activeRunWantsSpecCreate && firstSpec) {
+    commands.push({
+      id: 'validate-existing-spec',
+      command: `npx create-quiver spec validate ${firstSpec.path}`,
+      reason: `A spec already exists while run ${activeRun.run_id} points to spec creation.`,
+    });
+    commands.push({
+      id: 'find-ready-slice',
+      command: 'npx create-quiver next --all-ready',
+      reason: 'Find ready slices before creating another spec.',
+    });
+    if (firstSlice?.slice_json) {
+      commands.push({
+        id: 'prompt-existing-slice',
+        command: `npx create-quiver ai prompt-slice --slice ${firstSlice.slice_json}`,
+        reason: 'Prepare a minimal executor prompt for the existing spec.',
+      });
+    }
+  } else {
+    commands.push({
+      id: activeRun ? 'continue-active-run' : 'create-ai-run',
+      command: activeRun ? activeRun.next_command : 'npx create-quiver ai run create --input <requirements.md>',
+      reason: activeRun ? `Continue AI run ${activeRun.run_id}.` : 'Start a new AI lifecycle run.',
+    });
+  }
 
   if (data.summary.slices > 0) {
+    if (data.active_slice?.reconciliation?.decision && data.active_slice.reconciliation.decision !== 'preserve') {
+      commands.push({
+        id: 'reconcile-active-slice',
+        command: 'npx create-quiver ai active-slice reconcile --dry-run',
+        reason: 'Review active-slice state before assigning more execution work.',
+      });
+    }
     commands.push({
       id: 'inspect-slices',
       command: 'npx create-quiver ai slices list',
@@ -379,6 +410,7 @@ function collectLifecycleExport(projectRoot, options = {}) {
   const approvals = normalizeApprovals(projectRoot);
   const progress = summarizeProgress(slices);
   const evidence = collectEvidenceEntries(slices);
+  const activeSlice = collectActiveSliceState(projectRoot, { slices: allSlices });
   const blockers = normalizedSlices
     .filter((slice) => slice.blocked_reason || String(slice.status).toLowerCase() === 'blocked')
     .map((slice) => ({ ref: slice.ref, reason: slice.blocked_reason || 'blocked' }));
@@ -389,6 +421,9 @@ function collectLifecycleExport(projectRoot, options = {}) {
   if (layout.layout === 'legacy' || layout.layout === 'hybrid' || layout.layout === 'incomplete') {
     blockers.push({ ref: 'migration', reason: layout.recommendations.join(' ') });
   }
+  if (activeSlice.reconciliation.decision === 'blocked') {
+    blockers.push({ ref: 'active-slice', reason: activeSlice.reconciliation.reason });
+  }
 
   const exportData = {
     schema_version: EXPORT_SCHEMA_VERSION,
@@ -413,6 +448,7 @@ function collectLifecycleExport(projectRoot, options = {}) {
       runs: runs.length,
       configured_agents: agents.filter((agent) => agent.configured).length,
       approvals: approvals.length,
+      active_slice_sources: activeSlice.sources.length,
       warnings: 0,
     },
     agents,
@@ -437,6 +473,7 @@ function collectLifecycleExport(projectRoot, options = {}) {
       dry_run_command: 'npx create-quiver migrate --dry-run',
     },
     evidence,
+    active_slice: activeSlice,
     warnings: [],
     blockers,
     next_steps: [],
@@ -480,6 +517,7 @@ function collectLifecycleExport(projectRoot, options = {}) {
         blocker: slice.blocked_reason,
       })),
       dependencies: graph.edges,
+      active_slice: activeSlice,
     },
   };
 
@@ -513,6 +551,15 @@ function formatLifecycleInspect(data) {
     lines.push(`- ${step.command}`);
   }
 
+  if (data.active_slice) {
+    lines.push(
+      '',
+      'Active slice state',
+      `- Sources: ${data.active_slice.sources.length}`,
+      `- Reconciliation: ${data.active_slice.reconciliation.decision} (${data.active_slice.reconciliation.reason})`,
+    );
+  }
+
   if (data.dashboard.blockers.length > 0) {
     lines.push('', 'Blockers');
     for (const blocker of data.dashboard.blockers) {

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

@@ -59,7 +59,8 @@ function formatGhInstallGuidance() {
     'GitHub CLI is not installed.',
     'macOS: brew install gh',
     'Linux: follow https://github.com/cli/cli/blob/trunk/docs/install_linux.md or use your distro package manager',
-    'Windows: winget install GitHub.cli',
+    'Windows PowerShell: winget install GitHub.cli',
+    'Git Bash/WSL: install gh inside the environment where the command will run, then authenticate there',
   ].join('\n');
 }
 
@@ -89,6 +90,16 @@ function formatShellPathGuidance(optionName, examplePath) {
   ].join('\n');
 }
 
+function formatSshAliasGuidance(alias = '<alias>') {
+  const resolvedAlias = alias || '<alias>';
+  return [
+    'SSH alias setup:',
+    `- macOS/Linux/Git Bash/WSL: edit ~/.ssh/config and add a Host entry such as \`Host ${resolvedAlias}\`, \`HostName github.com\`, \`User git\`, and \`IdentityFile ~/.ssh/<key>\`.`,
+    `- Windows PowerShell: edit $HOME\\.ssh\\config and add the same Host entry for ${resolvedAlias}.`,
+    `- Verify the alias with: ssh -T ${resolvedAlias}`,
+  ].join('\n');
+}
+
 function formatCommandForShell(command, args, quoter) {
   return `${command} ${args.map(quoter).join(' ')}`;
 }
@@ -326,7 +337,7 @@ function ensureSshHostAlias(sshHostAlias) {
       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/Git Bash/WSL: add a Host entry in ~/.ssh/config, for example `Host github-work`. Windows PowerShell: add the Host entry in $HOME\\.ssh\\config.',
+        fix: formatSshAliasGuidance('github-work'),
         nextCommand: 'ssh -T <alias>',
       }),
     );
@@ -675,6 +686,7 @@ module.exports = {
   ensureWorktreeReady,
   findPrBodyCandidates,
   formatGhInstallGuidance,
+  formatSshAliasGuidance,
   formatPreflightReport,
   formatPrCreateReport,
   preflightGitHubPr,