create-quiver 0.10.0 → 0.12.0

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

@@ -249,6 +249,157 @@ function ensureIdentityFile(repoRoot, identityFile) {
   return resolved;
 }
 
+function findPrBodyCandidates(repoRoot) {
+  const candidates = [];
+  const rootPr = path.join(repoRoot, 'pr.md');
+  if (fs.existsSync(rootPr)) {
+    candidates.push(rootPr);
+  }
+
+  const specsDir = path.join(repoRoot, 'specs');
+  if (fs.existsSync(specsDir)) {
+    for (const entry of fs.readdirSync(specsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      const candidate = path.join(specsDir, entry.name, 'pr.md');
+      if (fs.existsSync(candidate)) {
+        candidates.push(candidate);
+      }
+    }
+  }
+
+  return candidates.sort((left, right) => left.localeCompare(right));
+}
+
+function resolvePrBodyPath(repoRoot, prBodyPath) {
+  const configured = String(prBodyPath || '').trim();
+  if (configured) {
+    const resolved = resolveConfiguredPath(repoRoot, configured);
+    if (!fs.existsSync(resolved)) {
+      throw createError('MISSING_PR_BODY', formatError(`missing PR body file at ${resolved}. Pass --input specs/<spec-slug>/pr.md or generate pr.md first.`), {
+        prBodyPath: configured,
+        resolvedPrBodyPath: resolved,
+      });
+    }
+    return resolved;
+  }
+
+  const candidates = findPrBodyCandidates(repoRoot);
+  if (candidates.length === 1) {
+    return candidates[0];
+  }
+  if (candidates.length === 0) {
+    throw createError('MISSING_PR_BODY', formatError('missing PR body file. Pass --input specs/<spec-slug>/pr.md or generate pr.md first.'), {
+      candidates,
+    });
+  }
+
+  throw createError('AMBIGUOUS_PR_BODY', formatError(`multiple pr.md files found: ${candidates.map((item) => path.relative(repoRoot, item).split(path.sep).join('/')).join(', ')}. Pass --input with the intended PR body.`), {
+    candidates,
+  });
+}
+
+function readPrBody(repoRoot, prBodyPath) {
+  const resolved = resolvePrBodyPath(repoRoot, prBodyPath);
+  const body = fs.readFileSync(resolved, 'utf8');
+  if (!body.trim()) {
+    throw createError('EMPTY_PR_BODY', formatError(`PR body file is empty: ${path.relative(repoRoot, resolved).split(path.sep).join('/')}`), {
+      prBodyPath: resolved,
+    });
+  }
+  return {
+    body,
+    path: resolved,
+  };
+}
+
+function extractPrTitle(prBody, fallbackTitle) {
+  const lines = String(prBody || '').split(/\r?\n/);
+  const titleIndex = lines.findIndex((line) => /^##\s+Title\s*$/i.test(line.trim()));
+  if (titleIndex !== -1) {
+    for (const line of lines.slice(titleIndex + 1)) {
+      const value = line.trim().replace(/^#+\s*/, '');
+      if (value) {
+        return value;
+      }
+    }
+  }
+
+  const firstHeading = lines.find((line) => /^#\s+\S/.test(line.trim()));
+  if (firstHeading) {
+    return firstHeading.trim().replace(/^#\s+/, '');
+  }
+
+  return fallbackTitle || 'Quiver PR';
+}
+
+function buildPrCreateArgs(plan) {
+  const args = [
+    'pr',
+    'create',
+    '--base',
+    plan.baseBranch,
+    '--head',
+    plan.branchName,
+    '--title',
+    plan.title,
+    '--body-file',
+    plan.prBodyPath,
+  ];
+  return args;
+}
+
+function buildPrCreatePlan(repoRoot, preflightReport, options = {}) {
+  const prBody = readPrBody(repoRoot, options.prBodyPath || options.input);
+  const baseBranch = String(options.baseBranch || 'main').trim() || 'main';
+  const title = String(options.title || '').trim() || extractPrTitle(prBody.body, preflightReport.branchName);
+  const plan = {
+    baseBranch,
+    branchName: preflightReport.branchName,
+    ghCommand: options.ghCommand || DEFAULT_GH_COMMAND,
+    prBodyPath: prBody.path,
+    prBodyRelativePath: path.relative(repoRoot, prBody.path).split(path.sep).join('/'),
+    remote: preflightReport.remote,
+    repoRoot,
+    title,
+  };
+  plan.args = buildPrCreateArgs(plan);
+  return plan;
+}
+
+function runGhPrCreate(plan, options = {}) {
+  const result = runCommand(plan.ghCommand, plan.args, {
+    cwd: plan.repoRoot,
+    runner: options.runner || options.ghCreateRunner || spawnSync,
+  });
+
+  if (result && result.error) {
+    throw createError('GH_PR_CREATE_FAILED', formatError(`gh pr create could not be executed. ${result.error.message}`), {
+      args: plan.args,
+      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() : '';
+    throw createError('GH_PR_CREATE_FAILED', `${formatError('gh pr create failed.')}${[stderr, stdout].filter(Boolean).length > 0 ? `\n${[stderr, stdout].filter(Boolean).join('\n')}` : ''}`, {
+      args: plan.args,
+      status: result && result.status,
+      stderr,
+      stdout,
+    });
+  }
+
+  return {
+    status: result.status,
+    stdout: typeof result.stdout === 'string' ? result.stdout : '',
+    stderr: typeof result.stderr === 'string' ? result.stderr : '',
+  };
+}
+
 function buildPreflightReport(repoRoot, options = {}, checks = {}) {
   return {
     ok: true,
@@ -310,20 +461,65 @@ function formatPreflightReport(report, options = {}) {
   return `${lines.join('\n')}\n`;
 }
 
+function quoteCommandArg(arg) {
+  const value = String(arg);
+  return /^[A-Za-z0-9_./:=@-]+$/.test(value) ? value : JSON.stringify(value);
+}
+
+function formatPrCreateReport({ preflight, plan, result }, options = {}) {
+  const dryRun = options.dryRun === true;
+  const create = options.create === true;
+  const lines = [
+    `GitHub pr ${dryRun ? 'dry-run' : create ? 'created' : 'preflight'}`,
+    `Remote: ${preflight.remote}`,
+    `Branch: ${preflight.branchName}`,
+    `Base: ${plan.baseBranch}`,
+    `PR body: ${plan.prBodyRelativePath}`,
+    `Title: ${plan.title}`,
+    `Command: ${plan.ghCommand} ${plan.args.map(quoteCommandArg).join(' ')}`,
+  ];
+
+  if (preflight.sshHostAlias) {
+    lines.push(`SSH host alias: ${preflight.sshHostAlias}`);
+  }
+
+  if (preflight.identityFile) {
+    lines.push(`Identity file: ${preflight.identityFile}`);
+  }
+
+  if (dryRun) {
+    lines.push('No PR will be created in dry-run mode.');
+  } else if (!create) {
+    lines.push('No PR was created. Re-run with --create after reviewing the plan.');
+  } else if (result && result.stdout) {
+    lines.push(result.stdout.trimEnd());
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
 module.exports = {
   DEFAULT_GH_COMMAND,
   DEFAULT_GITFLOW_GUIDE_PATH,
   DEFAULT_REMOTE,
   GitHubPreflightError,
+  buildPrCreateArgs,
+  buildPrCreatePlan,
   buildPreflightReport,
+  extractPrTitle,
   ensureGhAuthenticated,
   ensureGhInstalled,
   ensureGitFlowGuide,
   ensureIdentityFile,
   ensureRemote,
   ensureWorktreeReady,
+  findPrBodyCandidates,
   formatGhInstallGuidance,
   formatPreflightReport,
+  formatPrCreateReport,
   preflightGitHubPr,
+  readPrBody,
   resolveConfiguredPath,
+  resolvePrBodyPath,
+  runGhPrCreate,
 };

package/src/create-quiver/lib/ai/onboarding-template.js

@@ -0,0 +1,365 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { getPreparedContextDocPaths } = require('./context-packs');
+
+const PROMPT_SOURCE = 'packaged planner onboarding template';
+const PACKAGE_ROOT = path.resolve(__dirname, '../../../..');
+
+const ONBOARDING_DOCS = Object.freeze([
+  ['README.md', 'project entrypoint and human summary'],
+  ['AGENTS.md', 'agent router and reading rules'],
+  ['docs/INDEX.md', 'index-first navigation map'],
+  ['docs/PROJECT_MAP.md', 'stack, commands, and structure facts'],
+  ['docs/AI_CONTEXT.md', 'AI working contract'],
+  ['docs/AI_ONBOARDING_PROMPT.md', 'project-specific onboarding contract'],
+  ['docs/CONTEXTO.md', 'human-readable project context'],
+  ['docs/WORKFLOW.md', 'WDD/SDD workflow rules'],
+  ['docs/STATUS.md', 'current state and open risks'],
+  ['docs/DECISIONS.md', 'durable decisions'],
+]);
+
+const OMITTED_BY_DEFAULT = Object.freeze([
+  'Do not read all docs/ recursively by default.',
+  'Do not read source trees until the selected docs identify relevant files.',
+  'Do not read dependency folders, generated outputs, caches, secrets, or local AI state.',
+  'Use .quiver/scans/PROJECT_SCAN.json only when docs/PROJECT_MAP.md is not enough.',
+]);
+
+const CONTEXT_PREP_SOURCE_DOCS = Object.freeze([
+  ['README.md', 'project entrypoint and human summary'],
+  ['AGENTS.md', 'agent router and reading rules'],
+  ['README_FOR_AI.md', 'framework guidance source; not project debt when absent'],
+  ['docs/INDEX.md', 'index-first navigation map'],
+  ['docs/PROJECT_MAP.md', 'stack, commands, and structure facts'],
+  ['docs/WORKFLOW.md', 'workflow rules and execution contract'],
+  ['docs/AI_CONTEXT.md', 'agent-facing project context pack'],
+  ['docs/AI_ONBOARDING_PROMPT.md', 'project-specific onboarding contract'],
+  ['docs/CONTEXTO.md', 'human-readable project context'],
+  ['docs/STATUS.md', 'current state and open risks'],
+  ['docs/DECISIONS.md', 'durable decisions log'],
+]);
+
+function hasPath(projectRoot, relativePath) {
+  return fs.existsSync(path.join(projectRoot, relativePath));
+}
+
+function toProjectSlug(projectName) {
+  return String(projectName || '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'quiver-project';
+}
+
+function readProjectName(projectRoot) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      if (typeof packageJson.name === 'string' && packageJson.name.trim()) {
+        return packageJson.name.trim();
+      }
+    } catch {
+      // Best effort only. Fall back to the directory name when package.json is unreadable.
+    }
+  }
+
+  return path.basename(projectRoot) || 'Quiver Project';
+}
+
+function renderTemplate(text, replacements) {
+  return text
+    .replace(/{{PROJECT_NAME}}/g, replacements.projectName)
+    .replace(/{{PROJECT_SLUG}}/g, replacements.projectSlug)
+    .replace(/\[project\]/g, replacements.projectSlug)
+    .replace(/\[project-name\]/g, replacements.projectSlug)
+    .replace(/\[project-slug\]/g, replacements.projectSlug)
+    .replace(/{{FECHA}}/g, replacements.currentDate)
+    .replace(/{{FECHA_PROXIMA}}/g, replacements.datePlus7 || replacements.currentDate)
+    .replace(/{{FECHA_PROXIMA_MES}}/g, replacements.datePlus30 || replacements.currentDate)
+    .replace(/{{FECHA_LAUNCH}}/g, replacements.datePlus35 || replacements.currentDate)
+    .replace(/{{ESTADO}}/g, replacements.estado || 'En preparación')
+    .replace(/{{FASE}}/g, replacements.fase || 'Fase 0')
+    .replace(/{{X}}%/g, `${typeof replacements.progress === 'number' ? replacements.progress : 0}%`)
+    .replace(/{{PACKAGE_MANAGER}}/g, replacements.packageManager || 'npm')
+    .replace(/{{STACK_SUMMARY}}/g, replacements.stackSummary || 'unknown until analyze')
+    .replace(/{{PRIMARY_INSTALL}}/g, replacements.primaryInstall || 'npm install')
+    .replace(/{{PRIMARY_DEV}}/g, replacements.primaryDev || 'not defined')
+    .replace(/{{PRIMARY_TEST}}/g, replacements.primaryTest || 'not defined')
+    .replace(/{{ANALYZE_COMMAND}}/g, replacements.analyzeCommand || 'npx create-quiver analyze')
+    .replace(/{{PLAN_COMMAND}}/g, replacements.planCommand || 'npx create-quiver plan')
+    .replace(/{{GRAPH_COMMAND}}/g, replacements.graphCommand || 'npx create-quiver graph')
+    .replace(/{{NEXT_COMMAND}}/g, replacements.nextCommand || 'npx create-quiver next')
+    .replace(/{{DOCTOR_COMMAND}}/g, replacements.doctorCommand || 'npx create-quiver doctor')
+    .replace(/{{START_SLICE_COMMAND}}/g, replacements.startSliceCommand || 'npx create-quiver start-slice <slice.json>')
+    .replace(/{{CHECK_SLICE_COMMAND}}/g, replacements.checkSliceCommand || 'npx create-quiver check-slice <slice.json>')
+    .replace(/{{CHECK_PR_COMMAND}}/g, replacements.checkPrCommand || 'npx create-quiver check-pr <slice.json>')
+    .replace(/{{CLEANUP_SLICE_COMMAND}}/g, replacements.cleanupSliceCommand || 'npx create-quiver cleanup-slice <slice.json>')
+    .replace(/{{CHECK_SCOPE_COMMAND}}/g, replacements.checkScopeCommand || 'npx create-quiver check-scope <slice.json>')
+    .replace(/{{REFRESH_ACTIVE_SLICES_COMMAND}}/g, replacements.refreshActiveSlicesCommand || 'npx create-quiver refresh-active-slices');
+}
+
+function uniq(values) {
+  return Array.from(new Set((Array.isArray(values) ? values : []).filter(Boolean)));
+}
+
+function markPendingConfirmation(value) {
+  const text = String(value || '').trim();
+  if (!text || /^(TODO|Assumption|Pending confirmation):/i.test(text)) {
+    return text;
+  }
+
+  return `Pending confirmation: ${text}`;
+}
+
+function formatDocStatusLines(items) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return ['- none'];
+  }
+
+  return items.map((item) => {
+    const status = item.present ? 'present' : 'absent';
+    const note = item.reason ? ` (${item.reason})` : '';
+    return `- ${item.path}: ${status}${note}`;
+  });
+}
+
+function formatSimpleBullets(items, emptyLabel = 'none') {
+  if (!Array.isArray(items) || items.length === 0) {
+    return [`- ${emptyLabel}`];
+  }
+
+  return items.map((item) => `- ${item}`);
+}
+
+function resolveProjectIdentity(projectRoot) {
+  const projectName = readProjectName(projectRoot);
+  return {
+    projectName,
+    projectSlug: toProjectSlug(projectName),
+  };
+}
+
+function collectOnboardingContextPlan(projectRoot) {
+  const docs = ONBOARDING_DOCS.map(([relativePath, reason]) => ({
+    path: relativePath,
+    reason,
+    present: hasPath(projectRoot, relativePath),
+  }));
+  const selectedDocs = docs.filter((item) => item.present);
+  const missingDocs = docs.filter((item) => !item.present);
+  const assumptions = [];
+  const risks = [];
+
+  if (!hasPath(projectRoot, 'docs/INDEX.md')) {
+    risks.push('docs/INDEX.md is missing, so the planner cannot use index-first navigation.');
+  }
+
+  if (!hasPath(projectRoot, 'docs/PROJECT_MAP.md')) {
+    risks.push('docs/PROJECT_MAP.md is missing; run analyze before broad onboarding.');
+  }
+
+  if (!hasPath(projectRoot, 'docs/AI_ONBOARDING_PROMPT.md')) {
+    risks.push('docs/AI_ONBOARDING_PROMPT.md is missing; project-specific onboarding may be incomplete.');
+  }
+
+  if (selectedDocs.length === 0) {
+    assumptions.push('No onboarding docs were detected; use README.md or initialize Quiver first.');
+  }
+
+  return {
+    promptSource: PROMPT_SOURCE,
+    selectedDocs,
+    missingDocs,
+    omittedByDefault: OMITTED_BY_DEFAULT.slice(),
+    assumptions,
+    risks,
+  };
+}
+
+function collectContextPreparationPlan(projectRoot) {
+  const onboardingPlan = collectOnboardingContextPlan(projectRoot);
+  const identity = resolveProjectIdentity(projectRoot);
+  const filesConsidered = CONTEXT_PREP_SOURCE_DOCS.map(([relativePath, reason]) => ({
+    path: relativePath,
+    reason,
+    present: hasPath(projectRoot, relativePath),
+  }));
+  const assumptions = uniq([
+    ...onboardingPlan.assumptions,
+    !hasPath(projectRoot, 'README_FOR_AI.md')
+      ? 'Assumption: README_FOR_AI.md is framework guidance only and is not counted as generated-project debt when absent.'
+      : null,
+  ]);
+  const risks = uniq([
+    ...onboardingPlan.risks.map(markPendingConfirmation),
+    !hasPath(projectRoot, 'docs/PROJECT_MAP.md')
+      ? 'Pending confirmation: docs/PROJECT_MAP.md is missing, so the draft must stay on documented facts only.'
+      : null,
+    !hasPath(projectRoot, 'docs/INDEX.md')
+      ? 'Pending confirmation: docs/INDEX.md is missing, so navigation should stay conservative and index-first.'
+      : null,
+  ]);
+
+  return {
+    ...onboardingPlan,
+    ...identity,
+    approvedDocPaths: getPreparedContextDocPaths(),
+    filesConsidered,
+    omittedPaths: onboardingPlan.omittedByDefault.slice(),
+    assumptions,
+    risks,
+  };
+}
+
+function buildContextPreparationNotes(plan) {
+  const lines = [
+    '## Context Preparation Notes',
+    '- TODO: confirm any repo fact that is not supported by README.md, AGENTS.md, docs/INDEX.md, or docs/PROJECT_MAP.md.',
+    '- Assumption: missing README_FOR_AI.md in a generated project is guidance-only and not project debt.',
+    '- Pending confirmation: keep writes limited to docs/context files and never product code.',
+    '',
+    '### Files Considered',
+    ...formatDocStatusLines(plan.filesConsidered),
+    '',
+    '### Assumptions',
+    ...formatSimpleBullets(plan.assumptions, 'none'),
+    '',
+    '### Risks',
+    ...formatSimpleBullets(plan.risks, 'none'),
+    '',
+    '### Omitted Paths',
+    ...formatSimpleBullets(plan.omittedPaths, 'none'),
+  ];
+
+  return `${lines.join('\n')}\n`;
+}
+
+function appendNotes(body, notes) {
+  const trimmedBody = String(body || '').replace(/\s+$/g, '');
+  const trimmedNotes = String(notes || '').trimEnd();
+  return `${trimmedBody}\n\n${trimmedNotes}\n`;
+}
+
+function readTemplate(relativePath) {
+  return fs.readFileSync(path.join(PACKAGE_ROOT, relativePath), 'utf8');
+}
+
+function buildContextPreparationDrafts(projectRoot) {
+  const plan = collectContextPreparationPlan(projectRoot);
+  const currentDate = new Date().toISOString().slice(0, 10);
+  const replacements = {
+    currentDate,
+    projectName: plan.projectName,
+    projectSlug: plan.projectSlug,
+    estado: 'En preparación',
+    fase: 'Fase 0',
+    progress: 0,
+  };
+  const notes = buildContextPreparationNotes(plan);
+  const decisionSection = [
+    '## Context Preparation Decisions',
+    '| Date | Decision | Reason | Alternatives | Impact |',
+    `| ${currentDate} | README_FOR_AI.md absence in generated projects is guidance-only, not project debt | Keeps prepare output aligned with generated repos. | Report it as debt | Dry-runs stay accurate and less noisy |`,
+    `| ${currentDate} | ai prepare-context must remain docs-only | Keeps context prep from touching product code. | Broader write targets | Draft generation stays safe and reviewable |`,
+  ].join('\n');
+  const docs = [
+    {
+      path: 'docs/AI_CONTEXT.md',
+      content: appendNotes(renderTemplate(readTemplate('docs/AI_CONTEXT.md.template'), replacements), notes),
+    },
+    {
+      path: 'docs/AI_ONBOARDING_PROMPT.md',
+      content: appendNotes(renderTemplate(readTemplate('docs/AI_ONBOARDING_PROMPT.md.template'), replacements), notes),
+    },
+    {
+      path: 'docs/CONTEXTO.md',
+      content: appendNotes(renderTemplate(readTemplate('docs/CONTEXTO.md.template'), replacements), notes),
+    },
+    {
+      path: 'docs/STATUS.md',
+      content: appendNotes(renderTemplate(readTemplate('docs/STATUS.md.template'), replacements), notes),
+    },
+    {
+      path: 'docs/DECISIONS.md',
+      content: appendNotes(renderTemplate(readTemplate('docs/DECISIONS.md.template'), replacements), decisionSection),
+    },
+  ];
+
+  return {
+    docs,
+    plan,
+  };
+}
+
+function formatDocBullets(items) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return ['- none'];
+  }
+
+  return items.map((item) => `- ${item.path}: ${item.reason}`);
+}
+
+function buildPlannerOnboardingPrompt({ pack, inputText, inputPath, repoRoot }) {
+  const plan = collectOnboardingContextPlan(repoRoot);
+  const sections = [
+    pack.prompt,
+    'Task: planner onboarding for this repository.',
+    'Goal: understand the project context and prepare safe WDD/SDD work with the smallest useful context.',
+    'Rules:',
+    '- Start with README.md and AGENTS.md when present.',
+    '- Then read docs/INDEX.md as the navigation map when present.',
+    '- Use docs/INDEX.md to choose only the docs needed for the current task.',
+    '- Do not read all docs/ recursively by default.',
+    '- Do not modify product code.',
+    '- Do not modify product code during onboarding.',
+    '- Do not invent architecture, workflow, roles, domain rules, or conventions.',
+    '- Report assumptions, risks, missing docs, and files read.',
+    'Selected docs to inspect first:',
+    ...formatDocBullets(plan.selectedDocs),
+    'Documentation debt to report if relevant:',
+    ...formatDocBullets(plan.missingDocs),
+    'Omit by default:',
+    ...plan.omittedByDefault.map((item) => `- ${item}`),
+  ];
+
+  if (inputPath) {
+    sections.push(`Input file: ${inputPath}`);
+  }
+
+  if (inputText) {
+    sections.push('Input:', inputText.trimEnd());
+  }
+
+  sections.push(
+    'Expected output:',
+    '- Files read.',
+    '- Files created or modified.',
+    '- Product code status.',
+    '- Project context prepared.',
+    '- WDD/SDD understanding based only on repo docs.',
+    '- Assumptions.',
+    '- Risks and blockers.',
+    '- Next safe steps.',
+  );
+
+  return {
+    plan,
+    prompt: sections.join('\n\n'),
+  };
+}
+
+module.exports = {
+  CONTEXT_PREP_SOURCE_DOCS,
+  OMITTED_BY_DEFAULT,
+  ONBOARDING_DOCS,
+  PROMPT_SOURCE,
+  buildContextPreparationDrafts,
+  buildContextPreparationPlan: collectContextPreparationPlan,
+  buildPlannerOnboardingPrompt,
+  collectOnboardingContextPlan,
+  resolveProjectIdentity,
+  renderTemplate,
+};