@pareto4/pp-core 1.21.1 → 1.23.1

package/scripts/live-runs/scrub.cjs

@@ -0,0 +1,291 @@
+'use strict';
+
+/**
+ * scrub.cjs - Phase 44 REACH-02 evidence scrub (D-11, Pitfall 6).
+ *
+ * A raw transcript carries the operator's home path, the scratch project's temp
+ * path, the user and host names, the operator's git identity, secret env values,
+ * account utilisation (`rate_limit_event`), account-linked ids (session, uuid,
+ * request) and credential, socket and memory-path fields. Everything goes through
+ * here before it is written to a path git will commit.
+ *
+ * Secrets have one shape: { paths: [{ value, token }], words: [{ value, token }] }.
+ * A path is replaced wherever it appears (its JSON-escaped form too), a word only
+ * where it is not part of a longer word. The replacement is one pass, so a token is
+ * never scrubbed again. `hostSecrets` builds the shape from the real machine; tests
+ * pass planted values instead.
+ */
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+const DROP_EVENT_TYPES = Object.freeze(['rate_limit_event']);
+const DROP_KEYS = Object.freeze(['credential_expires_at', 'messaging_socket_path', 'memory_paths']);
+const REDACT_KEYS = Object.freeze(['signature', 'request_id']);
+
+/**
+ * Account-linked ids that tie the evidence to the operator's account. Each distinct value
+ * becomes a stable placeholder (`<session-1>`, `<uuid-3>`), so links inside one transcript
+ * survive while the real ids do not.
+ */
+const PSEUDONYM_KEYS = Object.freeze({ session_id: 'session', uuid: 'uuid' });
+
+/** The throwaway identity the scratch repos commit under (driver.cjs GIT_IDENTITY): never a secret. */
+const THROWAWAY_IDENTITY = Object.freeze(['Live Run', 'live-run@example.invalid']);
+
+const MIN_SECRET_LENGTH = 3;
+const REMOVED = '<removed>';
+
+/** Env keys whose values are treated as secrets wherever they appear (a command's output included). */
+const SECRET_ENV_KEY_RE = /TOKEN|SECRET|KEY|PASSWORD|PASSWD|AUTH|CREDENTIAL/i;
+const MIN_ENV_SECRET_LENGTH = 8;
+
+/** The values of secret-looking env keys, as path-style secrets (replaced wherever they appear). */
+function envSecrets(env) {
+  const out = [];
+  for (const [key, value] of Object.entries(env || {})) {
+    if (!SECRET_ENV_KEY_RE.test(key) || typeof value !== 'string') continue;
+    const v = value.trim();
+    if (v.length >= MIN_ENV_SECRET_LENGTH) out.push({ value: v, token: '<secret>' });
+  }
+  return out;
+}
+
+function safeRealpath(p) {
+  try { return fs.realpathSync(p); } catch { return null; }
+}
+
+function quiet(command, args, { env, cwd } = {}) {
+  try {
+    return execFileSync(command, args, { env, cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 }).trim();
+  } catch {
+    return '';
+  }
+}
+
+/** `Name <email> 1700000000 +0100` -> { name, email }. */
+function parseIdent(ident) {
+  const m = /^(.*?)\s*<([^>]*)>/.exec(String(ident || ''));
+  return m ? { name: m[1].trim(), email: m[2].trim() } : { name: '', email: '' };
+}
+
+/**
+ * Every git name and email the operator's commits could carry: the global config with
+ * its include/includeIf files, the effective config in the repository, and git's own
+ * idea of the author and committer (which falls back to the implicit user@host identity
+ * when nothing is configured).
+ */
+function gitIdentities(env, repoRoot) {
+  const names = [];
+  const emails = [];
+  for (const cwd of [undefined, repoRoot]) {
+    const scope = cwd ? [] : ['--global'];
+    emails.push(quiet('git', ['config', ...scope, '--includes', '--get', 'user.email'], { env, cwd }));
+    names.push(quiet('git', ['config', ...scope, '--includes', '--get', 'user.name'], { env, cwd }));
+  }
+  for (const v of ['GIT_AUTHOR_IDENT', 'GIT_COMMITTER_IDENT']) {
+    const id = parseIdent(quiet('git', ['var', v], { env, cwd: repoRoot }));
+    names.push(id.name);
+    emails.push(id.email);
+  }
+  const keep = (list) => list.filter((v) => v && !THROWAWAY_IDENTITY.includes(v));
+  return { names: keep(names), emails: keep(emails) };
+}
+
+/** The host's names: os.hostname(), the fully qualified name, and the short form of each. */
+function hostNames(env) {
+  const full = [os.hostname(), quiet('hostname', ['-f'], { env })].filter(Boolean);
+  return [...full, ...full.map((h) => h.split('.')[0])];
+}
+
+/** Longest first, no duplicates, nothing shorter than 3 characters. */
+function tidy(entries) {
+  const seen = new Set();
+  const out = [];
+  for (const e of entries) {
+    if (typeof e.value !== 'string' || e.value.length < MIN_SECRET_LENGTH || seen.has(e.value)) continue;
+    seen.add(e.value);
+    out.push(e);
+  }
+  return out.sort((a, b) => b.value.length - a.value.length);
+}
+
+/**
+ * The secrets of this machine and this run: the operator's home, the scratch project,
+ * the person home, the temp root (each with its resolved real path), the values of
+ * secret-looking env keys (tokens, keys, passwords), the user and host names, and the
+ * global git email and name.
+ */
+function hostSecrets({ projectDir, personHome, extraPaths = [], env = process.env, repoRoot = REPO_ROOT } = {}) {
+  const pathEntries = [];
+  const addPath = (value, token) => {
+    if (!value) return;
+    pathEntries.push({ value, token });
+    const real = safeRealpath(value);
+    if (real && real !== value) pathEntries.push({ value: real, token });
+  };
+  addPath(projectDir, '<project>');
+  addPath(personHome, '<person-home>');
+  addPath(os.tmpdir(), '<tmp>');
+  addPath(env.HOME || os.homedir(), '~');
+  for (const extra of extraPaths) addPath(extra, '<removed>');
+  pathEntries.push(...envSecrets(env));
+
+  const wordEntries = [];
+  let user = '';
+  try { user = os.userInfo().username; } catch { /* no passwd entry: the user name stays unknown */ }
+  wordEntries.push({ value: user, token: '<user>' });
+  const hosts = hostNames(env);
+  for (const host of hosts) wordEntries.push({ value: host, token: '<host>' });
+  const { names, emails } = gitIdentities(env, repoRoot);
+  const shortHosts = new Set(hosts.map((h) => h.split('.')[0].toLowerCase()).filter((h) => h.length >= MIN_SECRET_LENGTH));
+  for (const email of emails) {
+    wordEntries.push({ value: email, token: '<email>' });
+    // An implicit identity is user@host.domain: its domain names the machine too.
+    const domain = email.includes('@') ? email.slice(email.lastIndexOf('@') + 1) : '';
+    if (domain && shortHosts.has(domain.split('.')[0].toLowerCase())) wordEntries.push({ value: domain, token: '<host>' });
+  }
+  for (const name of names) wordEntries.push({ value: name, token: '<git-name>' });
+
+  return { paths: tidy(pathEntries), words: tidy(wordEntries) };
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const jsonEscaped = (s) => JSON.stringify(s).slice(1, -1);
+
+function compile(secrets) {
+  const paths = (secrets && secrets.paths) || [];
+  const words = (secrets && secrets.words) || [];
+  const tokenOf = new Map();
+  const alternatives = [];
+  for (const w of words) {
+    tokenOf.set(w.value.toLowerCase(), w.token);
+    alternatives.push({ length: w.value.length, source: `(?<![A-Za-z0-9_])${escapeRe(w.value)}(?![A-Za-z0-9_])` });
+  }
+  for (const p of paths) {
+    for (const form of new Set([p.value, jsonEscaped(p.value)])) {
+      tokenOf.set(form.toLowerCase(), p.token);
+      alternatives.push({ length: form.length, source: escapeRe(form) });
+    }
+  }
+  if (alternatives.length === 0) return null;
+  alternatives.sort((a, b) => b.length - a.length);
+  return { re: new RegExp(alternatives.map((a) => a.source).join('|'), 'gi'), tokenOf };
+}
+
+/** Replace every secret in a string with its token, in one pass. */
+function scrubText(text, secrets) {
+  const compiled = compile(secrets);
+  if (!compiled) return String(text);
+  return String(text).replace(compiled.re, (m) => compiled.tokenOf.get(m.toLowerCase()) || REMOVED);
+}
+
+/** The stable placeholder for one account-linked id; `pseudo` maps kind -> (value -> placeholder). */
+function pseudonym(pseudo, kind, value) {
+  if (!pseudo.has(kind)) pseudo.set(kind, new Map());
+  const seen = pseudo.get(kind);
+  if (!seen.has(value)) seen.set(value, `<${kind}-${seen.size + 1}>`);
+  return seen.get(value);
+}
+
+function scrubValue(value, compiled, pseudo) {
+  if (typeof value === 'string') return compiled ? value.replace(compiled.re, (m) => compiled.tokenOf.get(m.toLowerCase()) || REMOVED) : value;
+  if (Array.isArray(value)) return value.map((v) => scrubValue(v, compiled, pseudo));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+      if (DROP_KEYS.includes(key)) continue;
+      const safeKey = scrubValue(key, compiled, pseudo);
+      if (REDACT_KEYS.includes(key) && v !== undefined && v !== null) out[safeKey] = REMOVED;
+      else if (Object.hasOwn(PSEUDONYM_KEYS, key) && typeof v === 'string' && v !== '') out[safeKey] = pseudonym(pseudo, PSEUDONYM_KEYS[key], v);
+      else out[safeKey] = scrubValue(v, compiled, pseudo);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * A scrubbed deep copy of one event, or null for an event type that is dropped. The input
+ * is not changed. Pass the same `pseudo` map for every event of one transcript so an id
+ * gets the same placeholder throughout.
+ */
+function scrubEvent(event, secrets, pseudo = new Map()) {
+  if (event && typeof event === 'object' && DROP_EVENT_TYPES.includes(event.type)) return null;
+  return scrubValue(event, compile(secrets), pseudo);
+}
+
+/** A session id shorter than this is not scrubbed where it is embedded in other text. */
+const MIN_EMBEDDED_ID_LENGTH = 8;
+
+/** Every non-empty string `session_id` in one event, in the order scrubValue meets them. */
+function collectSessionIds(value, found) {
+  if (Array.isArray(value)) {
+    for (const v of value) collectSessionIds(v, found);
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  for (const [key, v] of Object.entries(value)) {
+    if (DROP_KEYS.includes(key)) continue;
+    if (key === 'session_id' && typeof v === 'string' && v !== '') found.push(v);
+    else if (!REDACT_KEYS.includes(key) || v === undefined || v === null) collectSessionIds(v, found);
+  }
+}
+
+/**
+ * Scrub a whole stream-json transcript line by line. A line that does not parse still goes
+ * through scrubText. The CLI also writes the session id into paths (tool results under
+ * `projects/<dir>/<session-id>/`, task output under `<tmp>/<dir>/<session-id>/tasks/`), so
+ * every session id is first collected and then replaced wherever it appears, with the same
+ * placeholder its `session_id` key gets.
+ */
+function scrubJsonl(text, secrets) {
+  const out = [];
+  const pseudo = new Map();
+  const lines = String(text).split('\n').filter((raw) => raw.trim() !== '').map((raw) => {
+    try {
+      return { raw, ok: true, event: JSON.parse(raw) };
+    } catch {
+      return { raw, ok: false, event: undefined };
+    }
+  });
+  const sessionIds = [];
+  for (const { ok, event } of lines) {
+    const dropped = event && typeof event === 'object' && DROP_EVENT_TYPES.includes(event.type);
+    if (ok && !dropped) collectSessionIds(event, sessionIds);
+  }
+  const embedded = [];
+  for (const sid of sessionIds) {
+    const token = pseudonym(pseudo, PSEUDONYM_KEYS.session_id, sid);
+    if (sid.length >= MIN_EMBEDDED_ID_LENGTH) embedded.push({ value: sid, token });
+  }
+  const all = embedded.length === 0
+    ? secrets
+    : { paths: [...((secrets && secrets.paths) || []), ...embedded], words: (secrets && secrets.words) || [] };
+  for (const { raw, ok, event } of lines) {
+    if (!ok) {
+      out.push(scrubText(raw, all));
+      continue;
+    }
+    const clean = scrubEvent(event, all, pseudo);
+    if (clean !== null) out.push(JSON.stringify(clean));
+  }
+  return out.length === 0 ? '' : `${out.join('\n')}\n`;
+}
+
+module.exports = {
+  DROP_EVENT_TYPES,
+  DROP_KEYS,
+  REDACT_KEYS,
+  PSEUDONYM_KEYS,
+  SECRET_ENV_KEY_RE,
+  envSecrets,
+  hostSecrets,
+  scrubText,
+  scrubEvent,
+  scrubJsonl,
+};

package/scripts/live-runs/turn-guard.cjs

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * turn-guard.cjs - Phase 44 process-group guard for one CLI turn (driver.cjs runTurn).
+ *
+ * `node turn-guard.cjs <wallMs> <graceMs> <command> [args...]` starts the command in a
+ * process group of its own and passes its stdout and stderr through. At wallMs it sends
+ * SIGTERM to the whole group, at wallMs + graceMs SIGKILL. When the command exits, what
+ * is left of its group (background shells, hook processes) is killed too, so nothing
+ * from a turn keeps running while the next attempt starts or holds the output pipe open.
+ *
+ * The command's group is not the terminal's foreground group, so Ctrl-C (SIGINT) and a
+ * SIGTERM or SIGHUP aimed at the harness would not reach it. The guard therefore
+ * forwards those signals: it sends SIGTERM to the group, and SIGKILL after a short
+ * grace (or at once on a second signal). It also checks every second that its parent
+ * is still alive. When the parent is gone (for example a SIGKILL of run.cjs), it kills
+ * the group, because nobody is left to read the turn's output or stop it.
+ *
+ * On fd 3 it writes one JSON line for the driver: { status, signal, timedOut, spawnError }.
+ * spawnError is 'interrupted' after a forwarded signal and 'parent_gone' when the parent
+ * died. The spawn is an argv array with no shell. On Windows there are no process
+ * groups, so only the command itself is killed.
+ */
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+
+const STATUS_FD = 3;
+const IS_WINDOWS = process.platform === 'win32';
+const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+const INTERRUPT_GRACE_MS = 2000;
+const PARENT_POLL_MS = 1000;
+
+const [wallRaw, graceRaw, command, ...args] = process.argv.slice(2);
+const wallMs = Number(wallRaw);
+const graceMs = Number(graceRaw);
+
+let child = null;
+let timedOut = false;
+let interrupted = null;
+let done = false;
+let parentWatch = null;
+const timers = [];
+
+function killGroup(signal) {
+  if (!child || child.pid === undefined) return;
+  try {
+    if (IS_WINDOWS) child.kill(signal);
+    else process.kill(-child.pid, signal);
+  } catch {
+    // the group is already gone
+  }
+}
+
+function finish(report) {
+  if (done) return;
+  done = true;
+  for (const t of timers) clearTimeout(t);
+  if (parentWatch) clearInterval(parentWatch);
+  killGroup('SIGKILL');
+  try {
+    fs.writeSync(STATUS_FD, `${JSON.stringify(report)}\n`);
+  } catch {
+    // no status channel: the driver falls back to this process's own exit
+  }
+  // The timers are cleared and the child is gone, so the guard ends as soon as this returns.
+  // After a forwarded signal it exits the way the shell reports a signal death (128 + n).
+  const signum = interrupted && os.constants.signals[interrupted];
+  if (signum) process.exitCode = 128 + signum;
+  else process.exitCode = Number.isInteger(report.status) ? report.status : 1;
+}
+
+/** Ctrl-C, SIGTERM or SIGHUP to the guard: stop the group, which the terminal cannot reach. */
+function onSignal(sig) {
+  if (done) return;
+  if (interrupted) {
+    // a second signal: do not wait out the grace
+    finish({ status: null, signal: sig, timedOut, spawnError: 'interrupted' });
+    return;
+  }
+  interrupted = sig;
+  killGroup('SIGTERM');
+  const graceLeft = Math.min(graceMs, INTERRUPT_GRACE_MS);
+  timers.push(setTimeout(() => finish({ status: null, signal: sig, timedOut, spawnError: 'interrupted' }), graceLeft));
+}
+
+if (!command || !Number.isFinite(wallMs) || !Number.isFinite(graceMs)) {
+  process.stderr.write('turn-guard: usage: turn-guard.cjs <wallMs> <graceMs> <command> [args...]\n');
+  finish({ status: 2, signal: null, timedOut: false, spawnError: 'usage' });
+} else {
+  const parentPid = process.ppid;
+  for (const sig of FORWARDED_SIGNALS) process.on(sig, onSignal);
+  child = spawn(command, args, { stdio: ['ignore', 'inherit', 'inherit'], detached: !IS_WINDOWS });
+  child.on('error', (err) => finish({ status: null, signal: null, timedOut, spawnError: err.code || err.message }));
+  child.on('exit', (status, signal) => finish({ status, signal, timedOut, spawnError: interrupted ? 'interrupted' : null }));
+  timers.push(setTimeout(() => {
+    timedOut = true;
+    killGroup('SIGTERM');
+  }, wallMs));
+  timers.push(setTimeout(() => killGroup('SIGKILL'), wallMs + graceMs));
+  // The child's handle keeps the guard alive; this poll must not.
+  parentWatch = setInterval(() => {
+    if (process.ppid !== parentPid) finish({ status: null, signal: null, timedOut, spawnError: 'parent_gone' });
+  }, PARENT_POLL_MS);
+  parentWatch.unref();
+}

package/scripts/live-runs/walk-setup.cjs

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * walk-setup.cjs - Phase 44 PROOF-02 walk project setup (D-13, D-15).
+ *
+ * `node scripts/live-runs/walk-setup.cjs --walk business|engineer [--first-run]`
+ * builds a walk's throwaway project from the same build and the same fixtures as
+ * the live runs (scripts/live-runs/scratch-project.cjs and scenarios.cjs), saves
+ * the walk's audience in a temp person home, and prints the exact lines that start
+ * the walk, including PP_AUDIENCE and GSD_HOME.
+ *
+ * It never calls a model. It never adds a remote: the engineer walk reaches
+ * /pp-ship, and the only repository that walk may push to is a throwaway sandbox
+ * the facilitator makes by hand (D-15). The two folders it makes are kept for the
+ * walk and deleted by the facilitator afterwards.
+ *
+ * Flags: --walk business|engineer (required), --first-run (no audience saved, no
+ * PP_AUDIENCE line: the Phase 39 first-run moment), --dir <path> (missing or
+ * empty), --json, --help. Exit codes: 0 ok, 1 setup failed, 2 usage.
+ */
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { REPO_ROOT, createScratchProject } = require('./scratch-project.cjs');
+const { SCENARIOS } = require('./scenarios.cjs');
+const { ExitError, runMain } = require('../lib/cli-exit.cjs');
+
+const EXIT = Object.freeze({ OK: 0, FAILED: 1, USAGE: 2 });
+
+const ENGINEER_README = 'Sandbox project for a pp-core walk. It is thrown away afterwards and is never pushed anywhere except a throwaway sandbox repository.\n';
+
+function engineerFixture(projectDir) {
+  fs.writeFileSync(path.join(projectDir, 'README.md'), ENGINEER_README);
+}
+
+const WALKS = Object.freeze({
+  business: Object.freeze({
+    id: 'business',
+    audience: 'business',
+    fixture: SCENARIOS.s1.fixture,
+    initialCommit: false,
+    commands: Object.freeze(['pp-help', 'pp-progress', 'pp-resume-work', 'pp-discovery']),
+  }),
+  engineer: Object.freeze({
+    id: 'engineer',
+    audience: 'engineer',
+    fixture: engineerFixture,
+    initialCommit: true,
+    commands: Object.freeze(['pp-init', 'pp-new-project', 'pp-plan-phase', 'pp-execute-phase', 'pp-verify-work', 'pp-ship']),
+  }),
+});
+
+const USAGE_TEXT = [
+  'usage: node scripts/live-runs/walk-setup.cjs --walk business|engineer [--first-run] [--dir PATH] [--json]',
+  '',
+  'options:',
+  '  --walk business|engineer   which walk to set up (required)',
+  '  --first-run                save no audience and print no PP_AUDIENCE line (the first-run moment)',
+  '  --dir PATH                 build the project here (the folder must be missing or empty)',
+  '  --json                     print the result as JSON',
+  '  --help                     show this text',
+  '',
+  'exit codes: 0 ok, 1 setup failed, 2 usage',
+].join('\n');
+
+function usageError(message) {
+  return new ExitError(EXIT.USAGE, message);
+}
+
+/** Fail-closed argument parsing: an unknown flag, a missing value or an unknown walk is a usage error. */
+function parseArgs(argv) {
+  const opts = { walk: null, firstRun: false, dir: null, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === '--walk' || flag === '--dir') {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('--') || value === '') throw usageError(`${flag} needs a value`);
+      if (flag === '--walk') opts.walk = value;
+      // Absolute, so the printed `cd` works from the new terminal window the walk starts in.
+      else opts.dir = path.resolve(value);
+      i++;
+    } else if (flag === '--first-run') {
+      opts.firstRun = true;
+    } else if (flag === '--json') {
+      opts.json = true;
+    } else if (flag === '--help') {
+      opts.help = true;
+    } else {
+      throw usageError(`unknown option: ${flag}`);
+    }
+  }
+  if (opts.help) return opts;
+  if (opts.walk === null) throw usageError('--walk is required (business or engineer)');
+  if (!Object.prototype.hasOwnProperty.call(WALKS, opts.walk)) {
+    throw usageError(`unknown walk: ${opts.walk} (use business or engineer)`);
+  }
+  return opts;
+}
+
+/** Single-quote a value for a shell line; a single quote inside it is written as '\'' . */
+const shellQuote = (value) => `'${String(value).replace(/'/g, "'\\''")}'`;
+
+function buildCommit() {
+  return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+/**
+ * Build one walk's throwaway project and return what the facilitator needs.
+ * The folders are kept: nothing here cleans them up.
+ */
+function setupWalk({ walk, firstRun = false, dir, repoRoot = REPO_ROOT } = {}) {
+  const def = Object.prototype.hasOwnProperty.call(WALKS, walk) ? WALKS[walk] : null;
+  if (!def) throw new Error(`setupWalk: unknown walk ${JSON.stringify(walk)}`);
+  const audience = firstRun ? null : def.audience;
+  const project = createScratchProject({
+    label: `walk-${def.id}`,
+    audience,
+    fixture: def.fixture,
+    initialCommit: def.initialCommit,
+    commands: [...def.commands],
+    repoRoot,
+    dir,
+  });
+  const start = [`cd ${shellQuote(project.projectDir)}`, `export GSD_HOME=${shellQuote(project.personHome)}`];
+  if (audience) start.push(`export PP_AUDIENCE=${audience}`);
+  start.push('claude --setting-sources project,local --strict-mcp-config');
+  return {
+    walk: def.id,
+    projectDir: project.projectDir,
+    personHome: project.personHome,
+    audience,
+    firstRun,
+    buildCommit: buildCommit(),
+    start,
+  };
+}
+
+function defaultIo() {
+  return {
+    out: (text) => process.stdout.write(`${text}\n`),
+    err: (text) => process.stderr.write(`${text}\n`),
+  };
+}
+
+function report(result) {
+  const lines = [
+    `Walk: ${result.walk}${result.firstRun ? ' (first run: no audience saved)' : ''}`,
+    `Project folder: ${result.projectDir}`,
+    `Person-home folder: ${result.personHome}`,
+    '',
+    'Start the walk in a normal terminal window:',
+    ...result.start.map((line) => `  ${line}`),
+    '',
+    `Build commit: ${result.buildCommit}`,
+    'After the walk, delete both folders.',
+  ];
+  return lines.join('\n');
+}
+
+function main(argv = process.argv.slice(2), env = process.env, io = {}) {
+  void env;
+  const writers = { ...defaultIo(), ...io };
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    if (!(err instanceof ExitError)) throw err;
+    writers.err(err.message);
+    writers.err(USAGE_TEXT);
+    return err.code;
+  }
+  if (opts.help) {
+    writers.out(USAGE_TEXT);
+    return EXIT.OK;
+  }
+  if (opts.dir && fs.existsSync(opts.dir)) {
+    const stat = fs.statSync(opts.dir);
+    if (!stat.isDirectory() || fs.readdirSync(opts.dir).length > 0) {
+      writers.err(`--dir ${opts.dir} must be a missing or empty folder; nothing was changed`);
+      return EXIT.USAGE;
+    }
+  }
+  let result;
+  try {
+    result = setupWalk({ walk: opts.walk, firstRun: opts.firstRun, dir: opts.dir || undefined });
+  } catch (err) {
+    writers.err(`walk setup failed: ${String(err && err.message ? err.message : err).split('\n')[0]}`);
+    return EXIT.FAILED;
+  }
+  writers.out(opts.json ? JSON.stringify(result, null, 2) : report(result));
+  return EXIT.OK;
+}
+
+module.exports = { WALKS, parseArgs, main, setupWalk };
+
+if (require.main === module) runMain(() => main(process.argv.slice(2), process.env));