create-quiver 0.10.0 → 0.12.0

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

@@ -1,8 +1,11 @@
 const fs = require('node:fs');
 const path = require('node:path');
+const cp = require('node:child_process');
 
 const { buildContextPackMetadata, normalizeRole } = require('./context-packs');
 const { buildProviderInvocation, runProvider } = require('./providers');
+const { resolveProfileProvider } = require('../agent-profiles');
+const { runGit } = require('../git');
 const { captureWorktreeSnapshot, validateScopeSnapshot } = require('../scope');
 const { resolveSliceContext } = require('../slice');
 
@@ -74,6 +77,199 @@ function formatList(items) {
   return items.map((item) => `- ${item}`);
 }
 
+function extractMarkdownHeading(text) {
+  const match = String(text || '').match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : '';
+}
+
+function extractMarkdownSection(text, headings) {
+  const lines = String(text || '').split(/\r?\n/);
+  const normalized = new Set(headings.map((heading) => String(heading).trim().toLowerCase()));
+  const section = [];
+  let capture = false;
+
+  for (const line of lines) {
+    const heading = line.match(/^##\s+(.+)$/);
+    if (heading) {
+      const key = heading[1].trim().toLowerCase();
+      if (normalized.has(key)) {
+        capture = true;
+        continue;
+      }
+      if (capture) {
+        break;
+      }
+    }
+
+    if (capture) {
+      section.push(line);
+    }
+  }
+
+  return section.join('\n').trim();
+}
+
+function buildSpecExcerpt(repoRoot, slice) {
+  const specPath = path.join(slice.specDirAbs, 'SPEC.md');
+  if (!fs.existsSync(specPath)) {
+    return {
+      path: toRelativePath(repoRoot, specPath),
+      lines: ['- n/a'],
+    };
+  }
+
+  const text = fs.readFileSync(specPath, 'utf8');
+  const title = extractMarkdownHeading(text);
+  const objective = extractMarkdownSection(text, ['Objective', 'Objetivo']);
+  const lines = [];
+
+  if (title) {
+    lines.push(`- Title: ${title}`);
+  }
+  if (objective) {
+    lines.push(`- Objective: ${objective.replace(/\s+/g, ' ').slice(0, 500)}`);
+  }
+  if (lines.length === 0) {
+    lines.push('- SPEC.md exists, but no short title/objective excerpt was found.');
+  }
+
+  return {
+    path: toRelativePath(repoRoot, specPath),
+    lines,
+  };
+}
+
+function buildManualExecutorPrompt({ repoRoot, slicePath, role, context, tokenLimit } = {}) {
+  const executorContext = buildExecuteSliceContext({
+    repoRoot,
+    slicePath,
+    role: role || DEFAULT_EXECUTE_ROLE,
+    context: context || DEFAULT_EXECUTE_CONTEXT,
+  });
+  const canonicalRepoRoot = canonicalizeRepoRoot(repoRoot);
+  const closurePath = path.join(path.dirname(executorContext.slice.sliceAbs), 'CLOSURE_BRIEF.md');
+  const closureText = readTextFile(closurePath, canonicalRepoRoot);
+  const relativeClosurePath = toRelativePath(canonicalRepoRoot, closurePath);
+  const specExcerpt = buildSpecExcerpt(canonicalRepoRoot, executorContext.slice);
+  const slice = executorContext.slice;
+  const objective = String(slice.json.objective || slice.json.description || slice.sliceId).trim();
+  const restrictions = [
+    'Do not read the whole repo.',
+    'Do not modify files outside the allowed files.',
+    'Before editing, list the files you will read and the files you expect to modify.',
+    'Do not add unrequested features.',
+    'Do not refactor architecture unless the slice explicitly requires it.',
+    'If another file is needed, justify why before reading it.',
+    'If blocked, stop and report the blocker before improvising.',
+  ];
+  const outputFormat = [
+    '## Cambios realizados',
+    '## Archivos modificados',
+    '## Comandos ejecutados',
+    '## Validaciones',
+    '## Riesgos pendientes',
+    '## Proximo paso recomendado',
+  ];
+  const promptLines = [
+    'Act as a WDD + SDD executor agent.',
+    '',
+    'MODE: controlled SLICE execution.',
+    '',
+    'Slice objective:',
+    objective || 'n/a',
+    '',
+    'Minimal context:',
+    `- Spec: ${slice.specSlug}`,
+    `- Slice: ${slice.sliceId}`,
+    `- Slice file: ${slice.sliceRel}`,
+    `- Execution brief: ${executorContext.briefPath}`,
+    `- Closure brief: ${relativeClosurePath}`,
+    '',
+    'Relevant SPEC excerpts:',
+    `- Source: ${specExcerpt.path}`,
+    ...specExcerpt.lines,
+    '',
+    'Allowed files:',
+    ...formatList(executorContext.allowedFiles),
+    '',
+    'Restrictions:',
+    ...formatList(restrictions),
+    '',
+    'Acceptance criteria:',
+    ...formatList(slice.acceptance),
+    '',
+    'Validation commands:',
+    ...formatList(executorContext.validationCommands),
+    '',
+    'Exact deliverable expected:',
+    '- Implement only this slice.',
+    '- Keep the change inside the allowed files.',
+    '- Leave evidence in the final report.',
+    '',
+    'Required final report format:',
+    ...outputFormat.map((line) => `- ${line}`),
+    '',
+    `Suggested token limit: ${Number(tokenLimit) > 0 ? Number(tokenLimit) : 3000}`,
+    '',
+    'Execution brief content:',
+    executorContext.briefText.trimEnd(),
+    '',
+    'Closure brief content:',
+    closureText.trimEnd(),
+  ];
+
+  return {
+    allowedFiles: executorContext.allowedFiles,
+    closurePath: relativeClosurePath,
+    prompt: `${promptLines.join('\n')}\n`,
+    slice,
+    specExcerpt,
+    validationCommands: executorContext.validationCommands,
+  };
+}
+
+function runPromptSlice(repoRoot, options = {}) {
+  if (!options.slice) {
+    throw new Error(formatError('missing required --slice path for ai prompt-slice'));
+  }
+
+  const built = buildManualExecutorPrompt({
+    repoRoot,
+    slicePath: options.slice,
+    tokenLimit: options.tokenLimit,
+  });
+  process.stdout.write(built.prompt);
+
+  return {
+    task: 'prompt-slice',
+    slice: built.slice.sliceId,
+    specSlug: built.slice.specSlug,
+    prompt: built.prompt,
+  };
+}
+
+function buildRecoveryGuidance(slice) {
+  const sliceRef = slice && slice.sliceRel ? slice.sliceRel : '<slice.json>';
+  return [
+    'Recovery:',
+    `- Retry: npx create-quiver ai execute-slice --slice ${sliceRef}`,
+    '- Abort: inspect the local changes, then manually revert or stash anything you do not want to keep.',
+    '- Commit: rerun with --commit only after provider, scope, and validation pass.',
+  ].join('\n');
+}
+
+function appendRecovery(error, slice) {
+  if (!error || !error.message || error.message.includes('Recovery:')) {
+    return error;
+  }
+
+  const wrapped = new Error(`${error.message}\n\n${buildRecoveryGuidance(slice)}`);
+  wrapped.cause = error;
+  wrapped.code = error.code;
+  wrapped.details = error.details;
+  return wrapped;
+}
+
 function buildExecuteSliceContext({ repoRoot, slicePath, role, context }) {
   const canonicalRepoRoot = canonicalizeRepoRoot(repoRoot);
   const resolvedRole = normalizeRole(role || DEFAULT_EXECUTE_ROLE);
@@ -123,7 +319,7 @@ function buildExecuteSliceContext({ repoRoot, slicePath, role, context }) {
 
   sections.push(
     'Constraints:',
-    '- Do not commit automatically.',
+    '- Do not commit manually. Quiver can create the slice commit after scope and validation pass when the user enables --commit.',
     '- Do not fix scope violations automatically.',
     '- Do not run multiple executors concurrently.',
     '- Stay inside the allowed files declared by slice.json.',
@@ -142,7 +338,7 @@ function buildExecuteSliceContext({ repoRoot, slicePath, role, context }) {
   };
 }
 
-function formatExecuteSliceDryRunReport({ provider, role, contextPack, slice, briefPath, invocation, validationCommands, allowedFiles }) {
+function formatExecuteSliceDryRunReport({ provider, role, contextPack, slice, briefPath, invocation, validationCommands, allowedFiles, commitEnabled }) {
   const lines = [
     'AI execute-slice dry-run',
     `Provider: ${provider}`,
@@ -155,6 +351,7 @@ function formatExecuteSliceDryRunReport({ provider, role, contextPack, slice, br
     `Timeout: ${invocation.timeoutMs}ms`,
     `Prompt transport: ${invocation.promptTransport.mode}`,
     `Prompt length: ${invocation.promptLength} bytes`,
+    `Commit after validation: ${commitEnabled ? 'enabled' : 'disabled'}`,
     'Allowed files:',
     ...formatList(allowedFiles),
     'Validation commands:',
@@ -164,7 +361,7 @@ function formatExecuteSliceDryRunReport({ provider, role, contextPack, slice, br
   return `${lines.join('\n')}\n`;
 }
 
-function formatExecuteSliceResult({ slice, changedFiles, scopeResult }) {
+function formatExecuteSliceResult({ slice, changedFiles, scopeResult, validationResults, commitResult, commitEnabled }) {
   const lines = [
     'AI execute-slice completed',
     `Slice: ${slice.sliceId}`,
@@ -177,6 +374,17 @@ function formatExecuteSliceResult({ slice, changedFiles, scopeResult }) {
   }
 
   lines.push(`Scope validation: ${scopeResult.ok ? 'passed' : 'failed'}`);
+  if (!Array.isArray(validationResults) || validationResults.length === 0) {
+    lines.push('Validation commands: skipped (none declared)');
+  } else {
+    lines.push(`Validation commands: passed (${validationResults.length})`);
+  }
+  if (commitResult) {
+    lines.push(`Commit: created ${commitResult.hash}`);
+    lines.push(`Commit message: ${commitResult.message}`);
+  } else {
+    lines.push(`Commit: ${commitEnabled ? 'not created' : 'skipped'}`);
+  }
 
   return `${lines.join('\n')}\n`;
 }
@@ -190,9 +398,105 @@ function annotateProviderError(error, scope) {
   return wrapped;
 }
 
+function runValidationCommand(command, repoRoot) {
+  try {
+    const stdout = cp.execSync(command, {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      shell: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return {
+      command,
+      ok: true,
+      stdout,
+      stderr: '',
+      exitCode: 0,
+    };
+  } catch (error) {
+    return {
+      command,
+      ok: false,
+      stdout: error.stdout ? String(error.stdout) : '',
+      stderr: error.stderr ? String(error.stderr) : '',
+      exitCode: Number.isInteger(error.status) ? error.status : 1,
+      error,
+    };
+  }
+}
+
+function runValidationCommands(repoRoot, commands, runner = runValidationCommand) {
+  const results = [];
+  for (const command of commands) {
+    const result = runner(command, repoRoot);
+    results.push(result);
+    if (!result.ok) {
+      const details = [
+        formatError(`validation command failed: ${command}`),
+        `Exit code: ${result.exitCode}`,
+      ];
+      if (result.stderr) {
+        details.push(`stderr:\n${result.stderr.trimEnd()}`);
+      }
+      if (result.stdout) {
+        details.push(`stdout:\n${result.stdout.trimEnd()}`);
+      }
+      const error = new Error(details.join('\n'));
+      error.code = 'VALIDATION_FAILED';
+      error.details = { command, result, results };
+      throw error;
+    }
+  }
+  return results;
+}
+
+function commitTypeForSlice(slice) {
+  const type = String(slice.json.type || slice.json.git?.branch_type || '').trim().toLowerCase();
+  if (type === 'bugfix' || type === 'hotfix' || type === 'fix') {
+    return 'fix';
+  }
+  if (type === 'docs' || type === 'documentation') {
+    return 'docs';
+  }
+  if (type === 'test' || type === 'tests') {
+    return 'test';
+  }
+  if (type === 'chore') {
+    return 'chore';
+  }
+  return 'feat';
+}
+
+function buildSliceCommitMessage(slice) {
+  const title = String(slice.json.title || slice.sliceId || 'slice').trim();
+  const ticket = String(slice.ticket || '').trim();
+  const subject = ticket ? `${ticket} ${title}` : title;
+  return `${commitTypeForSlice(slice)}: ${subject}`;
+}
+
+function commitSliceChanges(repoRoot, slice, changedFiles, options = {}) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    const error = new Error(formatError('commit requested but provider produced no changed files.'));
+    error.code = 'NO_CHANGES_TO_COMMIT';
+    throw error;
+  }
+
+  const message = options.message || buildSliceCommitMessage(slice);
+  runGit(['add', '--', ...changedFiles], repoRoot);
+  runGit(['commit', '-m', message], repoRoot);
+
+  return {
+    files: changedFiles,
+    hash: runGit(['rev-parse', '--short', 'HEAD'], repoRoot),
+    message,
+  };
+}
+
 async function runExecuteSlice(repoRoot, options = {}) {
-  const provider = String(options.provider || DEFAULT_EXECUTE_PROVIDER).trim().toLowerCase();
   const role = normalizeRole(options.role || DEFAULT_EXECUTE_ROLE);
+  const provider = options.providerExplicit === true || (options.provider && options.providerExplicit !== false)
+    ? String(options.provider || DEFAULT_EXECUTE_PROVIDER).trim().toLowerCase()
+    : resolveProfileProvider(repoRoot, role, DEFAULT_EXECUTE_PROVIDER);
   const context = options.context || DEFAULT_EXECUTE_CONTEXT;
   const timeoutMs = normalizeTimeout(options.timeout);
 
@@ -231,6 +535,7 @@ async function runExecuteSlice(repoRoot, options = {}) {
       briefPath: executorContext.briefPath,
       allowedFiles: executorContext.allowedFiles,
       validationCommands: executorContext.validationCommands,
+      commitEnabled: options.commit === true,
     };
     process.stdout.write(formatExecuteSliceDryRunReport({
       provider,
@@ -241,13 +546,14 @@ async function runExecuteSlice(repoRoot, options = {}) {
       invocation,
       validationCommands: executorContext.validationCommands,
       allowedFiles: executorContext.allowedFiles,
+      commitEnabled: options.commit === true,
     }));
     return report;
   }
 
   const beforeSnapshot = captureWorktreeSnapshot(repoRoot);
   if (beforeSnapshot.files.length > 0 && options.allowDirty !== true) {
-    throw new Error(formatError(`ai execute-slice requires a clean worktree before running. Commit or stash first: ${beforeSnapshot.files.join(', ')}`));
+    throw appendRecovery(new Error(formatError(`ai execute-slice requires a clean worktree before running. Commit or stash first: ${beforeSnapshot.files.join(', ')}`)), executorContext.slice);
   }
 
   let result;
@@ -264,7 +570,7 @@ async function runExecuteSlice(repoRoot, options = {}) {
       tempFilePrefix: options.tempFilePrefix,
     });
   } catch (error) {
-    throw annotateProviderError(error, 'execute-slice');
+    throw appendRecovery(annotateProviderError(error, 'execute-slice'), executorContext.slice);
   }
 
   if (result.stdout) {
@@ -275,21 +581,64 @@ async function runExecuteSlice(repoRoot, options = {}) {
   }
 
   if (!result.ok) {
-    throw annotateProviderError(result.error || new Error('provider run failed'), 'execute-slice');
+    throw appendRecovery(annotateProviderError(result.error || new Error('provider run failed'), 'execute-slice'), executorContext.slice);
   }
 
   const afterSnapshot = captureWorktreeSnapshot(repoRoot);
-  const scopeResult = validateScopeSnapshot({
-    allowedFiles: executorContext.allowedFiles,
-    beforeSnapshot,
-    afterSnapshot,
-    strict: true,
-  });
+  let scopeResult;
+  try {
+    scopeResult = validateScopeSnapshot({
+      allowedFiles: executorContext.allowedFiles,
+      beforeSnapshot,
+      afterSnapshot,
+      strict: true,
+    });
+  } catch (error) {
+    throw appendRecovery(error, executorContext.slice);
+  }
+
+  let validationResults = [];
+  try {
+    validationResults = runValidationCommands(
+      repoRoot,
+      executorContext.validationCommands,
+      options.runValidationCommandFn,
+    );
+  } catch (error) {
+    throw appendRecovery(error, executorContext.slice);
+  }
+
+  const finalSnapshot = captureWorktreeSnapshot(repoRoot);
+  let finalScopeResult;
+  try {
+    finalScopeResult = validateScopeSnapshot({
+      allowedFiles: executorContext.allowedFiles,
+      beforeSnapshot,
+      afterSnapshot: finalSnapshot,
+      strict: true,
+    });
+  } catch (error) {
+    throw appendRecovery(error, executorContext.slice);
+  }
+
+  let commitResult = null;
+  if (options.commit === true) {
+    try {
+      commitResult = commitSliceChanges(repoRoot, executorContext.slice, finalScopeResult.changedFiles, {
+        message: options.commitMessage,
+      });
+    } catch (error) {
+      throw appendRecovery(error, executorContext.slice);
+    }
+  }
 
   process.stdout.write(formatExecuteSliceResult({
     slice: executorContext.slice,
-    changedFiles: scopeResult.changedFiles,
-    scopeResult,
+    changedFiles: finalScopeResult.changedFiles,
+    scopeResult: finalScopeResult,
+    validationResults,
+    commitResult,
+    commitEnabled: options.commit === true,
   }));
 
   return {
@@ -302,8 +651,10 @@ async function runExecuteSlice(repoRoot, options = {}) {
     invocation,
     result,
     beforeSnapshot,
-    afterSnapshot,
-    scopeResult,
+    afterSnapshot: finalSnapshot,
+    scopeResult: finalScopeResult,
+    validationResults,
+    commitResult,
   };
 }
 
@@ -312,12 +663,20 @@ module.exports = {
   DEFAULT_EXECUTE_PROVIDER,
   DEFAULT_EXECUTE_ROLE,
   annotateProviderError,
+  appendRecovery,
   buildExecuteSliceContext,
+  buildManualExecutorPrompt,
+  buildRecoveryGuidance,
+  buildSliceCommitMessage,
   canonicalizeRepoRoot,
+  commitSliceChanges,
   formatExecuteSliceDryRunReport,
   formatExecuteSliceResult,
+  runValidationCommand,
+  runValidationCommands,
   normalizeTimeout,
   readTextFile,
   resolveSliceJsonPath,
   runExecuteSlice,
+  runPromptSlice,
 };