create-quiver 0.9.0 → 0.10.0

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

@@ -0,0 +1,323 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { buildContextPackMetadata, normalizeRole } = require('./context-packs');
+const { buildProviderInvocation, runProvider } = require('./providers');
+const { captureWorktreeSnapshot, validateScopeSnapshot } = require('../scope');
+const { resolveSliceContext } = require('../slice');
+
+const DEFAULT_EXECUTE_PROVIDER = 'codex';
+const DEFAULT_EXECUTE_ROLE = 'executor';
+const DEFAULT_EXECUTE_CONTEXT = 'slice';
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function canonicalizeRepoRoot(repoRoot) {
+  try {
+    return fs.realpathSync(repoRoot);
+  } catch {
+    return path.resolve(repoRoot);
+  }
+}
+
+function readTextFile(filePath, repoRoot) {
+  const resolved = path.resolve(repoRoot, filePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(formatError(`missing required file: ${path.relative(repoRoot, resolved).split(path.sep).join('/')}`));
+  }
+
+  return fs.readFileSync(resolved, 'utf8');
+}
+
+function normalizeTimeout(timeoutMs) {
+  if (timeoutMs === undefined || timeoutMs === null || timeoutMs === '') {
+    return undefined;
+  }
+
+  const parsed = Number(timeoutMs);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(formatError(`invalid timeout value: ${timeoutMs}`));
+  }
+
+  return parsed;
+}
+
+function toRelativePath(repoRoot, absolutePath) {
+  return path.relative(repoRoot, absolutePath).split(path.sep).join('/');
+}
+
+function resolveSliceJsonPath(repoRoot, sliceInput) {
+  const value = String(sliceInput || '').trim();
+  if (!value) {
+    throw new Error(formatError('missing required --slice path for ai execute-slice'));
+  }
+
+  const resolved = path.resolve(repoRoot, value);
+  const slicePath = fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()
+    ? path.join(resolved, 'slice.json')
+    : resolved;
+
+  if (!fs.existsSync(slicePath)) {
+    throw new Error(formatError(`missing slice.json at ${toRelativePath(repoRoot, slicePath)}`));
+  }
+
+  return slicePath;
+}
+
+function formatList(items) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return ['- n/a'];
+  }
+
+  return items.map((item) => `- ${item}`);
+}
+
+function buildExecuteSliceContext({ repoRoot, slicePath, role, context }) {
+  const canonicalRepoRoot = canonicalizeRepoRoot(repoRoot);
+  const resolvedRole = normalizeRole(role || DEFAULT_EXECUTE_ROLE);
+  if (resolvedRole !== DEFAULT_EXECUTE_ROLE) {
+    throw new Error(formatError('ai execute-slice requires role executor'));
+  }
+
+  const resolvedSlicePath = resolveSliceJsonPath(canonicalRepoRoot, slicePath);
+  const slice = resolveSliceContext(canonicalRepoRoot, resolvedSlicePath);
+  const briefPath = path.join(path.dirname(slice.sliceAbs), 'EXECUTION_BRIEF.md');
+  const briefText = readTextFile(briefPath, canonicalRepoRoot);
+  const pack = buildContextPackMetadata({
+    role: resolvedRole,
+    packName: context || DEFAULT_EXECUTE_CONTEXT,
+    repoRoot: canonicalRepoRoot,
+  });
+  const relativeSlicePath = toRelativePath(canonicalRepoRoot, slice.sliceAbs);
+  const relativeBriefPath = toRelativePath(canonicalRepoRoot, briefPath);
+  const allowedFiles = Array.isArray(slice.files) ? slice.files.map((file) => String(file)) : [];
+  const acceptance = Array.isArray(slice.acceptance) ? slice.acceptance.map((item) => String(item)) : [];
+  const validationCommands = Array.isArray(slice.tests) ? slice.tests.map((item) => String(item)) : [];
+  const mustItems = Array.isArray(slice.json.must) ? slice.json.must.map((item) => String(item)) : [];
+  const excludedItems = Array.isArray(slice.json.not_included) ? slice.json.not_included.map((item) => String(item)) : [];
+
+  const sections = [
+    pack.prompt,
+    'Task: execute the slice directly in the repository using only the handoff below.',
+    `Slice: ${slice.sliceId}`,
+    `Spec: ${slice.specSlug}`,
+    `Slice file: ${relativeSlicePath}`,
+    `Execution brief: ${relativeBriefPath}`,
+    'Allowed files:',
+    ...formatList(allowedFiles),
+    'Acceptance criteria:',
+    ...formatList(acceptance),
+    'Validation commands:',
+    ...formatList(validationCommands),
+  ];
+
+  if (mustItems.length > 0) {
+    sections.push('Must:', ...formatList(mustItems));
+  }
+
+  if (excludedItems.length > 0) {
+    sections.push('Not included:', ...formatList(excludedItems));
+  }
+
+  sections.push(
+    'Constraints:',
+    '- Do not commit automatically.',
+    '- Do not fix scope violations automatically.',
+    '- Do not run multiple executors concurrently.',
+    '- Stay inside the allowed files declared by slice.json.',
+    'Execution brief:',
+    briefText.trimEnd(),
+  );
+
+  return {
+    allowedFiles,
+    briefPath: relativeBriefPath,
+    briefText,
+    context: pack,
+    prompt: sections.join('\n\n'),
+    slice,
+    validationCommands,
+  };
+}
+
+function formatExecuteSliceDryRunReport({ provider, role, contextPack, slice, briefPath, invocation, validationCommands, allowedFiles }) {
+  const lines = [
+    'AI execute-slice dry-run',
+    `Provider: ${provider}`,
+    `Role: ${role}`,
+    `Context pack: ${contextPack}`,
+    `Slice: ${slice.sliceId}`,
+    `Spec: ${slice.specSlug}`,
+    `Execution brief: ${briefPath}`,
+    `Command: ${invocation.command} ${invocation.args.join(' ')}`,
+    `Timeout: ${invocation.timeoutMs}ms`,
+    `Prompt transport: ${invocation.promptTransport.mode}`,
+    `Prompt length: ${invocation.promptLength} bytes`,
+    'Allowed files:',
+    ...formatList(allowedFiles),
+    'Validation commands:',
+    ...formatList(validationCommands),
+  ];
+
+  return `${lines.join('\n')}\n`;
+}
+
+function formatExecuteSliceResult({ slice, changedFiles, scopeResult }) {
+  const lines = [
+    'AI execute-slice completed',
+    `Slice: ${slice.sliceId}`,
+    `Spec: ${slice.specSlug}`,
+    `Changed files: ${changedFiles.length}`,
+  ];
+
+  for (const file of changedFiles) {
+    lines.push(`- ${file}`);
+  }
+
+  lines.push(`Scope validation: ${scopeResult.ok ? 'passed' : 'failed'}`);
+
+  return `${lines.join('\n')}\n`;
+}
+
+function annotateProviderError(error, scope) {
+  const message = error && error.message ? error.message : String(error);
+  const wrapped = new Error(formatError(`ai ${scope} failed: ${message}`));
+  wrapped.cause = error;
+  wrapped.code = error && error.code ? error.code : 'AI_PROVIDER_ERROR';
+  wrapped.details = error && error.details ? error.details : undefined;
+  return wrapped;
+}
+
+async function runExecuteSlice(repoRoot, options = {}) {
+  const provider = String(options.provider || DEFAULT_EXECUTE_PROVIDER).trim().toLowerCase();
+  const role = normalizeRole(options.role || DEFAULT_EXECUTE_ROLE);
+  const context = options.context || DEFAULT_EXECUTE_CONTEXT;
+  const timeoutMs = normalizeTimeout(options.timeout);
+
+  if (!options.slice) {
+    throw new Error(formatError('missing required --slice path for ai execute-slice'));
+  }
+
+  const executorContext = buildExecuteSliceContext({
+    repoRoot,
+    slicePath: options.slice,
+    role,
+    context,
+  });
+
+  const prompt = executorContext.prompt;
+  let invocation;
+
+  try {
+    invocation = buildProviderInvocation(provider, {
+      prompt,
+      cwd: repoRoot,
+      timeoutMs,
+    });
+  } catch (error) {
+    throw annotateProviderError(error, 'execute-slice');
+  }
+
+  if (options.dryRun) {
+    const report = {
+      task: 'execute-slice',
+      provider,
+      role,
+      contextPack: executorContext.context.packName,
+      slice: executorContext.slice.sliceId,
+      invocation,
+      briefPath: executorContext.briefPath,
+      allowedFiles: executorContext.allowedFiles,
+      validationCommands: executorContext.validationCommands,
+    };
+    process.stdout.write(formatExecuteSliceDryRunReport({
+      provider,
+      role,
+      contextPack: executorContext.context.packName,
+      slice: executorContext.slice,
+      briefPath: executorContext.briefPath,
+      invocation,
+      validationCommands: executorContext.validationCommands,
+      allowedFiles: executorContext.allowedFiles,
+    }));
+    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(', ')}`));
+  }
+
+  let result;
+  try {
+    result = await (options.runProviderFn || runProvider)(provider, {
+      prompt,
+      cwd: repoRoot,
+      timeoutMs,
+      dryRun: false,
+      probe: options.probe,
+      spawn: options.spawn,
+      tempRoot: options.tempRoot,
+      tempFileName: options.tempFileName,
+      tempFilePrefix: options.tempFilePrefix,
+    });
+  } catch (error) {
+    throw annotateProviderError(error, 'execute-slice');
+  }
+
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  if (!result.ok) {
+    throw annotateProviderError(result.error || new Error('provider run failed'), 'execute-slice');
+  }
+
+  const afterSnapshot = captureWorktreeSnapshot(repoRoot);
+  const scopeResult = validateScopeSnapshot({
+    allowedFiles: executorContext.allowedFiles,
+    beforeSnapshot,
+    afterSnapshot,
+    strict: true,
+  });
+
+  process.stdout.write(formatExecuteSliceResult({
+    slice: executorContext.slice,
+    changedFiles: scopeResult.changedFiles,
+    scopeResult,
+  }));
+
+  return {
+    task: 'execute-slice',
+    provider,
+    role,
+    contextPack: executorContext.context.packName,
+    slice: executorContext.slice.sliceId,
+    specSlug: executorContext.slice.specSlug,
+    invocation,
+    result,
+    beforeSnapshot,
+    afterSnapshot,
+    scopeResult,
+  };
+}
+
+module.exports = {
+  DEFAULT_EXECUTE_CONTEXT,
+  DEFAULT_EXECUTE_PROVIDER,
+  DEFAULT_EXECUTE_ROLE,
+  annotateProviderError,
+  buildExecuteSliceContext,
+  canonicalizeRepoRoot,
+  formatExecuteSliceDryRunReport,
+  formatExecuteSliceResult,
+  normalizeTimeout,
+  readTextFile,
+  resolveSliceJsonPath,
+  runExecuteSlice,
+};

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

@@ -0,0 +1,329 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { currentBranch, hasRemote, isCleanWorktree } = require('../git');
+
+const DEFAULT_GH_COMMAND = 'gh';
+const DEFAULT_REMOTE = 'origin';
+const DEFAULT_GITFLOW_GUIDE_PATH = 'docs/GITFLOW_PR_GUIDE.md';
+
+class GitHubPreflightError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'GitHubPreflightError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function normalizeOptionalPath(filePath) {
+  const value = String(filePath || '').trim();
+  if (!value) {
+    return '';
+  }
+
+  if (value === '~') {
+    return os.homedir();
+  }
+
+  if (value.startsWith('~/') || value.startsWith('~\\')) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+
+  return value;
+}
+
+function resolveConfiguredPath(repoRoot, filePath) {
+  const normalized = normalizeOptionalPath(filePath);
+  if (!normalized) {
+    return '';
+  }
+
+  if (path.isAbsolute(normalized)) {
+    return path.normalize(normalized);
+  }
+
+  return path.resolve(repoRoot, normalized);
+}
+
+function formatGhInstallGuidance() {
+  return [
+    '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',
+  ].join('\n');
+}
+
+function createError(code, message, details = {}) {
+  return new GitHubPreflightError(code, message, details);
+}
+
+function runCommand(command, args, options = {}) {
+  const runner = options.runner || spawnSync;
+  return runner(command, args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    shell: false,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function ensureGhInstalled(options = {}) {
+  const command = options.ghCommand || DEFAULT_GH_COMMAND;
+  const probeArgs = Array.isArray(options.ghProbeArgs) ? options.ghProbeArgs : ['--version'];
+  const result = runCommand(command, probeArgs, {
+    cwd: options.cwd,
+    runner: options.ghProbe || spawnSync,
+  });
+
+  if (result && result.error && result.error.code === 'ENOENT') {
+    throw createError('MISSING_GH_CLI', `${formatGhInstallGuidance()}\nRun gh auth login after installation.`, {
+      command,
+      probeArgs,
+      errorCode: result.error.code,
+    });
+  }
+
+  if (result && result.error) {
+    throw createError('GH_CLI_UNAVAILABLE', formatError(`GitHub CLI could not be executed. Check '${command}' and then run gh auth login.`), {
+      command,
+      probeArgs,
+      errorCode: result.error.code,
+      errorMessage: result.error.message,
+    });
+  }
+
+  if (!result || typeof result.status !== 'number' || result.status !== 0) {
+    const stderr = result && typeof result.stderr === 'string' ? result.stderr.trim() : '';
+    const stdout = result && typeof result.stdout === 'string' ? result.stdout.trim() : '';
+    const details = [stderr, stdout].filter(Boolean).join('\n');
+    throw createError(
+      'GH_CLI_UNAVAILABLE',
+      `${formatError(`GitHub CLI probe failed for '${command} ${probeArgs.join(' ')}'. Check your gh installation and then run gh auth login.`)}${details ? `\n${details}` : ''}`,
+      {
+        command,
+        probeArgs,
+        status: result && result.status,
+        stderr,
+        stdout,
+      },
+    );
+  }
+
+  return {
+    command,
+    probeArgs,
+    stdout: result && typeof result.stdout === 'string' ? result.stdout : '',
+    stderr: result && typeof result.stderr === 'string' ? result.stderr : '',
+    status: result && typeof result.status === 'number' ? result.status : 0,
+  };
+}
+
+function ensureGhAuthenticated(options = {}) {
+  const command = options.ghCommand || DEFAULT_GH_COMMAND;
+  const authArgs = Array.isArray(options.ghAuthArgs) ? options.ghAuthArgs : ['auth', 'status'];
+  const result = runCommand(command, authArgs, {
+    cwd: options.cwd,
+    runner: options.ghAuthProbe || options.ghProbe || spawnSync,
+  });
+
+  if (result && result.error && result.error.code === 'ENOENT') {
+    throw createError('MISSING_GH_CLI', `${formatGhInstallGuidance()}\nRun gh auth login after installation.`, {
+      command,
+      authArgs,
+      errorCode: result.error.code,
+    });
+  }
+
+  if (typeof result.status !== 'number' || result.status !== 0) {
+    const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+    const stdout = typeof result.stdout === 'string' ? result.stdout.trim() : '';
+    const details = [stderr, stdout].filter(Boolean).join('\n');
+    throw createError(
+      'GH_NOT_AUTHENTICATED',
+      `${formatError('gh auth status failed. Run gh auth login and then re-run the preflight.')}${details ? `\n${details}` : ''}`,
+      {
+        command,
+        authArgs,
+        status: result.status,
+        stderr,
+        stdout,
+      },
+    );
+  }
+
+  return {
+    command,
+    authArgs,
+    stdout: typeof result.stdout === 'string' ? result.stdout : '',
+    stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    status: result.status,
+  };
+}
+
+function ensureGitFlowGuide(repoRoot, guidePath) {
+  const resolved = resolveConfiguredPath(repoRoot, guidePath || DEFAULT_GITFLOW_GUIDE_PATH);
+  if (!resolved || !fs.existsSync(resolved)) {
+    throw createError(
+      'MISSING_GITFLOW_GUIDE',
+      formatError(`missing GitFlow PR guide at ${resolved || guidePath || DEFAULT_GITFLOW_GUIDE_PATH}. Create docs/GITFLOW_PR_GUIDE.md before opening the PR.`),
+      {
+        guidePath: resolved || guidePath || DEFAULT_GITFLOW_GUIDE_PATH,
+      },
+    );
+  }
+
+  return resolved;
+}
+
+function ensureRemote(repoRoot, remoteName = DEFAULT_REMOTE) {
+  if (!hasRemote(repoRoot, remoteName)) {
+    throw createError(
+      'MISSING_GIT_REMOTE',
+      formatError(`missing Git remote '${remoteName}'. Configure a remote before preparing the PR.`),
+      { remoteName },
+    );
+  }
+
+  return remoteName;
+}
+
+function ensureWorktreeReady(repoRoot, options = {}) {
+  const branchName = currentBranch(repoRoot);
+  if (!branchName) {
+    throw createError(
+      'DETACHED_HEAD',
+      formatError('current HEAD is detached. Check out the spec branch before preparing the PR.'),
+      { repoRoot },
+    );
+  }
+
+  const blockedBranches = Array.isArray(options.blockedBranches) && options.blockedBranches.length > 0
+    ? options.blockedBranches
+    : ['main', 'master', 'develop'];
+
+  if (blockedBranches.includes(branchName)) {
+    throw createError(
+      'UNSAFE_PR_BRANCH',
+      formatError(`current branch '${branchName}' is not a PR branch. Create or switch to the feature branch before continuing.`),
+      { branchName, blockedBranches },
+    );
+  }
+
+  if (!isCleanWorktree(repoRoot)) {
+    throw createError(
+      'DIRTY_WORKTREE',
+      formatError(`worktree has uncommitted changes on branch '${branchName}'. Commit or stash them before preparing the PR.`),
+      { branchName },
+    );
+  }
+
+  return branchName;
+}
+
+function ensureIdentityFile(repoRoot, identityFile) {
+  const normalized = String(identityFile || '').trim();
+  if (!normalized) {
+    return '';
+  }
+
+  const resolved = resolveConfiguredPath(repoRoot, normalized);
+  if (!fs.existsSync(resolved)) {
+    throw createError(
+      'MISSING_IDENTITY_FILE',
+      formatError(`missing SSH identity file at ${resolved}. Check the path you passed as identityFile.`),
+      {
+        identityFile: normalized,
+        resolvedIdentityFile: resolved,
+      },
+    );
+  }
+
+  return resolved;
+}
+
+function buildPreflightReport(repoRoot, options = {}, checks = {}) {
+  return {
+    ok: true,
+    repoRoot,
+    remote: checks.remote || options.remote || DEFAULT_REMOTE,
+    branchName: checks.branchName || '',
+    guidePath: checks.guidePath || '',
+    sshHostAlias: options.sshHostAlias || '',
+    identityFile: checks.identityFile || '',
+    gh: checks.gh || null,
+    auth: checks.auth || null,
+  };
+}
+
+function preflightGitHubPr(repoRoot, options = {}) {
+  const gh = ensureGhInstalled(options);
+  const auth = ensureGhAuthenticated(options);
+  const guidePath = ensureGitFlowGuide(repoRoot, options.gitFlowGuidePath);
+  const remote = ensureRemote(repoRoot, options.remote || DEFAULT_REMOTE);
+  const branchName = ensureWorktreeReady(repoRoot, options);
+  const identityFile = ensureIdentityFile(repoRoot, options.identityFile);
+
+  return buildPreflightReport(repoRoot, options, {
+    gh,
+    auth,
+    guidePath,
+    remote,
+    branchName,
+    identityFile,
+  });
+}
+
+function formatPreflightReport(report, options = {}) {
+  const mode = options.mode || 'pr';
+  const dryRun = options.dryRun === true;
+  const lines = [
+    `GitHub ${mode} ${dryRun ? 'dry-run' : 'preflight'}`,
+    `Remote: ${report.remote}`,
+    `Branch: ${report.branchName}`,
+    `GitFlow guide: ${path.relative(report.repoRoot, report.guidePath).split(path.sep).join('/')}`,
+  ];
+
+  if (report.sshHostAlias) {
+    lines.push(`SSH host alias: ${report.sshHostAlias}`);
+  }
+
+  if (report.identityFile) {
+    lines.push(`Identity file: ${report.identityFile}`);
+  }
+
+  lines.push('Checks: gh, gh auth status, git remote, worktree branch, GitFlow guide, SSH identity file');
+
+  if (dryRun) {
+    lines.push('No PR will be created in dry-run mode.');
+  } else {
+    lines.push('PR creation is not performed in this slice.');
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = {
+  DEFAULT_GH_COMMAND,
+  DEFAULT_GITFLOW_GUIDE_PATH,
+  DEFAULT_REMOTE,
+  GitHubPreflightError,
+  buildPreflightReport,
+  ensureGhAuthenticated,
+  ensureGhInstalled,
+  ensureGitFlowGuide,
+  ensureIdentityFile,
+  ensureRemote,
+  ensureWorktreeReady,
+  formatGhInstallGuidance,
+  formatPreflightReport,
+  preflightGitHubPr,
+  resolveConfiguredPath,
+};