create-quiver 0.13.0 → 0.14.1

package/src/create-quiver/lib/ai/plan-review.js

@@ -5,6 +5,7 @@ const { readPhaseApproval, resolveApprovedPlannerInput } = require('../approvals
 const { quiverInternalPaths } = require('../init-layout');
 
 const PLAN_REVIEW_PROMPT_SOURCE = 'packaged production-readiness plan review template';
+const PLAN_REVIEW_RECOMMENDATIONS = Object.freeze(['approve', 'approve-with-risk', 'revise']);
 
 function formatError(message) {
   return `create-quiver: ${message}`;
@@ -50,6 +51,141 @@ function samePath(projectRoot, left, right) {
   return Boolean(left && right && resolvePath(projectRoot, left) === resolvePath(projectRoot, right));
 }
 
+function normalizeList(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item || '').trim()).filter(Boolean);
+  }
+  if (typeof value === 'string' && value.trim()) {
+    return value.split(/\r?\n/).map((item) => item.replace(/^[-*]\s+/, '').trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function normalizeRecommendation(value) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/[_\s]+/g, '-');
+  if (PLAN_REVIEW_RECOMMENDATIONS.includes(normalized)) {
+    return normalized;
+  }
+  if (normalized === 'approved' || normalized === 'approvable') {
+    return 'approve';
+  }
+  if (normalized === 'approved-with-risk' || normalized === 'approvable-with-risk' || normalized === 'approve-with-risks') {
+    return 'approve-with-risk';
+  }
+  if (normalized === 'changes-required' || normalized === 'requires-revision' || normalized === 'needs-revision') {
+    return 'revise';
+  }
+  return '';
+}
+
+function recommendedNextCommand(recommendation, sourceVersion) {
+  if (recommendation === 'revise') {
+    return 'npx create-quiver ai revise --phase technical-plan --input <feedback.md> --dry-run';
+  }
+  return `npx create-quiver ai approve --phase technical-plan --version ${sourceVersion || '<n>'}`;
+}
+
+function parseJsonObject(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function extractStructuredReview(text) {
+  const raw = String(text || '').trim();
+  if (!raw) {
+    return null;
+  }
+
+  const direct = parseJsonObject(raw);
+  if (direct) {
+    return direct;
+  }
+
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (!fenced) {
+    return null;
+  }
+  return parseJsonObject(fenced[1].trim());
+}
+
+function normalizeStructuredReview(parsed, sourceVersion) {
+  const review = parsed?.review || parsed?.plan_review || parsed;
+  const requiredFixes = normalizeList(review.required_fixes || review.requiredFixes || review.blocking_issues || review.blockingIssues);
+  const optionalHardening = normalizeList(review.optional_hardening || review.optionalHardening || review.non_blocking_issues || review.nonBlockingIssues);
+  const risks = normalizeList(review.risks || review.remaining_risks || review.remainingRisks);
+  let approvalRecommendation = normalizeRecommendation(review.approval_recommendation || review.approvalRecommendation || review.recommendation);
+  const blocking = review.blocking === true || review.has_blockers === true || review.hasBlockers === true || requiredFixes.length > 0;
+
+  if (!approvalRecommendation) {
+    approvalRecommendation = blocking ? 'revise' : optionalHardening.length > 0 || risks.length > 0 ? 'approve-with-risk' : 'approve';
+  }
+
+  const normalizedBlocking = blocking || approvalRecommendation === 'revise';
+
+  return {
+    schema_version: 1,
+    approval_recommendation: approvalRecommendation,
+    blocking: normalizedBlocking,
+    next_command: String(review.next_command || review.nextCommand || '').trim() || recommendedNextCommand(approvalRecommendation, sourceVersion),
+    optional_hardening: optionalHardening,
+    required_fixes: requiredFixes,
+    risks,
+    source: 'structured',
+  };
+}
+
+function classifyReviewText(text) {
+  const value = String(text || '').toLowerCase();
+  if (/\b(revise|revision|required fix|required fixes|blocking|blocker|not approvable|not ready)\b/.test(value)) {
+    return 'revise';
+  }
+  if (/\b(approve with risk|approvable with risk|non-blocking|optional hardening|p1|p2|risk)\b/.test(value)) {
+    return 'approve-with-risk';
+  }
+  if (/\b(approve|approved|approvable|no blockers|no blocking|production ready)\b/.test(value)) {
+    return 'approve';
+  }
+  return 'approve-with-risk';
+}
+
+function derivePlanReviewResult(contents, options = {}) {
+  const structured = extractStructuredReview(contents);
+  if (structured) {
+    return normalizeStructuredReview(structured, options.inputVersion);
+  }
+
+  const approvalRecommendation = classifyReviewText(contents);
+  const fallbackNote = approvalRecommendation === 'approve-with-risk'
+    ? ['Review output did not include structured metadata; treat approval as risky and inspect the human review text before approving.']
+    : [];
+  const requiredFixes = approvalRecommendation === 'revise'
+    ? ['Review output indicates the technical plan must be revised before approval.']
+    : [];
+
+  return {
+    schema_version: 1,
+    approval_recommendation: approvalRecommendation,
+    blocking: approvalRecommendation === 'revise',
+    next_command: recommendedNextCommand(approvalRecommendation, options.inputVersion),
+    optional_hardening: fallbackNote,
+    required_fixes: requiredFixes,
+    risks: [],
+    source: 'heuristic',
+  };
+}
+
+function reviewBlocksApproval(review) {
+  const result = review?.meta?.review_result || review?.review_result || null;
+  if (!result) {
+    return false;
+  }
+  return result.blocking === true || result.approval_recommendation === 'revise';
+}
+
 function latestTechnicalPlanDraft(approval) {
   const version = Number(approval.meta?.draft?.version || 0);
   if (!version) {
@@ -184,6 +320,9 @@ function savePlanReview(projectRoot, options = {}) {
   const now = new Date().toISOString();
   const contents = String(options.contents || '');
   const inputPath = options.inputPath || '';
+  const reviewResult = derivePlanReviewResult(contents, {
+    inputVersion: options.inputVersion,
+  });
 
   fs.writeFileSync(reviewPath, contents);
   const meta = {
@@ -194,6 +333,7 @@ function savePlanReview(projectRoot, options = {}) {
     path: toRelativePosix(projectRoot, reviewPath),
     raw_artifact_path: options.rawArtifactPath || null,
     output_source: options.outputSource || null,
+    review_result: reviewResult,
     reviewed_at: now,
   };
   fs.writeFileSync(planReviewMetaPath(projectRoot), `${JSON.stringify(meta, null, 2)}\n`);
@@ -216,6 +356,10 @@ function assertPlanReviewed(projectRoot) {
       : ' Preview the review first, then run `npx create-quiver ai review-plan` to persist it.';
     throw new Error(formatError(`ai plan phase 'spec' requires a reviewed and approved technical-plan input; current review status: ${review.status}. Run \`${nextCommand}\`.${followUp}`));
   }
+  if (reviewBlocksApproval(review)) {
+    const result = review.meta.review_result;
+    throw new Error(formatError(`ai plan phase 'spec' requires an approvable production review; current approval recommendation is ${result.approval_recommendation}. Run \`${result.next_command || recommendedNextCommand('revise')}\`.`));
+  }
   return review;
 }
 
@@ -243,6 +387,8 @@ function buildPlanReviewPrompt({ pack, inputText, inputPath }) {
     '- operational risks',
     '- recommended fixes to the plan',
     'If ambiguity is not blocking, state the safest assumption and continue.',
+    'Required output contract: include a fenced json block with `{ "review": { "blocking": boolean, "approvalRecommendation": "approve|approve-with-risk|revise", "requiredFixes": [], "optionalHardening": [], "risks": [], "nextCommand": "" } }`.',
+    'Use `approve` only when no required fixes remain. Use `approve-with-risk` when only optional hardening or accepted risks remain. Use `revise` when required fixes or blocking ambiguity remain.',
   ];
 
   if (inputPath) {
@@ -261,6 +407,7 @@ function buildPlanReviewPrompt({ pack, inputText, inputPath }) {
 
 function summarizePlanReview(projectRoot) {
   const review = readPlanReview(projectRoot);
+  const result = review.meta?.review_result || null;
   const lines = [
     'Phase: plan-review',
     `Status: ${review.status}`,
@@ -271,16 +418,28 @@ function summarizePlanReview(projectRoot) {
   if (review.meta?.source_file) {
     lines.push(`Source file: ${review.meta.source_file}`);
   }
+  if (result) {
+    const requiredFixes = normalizeList(result.required_fixes);
+    const optionalHardening = normalizeList(result.optional_hardening);
+    lines.push(`Approval recommendation: ${result.approval_recommendation}`);
+    lines.push(`Blocking: ${result.blocking ? 'yes' : 'no'}`);
+    lines.push(`Required fixes: ${requiredFixes.length}`);
+    lines.push(`Optional hardening: ${optionalHardening.length}`);
+    lines.push(`Next command: ${result.next_command}`);
+  }
   return `${lines.join('\n')}\n`;
 }
 
 module.exports = {
   PLAN_REVIEW_PROMPT_SOURCE,
+  PLAN_REVIEW_RECOMMENDATIONS,
   assertPlanReviewed,
   buildPlanReviewPrompt,
+  derivePlanReviewResult,
   planReviewMetaPath,
   planReviewPath,
   readPlanReview,
+  reviewBlocksApproval,
   resolveTechnicalPlanReviewInput,
   resolveReviewedTechnicalPlanInput,
   savePlanReview,

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

@@ -357,7 +357,9 @@ function formatAiRunStatus(projectRoot, run) {
     ].join('\n');
   }
 
-  return [
+  const openRuns = listAiRuns(projectRoot).filter((item) => item.status !== 'closed');
+  const otherOpenRuns = openRuns.filter((item) => item.run_id !== run.run_id);
+  const lines = [
     'AI run status',
     `Run: ${run.run_id}`,
     `Status: ${run.status}`,
@@ -366,9 +368,22 @@ function formatAiRunStatus(projectRoot, run) {
     `Requirement: ${run.requirement?.path || '(missing)'}`,
     `State: ${toRelativePosix(projectRoot, runStatePath(projectRoot, run.run_id))}`,
     `Approvals: ${run.approvals_path}`,
+    `Open runs: ${openRuns.length}`,
+  ];
+
+  if (otherOpenRuns.length > 0) {
+    lines.push('Other open runs:');
+    for (const item of otherOpenRuns) {
+      lines.push(`- ${item.run_id}: ${item.phase} (${item.status}) -> ${nextCommandForPhase(item.phase)}`);
+    }
+  }
+
+  lines.push(
     `Next safe command: ${nextCommandForPhase(run.phase)}`,
     '',
-  ].join('\n');
+  );
+
+  return lines.join('\n');
 }
 
 function formatAiRunResume(projectRoot, run) {

package/src/create-quiver/lib/ai/spec-generator.js

@@ -278,6 +278,20 @@ function buildSpecGenerationManifest({ inputText, inputPath, repoRoot, specSlug
   return manifest;
 }
 
+function validateTechnicalPlanSpecContract(repoRoot, options = {}) {
+  const inputPath = options.inputPath || options.input;
+  const inputText = typeof options.inputText === 'string'
+    ? options.inputText
+    : readSourceText(inputPath, repoRoot);
+
+  return buildSpecGenerationManifest({
+    inputPath,
+    inputText,
+    repoRoot,
+    specSlug: options.specSlug,
+  });
+}
+
 function validateSpecCollision(specDir) {
   if (fs.existsSync(specDir)) {
     throw new Error(formatError(`spec directory already exists: ${path.relative(process.cwd(), specDir)}`));
@@ -381,5 +395,6 @@ module.exports = {
   generateSpecArtifacts,
   parseApprovedManifest,
   readSourceText,
+  validateTechnicalPlanSpecContract,
   validateGeneratedSliceJson,
 };

package/src/create-quiver/lib/cli/editor.js

@@ -0,0 +1,118 @@
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+function splitEditorCommand(value) {
+  const input = String(value || '').trim();
+  if (!input) return null;
+  const parts = [];
+  let current = '';
+  let quote = null;
+  let escaping = false;
+
+  for (const char of input) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === '\\') {
+      escaping = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current) {
+        parts.push(current);
+        current = '';
+      }
+      continue;
+    }
+    current += char;
+  }
+
+  if (current) parts.push(current);
+  return parts.length > 0 ? { command: parts[0], args: parts.slice(1) } : null;
+}
+
+function defaultEditorForPlatform(platform = os.platform()) {
+  return platform === 'win32' ? 'notepad' : 'vi';
+}
+
+function resolveEditor(env = process.env, options = {}) {
+  const candidates = [
+    { source: 'VISUAL', value: env.VISUAL },
+    { source: 'EDITOR', value: env.EDITOR },
+    ...((options.fallbacks || [defaultEditorForPlatform(options.platform)]).map((value) => ({
+      source: 'fallback',
+      value,
+    }))),
+  ];
+
+  for (const candidate of candidates) {
+    const parsed = splitEditorCommand(candidate.value);
+    if (parsed) {
+      return { ...parsed, source: candidate.source };
+    }
+  }
+
+  return null;
+}
+
+function openEditor(filePath, options = {}) {
+  const editor = options.editor || resolveEditor(options.env || process.env, options);
+  if (!editor) {
+    return {
+      ok: false,
+      canceled: true,
+      filePath,
+      reason: 'No editor configured. Set VISUAL or EDITOR, then rerun the command.',
+    };
+  }
+
+  const runner = options.spawnSync || spawnSync;
+  const result = runner(editor.command, [...editor.args, filePath], {
+    cwd: options.cwd || process.cwd(),
+    env: options.env || process.env,
+    shell: false,
+    stdio: options.stdio || 'inherit',
+  });
+
+  if (result.error) {
+    return {
+      ok: false,
+      canceled: true,
+      command: editor.command,
+      filePath,
+      reason: result.error.message,
+      source: editor.source,
+    };
+  }
+
+  const status = result.status ?? 0;
+  return {
+    ok: status === 0,
+    canceled: status !== 0,
+    command: editor.command,
+    exitCode: status,
+    filePath,
+    source: editor.source,
+  };
+}
+
+module.exports = {
+  defaultEditorForPlatform,
+  openEditor,
+  resolveEditor,
+  splitEditorCommand,
+};

package/src/create-quiver/lib/cli/theme.js

@@ -0,0 +1,100 @@
+const QUIVER_COLORS = Object.freeze({
+  sky: '#86C8F2',
+  blue: '#6BADEB',
+  periwinkle: '#7F9EE8',
+  violet: '#9B82E6',
+  magenta: '#D56AB0',
+});
+
+const STATUS_COLORS = Object.freeze({
+  info: 'sky',
+  command: 'blue',
+  planner: 'violet',
+  review: 'magenta',
+  risk: 'magenta',
+  muted: 'periwinkle',
+});
+
+function isTruthy(value) {
+  return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function isAsciiLocale(env = process.env) {
+  const locale = `${env.LC_ALL || ''} ${env.LC_CTYPE || ''} ${env.LANG || ''}`;
+  return /\bC\b|ASCII/i.test(locale);
+}
+
+function isDumbTerminal(env = process.env) {
+  return String(env.TERM || '').toLowerCase() === 'dumb';
+}
+
+function shouldUseColor(options = {}, env = process.env, tty = {}) {
+  if (options.json || options.noColor) return false;
+  if (env.NO_COLOR || env.FORCE_COLOR === '0') return false;
+  if (isDumbTerminal(env)) return false;
+  if (isTruthy(env.CI)) return false;
+  if (tty.stdout === false) return false;
+  if (options.color === true) return true;
+  return Boolean(tty.stdout);
+}
+
+function shouldUseUnicode(options = {}, env = process.env, tty = {}) {
+  if (options.ascii || options.json) return false;
+  if (isDumbTerminal(env) || isAsciiLocale(env)) return false;
+  if (tty.stdout === false) return false;
+  if (options.unicode === true) return true;
+  return Boolean(tty.stdout);
+}
+
+function hexToRgb(hex) {
+  const normalized = String(hex || '').replace(/^#/, '');
+  if (!/^[0-9a-f]{6}$/i.test(normalized)) {
+    return null;
+  }
+  return [
+    Number.parseInt(normalized.slice(0, 2), 16),
+    Number.parseInt(normalized.slice(2, 4), 16),
+    Number.parseInt(normalized.slice(4, 6), 16),
+  ];
+}
+
+function colorize(value, colorName, theme) {
+  const text = String(value ?? '');
+  if (!theme?.useColor) return text;
+  const rgb = hexToRgb(theme.colors[colorName] || colorName);
+  if (!rgb) return text;
+  return `\u001b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${text}\u001b[0m`;
+}
+
+function resolveTheme(options = {}, env = process.env, tty = {}) {
+  const useColor = shouldUseColor(options, env, tty);
+  const useUnicode = shouldUseUnicode(options, env, tty);
+  const symbols = useUnicode
+    ? { start: '◇', success: '✓', warning: '!', error: '✖', bullet: '•' }
+    : { start: '*', success: 'OK', warning: 'WARN', error: 'ERR', bullet: '-' };
+  const theme = {
+    colors: QUIVER_COLORS,
+    statusColors: STATUS_COLORS,
+    symbols,
+    useColor,
+    useUnicode,
+  };
+
+  return {
+    ...theme,
+    colorize: (value, colorName) => colorize(value, colorName, theme),
+    status: (status, value) => colorize(value, STATUS_COLORS[status] || 'sky', theme),
+  };
+}
+
+module.exports = {
+  QUIVER_COLORS,
+  STATUS_COLORS,
+  colorize,
+  isAsciiLocale,
+  isDumbTerminal,
+  isTruthy,
+  resolveTheme,
+  shouldUseColor,
+  shouldUseUnicode,
+};

package/src/create-quiver/lib/cli/ux-flags.js

@@ -0,0 +1,151 @@
+const UX_FLAG_OPTIONS = Object.freeze({
+  withPlanner: '--with-planner',
+  interactive: '--interactive',
+  review: '--review',
+});
+
+const UX_FLAG_MATRIX = Object.freeze({
+  'ai prepare-context': Object.freeze({
+    withPlanner: true,
+    interactive: true,
+    review: true,
+    note: 'planner-assisted docs-only context preparation',
+  }),
+  'ai plan': Object.freeze({
+    withPlanner: true,
+    interactive: true,
+    review: true,
+    note: 'planner draft generation and human approval workflow',
+  }),
+  'spec create': Object.freeze({
+    withPlanner: true,
+    interactive: true,
+    review: true,
+    note: 'spec generation from approved planner output',
+  }),
+  'ai pr': Object.freeze({
+    withPlanner: false,
+    interactive: true,
+    review: true,
+    note: 'PR body review and interactive PR inputs',
+  }),
+});
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function normalizeCommandKey(value) {
+  return String(value || '').trim().replace(/\s+/g, ' ');
+}
+
+function resolveUxCommandKey(args = {}) {
+  if (args.mode === 'ai') {
+    const command = args.aiCommand || '';
+    if (command === 'specs' || command === 'slices' || command === 'trace' || command === 'active-slice') {
+      return normalizeCommandKey(`ai ${command} ${args.aiSecondaryCommand || ''}`);
+    }
+    if (command === 'agent') {
+      return normalizeCommandKey(`ai ${command} ${args.aiAgentCommand || ''}`);
+    }
+    if (command === 'run') {
+      return normalizeCommandKey(`ai ${command} ${args.aiRunCommand || ''}`);
+    }
+    return normalizeCommandKey(`ai ${command}`);
+  }
+
+  if (args.mode === 'spec') {
+    return normalizeCommandKey(`spec ${args.specCommand || ''}`);
+  }
+
+  if (args.mode === 'demo') {
+    return normalizeCommandKey(`demo ${args.demoCommand || ''} ${args.demoName || ''}`);
+  }
+
+  if (args.mode === 'evidence') {
+    return normalizeCommandKey(`evidence ${args.evidenceCommand || ''}`);
+  }
+
+  return normalizeCommandKey(args.mode);
+}
+
+function getUxFlagSupport(commandKey) {
+  return UX_FLAG_MATRIX[normalizeCommandKey(commandKey)] || Object.freeze({
+    withPlanner: false,
+    interactive: false,
+    review: false,
+    note: 'no UX flag support',
+  });
+}
+
+function getRequestedUxFlags(args = {}) {
+  return Object.keys(UX_FLAG_OPTIONS).filter((key) => args[key] === true);
+}
+
+function supportedFlagList(support) {
+  return Object.entries(UX_FLAG_OPTIONS)
+    .filter(([key]) => support[key] === true)
+    .map(([, flag]) => flag);
+}
+
+function explainAlternative(flag) {
+  if (flag === 'withPlanner') {
+    return 'Use a planner-capable command such as: npx create-quiver ai prepare-context --with-planner --dry-run';
+  }
+  if (flag === 'interactive') {
+    return 'Use explicit non-interactive flags for automation, or run a command that documents --interactive support.';
+  }
+  if (flag === 'review') {
+    return 'Use a command with persistent AI-generated output, then rerun with --review after inspecting the dry-run.';
+  }
+  return 'Run: npx create-quiver --help';
+}
+
+function buildUnsupportedFlagError(commandKey, flag, support) {
+  const flagName = UX_FLAG_OPTIONS[flag];
+  const supported = supportedFlagList(support);
+  const supportedText = supported.length > 0 ? supported.join(', ') : 'none';
+
+  return new Error(formatError([
+    `UX flag ${flagName} is not supported by '${commandKey}'.`,
+    `Supported UX flags for '${commandKey}': ${supportedText}.`,
+    explainAlternative(flag),
+  ].join('\n')));
+}
+
+function validateUxFlagCombinations(args = {}, commandKey = resolveUxCommandKey(args)) {
+  if (args.json && args.interactive) {
+    throw new Error(formatError(`incompatible UX flags for '${commandKey}': --json cannot be combined with --interactive because JSON output must stay machine-readable.`));
+  }
+  if (args.json && args.review) {
+    throw new Error(formatError(`incompatible UX flags for '${commandKey}': --json cannot be combined with --review because editor review is a human-only flow.`));
+  }
+}
+
+function validateUxFlags(args = {}) {
+  const commandKey = resolveUxCommandKey(args);
+  validateUxFlagCombinations(args, commandKey);
+
+  const support = getUxFlagSupport(commandKey);
+  for (const flag of getRequestedUxFlags(args)) {
+    if (support[flag] !== true) {
+      throw buildUnsupportedFlagError(commandKey, flag, support);
+    }
+  }
+
+  return {
+    commandKey,
+    requested: getRequestedUxFlags(args).map((flag) => UX_FLAG_OPTIONS[flag]),
+    supported: supportedFlagList(support),
+  };
+}
+
+module.exports = {
+  UX_FLAG_MATRIX,
+  UX_FLAG_OPTIONS,
+  getRequestedUxFlags,
+  getUxFlagSupport,
+  resolveUxCommandKey,
+  validateUxFlagCombinations,
+  validateUxFlags,
+};