create-quiver 0.15.3 → 0.16.0

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

@@ -3,6 +3,23 @@ const path = require('path');
 const { spawnSync } = require('node:child_process');
 
 const DEFAULT_OUTPUT_LIMIT = 4000;
+const SIGNAL_NUMBERS = {
+  SIGHUP: 1,
+  SIGINT: 2,
+  SIGQUIT: 3,
+  SIGILL: 4,
+  SIGTRAP: 5,
+  SIGABRT: 6,
+  SIGBUS: 7,
+  SIGFPE: 8,
+  SIGKILL: 9,
+  SIGUSR1: 10,
+  SIGSEGV: 11,
+  SIGUSR2: 12,
+  SIGPIPE: 13,
+  SIGALRM: 14,
+  SIGTERM: 15,
+};
 
 function redactSecrets(text) {
   return String(text || '')
@@ -40,6 +57,83 @@ function defaultEvidencePath(repoRoot, startedAt = new Date()) {
   return path.join(repoRoot, '.quiver', 'evidence', `evidence-${stamp}.md`);
 }
 
+function isPathInside(parentPath, childPath) {
+  const relative = path.relative(parentPath, childPath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function realpathExistingAncestor(targetPath) {
+  let current = targetPath;
+  while (!fs.existsSync(current)) {
+    const next = path.dirname(current);
+    if (next === current) {
+      return fs.realpathSync(current);
+    }
+    current = next;
+  }
+  return fs.realpathSync(current);
+}
+
+function assertSafeProjectPath(repoRoot, targetPath, label = 'evidence path') {
+  const rootPath = path.resolve(repoRoot);
+  const rootReal = fs.realpathSync(rootPath);
+  const resolved = path.resolve(rootPath, targetPath);
+  const ancestorReal = realpathExistingAncestor(resolved);
+  const pathLooksInsideRoot = isPathInside(rootPath, resolved) || isPathInside(rootReal, resolved);
+
+  if (!pathLooksInsideRoot || !isPathInside(rootReal, ancestorReal)) {
+    throw new Error(`create-quiver: ${label} must stay inside the project root.`);
+  }
+
+  return resolved;
+}
+
+function resolveEvidenceOutputPath(repoRoot, outputPath, startedAtDate = new Date()) {
+  const resolved = outputPath
+    ? assertSafeProjectPath(repoRoot, outputPath, 'evidence output path')
+    : defaultEvidencePath(repoRoot, startedAtDate);
+  const directory = path.dirname(resolved);
+
+  if (fs.existsSync(resolved) && fs.lstatSync(resolved).isSymbolicLink()) {
+    throw new Error('create-quiver: evidence output path cannot be a symlink.');
+  }
+
+  fs.mkdirSync(directory, { recursive: true });
+  const rootReal = fs.realpathSync(repoRoot);
+  const directoryReal = fs.realpathSync(directory);
+  if (!isPathInside(rootReal, directoryReal)) {
+    throw new Error('create-quiver: evidence output path must stay inside the project root.');
+  }
+
+  return resolved;
+}
+
+function resolveEvidenceReadPath(repoRoot, evidencePath) {
+  if (!evidencePath) {
+    throw new Error('create-quiver: evidence show requires an evidence file path.');
+  }
+
+  const resolved = assertSafeProjectPath(repoRoot, evidencePath, 'evidence read path');
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`create-quiver: evidence file not found: ${evidencePath}`);
+  }
+
+  const rootReal = fs.realpathSync(repoRoot);
+  const fileReal = fs.realpathSync(resolved);
+  if (!isPathInside(rootReal, fileReal)) {
+    throw new Error('create-quiver: evidence read path must stay inside the project root.');
+  }
+
+  return resolved;
+}
+
+function signalExitCode(signal) {
+  if (!signal) {
+    return null;
+  }
+  return 128 + (SIGNAL_NUMBERS[signal] || 0) || 1;
+}
+
 function renderEvidenceMarkdown(record) {
   return `# Quiver Evidence
 
@@ -48,6 +142,7 @@ function renderEvidenceMarkdown(record) {
 - Duration ms: ${record.duration_ms}
 - Started at: ${record.started_at}
 - Finished at: ${record.finished_at}
+- Signal: ${record.signal || '-'}
 - Output truncated: ${record.output_truncated ? 'yes' : 'no'}
 
 ## Stdout
@@ -66,10 +161,11 @@ ${record.stderr || ''}
 
 function runEvidenceCommand(repoRoot, commandArgs, options = {}) {
   if (!Array.isArray(commandArgs) || commandArgs.length === 0) {
-    throw new Error('create-quiver: evidence run requires a command after --');
+    throw new Error(options.missingCommandMessage || 'create-quiver: evidence run requires a command after --');
   }
 
   const startedAtDate = new Date();
+  const outputPath = resolveEvidenceOutputPath(repoRoot, options.outputPath, startedAtDate);
   const started = Date.now();
   const result = (options.spawnSync || spawnSync)(commandArgs[0], commandArgs.slice(1), {
     cwd: repoRoot,
@@ -78,7 +174,8 @@ function runEvidenceCommand(repoRoot, commandArgs, options = {}) {
   });
   const finishedAtDate = new Date();
   const duration = Date.now() - started;
-  const exitCode = typeof result.status === 'number' ? result.status : 1;
+  const signal = result.signal || '';
+  const exitCode = typeof result.status === 'number' ? result.status : (signalExitCode(signal) || 1);
   const stdout = truncateText(redactSecrets(result.stdout || ''), options.maxOutput || DEFAULT_OUTPUT_LIMIT);
   const stderr = truncateText(redactSecrets(result.stderr || result.error?.message || ''), options.maxOutput || DEFAULT_OUTPUT_LIMIT);
   const record = {
@@ -87,15 +184,12 @@ function runEvidenceCommand(repoRoot, commandArgs, options = {}) {
     exit_code: exitCode,
     finished_at: finishedAtDate.toISOString(),
     output_truncated: stdout.truncated || stderr.truncated,
+    signal,
     stderr: stderr.text,
     stdout: stdout.text,
     started_at: startedAtDate.toISOString(),
   };
-  const outputPath = options.outputPath
-    ? path.resolve(repoRoot, options.outputPath)
-    : defaultEvidencePath(repoRoot, startedAtDate);
 
-  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, renderEvidenceMarkdown(record));
 
   return {
@@ -105,11 +199,72 @@ function runEvidenceCommand(repoRoot, commandArgs, options = {}) {
   };
 }
 
+function parseEvidenceMarkdown(content) {
+  const text = String(content || '');
+  const field = (label) => {
+    const match = text.match(new RegExp(`^- ${label}: (.*)$`, 'm'));
+    return match ? match[1].trim() : '';
+  };
+  const rawExitCode = field('Exit code');
+  const rawDuration = field('Duration ms');
+
+  return {
+    command: field('Command').replace(/^`|`$/g, ''),
+    duration_ms: Number.isFinite(Number(rawDuration)) ? Number(rawDuration) : null,
+    exit_code: Number.isFinite(Number(rawExitCode)) ? Number(rawExitCode) : null,
+    finished_at: field('Finished at'),
+    output_truncated: field('Output truncated') === 'yes',
+    signal: field('Signal') === '-' ? '' : field('Signal'),
+    started_at: field('Started at'),
+  };
+}
+
+function listEvidenceFiles(repoRoot) {
+  const evidenceDir = path.join(repoRoot, '.quiver', 'evidence');
+  if (!fs.existsSync(evidenceDir)) {
+    return [];
+  }
+
+  const rootReal = fs.realpathSync(repoRoot);
+  const dirReal = fs.realpathSync(evidenceDir);
+  if (!isPathInside(rootReal, dirReal)) {
+    throw new Error('create-quiver: evidence directory must stay inside the project root.');
+  }
+
+  return fs.readdirSync(evidenceDir)
+    .filter((entry) => entry.endsWith('.md'))
+    .sort()
+    .map((entry) => {
+      const filePath = path.join(evidenceDir, entry);
+      const content = fs.readFileSync(resolveEvidenceReadPath(repoRoot, filePath), 'utf8');
+      return {
+        path: path.relative(repoRoot, filePath).split(path.sep).join('/'),
+        ...parseEvidenceMarkdown(content),
+      };
+    });
+}
+
+function showEvidenceFile(repoRoot, evidencePath) {
+  const resolved = resolveEvidenceReadPath(repoRoot, evidencePath);
+  const content = fs.readFileSync(resolved, 'utf8');
+  return {
+    content,
+    path: path.relative(repoRoot, resolved).split(path.sep).join('/'),
+    record: parseEvidenceMarkdown(content),
+  };
+}
+
 module.exports = {
   DEFAULT_OUTPUT_LIMIT,
   defaultEvidencePath,
+  listEvidenceFiles,
+  parseEvidenceMarkdown,
   redactSecrets,
   renderEvidenceMarkdown,
+  resolveEvidenceOutputPath,
+  resolveEvidenceReadPath,
   runEvidenceCommand,
+  showEvidenceFile,
+  signalExitCode,
   truncateText,
 };

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

@@ -2,6 +2,8 @@ const cp = require('child_process');
 const fs = require('fs');
 const path = require('path');
 
+const DEFAULT_BASE_BRANCH_CANDIDATES = ['main', 'master', 'develop'];
+
 function runGit(args, cwd, options = {}) {
   return cp.execFileSync('git', args, {
     cwd,
@@ -123,6 +125,98 @@ function hasRemote(repoRoot, remoteName = 'origin') {
   return remoteList(repoRoot).includes(remoteName);
 }
 
+function normalizeBranchName(value) {
+  return String(value || '').trim();
+}
+
+function remoteHeadBranch(repoRoot, remote = 'origin') {
+  const value = tryGit(['symbolic-ref', '--quiet', '--short', `refs/remotes/${remote}/HEAD`], repoRoot);
+  const prefix = `${remote}/`;
+  return value.startsWith(prefix) ? value.slice(prefix.length) : '';
+}
+
+function uniqueBaseCandidates(candidates) {
+  const seen = new Set();
+  return candidates.filter((candidate) => {
+    const branch = normalizeBranchName(candidate.branch);
+    if (!branch || seen.has(branch)) {
+      return false;
+    }
+    seen.add(branch);
+    candidate.branch = branch;
+    return true;
+  });
+}
+
+function buildBaseBranchCandidates(repoRoot, options = {}) {
+  const remote = options.remote || 'origin';
+  const explicitBaseBranch = normalizeBranchName(options.explicitBaseBranch);
+  const preferredBaseBranch = normalizeBranchName(options.preferredBaseBranch);
+  const defaults = Array.isArray(options.defaultBranches) && options.defaultBranches.length > 0
+    ? options.defaultBranches
+    : DEFAULT_BASE_BRANCH_CANDIDATES;
+
+  if (explicitBaseBranch) {
+    return [{ branch: explicitBaseBranch, source: '--base', explicit: true }];
+  }
+
+  return uniqueBaseCandidates([
+    preferredBaseBranch ? { branch: preferredBaseBranch, source: options.preferredSource || 'slice.git.base_branch', explicit: false } : null,
+    { branch: remoteHeadBranch(repoRoot, remote), source: 'remote HEAD', explicit: false },
+    ...defaults.map((branch) => ({ branch, source: 'fallback', explicit: false })),
+  ].filter(Boolean));
+}
+
+function resolveBaseRef(repoRoot, options = {}) {
+  const remote = options.remote || 'origin';
+  const candidates = buildBaseBranchCandidates(repoRoot, options);
+
+  for (const candidate of candidates) {
+    if (remote && hasRemoteBranch(repoRoot, candidate.branch, remote)) {
+      return {
+        baseBranch: candidate.branch,
+        baseRef: `${remote}/${candidate.branch}`,
+        candidates,
+        explicit: candidate.explicit,
+        remote,
+        source: candidate.source,
+      };
+    }
+    if (hasLocalBranch(repoRoot, candidate.branch)) {
+      return {
+        baseBranch: candidate.branch,
+        baseRef: candidate.branch,
+        candidates,
+        explicit: candidate.explicit,
+        remote: '',
+        source: candidate.source,
+      };
+    }
+  }
+
+  if (options.missingOk === true) {
+    const first = candidates[0] || { branch: '', source: 'fallback', explicit: false };
+    return {
+      baseBranch: first.branch,
+      baseRef: '',
+      candidates,
+      explicit: first.explicit,
+      remote: '',
+      source: first.source,
+    };
+  }
+
+  throw new Error(`create-quiver: missing base branch. Tried: ${candidates.map((candidate) => candidate.branch).join(', ') || '(none)'}.`);
+}
+
+function resolveBaseBranchName(repoRoot, options = {}) {
+  const resolution = resolveBaseRef(repoRoot, {
+    ...options,
+    missingOk: true,
+  });
+  return resolution.baseBranch || DEFAULT_BASE_BRANCH_CANDIDATES[0];
+}
+
 function isCleanWorktree(repoRoot) {
   return Boolean(repoRoot && fs.existsSync(repoRoot) && isGitWorktree(repoRoot) && statusPorcelain(repoRoot) === '');
 }
@@ -195,8 +289,10 @@ function catFileExists(repoRoot, specRef) {
 
 module.exports = {
   branchDelete,
+  buildBaseBranchCandidates,
   catFileExists,
   currentBranch,
+  DEFAULT_BASE_BRANCH_CANDIDATES,
   fetchBranch,
   fetchRemote,
   hasLocalBranch,
@@ -211,7 +307,10 @@ module.exports = {
   isGitWorktree,
   isLinkedWorktree,
   revListCount,
+  remoteHeadBranch,
   remoteList,
+  resolveBaseBranchName,
+  resolveBaseRef,
   runGit,
   statusPorcelain,
   tryGit,

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

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { createTranslator } = require('./i18n/catalog');
 
 const REQUIRED_HEADINGS = [
   '## Background',
@@ -141,23 +142,31 @@ function formatMinimalTemplate(kind) {
   return lines.join('\n').trimEnd();
 }
 
-function formatMissingSectionsError(resolved, missingSections) {
+function formatMissingSectionsError(resolved, missingSections, options = {}) {
+  const translator = createTranslator(options.language);
   return [
-    `create-quiver: ${resolved.label.toLowerCase()} is missing required sections: ${missingSections.join(', ')}`,
+    `create-quiver: ${translator.t('handoff.error.missing_sections', {
+      sections: missingSections.join(', '),
+      subject: translator.t(`handoff.subject.${resolved.kind}`),
+    })}`,
     '',
-    'Accepted headings/aliases:',
+    translator.t('handoff.accepted_headings'),
     formatAliasGuidance(resolved.kind),
     '',
-    'Minimal template:',
+    translator.t('handoff.minimal_template'),
     formatMinimalTemplate(resolved.kind),
   ].join('\n');
 }
 
-function checkHandoff(handoffInput, repoRoot = process.cwd()) {
+function checkHandoff(handoffInput, repoRoot = process.cwd(), options = {}) {
   const resolved = resolveHandoffPath(repoRoot, handoffInput);
+  const translator = createTranslator(options.language);
 
   if (!fs.existsSync(resolved.absolutePath)) {
-    throw new Error(`create-quiver: missing ${resolved.label.toLowerCase()} file: ${resolved.relativePath}`);
+    throw new Error(`create-quiver: ${translator.t('handoff.error.missing_file', {
+      path: resolved.relativePath,
+      subject: translator.t(`handoff.subject.${resolved.kind}`),
+    })}`);
   }
 
   const text = fs.readFileSync(resolved.absolutePath, 'utf8');
@@ -165,7 +174,7 @@ function checkHandoff(handoffInput, repoRoot = process.cwd()) {
     ? validateHandoffSections(text)
     : validateBriefSections(text, resolved.kind);
   if (missingSections.length > 0) {
-    throw new Error(formatMissingSectionsError(resolved, missingSections));
+    throw new Error(formatMissingSectionsError(resolved, missingSections, options));
   }
 
   return resolved;

package/src/create-quiver/lib/i18n/catalog.js

@@ -0,0 +1,152 @@
+const { DEFAULT_LANGUAGE, SUPPORTED_LANGUAGES, normalizeLanguage } = require('./language');
+const en = require('./messages/en');
+const es = require('./messages/es');
+
+const CATALOGS = Object.freeze({
+  en,
+  es,
+});
+
+function getCatalog(language = DEFAULT_LANGUAGE) {
+  const normalized = normalizeLanguage(language) || DEFAULT_LANGUAGE;
+  return CATALOGS[normalized] || CATALOGS[DEFAULT_LANGUAGE];
+}
+
+function listMessageKeys(catalog) {
+  return Object.keys(catalog?.messages || {}).sort();
+}
+
+function validateCatalogCompleteness(catalogs = CATALOGS) {
+  const baseKeys = listMessageKeys(catalogs[DEFAULT_LANGUAGE]);
+  const missing = [];
+  const extra = [];
+
+  for (const language of SUPPORTED_LANGUAGES) {
+    const keys = listMessageKeys(catalogs[language]);
+    for (const key of baseKeys) {
+      if (!keys.includes(key)) {
+        missing.push(`${language}:${key}`);
+      }
+    }
+    for (const key of keys) {
+      if (!baseKeys.includes(key)) {
+        extra.push(`${language}:${key}`);
+      }
+    }
+  }
+
+  return {
+    ok: missing.length === 0 && extra.length === 0,
+    missing,
+    extra,
+  };
+}
+
+function assertCatalogCompleteness(catalogs = CATALOGS) {
+  const report = validateCatalogCompleteness(catalogs);
+  if (!report.ok) {
+    throw new Error([
+      'i18n catalog completeness failed',
+      ...report.missing.map((item) => `missing ${item}`),
+      ...report.extra.map((item) => `extra ${item}`),
+    ].join('\n'));
+  }
+  return report;
+}
+
+function sanitizeInterpolationValue(value) {
+  if (value === null || typeof value === 'undefined') {
+    return '';
+  }
+
+  return String(value)
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/\r/g, '\\r')
+    .replace(/\n/g, '\\n')
+    .replace(/\t/g, '\\t')
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '');
+}
+
+function interpolate(template, params = {}) {
+  return String(template).replace(/\{([a-zA-Z0-9_.-]+)\}/g, (match, name) => {
+    if (!Object.prototype.hasOwnProperty.call(params, name)) {
+      return `[missing:${name}]`;
+    }
+    return sanitizeInterpolationValue(params[name]);
+  });
+}
+
+function selectPluralTemplate(message, params = {}) {
+  if (!message || typeof message !== 'object' || Array.isArray(message)) {
+    return message;
+  }
+
+  const count = Number(params.count);
+  if (count === 1 && typeof message.one === 'string') {
+    return message.one;
+  }
+  if (typeof message.other === 'string') {
+    return message.other;
+  }
+  if (typeof message.one === 'string') {
+    return message.one;
+  }
+  return '';
+}
+
+function resolveMessage(language, key) {
+  const catalog = getCatalog(language);
+  const message = catalog.messages[key];
+  if (typeof message !== 'undefined') {
+    return {
+      message,
+      language: catalog.metadata.language,
+      fallback: false,
+    };
+  }
+
+  const fallbackCatalog = getCatalog(DEFAULT_LANGUAGE);
+  const fallbackMessage = fallbackCatalog.messages[key];
+  if (typeof fallbackMessage !== 'undefined') {
+    return {
+      message: fallbackMessage,
+      language: DEFAULT_LANGUAGE,
+      fallback: true,
+    };
+  }
+
+  return {
+    message: `[missing:${key}]`,
+    language: DEFAULT_LANGUAGE,
+    fallback: true,
+    missing: true,
+  };
+}
+
+function translate(language, key, params = {}) {
+  const resolved = resolveMessage(language, key);
+  const template = selectPluralTemplate(resolved.message, params);
+  return interpolate(template, params);
+}
+
+function createTranslator(language = DEFAULT_LANGUAGE) {
+  return {
+    language: getCatalog(language).metadata.language,
+    t(key, params = {}) {
+      return translate(language, key, params);
+    },
+  };
+}
+
+module.exports = {
+  CATALOGS,
+  assertCatalogCompleteness,
+  createTranslator,
+  getCatalog,
+  interpolate,
+  listMessageKeys,
+  resolveMessage,
+  sanitizeInterpolationValue,
+  translate,
+  validateCatalogCompleteness,
+};