create-quiver 0.17.1 → 0.17.3

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

@@ -1,4 +1,5 @@
 const fs = require('node:fs');
+const crypto = require('node:crypto');
 const os = require('node:os');
 const path = require('node:path');
 
@@ -7,6 +8,7 @@ const { quiverInternalPaths } = require('../init-layout');
 
 const RAW_ARTIFACT_SCHEMA_VERSION = 1;
 const DEFAULT_MAX_PROVIDER_PROMPT_BYTES = 1024 * 1024;
+const DEFAULT_MAX_RAW_PROVIDER_STREAM_BYTES = 64 * 1024;
 const DEFAULT_MAX_REVISION_INPUT_BYTES = 400 * 1024;
 const DEFAULT_COMPACTED_REVISION_INPUT_BYTES = 120 * 1024;
 
@@ -74,6 +76,71 @@ function normalizePositiveInteger(value, fallback) {
   return Math.floor(parsed);
 }
 
+function sha256(value) {
+  return crypto.createHash('sha256').update(String(value || ''), 'utf8').digest('hex');
+}
+
+function sliceStartToByteLimit(text, maxBytes) {
+  let value = String(text || '');
+  while (byteLength(value) > maxBytes && value.length > 0) {
+    value = value.slice(0, Math.max(0, value.length - Math.ceil((byteLength(value) - maxBytes) / 2) - 8));
+  }
+  return value;
+}
+
+function sliceEndToByteLimit(text, maxBytes) {
+  let value = String(text || '');
+  while (byteLength(value) > maxBytes && value.length > 0) {
+    value = value.slice(Math.min(value.length, Math.ceil((byteLength(value) - maxBytes) / 2) + 8));
+  }
+  return value;
+}
+
+function limitRawProviderStream(text, options = {}) {
+  const maxBytes = normalizePositiveInteger(
+    options.maxBytes ?? process.env.QUIVER_AI_MAX_RAW_PROVIDER_STREAM_BYTES,
+    DEFAULT_MAX_RAW_PROVIDER_STREAM_BYTES,
+  );
+  const value = normalizeText(text);
+  const originalBytes = byteLength(value);
+  const digest = sha256(value);
+
+  if (originalBytes <= maxBytes) {
+    return {
+      text: value,
+      metadata: {
+        bytes: originalBytes,
+        stored_bytes: originalBytes,
+        max_bytes: maxBytes,
+        truncated: false,
+        sha256: digest,
+      },
+    };
+  }
+
+  const marker = `\n[... Quiver truncated provider stream; original_bytes=${originalBytes}; sha256=${digest} ...]\n`;
+  const markerBytes = byteLength(marker);
+  const contentBudget = Math.max(0, maxBytes - markerBytes);
+  const headBudget = Math.floor(contentBudget * 0.6);
+  const tailBudget = contentBudget - headBudget;
+  const head = sliceStartToByteLimit(value, headBudget);
+  const tail = sliceEndToByteLimit(value, tailBudget);
+  const stored = `${head}${marker}${tail}`;
+
+  return {
+    text: stored,
+    metadata: {
+      bytes: originalBytes,
+      stored_bytes: byteLength(stored),
+      max_bytes: maxBytes,
+      truncated: true,
+      sha256: digest,
+      head_bytes: byteLength(head),
+      tail_bytes: byteLength(tail),
+    },
+  };
+}
+
 function resolveAiArtifactLimits(options = {}) {
   return {
     maxProviderPromptBytes: normalizePositiveInteger(
@@ -185,6 +252,14 @@ function writeRawProviderArtifact(projectRoot, runId, scope, result, options = {
         command: result.error.command || null,
       }
     : null;
+  const stdout = limitRawProviderStream(
+    redactSensitiveLocalValues(result?.stdout || '', { projectRoot }),
+    { maxBytes: options.maxRawProviderStreamBytes },
+  );
+  const stderr = limitRawProviderStream(
+    redactSensitiveLocalValues(result?.stderr || '', { projectRoot }),
+    { maxBytes: options.maxRawProviderStreamBytes },
+  );
   const artifact = {
     schema_version: RAW_ARTIFACT_SCHEMA_VERSION,
     kind: 'provider-output',
@@ -200,8 +275,12 @@ function writeRawProviderArtifact(projectRoot, runId, scope, result, options = {
     signal: result?.signal || null,
     timeout_ms: typeof result?.timeoutMs === 'number' ? result.timeoutMs : null,
     prompt_transport: result?.promptTransport || null,
-    stdout: redactSensitiveLocalValues(result?.stdout || '', { projectRoot }),
-    stderr: redactSensitiveLocalValues(result?.stderr || '', { projectRoot }),
+    stdout: stdout.text,
+    stderr: stderr.text,
+    streams: {
+      stdout: stdout.metadata,
+      stderr: stderr.metadata,
+    },
     error: serializedError ? JSON.parse(redactSensitiveLocalValues(JSON.stringify(serializedError), { projectRoot })) : null,
     metadata: options.metadata || {},
   };
@@ -309,12 +388,14 @@ function assertProviderPromptWithinLimit(prompt, options = {}) {
 module.exports = {
   DEFAULT_COMPACTED_REVISION_INPUT_BYTES,
   DEFAULT_MAX_PROVIDER_PROMPT_BYTES,
+  DEFAULT_MAX_RAW_PROVIDER_STREAM_BYTES,
   DEFAULT_MAX_REVISION_INPUT_BYTES,
   RAW_ARTIFACT_SCHEMA_VERSION,
   assertProviderPromptWithinLimit,
   byteLength,
   compactRevisionInput,
   extractCleanProviderOutput,
+  limitRawProviderStream,
   redactSensitiveLocalValues,
   resolveAiArtifactLimits,
   writeRawProviderArtifact,

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

@@ -17,6 +17,12 @@ const UX_FLAG_MATRIX = Object.freeze({
     review: true,
     note: 'planner-assisted docs-only context preparation',
   }),
+  'ai analyze-project': Object.freeze({
+    withPlanner: false,
+    interactive: false,
+    review: true,
+    note: 'deep project analysis and advanced proposal review',
+  }),
   'ai plan': Object.freeze({
     withPlanner: true,
     interactive: true,

package/src/create-quiver/lib/doctor.js

@@ -39,6 +39,75 @@ const ROOT_GITIGNORE_DEFAULTS = [
   'coverage/',
 ];
 
+const AGENTS_SECTION_DEFAULTS = [
+  {
+    label: 'Purpose',
+    pattern: /^Purpose$/m,
+    lines: [
+      'Purpose',
+      '',
+      'This file routes AI agents in this repository. Read it before loading broader project context.',
+    ],
+  },
+  {
+    label: 'Reading Budget',
+    pattern: /^## Reading Budget$/m,
+    lines: [
+      '## Reading Budget',
+      '',
+      '- Planning: load only the docs needed for the current requirement.',
+      '- Execution: start from the active slice context before reading broad docs.',
+      '- Debug: gather the smallest reproducible evidence before proposing fixes.',
+    ],
+  },
+  {
+    label: 'Reading Order',
+    pattern: /^## Reading Order$/m,
+    lines: [
+      '## Reading Order',
+      '',
+      '1. README.md',
+      '2. docs/AI_CONTEXT.md',
+      '3. docs/PROJECT_MAP.md when architecture or structure facts are needed',
+      '4. Active spec/slice docs only when working on an approved slice',
+    ],
+  },
+  {
+    label: 'Output Policy',
+    pattern: /^## Output Policy$/m,
+    lines: [
+      '## Output Policy',
+      '',
+      '- Keep responses concise and actionable.',
+      '- Cite files or commands when reporting evidence.',
+      '- Do not claim unsupported project facts as confirmed.',
+    ],
+  },
+  {
+    label: 'Slice Execution Rules',
+    pattern: /^## Slice Execution Rules$/m,
+    lines: [
+      '## Slice Execution Rules',
+      '',
+      '- Do not implement code before acceptance criteria and technical plan approval.',
+      '- Execute one approved slice at a time.',
+      '- Keep changes inside the slice scope unless the handoff explicitly allows expansion.',
+    ],
+  },
+  {
+    label: 'Links',
+    pattern: /^## Links$/m,
+    lines: [
+      '## Links',
+      '',
+      '- AI Context: `./docs/AI_CONTEXT.md`',
+      '- Project Map: `./docs/PROJECT_MAP.md`',
+      '- Decisions: `./docs/DECISIONS.md`',
+      '- Workflow: `./docs/WORKFLOW.md`',
+    ],
+  },
+];
+
 function readTextIfExists(filePath) {
   if (!fs.existsSync(filePath)) {
     return null;
@@ -152,21 +221,30 @@ function countAgentsSections(projectRoot) {
     return ['AGENTS.md'];
   }
 
-  const requiredSections = [
-    [/^Purpose$/m, 'Purpose'],
-    [/^## Reading Budget$/m, 'Reading Budget'],
-    [/^## Reading Order$/m, 'Reading Order'],
-    [/^## Output Policy$/m, 'Output Policy'],
-    [/^## Slice Execution Rules$/m, 'Slice Execution Rules'],
-    [/^## Links$/m, 'Links'],
-  ];
-
-  const missing = requiredSections
-    .filter(([pattern]) => !pattern.test(text))
-    .map(([, label]) => label);
+  const missing = AGENTS_SECTION_DEFAULTS
+    .filter((section) => !section.pattern.test(text))
+    .map((section) => section.label);
   return missing;
 }
 
+function buildAgentsContractText(sectionLabels = null) {
+  const labels = Array.isArray(sectionLabels) && sectionLabels.length > 0
+    ? new Set(sectionLabels)
+    : null;
+  const selectedSections = AGENTS_SECTION_DEFAULTS.filter((section) => !labels || labels.has(section.label));
+  const lines = labels ? [] : ['# AGENTS Router', ''];
+  for (const [index, section] of selectedSections.entries()) {
+    if (lines.length > 0 && lines[lines.length - 1] !== '') {
+      lines.push('');
+    }
+    if (index > 0 && lines[lines.length - 1] !== '') {
+      lines.push('');
+    }
+    lines.push(...section.lines);
+  }
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n')}\n`;
+}
+
 function countTieredPackSizeWarnings(projectRoot) {
   const warnings = [];
 
@@ -522,6 +600,23 @@ function buildDoctorFixPlan(projectRoot) {
     });
   }
 
+  const agentsMissing = countAgentsSections(projectRoot);
+  if (agentsMissing.includes('AGENTS.md')) {
+    fixes.push({
+      type: 'write-json-or-text',
+      path: 'AGENTS.md',
+      description: 'Create missing AGENTS.md AI routing contract.',
+      content: buildAgentsContractText(),
+    });
+  } else if (agentsMissing.length > 0) {
+    fixes.push({
+      type: 'append-lines',
+      path: 'AGENTS.md',
+      description: `Append missing AGENTS.md contract sections: ${agentsMissing.join(', ')}.`,
+      lines: buildAgentsContractText(agentsMissing).trimEnd().split('\n'),
+    });
+  }
+
   const packageJsonPath = path.join(projectRoot, 'package.json');
   if (fs.existsSync(packageJsonPath)) {
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));

package/src/create-quiver/lib/i18n/messages/en.js

@@ -15,6 +15,10 @@ module.exports = {
       commandDescriptions: {},
       optionDescriptions: {
         'Show one human dashboard section': 'Show one human dashboard section (overview, specs, slices, blockers, warnings, agents, approvals, runs, active-slice, next-steps)',
+        'For ai analyze-project, apply validated documentation proposals through the safe docs workflow': 'For ai analyze-project, apply validated documentation proposals through the safe docs workflow',
+        'For ai analyze-project, save a validated documentation proposal without writing final docs': 'For ai analyze-project, save a validated documentation proposal without writing final docs',
+        'For ai analyze-project, show or save the proposed documentation diff': 'For ai analyze-project, show or save the proposed documentation diff',
+        'For ai analyze-project, allow dirty target docs checks where the safe apply workflow supports it': 'For ai analyze-project, allow dirty target docs checks where the safe apply workflow supports it',
       },
     },
     'common.command.help': 'Run: npx create-quiver --help',
@@ -56,6 +60,30 @@ module.exports = {
     'ai.actionable.fix': 'Fix',
     'ai.actionable.impact': 'Impact',
     'ai.actionable.next_command': 'Next command',
+    'ai.analyze_project.apply.after_diff_question': 'What do you want to do after reviewing the diff?',
+    'ai.analyze_project.apply.cancelled': 'AI analyze-project apply canceled',
+    'ai.analyze_project.apply.cancelled_writes': 'Writes: none (final docs were not modified)',
+    'ai.analyze_project.apply.completed': 'Analysis completed.',
+    'ai.analyze_project.apply.context_artifact': 'Selected context: {path}',
+    'ai.analyze_project.apply.counts': 'Changes: {changed}; dirty target docs: {dirty}',
+    'ai.analyze_project.apply.diff_title': 'Diff preview',
+    'ai.analyze_project.apply.diff_truncated': '[diff truncated; full diff saved in the artifact]',
+    'ai.analyze_project.apply.full_diff_artifact': 'Full diff artifact: {path}',
+    'ai.analyze_project.apply.generated': 'AI generated a documentation proposal from the project source code.',
+    'ai.analyze_project.apply.option.apply.hint': 'Writes proposed docs using safe merge and a prior snapshot.',
+    'ai.analyze_project.apply.option.apply.label': 'Apply documentation',
+    'ai.analyze_project.apply.option.cancel.hint': 'Does not write final documentation.',
+    'ai.analyze_project.apply.option.cancel.label': 'Cancel',
+    'ai.analyze_project.apply.option.edit.hint': 'Opens the proposal in your editor before applying.',
+    'ai.analyze_project.apply.option.edit.label': 'Edit proposal',
+    'ai.analyze_project.apply.option.save.hint': 'Saves the proposal under .quiver/runs without final docs writes.',
+    'ai.analyze_project.apply.option.save.label': 'Save proposal',
+    'ai.analyze_project.apply.option.view_diff.hint': 'Shows a bounded terminal diff before deciding.',
+    'ai.analyze_project.apply.option.view_diff.label': 'View diff',
+    'ai.analyze_project.apply.proposed_files': 'Proposed files:',
+    'ai.analyze_project.apply.question': 'What do you want to do?',
+    'ai.analyze_project.apply.recommended': 'recommended',
+    'ai.analyze_project.apply.repair': 'Repair manifest: {value}',
     'ai.agent.choice.model_available': 'available',
     'ai.agent.choice.model_custom': 'Custom',
     'ai.agent.choice.model_recommended': 'recommended',
@@ -282,10 +310,15 @@ module.exports = {
     'ai.planner.progress.reading_base_docs': 'Reading base docs',
     'ai.planner.progress.reading_input': 'Reading input',
     'ai.planner.progress.reading_technical_plan': 'Reading technical plan',
+    'ai.planner.progress.repairing_schema': 'Repairing schema drift',
     'ai.planner.progress.repair_plan': 'Running plan repair',
+    'ai.planner.progress.retrying_agent': 'Retrying agent',
     'ai.planner.progress.review_plan': 'Running plan review',
     'ai.planner.progress.running_agent': 'Running agent...',
+    'ai.planner.progress.selecting_sample': 'Selecting sample',
     'ai.planner.progress.title': '{action} with {profile}',
+    'ai.planner.progress.validating_schema': 'Validating schema',
+    'ai.planner.progress.writing_artifacts': 'Writing artifacts',
     'ai.repair_plan.original_preserved': 'Original approved artifact: preserved',
     'ai.repair_plan.saved': 'AI technical-plan repair draft saved',
     'ai.repair_plan.source_approved_artifact': 'Source approved artifact',

package/src/create-quiver/lib/i18n/messages/es.js

@@ -37,6 +37,7 @@ module.exports = {
         'ai active-slice status|reconcile': 'Inspecciona o simula reconciliar el estado local de active-slice desde todas las fuentes soportadas.',
         'ai status': 'Muestra fase actual del ciclo de vida de IA, versiones aprobadas, bloqueos y proximo comando.',
         'ai resume': 'Reanuda la guia desde la ultima fase valida del ciclo de vida sin memoria de chat.',
+        'ai analyze-project': 'Analiza una muestra acotada del proyecto y genera propuestas documentales auditadas.',
         'ai onboard': 'Ejecuta o imprime el prompt de onboarding del planner con contexto optimizado por tokens.',
         'ai prepare-context': 'Previsualiza o escribe actualizaciones docs-only del contexto de IA con supuestos y riesgos.',
         'ai agent set|list|show|doctor|repair': 'Gestiona, diagnostica y simula reparaciones de perfiles planner, executor, reviewer y doctor sin secretos.',
@@ -108,6 +109,10 @@ module.exports = {
         'Enable planner-assisted behavior on commands that explicitly support it': 'Activa comportamiento asistido por planner en comandos que lo soportan explicitamente',
         'Enable prompts on commands that explicitly support interactive choices': 'Activa prompts en comandos que soportan elecciones interactivas explicitamente',
         'Open or prepare human review before persistent writes where supported': 'Abre o prepara revision humana antes de escrituras persistentes donde este soportado',
+        'For ai analyze-project, apply validated documentation proposals through the safe docs workflow': 'En ai analyze-project, aplica propuestas de documentacion validadas mediante el flujo seguro de docs',
+        'For ai analyze-project, save a validated documentation proposal without writing final docs': 'En ai analyze-project, guarda una propuesta de documentacion validada sin escribir docs finales',
+        'For ai analyze-project, show or save the proposed documentation diff': 'En ai analyze-project, muestra o guarda el diff de documentacion propuesto',
+        'For ai analyze-project, allow dirty target docs checks where the safe apply workflow supports it': 'En ai analyze-project, permite checks de docs destino con cambios donde el flujo seguro lo soporte',
         'Select methodology where supported (currently wdd-sdd)': 'Selecciona metodologia donde este soportado (actualmente wdd-sdd)',
         'Disable ANSI colors in human output': 'Desactiva colores ANSI en la salida humana',
         'For doctor, apply safe non-destructive repairs': 'En doctor, aplica reparaciones seguras no destructivas',
@@ -171,6 +176,30 @@ module.exports = {
     'ai.actionable.fix': 'Arreglo',
     'ai.actionable.impact': 'Impacto',
     'ai.actionable.next_command': 'Siguiente comando',
+    'ai.analyze_project.apply.after_diff_question': 'Que queres hacer despues de revisar el diff?',
+    'ai.analyze_project.apply.cancelled': 'Aplicacion de analyze-project cancelada',
+    'ai.analyze_project.apply.cancelled_writes': 'Escrituras: ninguna (no se modificaron docs finales)',
+    'ai.analyze_project.apply.completed': 'Analisis completado.',
+    'ai.analyze_project.apply.context_artifact': 'Contexto seleccionado: {path}',
+    'ai.analyze_project.apply.counts': 'Cambios: {changed}; docs destino con contenido: {dirty}',
+    'ai.analyze_project.apply.diff_title': 'Vista previa del diff',
+    'ai.analyze_project.apply.diff_truncated': '[diff truncado; el diff completo se guardo en el artifact]',
+    'ai.analyze_project.apply.full_diff_artifact': 'Artifact de diff completo: {path}',
+    'ai.analyze_project.apply.generated': 'La IA genero una propuesta de documentacion basada en el codigo del proyecto.',
+    'ai.analyze_project.apply.option.apply.hint': 'Escribe los docs propuestos usando merge seguro y snapshot previo.',
+    'ai.analyze_project.apply.option.apply.label': 'Aplicar documentacion',
+    'ai.analyze_project.apply.option.cancel.hint': 'No escribe documentacion final.',
+    'ai.analyze_project.apply.option.cancel.label': 'Cancelar',
+    'ai.analyze_project.apply.option.edit.hint': 'Abre la propuesta en tu editor antes de aplicar.',
+    'ai.analyze_project.apply.option.edit.label': 'Editar propuesta',
+    'ai.analyze_project.apply.option.save.hint': 'Guarda la propuesta en .quiver/runs sin escribir docs finales.',
+    'ai.analyze_project.apply.option.save.label': 'Guardar propuesta',
+    'ai.analyze_project.apply.option.view_diff.hint': 'Muestra un diff acotado en terminal antes de decidir.',
+    'ai.analyze_project.apply.option.view_diff.label': 'Ver diff',
+    'ai.analyze_project.apply.proposed_files': 'Archivos propuestos:',
+    'ai.analyze_project.apply.question': 'Que queres hacer?',
+    'ai.analyze_project.apply.recommended': 'recomendado',
+    'ai.analyze_project.apply.repair': 'Manifest de reparacion: {value}',
     'ai.agent.choice.model_available': 'disponible',
     'ai.agent.choice.model_custom': 'Custom',
     'ai.agent.choice.model_recommended': 'recomendado',
@@ -397,10 +426,15 @@ module.exports = {
     'ai.planner.progress.reading_base_docs': 'Leyendo docs base',
     'ai.planner.progress.reading_input': 'Leyendo entrada',
     'ai.planner.progress.reading_technical_plan': 'Leyendo plan tecnico',
+    'ai.planner.progress.repairing_schema': 'Reparando drift de schema',
     'ai.planner.progress.repair_plan': 'Ejecutando reparacion del plan',
+    'ai.planner.progress.retrying_agent': 'Reintentando agente',
     'ai.planner.progress.review_plan': 'Ejecutando revision del plan',
     'ai.planner.progress.running_agent': 'Ejecutando agente...',
+    'ai.planner.progress.selecting_sample': 'Seleccionando muestra',
     'ai.planner.progress.title': '{action} con {profile}',
+    'ai.planner.progress.validating_schema': 'Validando schema',
+    'ai.planner.progress.writing_artifacts': 'Escribiendo artifacts',
     'ai.repair_plan.original_preserved': 'Artefacto aprobado original: preservado',
     'ai.repair_plan.saved': 'Draft de reparacion de technical-plan guardado',
     'ai.repair_plan.source_approved_artifact': 'Artefacto aprobado fuente',