pincer-workflow 0.6.0 → 1.0.0

package/template/scripts/pincer/cli.cjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+'use strict';
+// PINCER engine — argv dispatch for the entry points (docs/engine.md,
+// "Commands and exit codes"). Exit codes: 0 ok, 1 refused, 2 usage,
+// 3 no agreement or stage off, 130 interrupted.
+const fs = require('node:fs');
+const path = require('node:path');
+const util = require('./util.cjs');
+const harness = require('./harness.cjs');
+const ticket = require('./ticket.cjs');
+const status = require('./status.cjs');
+const evidence = require('./evidence.cjs');
+const recon = require('./recon.cjs');
+const writer = require('./blueprint.cjs');
+const generate = require('./generate.cjs');
+
+const USAGE = `usage: node scripts/pincer/cli.cjs [--root <dir>] <command> ...
+  ticket <start|verify|done|accept> <T-NN> [--by "<name>" --words "<what they said>"]
+  status [--json] [--stage <name>]
+  evidence validate <manifest> [--candidate <sha>] | digest <file>...
+  recon [--json] [--network]
+  write [--answers <file>]
+  generate [--harness <file>] [--platform <claude,codex,copilot|all>] [--overwrite]
+`;
+const GENERATE_USAGE = `usage: scripts/sync-prompts.sh [--harness <file>] [--platform <claude,codex,copilot|all>] [--overwrite]
+`;
+const BLUEPRINT_USAGE = `usage: scripts/pincer-blueprint.cjs recon [--json] [--network]
+       scripts/pincer-blueprint.cjs write [--answers <file>]
+       scripts/pincer-blueprint.cjs generate [--harness <file>] [--platform <list>] [--overwrite]
+`;
+const BLUEPRINT_VERBS = ['recon', 'write', 'generate'];
+const EVIDENCE_USAGE = `usage: scripts/pincer-evidence.cjs validate <manifest> [--candidate <sha>]
+       scripts/pincer-evidence.cjs digest <file>...
+`;
+const STATUS_USAGE = `usage: scripts/pincer-status.sh [--json] [--stage <name>]
+`;
+const TICKET_USAGE = `usage: scripts/pincer-ticket.sh <verb> <T-NN>
+  start  T-NN                                     open -> in_progress
+  verify T-NN                                     run the Verification block, stamp the receipt
+  done   T-NN                                     close on a current passing check, all criteria ticked
+  accept T-NN --by "<name>" --words "<their words>"   record the person's acceptance
+`;
+const TICKET_VERBS = ['start', 'verify', 'done', 'accept'];
+
+// The project root: --root, else the nearest directory from the working
+// directory up that holds harness.json, else the working directory.
+function resolveRoot(argv) {
+  const args = [];
+  let root = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root') { root = argv[++i]; if (root === undefined) return { problem: '--root needs a directory' }; }
+    else if (argv[i].startsWith('--root=')) root = argv[i].slice('--root='.length);
+    else args.push(argv[i]);
+  }
+  if (root !== null) return { root: path.resolve(root), args };
+  let dir = process.cwd();
+  for (;;) {
+    if (fs.existsSync(path.join(dir, harness.HARNESS_FILE))) return { root: dir, args };
+    const parent = path.dirname(dir);
+    if (parent === dir) return { root: process.cwd(), args };
+    dir = parent;
+  }
+}
+
+// --name value pairs; unknown flags and bare words are usage problems.
+function flags(rest, allowed) {
+  const out = {};
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    const eq = arg.startsWith('--') ? arg.indexOf('=') : -1;
+    const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+    if (!arg.startsWith('--') || !allowed.includes(name)) return { problem: `unexpected argument ${arg}` };
+    const value = eq === -1 ? rest[++i] : arg.slice(eq + 1);
+    if (value === undefined) return { problem: `--${name} needs a value` };
+    out[name] = value;
+  }
+  return out;
+}
+
+async function ticketCommand(root, args, io) {
+  const [verb, id, ...rest] = args;
+  if (!TICKET_VERBS.includes(verb) || !id) { io.err(TICKET_USAGE); return ticket.EXIT.USAGE; }
+  const options = flags(rest, verb === 'accept' ? ['by', 'words'] : []);
+  if (options.problem) { io.err(`pincer-ticket: ${options.problem}\n${TICKET_USAGE}`); return ticket.EXIT.USAGE; }
+  if (verb === 'accept' && (!('by' in options) || !('words' in options))) { io.err(`pincer-ticket: accept needs --by and --words\n${TICKET_USAGE}`); return ticket.EXIT.USAGE; }
+  if (verb === 'start') { const r = ticket.start(root, id); io.out(r.out); return r.exit; }
+  if (verb === 'accept') { const r = ticket.accept(root, id, options); io.out(r.out); return r.exit; }
+  return (await ticket[verb](root, id, io)).exit;
+}
+
+function statusCommand(root, args, io) {
+  let json = false, stage = null;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') json = true;
+    else if (arg === '--stage') { stage = args[++i]; if (stage === undefined) { io.err(STATUS_USAGE); return 2; } }
+    else if (arg.startsWith('--stage=')) stage = arg.slice('--stage='.length);
+    else { io.err(`pincer-status: unexpected argument ${arg}\n${STATUS_USAGE}`); return 2; }
+  }
+  if (stage !== null) {
+    const gate = status.stageGate(root, stage);
+    (gate.exit === 0 ? io.out : io.err)(`${gate.message}\n`);
+    return gate.exit;
+  }
+  const report = status.gather(root);
+  io.out(json ? `${JSON.stringify(report, null, 2)}\n` : status.render(report));
+  if (report.harnessProblem) { io.err(`${harness.HARNESS_FILE}: ${report.harnessProblem}\n`); return 3; }
+  return 0;
+}
+
+// Paths typed on the command line resolve against the working directory.
+const fromCwd = (file) => (path.isAbsolute(file) ? file : path.resolve(process.cwd(), file));
+
+function evidenceCommand(root, args, io) {
+  const [verb, ...rest] = args;
+  if (verb === 'validate' && rest.length) {
+    const [file, ...more] = rest;
+    const options = flags(more, ['candidate']);
+    if (options.problem) { io.err(`pincer-evidence: ${options.problem}\n${EVIDENCE_USAGE}`); return 2; }
+    const abs = fromCwd(file);
+    const problems = evidence.validate(root, abs, { candidate: options.candidate });
+    if (problems.length) { for (const p of problems) io.err(`evidence: ${file}: ${p}\n`); return 1; }
+    io.out(`ok ${util.readJson(abs).candidate}\n`);
+    return 0;
+  }
+  if (verb === 'digest' && rest.length) {
+    let failed = false;
+    for (const file of rest) {
+      try { io.out(`${evidence.digestFile(fromCwd(file))}  ${file}\n`); } catch (error) { io.err(`evidence: ${file}: ${error.message}\n`); failed = true; }
+    }
+    return failed ? 1 : 0;
+  }
+  io.err(EVIDENCE_USAGE);
+  return 2;
+}
+
+function reconCommand(root, args, io) {
+  let json = false, network = false;
+  for (const arg of args) {
+    if (arg === '--json') json = true;
+    else if (arg === '--network') network = true;
+    else { io.err(`pincer-blueprint: unexpected argument ${arg}\n${BLUEPRINT_USAGE}`); return 2; }
+  }
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) { io.err(`pincer-blueprint: ${root} is not a directory\n`); return 1; }
+  const result = recon.recon(root, { network });
+  io.out(json ? `${JSON.stringify(result, null, 2)}\n` : recon.render(result));
+  return 0;
+}
+
+// write: answers (default harness.json itself) -> harness.json, the agreement
+// in AGENTS.md, the project copies. Problems go to stderr, one per line.
+function writeCommand(root, args, io) {
+  const options = flags(args, ['answers']);
+  if (options.problem) { io.err(`pincer-blueprint: ${options.problem}\n${BLUEPRINT_USAGE}`); return 2; }
+  const given = options.answers;
+  const result = writer.write(root, given === undefined ? {} : { answers: fromCwd(given), label: given });
+  if (!result.ok) { for (const p of result.problems) io.err(`pincer-blueprint: ${p}\n`); return result.exit; }
+  for (const file of result.written) io.out(`wrote ${file}\n`);
+  reportGenerated(result.generated, io, 'pincer-blueprint');
+  return 0;
+}
+
+// What the library or its table could not provide, as one sentence.
+function missingText(name) {
+  if (name === 'models.json') return 'library has no models.json; run npx pincer-workflow update';
+  if (name.startsWith('models.json:')) return `${name} — fix the library table; after an update the upstream copy is beside it as models.json.new`;
+  if (name.startsWith('models/')) { const [platform, tier] = name.slice('models/'.length).split('/'); return `library table has no ${platform} value for tier ${tier}; set models.map.${platform}.${tier} in harness.json`; }
+  if (name.startsWith('agents/')) return `library has no agent ${name.slice('agents/'.length)}`;
+  return `library has no stage ${name}`;
+}
+// The generator's report as lines: what was written, kept (with or without a
+// sidecar), removed, and what the library or the manifest could not provide.
+function reportGenerated(report, io, who) {
+  for (const file of report.written) io.out(`wrote ${file}\n`);
+  for (const file of report.conflicted) io.out(`kept ${file} (edited; fresh copy in ${file}.new)\n`);
+  for (const file of report.retained) io.out(`kept ${file} (edited; not removed)\n`);
+  for (const file of report.removed) io.out(`removed ${file}\n`);
+  for (const name of report.missing) io.err(`${who}: warning: ${missingText(name)}\n`);
+  for (const rel of report.unsafe) io.err(`${who}: warning: ignored unsafe baseline path ${rel} in ${generate.MANIFEST}\n`);
+}
+
+// generate: the project copies, Codex skills and Copilot prompts from the
+// library and the agreement; edited copies are kept and get a .new sidecar.
+function generateCommand(root, args, io) {
+  let overwrite = false;
+  const rest = args.filter((arg) => { if (arg === '--overwrite') { overwrite = true; return false; } return true; });
+  const options = flags(rest, ['harness', 'platform']);
+  if (options.problem) { io.err(`pincer-generate: ${options.problem}\n${GENERATE_USAGE}`); return 2; }
+  let platforms;
+  if (options.platform !== undefined) {
+    platforms = options.platform === 'all' ? [...generate.PLATFORMS] : options.platform.split(',').map((p) => p.trim()).filter(Boolean);
+    if (!platforms.length || platforms.some((p) => !generate.PLATFORMS.includes(p))) { io.err(`pincer-generate: --platform takes ${generate.PLATFORMS.join(', ')} or all\n${GENERATE_USAGE}`); return 2; }
+  }
+  const loaded = harness.load(root, options.harness === undefined ? undefined : fromCwd(options.harness));
+  if (!loaded.ok) { io.err(`${options.harness === undefined ? harness.HARNESS_FILE : options.harness}: ${loaded.message}\n`); return 3; }
+  const report = generate.generate(root, { harness: loaded.harness, platforms, overwrite });
+  reportGenerated(report, io, 'pincer-generate');
+  io.out(`generated: ${report.written.length} written, ${report.skipped.length} unchanged, ${report.conflicted.length + report.retained.length} kept, ${report.removed.length} removed\n`);
+  return 0;
+}
+
+// scripts/pincer-blueprint.cjs: the blueprint verbs only, same root rules.
+async function blueprint(argv = process.argv.slice(2), io = { out: util.out, err: util.err }) {
+  const resolved = resolveRoot(argv);
+  if (resolved.problem || !BLUEPRINT_VERBS.includes(resolved.args[0])) { io.err(BLUEPRINT_USAGE); return 2; }
+  return main(argv, io);
+}
+
+async function main(argv = process.argv.slice(2), io = { out: util.out, err: util.err }) {
+  const resolved = resolveRoot(argv);
+  if (resolved.problem) { io.err(`pincer: ${resolved.problem}\n${USAGE}`); return 2; }
+  const { root, args } = resolved;
+  const [command, ...rest] = args;
+  try {
+    if (command === 'ticket') return await ticketCommand(root, rest, io);
+    if (command === 'status') return statusCommand(root, rest, io);
+    if (command === 'evidence') return evidenceCommand(root, rest, io);
+    if (command === 'recon') return reconCommand(root, rest, io);
+    if (command === 'write') return writeCommand(root, rest, io);
+    if (command === 'generate') return generateCommand(root, rest, io);
+    io.err(USAGE);
+    return 2;
+  } catch (error) {
+    if (error instanceof ticket.Refusal) { io.err(`${error.prefix ? `${error.prefix}: ` : ''}${error.message}\n`); return error.exit; }
+    io.err(`pincer: ${error.message}\n`);
+    if (process.env.PINCER_DEBUG) io.err(`${error.stack}\n`);
+    return 1;
+  }
+}
+
+if (require.main === module) main().then((code) => { process.exitCode = code; });
+
+module.exports = { main, blueprint, resolveRoot, flags, USAGE, TICKET_USAGE, STATUS_USAGE, EVIDENCE_USAGE, BLUEPRINT_USAGE, GENERATE_USAGE };

package/template/scripts/pincer/evidence.cjs

@@ -0,0 +1,142 @@
+'use strict';
+// PINCER engine — the evidence manifest, schema 1 (docs/engine.md, "Evidence
+// manifest schema 1"): which checks ran for a candidate, with their logs, and
+// the digests that prove the logs are the ones recorded. Validation reads the
+// manifest's directory and the spec it names; it never runs a check.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const SCHEMA = 1;
+const HEX40 = /^[0-9a-f]{40}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+const CHECK_ID = /^C-[0-9]{2,6}$/;
+const TOP_KEYS = ['schema', 'candidate', 'base', 'created', 'spec', 'environment', 'checks', 'visual_review', 'artifacts'];
+const ENV_KEYS = ['tools', 'limitations'];
+const CHECK_KEYS = ['id', 'kind', 'required', 'result', 'command', 'log', 'note'];
+const VISUAL_KEYS = ['applicable', 'reason'];
+const KINDS = ['command', 'review', 'visual'];
+const RESULTS = ['passed', 'failed', 'unverified'];
+const MAX_TEXT = 2000; // guard against pasted environment dumps
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const shortText = (v) => typeof v === 'string' && v.length <= MAX_TEXT;
+const nonempty = (v) => shortText(v) && v.trim() !== '';
+
+const digestFile = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+// Why a relative POSIX path is unsafe, or null when it is acceptable.
+function unsafePath(p) {
+  if (p.startsWith('/')) return 'absolute paths are not allowed';
+  if (/^[A-Za-z]:/.test(p)) return 'drive-letter paths are not allowed';
+  if (p.includes('\\')) return 'backslashes are not allowed; use relative POSIX paths';
+  if (p.split('/').some((s) => s === '' || s === '.' || s === '..')) return 'path must be normalized and relative (no "..", "." or empty segments)';
+  return null;
+}
+// Is `p`, relative to `dir`, inside `dir`?
+function inside(dir, p) {
+  if (p.startsWith('/') || /^[A-Za-z]:/.test(p)) return false;
+  const target = path.resolve(dir, p);
+  return target.startsWith(dir + path.sep);
+}
+
+// Every problem with the manifest at manifestPath (absolute, or relative to
+// root); [] when it is valid. `candidate`, when given, must equal the
+// manifest's.
+function validate(root, manifestPath, { candidate } = {}) {
+  const abs = path.isAbsolute(manifestPath) ? manifestPath : path.join(root, manifestPath);
+  const dir = path.dirname(abs);
+  let raw;
+  try { raw = fs.readFileSync(abs, 'utf8'); } catch (error) {
+    return [error.code === 'ENOENT' ? 'manifest does not exist — run /pincer-evaluate to write evidence for this candidate' : `cannot read the manifest (${error.message})`];
+  }
+  let doc;
+  try { doc = JSON.parse(raw); } catch (error) { return [`malformed JSON (${error.message})`]; }
+  if (!isObject(doc)) return ['the manifest must be a JSON object'];
+  if (doc.schema !== SCHEMA) return [`unknown evidence schema ${JSON.stringify(doc.schema)} — this engine validates schema ${SCHEMA}`];
+
+  const problems = [];
+  const problem = (message) => problems.push(message);
+  for (const key of Object.keys(doc)) if (!TOP_KEYS.includes(key)) problem(`unknown top-level key "${key}"`);
+  for (const key of TOP_KEYS) if (!(key in doc)) problem(`missing "${key}"`);
+
+  // The candidate: a commit, the directory the manifest sits in, and the one asked for.
+  const candidateOk = typeof doc.candidate === 'string' && HEX40.test(doc.candidate);
+  if (!candidateOk) problem('candidate must be a full 40-hex commit ID');
+  else if (path.basename(dir) !== doc.candidate) problem(`candidate ${doc.candidate} is not the manifest's directory name (${path.basename(dir)}) — the manifest lives at <evidence home>/<candidate>/manifest.json`);
+  if (candidateOk && candidate && doc.candidate !== candidate) problem(`candidate ${doc.candidate} is not the expected candidate ${candidate}`);
+  if (typeof doc.base !== 'string' || !HEX40.test(doc.base)) problem('base must be a full 40-hex commit ID');
+  if (typeof doc.created !== 'string' || !ISO_UTC.test(doc.created)) problem('created must be an ISO UTC timestamp (YYYY-MM-DDTHH:MM:SSZ)');
+
+  // The spec, when the agreement has one.
+  if (doc.spec !== null && doc.spec !== undefined) {
+    if (!nonempty(doc.spec)) problem('spec must be a repository-relative path or null');
+    else {
+      const why = unsafePath(doc.spec);
+      if (why) problem(`spec ${doc.spec}: ${why}`);
+      else if (!fs.existsSync(path.join(root, doc.spec))) problem(`spec ${doc.spec} does not exist`);
+    }
+  }
+
+  if (!isObject(doc.environment)) problem('environment must be an object {tools, limitations}');
+  else {
+    for (const key of ENV_KEYS) if (!Array.isArray(doc.environment[key]) || !doc.environment[key].every(shortText)) problem(`environment.${key} must be a list of strings`);
+    for (const key of Object.keys(doc.environment)) if (!ENV_KEYS.includes(key)) problem(`environment.${key} is not allowed`);
+  }
+
+  // Artifacts: regular files inside the manifest's directory with matching digests.
+  const artifacts = new Set();
+  if (!isObject(doc.artifacts)) problem('artifacts must be an object {<path>: <sha256>} of files inside the evidence directory');
+  else {
+    for (const [p, digest] of Object.entries(doc.artifacts)) {
+      if (!inside(dir, p)) { problem(`artifact ${p}: outside the evidence directory ${path.basename(dir)}/`); continue; }
+      const why = unsafePath(p);
+      if (why) { problem(`artifact ${p}: ${why}`); continue; }
+      if (p === 'manifest.json') { problem('artifact manifest.json: the manifest cannot list itself'); continue; }
+      artifacts.add(p);
+      if (typeof digest !== 'string' || !SHA256.test(digest)) { problem(`artifact ${p}: sha256 must be a full 64-hex digest`); continue; }
+      const target = path.join(dir, p);
+      let stat;
+      try { stat = fs.statSync(target); } catch { problem(`artifact ${p}: missing — no such file under the evidence directory`); continue; }
+      if (!stat.isFile()) { problem(`artifact ${p}: not a regular file`); continue; }
+      if (digestFile(target) !== digest) problem(`artifact ${p}: digest mismatch — the file changed after the evidence was recorded`);
+    }
+  }
+
+  // Checks: C-NN ids, a kind, a result, a command for command checks, a listed log; required ones passed.
+  if (!Array.isArray(doc.checks) || doc.checks.length === 0) problem('checks must be a non-empty array');
+  else {
+    const ids = new Set();
+    doc.checks.forEach((check, index) => {
+      const name = isObject(check) && typeof check.id === 'string' ? check.id : `#${index + 1}`;
+      if (!isObject(check)) { problem(`check ${name}: must be an object`); return; }
+      for (const key of Object.keys(check)) if (!CHECK_KEYS.includes(key)) problem(`check ${name}: key "${key}" is not allowed`);
+      if (typeof check.id !== 'string' || !CHECK_ID.test(check.id)) problem(`check ${name}: id must be C-NN`);
+      else if (ids.has(check.id)) problem(`duplicate check id ${check.id}`);
+      else ids.add(check.id);
+      if (!KINDS.includes(check.kind)) problem(`check ${name}: kind must be ${KINDS.join(', ')}`);
+      if (typeof check.required !== 'boolean') problem(`check ${name}: required must be true or false`);
+      if (!RESULTS.includes(check.result)) problem(`check ${name}: result must be ${RESULTS.join(', ')}`);
+      if (check.kind === 'command') { if (!nonempty(check.command)) problem(`check ${name}: command must be the command line a command check ran`); }
+      else if (!(check.command === null || check.command === undefined || shortText(check.command))) problem(`check ${name}: command must be a string or null`);
+      if (check.log !== null && check.log !== undefined) {
+        if (!nonempty(check.log)) problem(`check ${name}: log must be a path inside the evidence directory, or null`);
+        else if (!artifacts.has(check.log)) problem(`check ${name}: log ${check.log} is not listed in artifacts`);
+      }
+      if ('note' in check && !shortText(check.note)) problem(`check ${name}: note must be a short string`);
+      if (check.required === true && check.result !== 'passed') problem(`required check ${name} is ${check.result} — the candidate is not ready until it passes`);
+    });
+  }
+
+  if (!isObject(doc.visual_review)) problem('visual_review must be an object {applicable, reason?}');
+  else {
+    const visual = doc.visual_review;
+    for (const key of Object.keys(visual)) if (!VISUAL_KEYS.includes(key)) problem(`visual_review.${key} is not allowed`);
+    if (typeof visual.applicable !== 'boolean') problem('visual_review.applicable must be true or false');
+    else if (visual.applicable === false && !nonempty(visual.reason)) problem('visual_review.reason is required when visual review is not applicable (say why)');
+  }
+  return problems;
+}
+
+module.exports = { SCHEMA, validate, digestFile, unsafePath };