pincer-workflow 0.6.0 → 1.0.0

package/template/scripts/pincer/models.cjs

@@ -0,0 +1,121 @@
+'use strict';
+// PINCER engine — model tiers (docs/engine.md, "Models"). The agreement names a
+// tier per role; the library's models.json maps a tier to each platform's model
+// name; the agreement's map overrides a row; a library agent file may carry a
+// tier: default. Pure except the two readers. Dependency-free.
+const fs = require('node:fs');
+const path = require('node:path');
+const harness = require('./harness.cjs');
+
+const TABLE_FILE = 'models.json';
+const { TIERS, MAP_TIERS, PLATFORMS, OPTIONAL_STAGES } = harness;
+const SESSION = "the session's model";
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const filled = (value) => typeof value === 'string' && value.trim() !== '';
+
+// The library's table. A missing entry is not a fault (the generator reports it
+// when a tier needs it); a present entry that is not a non-empty string is.
+function readTable(libraryDir) {
+  const file = path.join(libraryDir, TABLE_FILE);
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (error) {
+    if (error.code === 'ENOENT') return { ok: false, missing: true, problem: `${TABLE_FILE}: no such file` };
+    return { ok: false, problem: `${TABLE_FILE}: ${error.message}` };
+  }
+  let table;
+  try { table = JSON.parse(raw); } catch (error) { return { ok: false, problem: `${TABLE_FILE}: invalid JSON (${error.message})` }; }
+  if (!isObject(table) || table.schema !== 1) return { ok: false, problem: `${TABLE_FILE}: schema must be 1` };
+  for (const platform of PLATFORMS) {
+    if (table[platform] === undefined) continue;
+    if (!isObject(table[platform])) return { ok: false, problem: `${TABLE_FILE}: ${platform} must be an object` };
+    for (const tier of MAP_TIERS) {
+      const value = table[platform][tier];
+      if (value !== undefined && !filled(value)) return { ok: false, problem: `${TABLE_FILE}: ${platform}.${tier} must be a non-empty string` };
+    }
+  }
+  return { ok: true, table };
+}
+
+// The table with the agreement's map laid over it; a copy, the inputs untouched.
+function overlay(table, map) {
+  const out = { ...(isObject(table) ? table : {}) };
+  for (const platform of PLATFORMS) {
+    const row = { ...(isObject(out[platform]) ? out[platform] : {}) };
+    const over = isObject(map) && isObject(map[platform]) ? map[platform] : {};
+    for (const tier of MAP_TIERS) if (filled(over[tier])) row[tier] = over[tier];
+    out[platform] = row;
+  }
+  return out;
+}
+
+// null: no model field (inherit or not set); undefined: the table has no entry.
+function modelFor(table, platform, tier) {
+  if (!tier || tier === 'inherit') return null;
+  const row = isObject(table) && isObject(table[platform]) ? table[platform] : {};
+  return filled(row[tier]) ? row[tier] : undefined;
+}
+
+// The tier: field of a library agent's frontmatter; '' when absent.
+function libraryTier(libraryDir, name) {
+  let text;
+  try { text = fs.readFileSync(path.join(libraryDir, 'agents', `${name}.md`), 'utf8'); } catch { return ''; }
+  const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  const match = block && /^tier:\s*["']?([a-z]+)["']?\s*$/m.exec(block[1]);
+  return match && TIERS.includes(match[1]) ? match[1] : '';
+}
+
+// What each role runs on: every optional stage that is on and every active
+// agent. The agreement's tier wins, then the library's default, then ''.
+function effective(doc, libraryDir) {
+  const h = harness.normalize(doc);
+  const out = { stages: {}, agents: {} };
+  for (const stage of OPTIONAL_STAGES) {
+    if (!harness.stageOn(h, stage)) continue;
+    const entry = isObject(h.models.stages[stage]) ? h.models.stages[stage] : {};
+    out.stages[stage] = { tier: filled(entry.tier) ? entry.tier : '', effort: filled(entry.effort) ? entry.effort : '' };
+  }
+  for (const name of harness.activeAgents(h)) {
+    const entry = isObject(h.models.agents[name]) ? h.models.agents[name] : {};
+    const agreed = filled(entry.tier) ? entry.tier : '';
+    const fallback = agreed ? '' : libraryTier(libraryDir, name);
+    out.agents[name] = { tier: agreed || fallback, effort: filled(entry.effort) ? entry.effort : '', source: agreed ? 'agreement' : fallback ? 'library' : 'none' };
+  }
+  return out;
+}
+
+// 'strong', 'strong/high', 'effort high', or '' for an unset role.
+function describeEntry(entry) {
+  const tier = entry && filled(entry.tier) ? entry.tier : '';
+  const effort = entry && filled(entry.effort) ? entry.effort : '';
+  if (tier && effort) return `${tier}/${effort}`;
+  if (tier) return tier;
+  if (effort) return `effort ${effort}`;
+  return '';
+}
+const agentNames = (eff) => Object.keys(isObject(eff.agents) ? eff.agents : {}).sort();
+const stageNames = (eff) => OPTIONAL_STAGES.filter((stage) => isObject(eff.stages) && eff.stages[stage]);
+
+// The status line: stages, then agents; '' when nothing is set.
+function statusLine(eff) {
+  const stages = stageNames(eff).filter((s) => describeEntry(eff.stages[s])).map((s) => `${s} ${describeEntry(eff.stages[s])}`);
+  const agents = agentNames(eff).filter((n) => describeEntry(eff.agents[n])).map((n) => `${n} ${describeEntry(eff.agents[n])}`);
+  return [stages.join(', '), agents.join(', ')].filter(Boolean).join('; ');
+}
+
+// The agreement's Models line: stages, then agents grouped by tier.
+function agreementLine(eff) {
+  const onWhat = (tier) => (tier && tier !== 'inherit' ? tier : SESSION);
+  const note = (entry) => (filled(entry.effort) ? ` (${entry.effort} effort)` : '');
+  const list = (items) => (items.length > 1 ? `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}` : items[0]);
+  const stages = stageNames(eff).filter((s) => describeEntry(eff.stages[s])).map((s) => `${s} on ${onWhat(eff.stages[s].tier)}${note(eff.stages[s])}`);
+  const groups = [];
+  for (const tier of [...TIERS, '']) {
+    const names = agentNames(eff).filter((n) => describeEntry(eff.agents[n]) && (filled(eff.agents[n].tier) ? eff.agents[n].tier : '') === tier);
+    if (names.length) groups.push(`${list(names.map((n) => `${n}${note(eff.agents[n])}`))} on ${onWhat(tier)}`);
+  }
+  if (!stages.length && !groups.length) return `${SESSION} everywhere.`;
+  return [stages.join(', '), ...groups, `everything else on ${SESSION}.`].filter(Boolean).join('; ');
+}
+
+module.exports = { TABLE_FILE, readTable, overlay, modelFor, libraryTier, effective, describeEntry, statusLine, agreementLine };

package/template/scripts/{pincer-runtime → pincer}/parse.cjs

@@ -1,27 +1,29 @@
 'use strict';
-// PINCER runtime — parser and validator for the supported Markdown grammar
-// (docs/runtime-contracts.md, "Supported grammar" and "Content revisions").
-// Dependency-free. The rules and diagnostics match the v0.4.1 Bash validators
-// so the two never disagree; the Node module is now the only implementation.
+// PINCER engine — parser and validator for the ticket and spec grammar
+// (docs/engine.md, "Ticket fields and receipts"). Dependency-free.
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
 
 const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
-const PRD_REF = /^\.prd\/prd-v([1-9][0-9]{0,8})\.md$/;
-const HEX40 = /^[0-9a-f]{40}$/;
+const SPEC_REF = /^[^\s]+\.md$/;
 const DEFAULT_TIMEOUT = 600;
 const MAX_TIMEOUT = 2147483; // setTimeout's 32-bit millisecond limit, in seconds
-const LIFECYCLE_FIELDS = ['status', 'started', 'finished', 'verified', 'last_check'];
-const CHECKBOX_LINE = /^([ \t]*(?:[-+*]|[0-9]+[.)])[ \t]+)\[([ xX])\]/;
+// The fields only scripts/pincer-ticket.sh writes; the hook protects the same list.
+const LIFECYCLE_FIELDS = ['status', 'started', 'last_check', 'verified', 'finished', 'accepted', 'accepted_by', 'accepted_words'];
+// Keys whose value is kept verbatim: the inline-comment rule (`#` to end of
+// line) does not apply, because the person's words may contain `#`.
+const VERBATIM_KEYS = new Set(['accepted_words']);
+const SPEC_STATUSES = ['draft', 'approved', 'built'];
 
-const sha256 = text => crypto.createHash('sha256').update(text).digest('hex');
-const lines = text => {
+const sha256 = (text) => crypto.createHash('sha256').update(text).digest('hex');
+const lines = (text) => {
   const all = String(text).split('\n');
   if (all.length && all[all.length - 1] === '') all.pop();
   return all;
 };
+const fieldValue = (key, raw) => (VERBATIM_KEYS.has(key) ? raw : raw.replace(/#.*/, '')).trim();
 
 // CLI shorthand -> canonical ID ("3" -> "T-03"); null when not a ticket id.
 function normalizeId(input) {
@@ -53,24 +55,20 @@ function parseFrontmatter(text, kind = 'ticket') {
     }
     const key = line.slice(0, line.indexOf(':'));
     if (key in fields) return { problem: `duplicate ${kind === 'ticket' ? 'frontmatter' : 'metadata'} key: ${key}`, rows };
-    let value = line.slice(key.length + 1);
-    value = value.replace(/#.*/, '').trim();
-    fields[key] = value;
+    fields[key] = fieldValue(key, line.slice(key.length + 1));
     order.push(key);
   }
   return { problem: 'frontmatter must close with ---', rows };
 }
 
-// Read one frontmatter field the way the Bash helper did (first match, comment
-// stripped), tolerating files without valid frontmatter.
+// Read one frontmatter field (first match), tolerating files whose
+// frontmatter does not validate; '' when absent.
 function frontmatterField(text, key) {
-  const fm = parseFrontmatter(text);
-  if (fm.problem && fm.problem !== 'frontmatter must close with ---') {
-    if (fm.problem === 'frontmatter must begin with ---') return '';
-  }
-  for (const line of lines(text).slice(1)) {
+  const rows = lines(text);
+  if (rows[0] !== '---') return '';
+  for (const line of rows.slice(1)) {
     if (line === '---') break;
-    if (line.startsWith(`${key}:`)) return line.slice(key.length + 1).replace(/#.*/, '').trim();
+    if (line.startsWith(`${key}:`)) return fieldValue(key, line.slice(key.length + 1));
   }
   return '';
 }
@@ -88,9 +86,10 @@ function verificationCommands(text) {
   }
   return out;
 }
-// The block as the legacy helper hashed and executed it: joined lines, one trailing newline.
-const blockText = text => { const c = verificationCommands(text); return c.length ? `${c.join('\n')}\n` : ''; };
-const legacyBlockHash = text => sha256(blockText(text)).slice(0, 12);
+// The block as it is hashed and executed: joined lines, one trailing newline.
+const blockText = (text) => { const c = verificationCommands(text); return c.length ? `${c.join('\n')}\n` : ''; };
+// Twelve hex characters of sha256 over the block: the receipt hash.
+const blockHash = (text) => sha256(blockText(text)).slice(0, 12);
 
 function unticked(text) {
   const out = [];
@@ -109,6 +108,13 @@ function effectiveTimeout(fields) {
   return fields.timeout ? Number(fields.timeout) : DEFAULT_TIMEOUT;
 }
 
+// A spec reference is a relative path inside the repository to a .md file.
+function specRefProblem(ref) {
+  if (typeof ref !== 'string' || !SPEC_REF.test(ref)) return 'must be a relative path to a .md file, such as specs/spec-v1.md';
+  if (ref.startsWith('/') || ref.split(/[\\/]/).includes('..')) return 'must stay inside the repository (no leading / or ..)';
+  return null;
+}
+
 // Full ticket validation. Returns { ok, problems, fields, timeout }.
 function validateTicket(file, text) {
   const problems = [];
@@ -154,7 +160,7 @@ function validateTicket(file, text) {
   }
   if (!['open', 'in_progress', 'done'].includes(fields.status)) problems.push('status must be open, in_progress, or done');
   if (!['S', 'M', 'L'].includes(fields.size)) problems.push('size must be S, M, or L');
-  for (const key of ['started', 'finished']) if (key in fields && !TIMESTAMP.test(fields[key])) problems.push(`${key} must be an ISO UTC timestamp`);
+  for (const key of ['started', 'finished', 'accepted']) if (key in fields && !TIMESTAMP.test(fields[key])) problems.push(`${key} must be an ISO UTC timestamp`);
   for (const key of ['verified', 'last_check']) {
     if (!(key in fields)) continue;
     const parts = fields[key].split(/[ \t]+/);
@@ -162,7 +168,15 @@ function validateTicket(file, text) {
     if (parts.length !== expected || !TIMESTAMP.test(parts[0]) || !/^[0-9a-f]{12}$/.test(parts[parts.length - 1])) problems.push(`malformed ${key} timestamp/hash`);
     else if (key === 'last_check' && !['running', 'passed', 'failed', 'interrupted'].includes(parts[1])) problems.push('invalid last_check outcome');
   }
+  // The floor: an acceptance is a timestamp, a named person and their words, all three or none.
+  const acceptance = ['accepted', 'accepted_by', 'accepted_words'].filter((key) => key in fields);
+  if (acceptance.length) {
+    for (const key of ['accepted', 'accepted_by', 'accepted_words']) {
+      if (!(key in fields) || fields[key] === '') problems.push(`${key} is required when a ticket is accepted (write it with pincer-ticket.sh accept)`);
+    }
+  }
   if ('timeout' in fields && (!/^[1-9][0-9]{0,8}$/.test(fields.timeout) || Number(fields.timeout) > MAX_TIMEOUT)) problems.push(`timeout must be a positive integer number of seconds (at most ${MAX_TIMEOUT})`);
+  if ('spec' in fields) { const problem = specRefProblem(fields.spec); if (problem) problems.push(`spec ${problem}`); }
   const deps = fields.depends_on;
   if (!('depends_on' in fields) || !/^\[[ \t]*(T-[0-9]+([ \t]*,[ \t]*T-[0-9]+)*)?[ \t]*\]$/.test(deps)) problems.push('depends_on must be an inline list such as [T-01, T-02]');
   else {
@@ -190,127 +204,63 @@ function dependencies(fields) {
   return ((fields.depends_on || '').match(/T-[0-9]+/g) || []);
 }
 
-// PRDs and evaluation notes use the same deliberately small metadata format.
-function validateMetadata(text) {
-  const fm = parseFrontmatter(text, 'metadata');
-  return fm.problem ? { ok: false, problems: [fm.problem], fields: {} } : { ok: true, problems: [], fields: fm.fields };
+// <ticketsDir>/T-NN-*.md resolution, paths relative to the root.
+function ticketFiles(root, ticketsDir = 'tickets') {
+  const dir = path.join(root, ticketsDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((name) => /^T-[0-9]+.*\.md$/.test(name)).sort().map((name) => path.posix.join(ticketsDir, name));
+}
+function ticketFile(root, ticketsDir, input) {
+  const id = normalizeId(input);
+  if (!id) return { problem: `not a ticket id (expected 1..999999): ${input}` };
+  const matches = ticketFiles(root, ticketsDir).filter((f) => path.basename(f).startsWith(`${id}-`));
+  if (matches.length > 1) return { problem: `several files match ${path.posix.join(ticketsDir, id)}-*.md` };
+  if (matches.length === 0) return { problem: `no ticket file ${path.posix.join(ticketsDir, id)}-*.md` };
+  return { id, file: matches[0] };
 }
 
-function validatePrd(root, ref) {
-  const match = typeof ref === 'string' ? ref.match(PRD_REF) : null;
-  if (!match) return { ok: false, problems: [`invalid PRD reference ${ref}; use .prd/prd-vN.md`], prefix: 'pincer' };
+// A spec: closed frontmatter with status draft, approved or built.
+function validateSpec(root, ref) {
+  const problem = specRefProblem(ref);
+  if (problem) return { ok: false, problems: [`spec ${problem}: ${ref}`], fields: {} };
   const file = path.join(root, ref);
-  if (!fs.existsSync(file)) return { ok: false, problems: [`PRD does not exist: ${ref}`], prefix: 'pincer' };
+  if (!fs.existsSync(file)) return { ok: false, problems: [`spec does not exist: ${ref}`], fields: {} };
   const text = fs.readFileSync(file, 'utf8');
-  const meta = validateMetadata(text);
-  if (!meta.ok) return { ok: false, problems: meta.problems, file: ref };
+  const fm = parseFrontmatter(text, 'spec');
+  if (fm.problem) return { ok: false, problems: [`${ref}: ${fm.problem}`], fields: {} };
   const problems = [];
-  const { fields } = meta;
-  if (fields.version !== match[1]) problems.push(`version must match filename (${match[1]})`);
-  if (!['draft', 'ticketed', 'built'].includes(fields.status)) problems.push('PRD status must be draft, ticketed, or built');
-  if (!['', 'small', 'standard', undefined].includes(fields.profile)) problems.push('profile must be small or standard (omit for standard)');
-  return { ok: problems.length === 0, problems, file: ref, fields, text, profile: fields.profile || 'standard' };
+  if (!SPEC_STATUSES.includes(fm.fields.status)) problems.push(`${ref}: status must be ${SPEC_STATUSES.join(', ')}`);
+  return { ok: problems.length === 0, problems, fields: fm.fields, file: ref, text };
 }
 
-// Normalizations (contract "Content revisions"): lifecycle fields and checkbox
-// marks are the only exceptions; everything else contributes to identity.
-function normalizeTicket(text) {
-  const rows = lines(text);
-  const out = [];
-  let closed = rows[0] !== '---';
-  let otherFence = false, inAccept = false;
-  for (let i = 0; i < rows.length; i++) {
-    const line = rows[i];
-    if (!closed) {
-      if (i > 0 && line === '---') closed = true;
-      else if (i > 0) {
-        const key = (line.match(/^([a-z_][a-z0-9_]*):/) || [])[1];
-        if (key && LIFECYCLE_FIELDS.includes(key)) continue;
-      }
-      out.push(line);
-      continue;
-    }
-    if (otherFence) { if (/^[ \t]*```/.test(line)) otherFence = false; out.push(line); continue; }
-    if (/^[ \t]*```/.test(line)) { otherFence = true; out.push(line); continue; }
-    if (/^## Acceptance Criteria[ \t]*$/.test(line)) inAccept = true;
-    else if (/^## /.test(line)) inAccept = false;
-    out.push(inAccept ? line.replace(CHECKBOX_LINE, '$1[ ]') : line);
-  }
-  return `${out.join('\n')}\n`;
+// Set or remove one frontmatter field, keeping every other line as it is. A
+// value is kept to one line. The text must have a closed frontmatter.
+function frontmatterEnd(rows, key) {
+  if (rows[0] !== '---') throw new Error(`cannot edit ${key}: frontmatter must begin with ---`);
+  const end = rows.indexOf('---', 1);
+  if (end === -1) throw new Error(`cannot edit ${key}: frontmatter must close with ---`);
+  return end;
 }
-function normalizePrd(text) {
+function fmSet(text, key, value) {
   const rows = lines(text);
-  const out = [];
-  let closed = rows[0] !== '---';
-  for (let i = 0; i < rows.length; i++) {
-    const line = rows[i];
-    if (!closed) {
-      if (i > 0 && line === '---') closed = true;
-      else if (i > 0 && /^status:/.test(line)) continue;
-    }
-    out.push(line);
-  }
-  return `${out.join('\n')}\n`;
+  const end = frontmatterEnd(rows, key);
+  const line = `${key}: ${String(value).replace(/\r?\n/g, ' ')}`;
+  const at = rows.findIndex((row, i) => i > 0 && i < end && row.startsWith(`${key}:`));
+  if (at === -1) rows.splice(end, 0, line); else rows[at] = line;
+  return `${rows.join('\n')}\n`;
 }
-// Split a ticket text into the parts the structural agreement difference names:
-// the frontmatter, the Acceptance Criteria section, the Verification section and
-// everything else (headings inside fenced blocks are ignored, as elsewhere).
-function ticketSections(text) {
+function fmUnset(text, key) {
   const rows = lines(text);
-  const parts = { frontmatter: [], acceptance: [], verification: [], other: [] };
-  let inFront = rows[0] === '---', section = 'other', fence = false;
-  for (let i = 0; i < rows.length; i++) {
-    const line = rows[i];
-    if (inFront) { parts.frontmatter.push(line); if (i > 0 && line === '---') inFront = false; continue; }
-    if (fence) { parts[section].push(line); if (/^[ \t]*```/.test(line)) fence = false; continue; }
-    if (/^[ \t]*```/.test(line)) { fence = true; parts[section].push(line); continue; }
-    if (/^## Acceptance Criteria[ \t]*$/.test(line)) section = 'acceptance';
-    else if (/^## Verification[ \t]*$/.test(line)) section = 'verification';
-    else if (/^## /.test(line)) section = 'other';
-    parts[section].push(line);
-  }
-  return Object.fromEntries(Object.entries(parts).map(([k, v]) => [k, v.join('\n')]));
-}
-const ticketDigest = text => sha256(normalizeTicket(text));
-const prdDigest = text => sha256(normalizePrd(text));
-const checkDigest = (text, timeoutSeconds = DEFAULT_TIMEOUT) => sha256(`${blockText(text)}timeout=${timeoutSeconds}\n`);
-
-// tickets/T-NN-*.md resolution and set validation.
-function ticketFiles(root) {
-  const dir = path.join(root, 'tickets');
-  if (!fs.existsSync(dir)) return [];
-  return fs.readdirSync(dir).filter(name => /^T-[0-9]+.*\.md$/.test(name)).sort().map(name => `tickets/${name}`);
-}
-function ticketFile(root, input) {
-  const id = normalizeId(input);
-  if (!id) return { problem: `not a ticket id (expected 1..999999): ${input}` };
-  const matches = ticketFiles(root).filter(f => path.basename(f).startsWith(`${id}-`));
-  if (matches.length > 1) return { problem: `several files match tickets/${id}-*.md` };
-  if (matches.length === 0) return { problem: `no ticket file tickets/${id}-*.md` };
-  return { id, file: matches[0] };
-}
-function validateTicketSet(root) {
-  const files = ticketFiles(root);
-  const ids = new Set();
-  for (const file of files) {
-    const id = frontmatterField(fs.readFileSync(path.join(root, file), 'utf8'), 'ticket');
-    if (id) {
-      if (ids.has(id)) return { ok: false, problems: [`duplicate ticket ID: ${id}`] };
-      ids.add(id);
-    }
-  }
-  for (const file of files) {
-    const result = validateTicket(file, fs.readFileSync(path.join(root, file), 'utf8'));
-    if (!result.ok) return { ok: false, file, problems: result.problems };
-  }
-  return { ok: true, files };
+  const end = frontmatterEnd(rows, key);
+  const at = rows.findIndex((row, i) => i > 0 && i < end && row.startsWith(`${key}:`));
+  if (at === -1) return text;
+  rows.splice(at, 1);
+  return `${rows.join('\n')}\n`;
 }
 
 module.exports = {
-  TIMESTAMP, PRD_REF, HEX40, DEFAULT_TIMEOUT, MAX_TIMEOUT, LIFECYCLE_FIELDS,
+  TIMESTAMP, SPEC_REF, DEFAULT_TIMEOUT, MAX_TIMEOUT, LIFECYCLE_FIELDS, SPEC_STATUSES,
   sha256, lines, normalizeId, canonicalId, parseFrontmatter, frontmatterField,
-  verificationCommands, blockText, legacyBlockHash, unticked, effectiveTimeout,
-  validateTicket, dependencies, validateMetadata, validatePrd,
-  normalizeTicket, normalizePrd, ticketDigest, prdDigest, checkDigest, ticketSections,
-  ticketFiles, ticketFile, validateTicketSet,
+  verificationCommands, blockText, blockHash, unticked, effectiveTimeout,
+  validateTicket, dependencies, ticketFiles, ticketFile, validateSpec, fmSet, fmUnset,
 };

package/template/scripts/pincer/recon.cjs

@@ -0,0 +1,205 @@
+'use strict';
+// PINCER blueprint — repository recon (docs/engine.md, "Recon"). Reads git, the
+// filesystem and, only when asked, gh; decides greenfield or brownfield and says
+// why; pre-fills the parts of harness.json it could see. Offline by default.
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const util = require('./util.cjs');
+
+// Directories never counted as source: dependencies, build output, the kit's own code.
+const SKIP_DIRS = new Set(['node_modules', '.git', '.claude', 'vendor', '.venv', 'venv', 'dist', 'build', 'target', '__pycache__']);
+const SKIP_PATHS = new Set(['scripts/pincer']);
+const MAX_ENTRIES = 50000; // walk budget; past it sourceFiles is a lower bound
+const LANGUAGES = {
+  js: 'JavaScript', mjs: 'JavaScript', cjs: 'JavaScript', jsx: 'JavaScript',
+  ts: 'TypeScript', mts: 'TypeScript', cts: 'TypeScript', tsx: 'TypeScript',
+  py: 'Python', go: 'Go', rs: 'Rust', java: 'Java', kt: 'Kotlin', scala: 'Scala',
+  rb: 'Ruby', php: 'PHP', cs: 'C#', swift: 'Swift', m: 'Objective-C', dart: 'Dart',
+  c: 'C', h: 'C', cpp: 'C++', cc: 'C++', hpp: 'C++', zig: 'Zig',
+  sh: 'Shell', bash: 'Shell', zsh: 'Shell', sql: 'SQL', vue: 'Vue', svelte: 'Svelte',
+  ex: 'Elixir', exs: 'Elixir', clj: 'Clojure', hs: 'Haskell', lua: 'Lua', r: 'R',
+};
+const TEST_PATH = /(^|\/)(tests?|spec|__tests__)\/|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)test_[^/]+\.py$|_test\.(py|go|rb|rs)$|_spec\.rb$/;
+const DEPLOY_FILES = ['vercel.json', 'netlify.toml', 'fly.toml', 'Dockerfile', 'render.yaml', 'Procfile', 'serverless.yml', 'wrangler.toml'];
+const INSTRUCTION_FILES = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.github/copilot-instructions.md', '.cursorrules', 'CONTRIBUTING.md', 'README.md'];
+const LOCKFILES = [
+  ['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['bun.lockb', 'bun'], ['bun.lock', 'bun'], ['package-lock.json', 'npm'],
+  ['package.json', 'npm'], ['uv.lock', 'uv'], ['poetry.lock', 'poetry'], ['Pipfile', 'pipenv'], ['requirements.txt', 'pip'],
+  ['Cargo.toml', 'cargo'], ['go.mod', 'go'], ['Gemfile', 'bundler'], ['composer.json', 'composer'],
+];
+
+const exists = (root, rel) => fs.existsSync(path.join(root, rel));
+const isDir = (root, rel) => { try { return fs.statSync(path.join(root, rel)).isDirectory(); } catch { return false; } };
+const listFiles = (root, rel) => (isDir(root, rel)
+  ? fs.readdirSync(path.join(root, rel), { withFileTypes: true }).filter((e) => e.isFile()).map((e) => `${rel}/${e.name}`).sort()
+  : []);
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+// Source files, languages by count and whether anything looks like a test.
+function walk(root) {
+  const counts = new Map();
+  let sourceFiles = 0, testFiles = 0, budget = MAX_ENTRIES;
+  const visit = (rel) => {
+    let entries;
+    try { entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => (a.name < b.name ? -1 : 1));
+    for (const entry of entries) {
+      if (budget-- <= 0) return;
+      const child = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name) && !SKIP_PATHS.has(child)) visit(child);
+      } else if (entry.isFile()) {
+        const language = LANGUAGES[path.extname(entry.name).slice(1).toLowerCase()];
+        if (!language) continue;
+        sourceFiles += 1;
+        counts.set(language, (counts.get(language) || 0) + 1);
+        if (TEST_PATH.test(child)) testFiles += 1;
+      }
+    }
+  };
+  visit('');
+  const languages = [...counts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).map(([name]) => name);
+  return { sourceFiles, languages, testFiles };
+}
+
+
+function gitFacts(root, unavailable) {
+  const facts = { git: false, commits: 0, authors: [], branch: '', branches: [], mergeStyle: 'unknown', remote: null, forge: null, tags: 0 };
+  if (util.tryGit(root, ['rev-parse', '--is-inside-work-tree']) !== 'true') { unavailable.push('git'); return facts; }
+  facts.git = true;
+  facts.commits = Number(util.tryGit(root, ['rev-list', '--count', 'HEAD'])) || 0;
+  const authors = util.tryGit(root, ['log', '--format=%an']);
+  facts.authors = authors ? [...new Set(authors.split('\n').filter(Boolean))].sort() : [];
+  facts.branch = util.tryGit(root, ['symbolic-ref', '--short', '-q', 'HEAD']) || util.tryGit(root, ['rev-parse', '--abbrev-ref', 'HEAD']) || '';
+  const branches = util.tryGit(root, ['branch', '--format=%(refname:short)']);
+  facts.branches = branches ? branches.split('\n').filter(Boolean).sort() : [];
+  if (util.tryGit(root, ['log', '--merges', '-1', '--format=%H'])) facts.mergeStyle = 'merge';
+  else if (facts.commits >= 5) facts.mergeStyle = 'squash-or-rebase';
+  const remotes = (util.tryGit(root, ['remote']) || '').split('\n').filter(Boolean);
+  const remoteName = remotes.includes('origin') ? 'origin' : remotes[0];
+  const url = remoteName ? util.tryGit(root, ['remote', 'get-url', remoteName]) : null;
+  if (url) {
+    facts.remote = util.stripUserinfo(url);
+    facts.forge = /(^|@|\/\/)github\.com[:/]/i.test(facts.remote) ? 'github' : 'other';
+  }
+  const tags = util.tryGit(root, ['tag']);
+  facts.tags = tags ? tags.split('\n').filter(Boolean).length : 0;
+  return facts;
+}
+
+// A workflow deploys when its file name, its name, a job id or an action it uses says so.
+function workflowDeploys(root, rel) {
+  let text;
+  try { text = fs.readFileSync(path.join(root, rel), 'utf8'); } catch { return false; }
+  const hits = [path.basename(rel, path.extname(rel))];
+  let inJobs = false;
+  for (const line of text.split('\n')) {
+    const name = /^\s*name:\s*(.+)$/.exec(line);
+    const uses = /^\s*-?\s*uses:\s*(.+)$/.exec(line);
+    if (name) hits.push(name[1]);
+    if (uses) hits.push(uses[1]);
+    if (/^jobs:\s*$/.test(line)) { inJobs = true; continue; }
+    if (/^\S/.test(line)) inJobs = false;
+    const job = inJobs && /^ {2}([A-Za-z0-9_-]+):\s*$/.exec(line);
+    if (job) hits.push(job[1]);
+  }
+  return hits.some((hit) => /deploy|pages/i.test(hit));
+}
+
+function codeFacts(root) {
+  const workflows = listFiles(root, '.github/workflows').filter((f) => /\.ya?ml$/.test(f));
+  const ci = [...workflows, ...(exists(root, '.gitlab-ci.yml') ? ['.gitlab-ci.yml'] : []), ...listFiles(root, '.circleci')];
+  const deploy = [...workflows.filter((f) => workflowDeploys(root, f)), ...DEPLOY_FILES.filter((f) => exists(root, f))].sort();
+  const lock = LOCKFILES.find(([file]) => exists(root, file));
+  const packageManager = lock ? lock[1] : null;
+  const pkg = util.readJson(path.join(root, 'package.json'));
+  let runner = null;
+  if (pkg && pkg.scripts && typeof pkg.scripts.test === 'string' && pkg.scripts.test.trim()) runner = `${['pnpm', 'yarn', 'bun'].includes(packageManager) ? packageManager : 'npm'} test`;
+  else if (exists(root, 'pytest.ini') || exists(root, 'pyproject.toml')) runner = 'pytest';
+  else if (exists(root, 'Cargo.toml')) runner = 'cargo test';
+  else if (exists(root, 'go.mod')) runner = 'go test ./...';
+  const walked = walk(root);
+  return {
+    ci, deploy,
+    tests: { present: walked.testFiles > 0, runner },
+    languages: walked.languages,
+    packageManager,
+    sourceFiles: walked.sourceFiles,
+    envExample: ['.env.example', '.env.sample', '.env.template'].some((f) => exists(root, f)),
+    instructions: [...INSTRUCTION_FILES.filter((f) => exists(root, f)), ...(isDir(root, 'docs') ? ['docs/'] : [])].sort(),
+    name: pkg && typeof pkg.name === 'string' && pkg.name.trim() ? pkg.name.trim() : path.basename(root),
+  };
+}
+
+// gh is consulted only when the caller allowed the network and gh is on PATH.
+function ghFacts(root, branch, network, unavailable) {
+  const facts = { available: false, issues: null, prs: null, protection: null };
+  const gh = (args) => {
+    try { return execFileSync('gh', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 20000 }); } catch (error) { return { error }; }
+  };
+  if (!network || gh(['--version']).error) { unavailable.push('gh'); return facts; }
+  facts.available = true;
+  const count = (args) => { const r = gh(args); if (r.error) return null; try { return JSON.parse(r).length; } catch { return null; } };
+  facts.issues = count(['issue', 'list', '--state', 'all', '--limit', '100', '--json', 'number']);
+  facts.prs = count(['pr', 'list', '--state', 'all', '--limit', '100', '--json', 'number']);
+  // Protection is asked about the forge's default branch; the local branch may not exist there.
+  const view = gh(['repo', 'view', '--json', 'defaultBranchRef', '--jq', '.defaultBranchRef.name']);
+  const target = (!view.error && view.trim()) || branch;
+  if (target) {
+    const r = gh(['api', `repos/{owner}/{repo}/branches/${target}/protection`]);
+    if (!r.error) facts.protection = true;
+    else if (/not protected/i.test(`${r.error.stdout || ''}${r.error.stderr || ''}`)) facts.protection = false;
+  }
+  if (facts.issues === null && facts.prs === null && facts.protection === null) unavailable.push('gh');
+  return facts;
+}
+
+// Brownfield when there is history and code, or CI, or something that deploys.
+function classify(facts) {
+  const reasons = [];
+  const commits = facts.commits || 0, sourceFiles = facts.sourceFiles || 0;
+  const ci = facts.ci || [], deploy = facts.deploy || [];
+  const history = facts.git !== false && commits >= 5 && sourceFiles >= 1;
+  if (history) reasons.push(`${plural(commits, 'commit')} and ${plural(sourceFiles, 'source file')}: there is history and code to respect.`);
+  if (ci.length) reasons.push(`CI is configured (${ci.join(', ')}).`);
+  if (deploy.length) reasons.push(`Something deploys (${deploy.join(', ')}): a running system to respect.`);
+  if (history || ci.length || deploy.length) return { kind: 'brownfield', reasons };
+  if (facts.git === false) reasons.push(sourceFiles ? `Not a git repository: ${plural(sourceFiles, 'source file')} but no history to respect.` : 'Not a git repository: no history to respect.');
+  else if (commits < 5) reasons.push(`${plural(commits, 'commit')} and ${plural(sourceFiles, 'source file')}: the first real job is also the first trace.`);
+  else reasons.push(`${plural(commits, 'commit')} but no source files: there is no code to respect yet.`);
+  reasons.push('No CI or deploy configuration.');
+  return { kind: 'greenfield', reasons };
+}
+
+// The answers recon can fill in before the interview; the developer confirms each.
+function prefill(facts, kind) {
+  const out = {
+    project: { name: facts.name, kind },
+    systems: { forge: facts.forge === 'github' ? 'github' : facts.remote ? 'other' : 'none', ci: facts.ci.length > 0 },
+    repo: {},
+  };
+  if (facts.remote) out.systems.remote = facts.remote;
+  if (facts.mergeStyle === 'merge') out.repo.merge = 'merge';
+  if (facts.gh.prs > 0) out.repo.pr = true;
+  if (facts.tests.runner) out.repo.checks = [facts.tests.runner];
+  return out;
+}
+
+function recon(root, { network = false } = {}) {
+  const unavailable = [];
+  const git = gitFacts(root, unavailable);
+  const code = codeFacts(root);
+  const { name, ...rest } = code;
+  const facts = { ...git, ...rest, gh: ghFacts(root, git.branch, network, unavailable) };
+  const { kind, reasons } = classify(facts);
+  return { kind, reasons, facts, prefill: prefill({ ...facts, name }, kind), unavailable };
+}
+
+function render(result) {
+  const lines = [result.kind, ...result.reasons.map((r) => `- ${r}`)];
+  if (result.unavailable.length) lines.push(`could not see: ${result.unavailable.join(', ')}`);
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = { recon, classify, prefill, render, stripUserinfo: util.stripUserinfo, walk, SKIP_DIRS, LANGUAGES };