create-quiver 0.17.2 → 0.17.4

package/src/create-quiver/index.js

@@ -230,7 +230,7 @@ const COMMAND_HELP_GROUPS = [
       ['ai active-slice status|reconcile', 'Inspect or dry-run reconcile local active-slice state from every supported source.'],
       ['ai status', 'Show current AI lifecycle phase, approved versions, blockers, and next command.'],
       ['ai resume', 'Resume guidance from the last valid lifecycle phase without chat memory.'],
-      ['ai analyze-project', 'Read and explain a bounded project sample without provider execution or writes.'],
+      ['ai analyze-project', 'Analyze a bounded project sample and apply validated documentation updates.'],
       ['ai onboard', 'Run or print the planner onboarding prompt with a token-aware context pack.'],
       ['ai prepare-context', 'Preview or write docs-only AI context updates with assumptions and risks.'],
       ['ai agent set|list|show|doctor|repair', 'Manage, diagnose, and dry-run repair planner, executor, reviewer, and doctor provider profiles without secrets.'],
@@ -330,6 +330,7 @@ function printUsage(language = DEFAULT_LANGUAGE) {
   npx create-quiver ai status [options]
   npx create-quiver ai resume [options]
   npx create-quiver ai analyze-project [--deep] [--dry-run] [--json]
+  npx create-quiver ai analyze-project apply --run <run-id>
   npx create-quiver ai inspect [options]
   npx create-quiver ai export [--format json|markdown]
   npx create-quiver ai specs list [--json]
@@ -396,6 +397,10 @@ ${helpText(help, 'headings', 'options', 'Options:')}
       --include-source        ${optionDescription(help, 'For ai analyze-project, include source files without requiring --deep')}
       --include-tests         ${optionDescription(help, 'For ai analyze-project, include test files in the sample')}
       --include-db            ${optionDescription(help, 'For ai analyze-project, include schema, migration, and DB files in the sample')}
+      --apply-docs            ${optionDescription(help, 'For ai analyze-project, apply validated documentation proposals through the safe docs workflow')}
+      --save-proposal         ${optionDescription(help, 'For ai analyze-project, save a validated documentation proposal without writing final docs')}
+      --diff                  ${optionDescription(help, 'For ai analyze-project, show or save the proposed documentation diff')}
+      --allow-dirty-docs      ${optionDescription(help, 'For ai analyze-project, allow dirty target docs checks where the safe apply workflow supports it')}
       --scope <path|name>     ${optionDescription(help, 'For ai analyze-project, restrict discovery to a repo path or workspace name')}
       --print-prompt          ${optionDescription(help, 'Print the exact AI prompt and exit without executing provider CLIs')}
       --with-planner          ${optionDescription(help, 'Enable planner-assisted behavior on commands that explicitly support it')}
@@ -579,6 +584,10 @@ function parseArgs(argv, options = {}) {
     aiAnalyzeIncludeDb: false,
     aiAnalyzeIncludeSource: false,
     aiAnalyzeIncludeTests: false,
+    aiAnalyzeApplyDocs: false,
+    aiAnalyzeSaveProposal: false,
+    aiAnalyzeDiff: false,
+    aiAnalyzeAllowDirtyDocs: false,
     aiAnalyzeMaxBytes: null,
     aiAnalyzeMaxFiles: null,
     aiAnalyzeScope: '',
@@ -763,6 +772,30 @@ function parseArgs(argv, options = {}) {
       continue;
     }
 
+    if (arg === '--apply-docs') {
+      result.aiAnalyzeApplyDocs = true;
+      result.aiAnalyzeOptionUsed = true;
+      continue;
+    }
+
+    if (arg === '--save-proposal') {
+      result.aiAnalyzeSaveProposal = true;
+      result.aiAnalyzeOptionUsed = true;
+      continue;
+    }
+
+    if (arg === '--diff') {
+      result.aiAnalyzeDiff = true;
+      result.aiAnalyzeOptionUsed = true;
+      continue;
+    }
+
+    if (arg === '--allow-dirty-docs') {
+      result.aiAnalyzeAllowDirtyDocs = true;
+      result.aiAnalyzeOptionUsed = true;
+      continue;
+    }
+
     if (arg === '--max-files') {
       const value = args[++index];
       if (typeof value === 'undefined') {
@@ -1332,6 +1365,15 @@ function parseArgs(argv, options = {}) {
     if (result.aiCommand === 'run' && !result.aiRunCommand && positional.length > 0) {
       result.aiRunCommand = positional.shift();
     }
+    if (result.aiCommand === 'analyze-project' && !result.aiSecondaryCommand && positional.length > 0) {
+      result.aiSecondaryCommand = positional.shift();
+    }
+    if (result.aiCommand === 'analyze-project' && result.aiSecondaryCommand && result.aiSecondaryCommand !== 'apply') {
+      throw new Error(formatError(`unsupported ai analyze-project subcommand: ${result.aiSecondaryCommand}. Supported tasks: apply`));
+    }
+    if (result.aiCommand === 'analyze-project' && result.aiSecondaryCommand === 'apply' && !result.aiRunId) {
+      throw new Error(formatError('ai analyze-project apply requires --run <run-id>'));
+    }
     if ((result.aiCommand === 'specs' || result.aiCommand === 'slices' || result.aiCommand === 'models' || result.aiCommand === 'trace' || result.aiCommand === 'active-slice') && !result.aiSecondaryCommand && positional.length > 0) {
       result.aiSecondaryCommand = positional.shift();
     }
@@ -1470,6 +1512,33 @@ function parseArgs(argv, options = {}) {
     throw new Error(formatError('--global is only supported by config language set. Use: npx create-quiver config language set <en|es> --global'));
   }
 
+  if (result.mode === 'ai' && result.aiCommand === 'analyze-project') {
+    if (result.review && result.aiAnalyzeApplyDocs) {
+      throw new Error(formatError('ai analyze-project --apply-docs cannot be combined with --review'));
+    }
+    if (result.dryRun && result.aiAnalyzeApplyDocs) {
+      throw new Error(formatError('ai analyze-project --dry-run cannot be combined with --apply-docs'));
+    }
+    if (result.dryRun && result.aiAnalyzeSaveProposal) {
+      throw new Error(formatError('ai analyze-project --dry-run cannot be combined with --save-proposal'));
+    }
+    if (result.dryRun && result.aiSecondaryCommand === 'apply') {
+      throw new Error(formatError('ai analyze-project apply --run cannot be combined with --dry-run'));
+    }
+    if (result.aiSecondaryCommand === 'apply' && (result.aiAnalyzeApplyDocs || result.aiAnalyzeSaveProposal || result.review)) {
+      throw new Error(formatError('ai analyze-project apply --run cannot be combined with --apply-docs, --save-proposal, or --review'));
+    }
+    if (result.aiSecondaryCommand === 'apply' && result.aiRunId === 'latest' && result.force) {
+      throw new Error(formatError('ai analyze-project apply --run latest cannot be combined with --yes'));
+    }
+    if (result.aiSecondaryCommand === 'apply' && result.aiRunId === 'latest' && result.json) {
+      throw new Error(formatError('ai analyze-project apply --run latest cannot be combined with --json'));
+    }
+    if (result.json && result.aiAnalyzeApplyDocs && !result.force) {
+      throw new Error(formatError('ai analyze-project --json with --apply-docs requires --yes'));
+    }
+  }
+
   return result;
 }
 
@@ -3519,6 +3588,10 @@ async function run(argv) {
       await runAiAnalyzeProject(process.cwd(), {
         deep: args.aiAnalyzeDeep,
         dryRun: args.dryRun,
+        allowDirtyDocs: args.aiAnalyzeAllowDirtyDocs,
+        applyDocs: args.aiAnalyzeApplyDocs,
+        applyRun: args.aiSecondaryCommand === 'apply',
+        diff: args.aiAnalyzeDiff,
         force: args.force,
         includeDb: args.aiAnalyzeIncludeDb,
         includeSource: args.aiAnalyzeIncludeSource,
@@ -3528,10 +3601,16 @@ async function run(argv) {
         language: args.language,
         maxBytes: args.aiAnalyzeMaxBytes || undefined,
         maxFiles: args.aiAnalyzeMaxFiles || undefined,
+        model: args.aiModel || undefined,
         printPrompt: args.aiPrintPrompt,
+        provider: args.aiProvider || undefined,
+        providerExplicit: args.aiProviderExplicit,
         review: args.review,
+        runId: args.aiRunId || undefined,
+        saveProposal: args.aiAnalyzeSaveProposal,
         scope: args.aiAnalyzeScope || undefined,
         strict: args.strict,
+        timeout: args.aiTimeout || undefined,
       });
       return;
     }

package/src/create-quiver/lib/ai/analyze-project-apply.js

@@ -0,0 +1,269 @@
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+
+const {
+  buildAnalyzeProjectWritePlan,
+  createAnalyzeProjectSnapshot,
+  writeAnalyzeProjectDocs,
+} = require('./analyze-project-docs');
+const {
+  buildAnalyzeProjectProposalArtifactPaths,
+  normalizeAnalyzeProjectProposalManifest,
+  writeAnalyzeProjectProposalArtifacts,
+  writeAnalyzeProjectWriteManifest,
+} = require('./analyze-project-proposal');
+const { validateAnalyzeProjectPostWrite } = require('./analyze-project-validation');
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+class AnalyzeProjectApplyError extends Error {
+  constructor(message, issues = []) {
+    super(formatError(message));
+    this.name = 'AnalyzeProjectApplyError';
+    this.code = 'AI_ANALYZE_PROJECT_APPLY_BLOCKED';
+    this.issues = issues;
+  }
+}
+
+function sha256(contents) {
+  return crypto.createHash('sha256').update(String(contents || ''), 'utf8').digest('hex');
+}
+
+function readCurrentHash(item) {
+  if (!fs.existsSync(item.destinationPath)) {
+    return null;
+  }
+  return sha256(fs.readFileSync(item.destinationPath, 'utf8'));
+}
+
+function collectWrittenDocs(writePlan) {
+  const written = [];
+  for (const item of writePlan) {
+    if (item.action === 'skip') {
+      continue;
+    }
+    if (readCurrentHash(item) === item.after_sha256) {
+      written.push(item.path);
+    }
+  }
+  return written;
+}
+
+function assertAnalyzeProjectApplyPreflight(writePlan, proposalManifest, options = {}) {
+  const issues = [];
+  const beforeHashes = proposalManifest?.doc_before_hashes || {};
+
+  for (const item of writePlan) {
+    if (item.action === 'skip') {
+      continue;
+    }
+    if (item.dirty === true && options.allowDirtyDocs !== true) {
+      issues.push({
+        path: item.path,
+        issue: 'dirty-target-doc',
+        message: 'target documentation already has human content; --yes requires --allow-dirty-docs or interactive review',
+      });
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(beforeHashes, item.path)) {
+      issues.push({
+        path: item.path,
+        issue: 'missing-before-hash',
+        message: 'proposal manifest is missing the current doc hash for this target path',
+      });
+      continue;
+    }
+
+    const currentHash = readCurrentHash(item);
+    const expectedHash = beforeHashes[item.path] || null;
+    if (currentHash !== expectedHash) {
+      issues.push({
+        path: item.path,
+        issue: 'stale-target-doc',
+        message: 'target documentation changed after the proposal was built',
+        expected_sha256: expectedHash,
+        current_sha256: currentHash,
+      });
+    }
+  }
+
+  if (issues.length > 0) {
+    throw new AnalyzeProjectApplyError(
+      'ai analyze-project --apply-docs --yes blocked before writing final docs',
+      issues,
+    );
+  }
+
+  return { ok: true, issues: [] };
+}
+
+function validationFromWriteError(error, options = {}) {
+  return {
+    ok: false,
+    strict: options.strict === true,
+    errors: [{
+      path: null,
+      issue: 'write-failed',
+      message: error?.message || 'analyze-project doc write failed',
+    }],
+    warnings: [],
+  };
+}
+
+function normalizeLoadedProposalArtifacts(runId, proposalArtifacts = {}, proposalManifest = null) {
+  const paths = buildAnalyzeProjectProposalArtifactPaths(runId);
+  const manifestData = normalizeAnalyzeProjectProposalManifest(proposalManifest || proposalArtifacts.manifest_data || {});
+  return {
+    root: proposalArtifacts.root || paths.root,
+    proposal_json: proposalArtifacts.proposal_json || manifestData.proposal_json,
+    proposal_markdown: proposalArtifacts.proposal_markdown || manifestData.proposal_markdown,
+    proposal_diff: proposalArtifacts.proposal_diff || manifestData.proposal_diff,
+    manifest: proposalArtifacts.manifest || paths.manifest,
+    proposal_sha256: proposalArtifacts.proposal_sha256 || manifestData.proposal_sha256,
+    doc_paths: proposalArtifacts.doc_paths || manifestData.doc_paths || [],
+    changed_docs: proposalArtifacts.changed_docs || manifestData.doc_paths || [],
+    manifest_data: manifestData,
+    files: Array.isArray(proposalArtifacts.files)
+      ? proposalArtifacts.files
+      : [
+        manifestData.proposal_json,
+        manifestData.proposal_markdown,
+        manifestData.proposal_diff,
+        paths.manifest,
+      ],
+  };
+}
+
+function applyAnalyzeProjectDocProposal(repoRoot, options = {}) {
+  const runId = String(options.runId || '').trim();
+  const proposal = options.proposal;
+  const now = options.now instanceof Date ? options.now : new Date(options.now || Date.now());
+  const writePlan = buildAnalyzeProjectWritePlan(repoRoot, proposal);
+  const applyEvents = Array.isArray(options.events) ? options.events : [];
+  const proposalArtifacts = options.proposalArtifacts
+    ? normalizeLoadedProposalArtifacts(runId, options.proposalArtifacts, options.proposalManifest)
+    : writeAnalyzeProjectProposalArtifacts(repoRoot, {
+      runId,
+      now,
+      provider: options.provider,
+      language: options.language,
+      proposal,
+      writePlan,
+      selectedContextManifest: options.selectedContextManifest,
+      repairManifest: options.repairManifest,
+      events: [{ type: 'proposal-saved-before-apply', at: now.toISOString() }],
+    });
+
+  try {
+    assertAnalyzeProjectApplyPreflight(writePlan, proposalArtifacts.manifest_data, {
+      allowDirtyDocs: options.allowDirtyDocs === true,
+    });
+  } catch (error) {
+    error.proposal_artifacts = proposalArtifacts;
+    error.write_plan = writePlan;
+    throw error;
+  }
+
+  const snapshot = createAnalyzeProjectSnapshot(repoRoot, { run_id: runId }, writePlan, {
+    providerArtifact: options.providerArtifact,
+    proposal,
+    now,
+  });
+  const plannedManifest = writeAnalyzeProjectWriteManifest(repoRoot, {
+    runId,
+    now,
+    proposalManifest: proposalArtifacts.manifest,
+    snapshot,
+    writePlan,
+    strict: options.strict === true,
+    status: 'planned',
+    events: [
+      ...applyEvents,
+      { type: 'write-planned', at: now.toISOString() },
+    ],
+  });
+
+  let writtenDocs = [];
+  try {
+    writtenDocs = writeAnalyzeProjectDocs(writePlan);
+  } catch (error) {
+    const partialDocs = collectWrittenDocs(writePlan);
+    const failedManifest = writeAnalyzeProjectWriteManifest(repoRoot, {
+      runId,
+      now: new Date(),
+      proposalManifest: proposalArtifacts.manifest,
+      snapshot,
+      writePlan,
+      writtenDocs: partialDocs,
+      validation: validationFromWriteError(error, { strict: options.strict === true }),
+      partialWrite: partialDocs.length > 0,
+      status: 'completed',
+      events: [
+        ...applyEvents,
+        { type: 'write-planned', at: now.toISOString() },
+        { type: 'write-failed', at: new Date().toISOString(), message: error?.message || 'write failed' },
+      ],
+    });
+    error.write_manifest = failedManifest;
+    error.snapshot = snapshot;
+    error.written_docs = partialDocs;
+    throw error;
+  }
+
+  const writeReport = {
+    ...options.report,
+    apply_docs: true,
+    writes: writtenDocs,
+    doc_proposal: proposal,
+    write_plan: options.summarizeWritePlan
+      ? options.summarizeWritePlan(writePlan)
+      : writePlan,
+    snapshot,
+    written_docs: writtenDocs,
+    proposal_artifacts: {
+      root: proposalArtifacts.root,
+      proposal_json: proposalArtifacts.proposal_json,
+      proposal_markdown: proposalArtifacts.proposal_markdown,
+      proposal_diff: proposalArtifacts.proposal_diff,
+      manifest: proposalArtifacts.manifest,
+      proposal_sha256: proposalArtifacts.proposal_sha256,
+      proposal_edited: options.proposalEdited === true,
+    },
+    write_manifest: {
+      path: plannedManifest.path,
+    },
+  };
+  const postWriteValidation = validateAnalyzeProjectPostWrite(repoRoot, writeReport, {
+    strict: options.strict === true,
+  });
+  const finalManifest = writeAnalyzeProjectWriteManifest(repoRoot, {
+    runId,
+    now: new Date(),
+    proposalManifest: proposalArtifacts.manifest,
+    snapshot,
+    writePlan,
+    writtenDocs,
+    validation: postWriteValidation,
+    partialWrite: false,
+    status: 'completed',
+    events: [
+      ...applyEvents,
+      { type: 'write-planned', at: now.toISOString() },
+      { type: 'write-completed', at: new Date().toISOString(), written_docs: writtenDocs },
+    ],
+  });
+
+  return {
+    ...writeReport,
+    post_write_validation: postWriteValidation,
+    write_manifest: finalManifest,
+  };
+}
+
+module.exports = {
+  AnalyzeProjectApplyError,
+  applyAnalyzeProjectDocProposal,
+  assertAnalyzeProjectApplyPreflight,
+};

package/src/create-quiver/lib/ai/analyze-project-docs.js

@@ -93,6 +93,21 @@ function mergeManagedBlock(currentContent, proposedContent) {
   return `${current.replace(/\s+$/g, '')}\n\n${block}`;
 }
 
+function redactSnapshotValue(value, repoRoot) {
+  if (typeof value === 'string') {
+    return redactSensitiveLocalValues(value, { projectRoot: repoRoot });
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSnapshotValue(item, repoRoot));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, redactSnapshotValue(item, repoRoot)]),
+    );
+  }
+  return value;
+}
+
 function validateDocPath(docPath) {
   let normalized;
   try {
@@ -303,7 +318,7 @@ function createAnalyzeProjectSnapshot(repoRoot, run, writePlan, options = {}) {
 
   const providerArtifactPath = path.join(rawRoot, 'analyze-project-provider-artifact.json');
   const providerArtifact = options.providerArtifact
-    ? JSON.parse(redactSensitiveLocalValues(JSON.stringify(options.providerArtifact), { projectRoot: repoRoot }))
+    ? redactSnapshotValue(options.providerArtifact, repoRoot)
     : null;
   fs.writeFileSync(providerArtifactPath, `${JSON.stringify(providerArtifact, null, 2)}\n`);
 

package/src/create-quiver/lib/ai/analyze-project-interactive.js

@@ -0,0 +1,241 @@
+const { selectOption } = require('../cli/selectors');
+const { createUx, resolveUxMode } = require('../cli/ux');
+const { createTranslator } = require('../i18n/catalog');
+const { formatAnalyzeProjectDiffPreview } = require('./analyze-project-docs');
+
+const APPLY_ACTION = 'apply';
+const VIEW_DIFF_ACTION = 'view-diff';
+const SAVE_ACTION = 'save-proposal';
+const EDIT_ACTION = 'edit-proposal';
+const CANCEL_ACTION = 'cancel';
+
+function canUseAnalyzeProjectInteractiveSelector(options = {}) {
+  const mode = resolveUxMode({
+    interactive: true,
+    json: options.json,
+    noColor: options.noColor,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    stderrIsTTY: options.stderrIsTTY,
+  }, options.env || process.env, {
+    input: options.inputStream || process.stdin,
+    output: options.outputStream || process.stdout,
+    error: options.errorStream || process.stderr,
+  });
+  return mode.usePrompts === true;
+}
+
+function changedItems(writePlan = []) {
+  return (Array.isArray(writePlan) ? writePlan : []).filter((item) => item.action && item.action !== 'skip');
+}
+
+function selectRecommendedAction(writePlan = []) {
+  const changed = changedItems(writePlan);
+  const higherRisk = changed.some((item) => item.dirty === true || item.action === 'update');
+  return higherRisk ? VIEW_DIFF_ACTION : APPLY_ACTION;
+}
+
+function withRecommendation(label, recommended, translator) {
+  return recommended ? `${label} (${translator.t('ai.analyze_project.apply.recommended')})` : label;
+}
+
+function buildAnalyzeProjectApplyChoices(translator, recommendedAction, options = {}) {
+  const includeDiff = options.includeDiff !== false;
+  const applyChoice = {
+    label: withRecommendation(translator.t('ai.analyze_project.apply.option.apply.label'), recommendedAction === APPLY_ACTION, translator),
+    value: APPLY_ACTION,
+    hint: translator.t('ai.analyze_project.apply.option.apply.hint'),
+    default: recommendedAction === APPLY_ACTION,
+  };
+  const diffChoice = {
+    label: withRecommendation(translator.t('ai.analyze_project.apply.option.view_diff.label'), recommendedAction === VIEW_DIFF_ACTION, translator),
+    value: VIEW_DIFF_ACTION,
+    hint: translator.t('ai.analyze_project.apply.option.view_diff.hint'),
+    default: recommendedAction === VIEW_DIFF_ACTION,
+  };
+  const choices = [];
+
+  if (includeDiff && recommendedAction === VIEW_DIFF_ACTION) {
+    choices.push(diffChoice, applyChoice);
+  } else {
+    choices.push(applyChoice);
+    if (includeDiff) {
+      choices.push(diffChoice);
+    }
+  }
+
+  choices.push(
+    {
+      label: translator.t('ai.analyze_project.apply.option.save.label'),
+      value: SAVE_ACTION,
+      hint: translator.t('ai.analyze_project.apply.option.save.hint'),
+    },
+    {
+      label: translator.t('ai.analyze_project.apply.option.edit.label'),
+      value: EDIT_ACTION,
+      hint: translator.t('ai.analyze_project.apply.option.edit.hint'),
+    },
+    {
+      label: translator.t('ai.analyze_project.apply.option.cancel.label'),
+      value: CANCEL_ACTION,
+      hint: translator.t('ai.analyze_project.apply.option.cancel.hint'),
+    },
+  );
+
+  return choices;
+}
+
+function formatAnalyzeProjectApplySummary(report = {}, proposal = {}, writePlan = [], options = {}) {
+  const translator = createTranslator(options.language);
+  const changed = changedItems(writePlan);
+  const dirty = changed.filter((item) => item.dirty === true);
+  const docs = Array.isArray(proposal?.docs) ? proposal.docs : [];
+  const lines = [
+    translator.t('ai.analyze_project.apply.completed'),
+    translator.t('ai.analyze_project.apply.generated'),
+    '',
+    translator.t('ai.analyze_project.apply.proposed_files'),
+  ];
+
+  if (docs.length === 0) {
+    lines.push(`- ${translator.t('common.none')}`);
+  } else {
+    for (const doc of docs) {
+      const plan = writePlan.find((item) => item.path === doc.path);
+      lines.push(`- ${doc.path}${plan?.action ? ` (${plan.action})` : ''}`);
+    }
+  }
+
+  lines.push(
+    '',
+    translator.t('ai.analyze_project.apply.counts', {
+      changed: changed.length,
+      dirty: dirty.length,
+    }),
+  );
+
+  if (report.analysis_validation?.repaired === true || report.analysis_validation?.repair_manifest) {
+    lines.push(translator.t('ai.analyze_project.apply.repair', {
+      value: report.analysis_validation.repair_manifest?.path || report.analysis_validation.repair_manifest || translator.t('common.yes'),
+    }));
+  }
+  if (report.selected_context_manifest) {
+    lines.push(translator.t('ai.analyze_project.apply.context_artifact', {
+      path: report.selected_context_manifest.path || report.selected_context_manifest,
+    }));
+  }
+
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function formatBoundedAnalyzeProjectDiff(writePlan = [], options = {}) {
+  const translator = createTranslator(options.language);
+  const maxLines = Number.isInteger(options.maxDiffLines) ? Math.max(1, options.maxDiffLines) : 80;
+  const maxChars = Number.isInteger(options.maxDiffChars) ? Math.max(500, options.maxDiffChars) : 8_000;
+  const rawLines = formatAnalyzeProjectDiffPreview(writePlan);
+  const lines = rawLines.slice(0, maxLines);
+  let text = lines.join('\n');
+  let truncated = rawLines.length > lines.length;
+
+  if (text.length > maxChars) {
+    text = text.slice(0, maxChars).replace(/\s+$/g, '');
+    truncated = true;
+  }
+
+  if (truncated) {
+    text = `${text}\n${translator.t('ai.analyze_project.apply.diff_truncated')}`;
+  }
+
+  return `${translator.t('ai.analyze_project.apply.diff_title')}\n${text}\n`;
+}
+
+async function chooseAnalyzeProjectApplyAction(message, choices, options = {}) {
+  return selectOption(message, choices, {
+    name: 'ai analyze-project apply action',
+    flag: '--apply-docs',
+    interactive: true,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    stderrIsTTY: options.stderrIsTTY,
+    noColor: options.noColor,
+    env: options.env,
+    prompts: options.prompts,
+    promptSelect: options.promptSelect,
+    input: options.inputStream,
+    output: options.outputStream,
+    error: options.errorStream,
+  });
+}
+
+async function runAnalyzeProjectInteractiveApplySelector(context = {}) {
+  const options = context.options || {};
+  const translator = createTranslator(options.language);
+  const ux = createUx({ ...options, interactive: true });
+
+  if (!canUseAnalyzeProjectInteractiveSelector(options)) {
+    throw new Error([
+      'create-quiver: ai analyze-project --apply-docs requires an interactive TTY unless --yes is passed.',
+      'Next safe step: use `npx create-quiver ai analyze-project --deep --apply-docs --yes --provider <provider> --model <model>` for automation, or rerun from an interactive terminal.',
+    ].join('\n'));
+  }
+
+  const recommendedAction = selectRecommendedAction(context.writePlan);
+  process.stdout.write(formatAnalyzeProjectApplySummary(context.report, context.proposal, context.writePlan, options));
+
+  const first = await chooseAnalyzeProjectApplyAction(
+    translator.t('ai.analyze_project.apply.question'),
+    buildAnalyzeProjectApplyChoices(translator, recommendedAction),
+    options,
+  );
+
+  if (first.value === APPLY_ACTION) {
+    return context.actions.apply({ allowDirtyDocs: true, interactiveAction: APPLY_ACTION });
+  }
+  if (first.value === SAVE_ACTION) {
+    return context.actions.save({ interactiveAction: SAVE_ACTION });
+  }
+  if (first.value === EDIT_ACTION) {
+    return context.actions.edit({ interactiveAction: EDIT_ACTION });
+  }
+  if (first.value === CANCEL_ACTION) {
+    return context.actions.cancel({ interactiveAction: CANCEL_ACTION });
+  }
+
+  const savedReport = await context.actions.save({ interactiveAction: VIEW_DIFF_ACTION, silent: true });
+  ux.section(translator.t('ai.analyze_project.apply.full_diff_artifact', {
+    path: savedReport.proposal_artifacts?.proposal_diff || translator.t('common.none'),
+  }));
+  process.stdout.write(formatBoundedAnalyzeProjectDiff(context.writePlan, options));
+
+  const second = await chooseAnalyzeProjectApplyAction(
+    translator.t('ai.analyze_project.apply.after_diff_question'),
+    buildAnalyzeProjectApplyChoices(translator, APPLY_ACTION, { includeDiff: false }),
+    options,
+  );
+
+  if (second.value === APPLY_ACTION) {
+    return context.actions.apply({ allowDirtyDocs: true, interactiveAction: APPLY_ACTION });
+  }
+  if (second.value === SAVE_ACTION) {
+    return context.actions.save({ interactiveAction: SAVE_ACTION, savedReport });
+  }
+  if (second.value === EDIT_ACTION) {
+    return context.actions.edit({ interactiveAction: EDIT_ACTION });
+  }
+  return context.actions.cancel({ interactiveAction: CANCEL_ACTION, savedReport });
+}
+
+module.exports = {
+  APPLY_ACTION,
+  CANCEL_ACTION,
+  EDIT_ACTION,
+  SAVE_ACTION,
+  VIEW_DIFF_ACTION,
+  buildAnalyzeProjectApplyChoices,
+  canUseAnalyzeProjectInteractiveSelector,
+  formatAnalyzeProjectApplySummary,
+  formatBoundedAnalyzeProjectDiff,
+  runAnalyzeProjectInteractiveApplySelector,
+  selectRecommendedAction,
+};