@marcomigozzi/trailhead 0.14.0 → 0.16.0

package/plugins/trailhead/templates/trailhead-auto-run.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead auto run record (self-contained, ships in templates/ so it reaches
+// every install channel: bin/trailhead.js copies templates/ wholesale for
+// Claude/npm and Codex). Persists the start-up choices and the working lists of
+// an autonomous run in <repo>/.trailhead/auto-run.json, so a run survives a
+// context compaction (and a crash) without asking again. #295.
+// Written at the main checkout only, never in a slot workspace.
+//
+// CLI:
+//   node trailhead-auto-run.js start --repo <dir> --scope <s> --slots <n> --review <r> [--replace]
+//   node trailhead-auto-run.js read --repo <dir>
+//   node trailhead-auto-run.js skip --repo <dir> --ticket <n>
+//   node trailhead-auto-run.js unmerged --repo <dir> --ticket <n> --branch <b>
+//        [--file <path> ...] [--merge-ticket <n>]
+//   node trailhead-auto-run.js clear --repo <dir>
+// --repo defaults to cwd. File shape:
+//   { version: 1, scope, slots, review, session, skip: [<n>...],
+//     unmerged: [{ ticket, branch, files: [...], mergeTicket: <n>|null }],
+//     startedAt, updatedAt }
+// scope: map:<n> | whiteboard | everything (trailhead-auto-queue.js tokens).
+// slots: 1 to 4. review: config | 1 | 2 | 3 | until (plan-review-rounds
+// tokens) or skip (the ask was skipped). session: CLAUDE_CODE_SESSION_ID at
+// start (null when unset, as on Codex).
+// Prints one JSON line {"status","path","record"?,"sameSession"?,"message"?}.
+//   start:    written | exists (record on file, kept unless --replace) | skipped
+//   read:     found (+ sameSession) | absent | corrupt | skipped
+//   skip, unmerged: written | absent | corrupt | skipped
+//   clear:    cleared | absent | skipped
+// A corrupt file (unparseable, or an invalid version/scope/slots/review) is
+// reported and never rewritten except by `start --replace`; invalid list
+// entries (skip, unmerged) are dropped from an otherwise found record.
+// Exit 0 on every normal outcome and on any unexpected I/O error (it must never
+// block the run: status skipped with the message); exit 2 only on a usage or
+// validation error (nothing is written).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const STATE_DIR = '.trailhead';
+const STATE_FILE = 'auto-run.json';
+const VERSION = 1;
+const REVIEWS = ['config', '1', '2', '3', 'until', 'skip'];
+const SCOPE_RE = /^(map:[1-9]\d*|whiteboard|everything)$/;
+const COMMANDS = ['start', 'read', 'skip', 'unmerged', 'clear'];
+const FLAGS = {
+  start: ['--repo', '--scope', '--slots', '--review', '--replace'],
+  read: ['--repo'],
+  skip: ['--repo', '--ticket'],
+  unmerged: ['--repo', '--ticket', '--branch', '--file', '--merge-ticket'],
+  clear: ['--repo'],
+};
+
+const isPosInt = (v) => Number.isInteger(v) && v > 0;
+const isLine = (v) => typeof v === 'string' && v.trim() !== '' && !/[\u0000-\u001f\u007f]/.test(v);
+
+// Strict parse of a positive integer from a CLI string; null if invalid.
+function parsePosInt(text) {
+  return /^[1-9]\d*$/.test(text) ? Number(text) : null;
+}
+
+// Lista di ticket: solo interi positivi, senza doppioni, in ordine crescente.
+function cleanTickets(list) {
+  if (!Array.isArray(list)) return [];
+  return [...new Set(list.filter(isPosInt))].sort((a, b) => a - b);
+}
+
+// Una voce unmerged valida o null (la voce invalida viene scartata).
+function cleanUnmerged(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (!isPosInt(raw.ticket) || !isLine(raw.branch)) return null;
+  return {
+    ticket: raw.ticket,
+    branch: raw.branch.trim(),
+    files: Array.isArray(raw.files) ? raw.files.filter(isLine) : [],
+    mergeTicket: isPosInt(raw.mergeTicket) ? raw.mergeTicket : null,
+  };
+}
+
+// Una voce per ticket (l'ultima vince), in ordine di ticket.
+function cleanUnmergedList(list) {
+  if (!Array.isArray(list)) return [];
+  const byTicket = new Map();
+  for (const item of list) {
+    const entry = cleanUnmerged(item);
+    if (entry) byTicket.set(entry.ticket, entry);
+  }
+  return [...byTicket.values()].sort((a, b) => a.ticket - b.ticket);
+}
+
+// Normalizza un oggetto qualunque in un record. Un campo obbligatorio invalido
+// (version, scope, slots, review) rende il record corrotto: { error }.
+function sanitizeRecord(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return { error: 'not an object' };
+  if (raw.version !== VERSION) return { error: 'invalid version' };
+  if (typeof raw.scope !== 'string' || !SCOPE_RE.test(raw.scope)) return { error: 'invalid scope' };
+  if (!Number.isInteger(raw.slots) || raw.slots < 1 || raw.slots > 4) return { error: 'invalid slots' };
+  if (!REVIEWS.includes(raw.review)) return { error: 'invalid review' };
+  return {
+    record: {
+      version: VERSION,
+      scope: raw.scope,
+      slots: raw.slots,
+      review: raw.review,
+      session: typeof raw.session === 'string' && raw.session !== '' ? raw.session : null,
+      skip: cleanTickets(raw.skip),
+      unmerged: cleanUnmergedList(raw.unmerged),
+      startedAt: typeof raw.startedAt === 'string' ? raw.startedAt : null,
+      updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : null,
+    },
+  };
+}
+
+function parseArgs(argv) {
+  const command = argv[0];
+  if (!COMMANDS.includes(command)) {
+    return { error: `usage: expected one of ${COMMANDS.join(', ')}, got: ${command === undefined ? '(nothing)' : command}` };
+  }
+  const allowed = FLAGS[command];
+  const out = { command, repo: null, replace: false, files: [] };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!allowed.includes(flag)) return { error: `usage: unknown argument: ${flag}` };
+    if (flag === '--replace') { out.replace = true; continue; }
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    const value = argv[i];
+    if (flag === '--repo') out.repo = value;
+    else if (flag === '--scope') {
+      if (!SCOPE_RE.test(value)) return { error: `usage: --scope must be map:<n>, whiteboard or everything, got: ${value}` };
+      out.scope = value;
+    } else if (flag === '--slots') {
+      const n = parsePosInt(value);
+      if (n === null || n > 4) return { error: `usage: --slots must be 1 to 4, got: ${value}` };
+      out.slots = n;
+    } else if (flag === '--review') {
+      if (!REVIEWS.includes(value)) return { error: `usage: --review must be one of ${REVIEWS.join(', ')}, got: ${value}` };
+      out.review = value;
+    } else if (flag === '--ticket') {
+      if (parsePosInt(value) === null) return { error: `usage: --ticket must be a positive integer, got: ${value}` };
+      out.ticket = parsePosInt(value);
+    } else if (flag === '--merge-ticket') {
+      if (parsePosInt(value) === null) return { error: `usage: --merge-ticket must be a positive integer, got: ${value}` };
+      out.mergeTicket = parsePosInt(value);
+    } else if (flag === '--branch') {
+      if (!isLine(value)) return { error: 'usage: --branch must be a single non-empty line' };
+      out.branch = value.trim();
+    } else if (flag === '--file') {
+      if (!isLine(value)) return { error: 'usage: --file must be a single non-empty line' };
+      out.files.push(value);
+    }
+  }
+  const missing = { start: ['scope', 'slots', 'review'], skip: ['ticket'], unmerged: ['ticket', 'branch'] }[command] || [];
+  for (const key of missing) {
+    if (out[key] === undefined) return { error: `usage: ${command} needs --${key}` };
+  }
+  return out;
+}
+
+// Legge il file: { status: 'absent' } | { status: 'corrupt', message } | { status: 'found', record }.
+// Un errore di I/O (non di parsing) risale al chiamante, che risponde skipped.
+function readFile(file, fsMod) {
+  if (!fsMod.existsSync(file)) return { status: 'absent' };
+  const text = fsMod.readFileSync(file, 'utf8');
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return { status: 'corrupt', message: 'unparseable: ' + err.message };
+  }
+  const s = sanitizeRecord(raw);
+  return s.error ? { status: 'corrupt', message: s.error } : { status: 'found', record: s.record };
+}
+
+// Scrittura atomica: temp univoco nella stessa cartella, poi rename sul file;
+// il temp viene rimosso se qualcosa fallisce.
+function writeAtomic(dir, file, text, fsMod) {
+  fsMod.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.${STATE_FILE}.${process.pid}-${crypto.randomBytes(4).toString('hex')}.tmp`);
+  try {
+    fsMod.writeFileSync(tmp, text);
+    fsMod.renameSync(tmp, file);
+  } catch (err) {
+    try { fsMod.unlinkSync(tmp); } catch { /* pulizia best effort */ }
+    throw err;
+  }
+}
+
+function writeResult(stdout, result) {
+  stdout.write(JSON.stringify(result) + '\n');
+}
+
+function main(argv, { cwd, stdout, stderr, env, fs: fsMod, now } = {}) {
+  const cwd_ = cwd || process.cwd();
+  const out = stdout || process.stdout;
+  const err_ = stderr || process.stderr;
+  const env_ = env || process.env;
+  const fs_ = fsMod || fs;
+
+  const parsed = parseArgs(argv || []);
+  if (parsed.error) {
+    err_.write(parsed.error + '\n');
+    return 2;
+  }
+
+  const repoDir = parsed.repo ? path.resolve(cwd_, parsed.repo) : cwd_;
+  const dir = path.join(repoDir, STATE_DIR);
+  const file = path.join(dir, STATE_FILE);
+  const stamp = (now || new Date()).toISOString();
+  const save = (record) => writeAtomic(dir, file, JSON.stringify(record, null, 2) + '\n', fs_);
+
+  try {
+    if (parsed.command === 'clear') {
+      if (!fs_.existsSync(file)) {
+        writeResult(out, { status: 'absent', path: file });
+        return 0;
+      }
+      fs_.unlinkSync(file);
+      writeResult(out, { status: 'cleared', path: file });
+      return 0;
+    }
+
+    const sessionEnv = env_.CLAUDE_CODE_SESSION_ID;
+    const session = typeof sessionEnv === 'string' && sessionEnv !== '' ? sessionEnv : null;
+    const existing = readFile(file, fs_);
+
+    if (parsed.command === 'read') {
+      if (existing.status !== 'found') {
+        const result = { status: existing.status, path: file };
+        if (existing.message) result.message = existing.message;
+        writeResult(out, result);
+        return 0;
+      }
+      const sameSession = session !== null && existing.record.session !== null && existing.record.session === session;
+      writeResult(out, { status: 'found', path: file, record: existing.record, sameSession });
+      return 0;
+    }
+
+    if (parsed.command === 'start') {
+      if (existing.status !== 'absent' && !parsed.replace) {
+        // Un record corrotto non si sovrascrive in silenzio: serve --replace.
+        writeResult(out, { status: 'exists', path: file, record: existing.record || null, ...(existing.message ? { message: existing.message } : {}) });
+        return 0;
+      }
+      const record = {
+        version: VERSION,
+        scope: parsed.scope,
+        slots: parsed.slots,
+        review: parsed.review,
+        session,
+        skip: [],
+        unmerged: [],
+        startedAt: stamp,
+        updatedAt: stamp,
+      };
+      save(record);
+      writeResult(out, { status: 'written', path: file, record });
+      return 0;
+    }
+
+    // skip / unmerged: servono un record leggibile.
+    if (existing.status !== 'found') {
+      const result = { status: existing.status, path: file };
+      if (existing.message) result.message = existing.message;
+      writeResult(out, result);
+      return 0;
+    }
+    const base = existing.record;
+    const next = parsed.command === 'skip'
+      ? { ...base, skip: cleanTickets([...base.skip, parsed.ticket]) }
+      : {
+        ...base,
+        unmerged: cleanUnmergedList([
+          ...base.unmerged,
+          { ticket: parsed.ticket, branch: parsed.branch, files: parsed.files, mergeTicket: parsed.mergeTicket === undefined ? null : parsed.mergeTicket },
+        ]),
+      };
+    const record = { ...next, updatedAt: stamp };
+    save(record);
+    writeResult(out, { status: 'written', path: file, record });
+    return 0;
+  } catch (err) {
+    writeResult(out, { status: 'skipped', path: file, message: 'error: ' + (err && err.message ? err.message : String(err)) });
+    return 0;
+  }
+}
+
+module.exports = { REVIEWS, sanitizeRecord, parseArgs, main };
+
+if (require.main === module) {
+  const code = main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr, env: process.env });
+  process.exit(code);
+}

package/plugins/trailhead/templates/trailhead-auto-slot.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead auto-slot helper (self-contained, ships in templates/ so it reaches every
+// install channel). Opens and lists the slot workspaces of an autonomous run with
+// parallel slots: one workspace per ticket in flight, a worktree (or, on a superrepo,
+// an independent clone) at a sibling path on its own branch. #283.
+//
+// CLI:
+//   node trailhead-auto-slot.js open --repo <main-checkout> --ticket <n> --base <sha>
+//   node trailhead-auto-slot.js list --repo <main-checkout>
+//
+// Layout: the workspace of ticket <n> is <parent of the main checkout>/<basename>-t<n>
+// on the branch trailhead/t<n>.
+//
+// open (never overwrites anything, never removes anything):
+//   - the branch is already checked out in a worktree (at the slot path or any other
+//     path, e.g. one made by hand earlier): status "reentered" with that path;
+//   - the branch exists but has no worktree: "reattached" (git worktree add <path> <branch>);
+//   - neither: "created" (git worktree add -b <branch> <path> <base>), the branch pointing
+//     exactly at --base (the trunk SHA captured at claim, so a moved main checkout never
+//     changes it);
+//   - the branch's worktree is registered in git but its directory is gone (deleted by
+//     hand): "error" naming it and telling to run `git worktree prune` (never pruned here);
+//   - the slot path already exists: an independent git checkout on the branch (a clone
+//     slot) is "reentered" with kind "clone"; anything else is "error", never overwritten.
+//     This check comes before the submodule rule, so an existing path is never cloned over;
+//   - only a missing path, with the main checkout declaring a submodule (.gitmodules):
+//     "clone-required", nothing created. The caller sets the clone up at the same path, then checks out the branch
+//     at the same base, so a clone slot carries the same path, branch and base.
+// list: every slot workspace, sorted by ticket: each worktree on a trailhead/t<n> branch,
+//   plus each sibling <basename>-t<n> that is an independent git checkout on the branch
+//   trailhead/t<n> and not already a worktree. Each entry:
+//   {ticket, kind: "worktree"|"clone", branch, path, dirty, workState}
+//   A worktree git lists but whose directory is gone (stale) is kept out of slots and
+//   reported in warnings, with a `git worktree prune` suggestion.
+//   dirty is true when `git status --porcelain` is non-empty; workState is the parsed
+//   <path>/.trailhead/work-state.json, or null (missing, or unreadable plus a warning).
+//
+// Prints exactly one JSON line on stdout:
+//   open:  {"status":"created|reentered|reattached|clone-required","ticket":n,"branch":"...","path":"...","kind":"worktree|clone"}
+//   list:  {"status":"ok","slots":[...],"warnings":[...]}
+//   error: {"status":"error","reason":"..."}
+// Exit 0 on ok, 1 on an error, 2 on a usage error (stderr).
+
+const { spawnSync } = require('child_process');
+const nodeFs = require('fs');
+const path = require('path');
+
+function defaultGit(args) {
+  const r = spawnSync('git', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
+}
+
+const firstLine = (s) => String(s || '').split('\n').find((l) => l.trim()) || '';
+const branchOf = (n) => `trailhead/t${n}`;
+const BRANCH_RE = /^refs\/heads\/trailhead\/t(\d+)$/;
+
+// --- args ---------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const cmd = argv[0];
+  if (cmd !== 'open' && cmd !== 'list') return { error: `usage: expected open or list, got: ${cmd === undefined ? '(nothing)' : cmd}` };
+  const allowed = cmd === 'open' ? ['--repo', '--ticket', '--base'] : ['--repo'];
+  const o = { cmd, repo: null, ticket: null, base: null };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!allowed.includes(flag)) return { error: `usage: unknown argument: ${flag}` };
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    const v = argv[i];
+    if (flag === '--ticket') {
+      if (!/^[1-9]\d*$/.test(v)) return { error: `usage: --ticket must be a positive integer, got: ${v}` };
+      o.ticket = Number(v);
+    } else if (!v.trim()) {
+      return { error: `usage: ${flag} requires a non-empty value` };
+    } else if (flag === '--repo') {
+      o.repo = v;
+    } else {
+      o.base = v;
+    }
+  }
+  if (!o.repo) return { error: `usage: ${cmd} requires --repo` };
+  if (cmd === 'open' && !o.ticket) return { error: 'usage: open requires --ticket' };
+  if (cmd === 'open' && !o.base) return { error: 'usage: open requires --base' };
+  return o;
+}
+
+// --- git helpers --------------------------------------------------------------
+
+// [{ path, branch|null }] from `git worktree list --porcelain`, main checkout first.
+function parseWorktrees(text) {
+  const out = [];
+  for (const block of String(text).split(/\n\s*\n/)) {
+    let wt = null;
+    let branch = null;
+    for (const line of block.split('\n')) {
+      if (line.startsWith('worktree ')) wt = line.slice('worktree '.length);
+      else if (line.startsWith('branch ')) branch = line.slice('branch '.length);
+    }
+    if (wt) out.push({ path: wt, branch });
+  }
+  return out;
+}
+
+const realOr = (fs, p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+
+function hasSubmodule(fs, main) {
+  try {
+    return /^\s*\[submodule\s/m.test(fs.readFileSync(path.join(main, '.gitmodules'), 'utf8'));
+  } catch { return false; }
+}
+
+// --- open ---------------------------------------------------------------------
+
+function openSlot(ctx, o) {
+  const { git, fs, main, fail, emit } = ctx;
+  const branch = branchOf(o.ticket);
+  const target = path.join(path.dirname(main), `${path.basename(main)}-t${o.ticket}`);
+  const result = (status, p, kind) => { emit({ status, ticket: o.ticket, branch, path: p, kind }); return 0; };
+
+  const wl = git(['-C', o.repo, 'worktree', 'list', '--porcelain']);
+  if (wl.status !== 0) return fail(`git worktree list failed: ${firstLine(wl.stderr) || 'exit ' + wl.status}`);
+  const held = parseWorktrees(wl.stdout).find((w) => w.branch === `refs/heads/${branch}`);
+  if (held) {
+    if (!fs.existsSync(held.path)) return fail(`stale worktree of ${branch}: ${held.path} is gone from disk but git still lists it; run git worktree prune and retry`);
+    return result('reentered', held.path, 'worktree');
+  }
+
+  // The slot path is checked before the submodule rule, so an existing path is never cloned over.
+  if (fs.existsSync(target)) {
+    if (cloneOnBranch(git, fs, target, branch)) return result('reentered', target, 'clone');
+    return fail(`slot path already exists and is not a checkout of ${branch}: ${target}`);
+  }
+
+  if (hasSubmodule(fs, main)) return result('clone-required', target, 'clone');
+
+  const exists = git(['-C', o.repo, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]);
+  if (exists.status === 0) {
+    const add = git(['-C', o.repo, 'worktree', 'add', target, branch]);
+    if (add.status !== 0) return fail(`git worktree add failed: ${firstLine(add.stderr) || 'exit ' + add.status}`);
+    return result('reattached', target, 'worktree');
+  }
+
+  const base = git(['-C', o.repo, 'rev-parse', '--verify', '--quiet', `${o.base}^{commit}`]);
+  if (base.status !== 0) return fail(`base does not resolve to a commit: ${o.base}`);
+  const add = git(['-C', o.repo, 'worktree', 'add', '-b', branch, target, base.stdout.trim()]);
+  if (add.status !== 0) return fail(`git worktree add failed: ${firstLine(add.stderr) || 'exit ' + add.status}`);
+  return result('created', target, 'worktree');
+}
+
+// --- list ---------------------------------------------------------------------
+
+// { workState, warning } for the checkout at dir.
+function readWorkState(fs, dir) {
+  const file = path.join(dir, '.trailhead', 'work-state.json');
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (e) {
+    if (e && e.code === 'ENOENT') return { workState: null, warning: null };
+    return { workState: null, warning: `unreadable work state at ${file}` };
+  }
+  try { return { workState: JSON.parse(raw), warning: null }; } catch {
+    return { workState: null, warning: `unparseable work state at ${file}` };
+  }
+}
+
+function isDirty(git, dir) {
+  const r = git(['-C', dir, 'status', '--porcelain']);
+  return r.status === 0 ? { dirty: r.stdout.trim() !== '', warning: null } : { dirty: null, warning: `git status failed at ${dir}` };
+}
+
+// True when dir is an independent checkout (its git dir lives inside it) on `branch`.
+function cloneOnBranch(git, fs, dir, branch) {
+  const g = git(['-C', dir, 'rev-parse', '--absolute-git-dir']);
+  if (g.status !== 0) return false;
+  const gitDir = realOr(fs, g.stdout.trim());
+  const root = realOr(fs, dir);
+  if (gitDir !== root && !gitDir.startsWith(root + path.sep)) return false;
+  const b = git(['-C', dir, 'symbolic-ref', '--quiet', 'HEAD']);
+  return b.status === 0 && b.stdout.trim() === `refs/heads/${branch}`;
+}
+
+function listSlots(ctx, o) {
+  const { git, fs, main, fail, emit } = ctx;
+  const wl = git(['-C', o.repo, 'worktree', 'list', '--porcelain']);
+  if (wl.status !== 0) return fail(`git worktree list failed: ${firstLine(wl.stderr) || 'exit ' + wl.status}`);
+  const entries = [];
+  const warnings = [];
+  const seen = new Set();
+  for (const w of parseWorktrees(wl.stdout)) {
+    const m = w.branch && BRANCH_RE.exec(w.branch);
+    if (!m || realOr(fs, w.path) === main) continue;
+    seen.add(realOr(fs, w.path));
+    if (!fs.existsSync(w.path)) {
+      warnings.push(`stale worktree of ${branchOf(m[1])}: ${w.path} is gone from disk but git still lists it; run git worktree prune`);
+      continue;
+    }
+    entries.push({ ticket: Number(m[1]), kind: 'worktree', branch: branchOf(m[1]), path: w.path });
+  }
+
+  const parent = path.dirname(main);
+  const re = new RegExp(`^${path.basename(main).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-t(\\d+)$`);
+  let names = [];
+  try { names = fs.readdirSync(parent); } catch { /* unreadable parent: no clones */ }
+  for (const name of names) {
+    const m = re.exec(name);
+    if (!m) continue;
+    const dir = path.join(parent, name);
+    if (seen.has(realOr(fs, dir))) continue;
+    if (!cloneOnBranch(git, fs, dir, branchOf(m[1]))) continue;
+    entries.push({ ticket: Number(m[1]), kind: 'clone', branch: branchOf(m[1]), path: dir });
+  }
+
+  const slots = entries.sort((a, b) => a.ticket - b.ticket).map((e) => {
+    const d = isDirty(git, e.path);
+    const s = readWorkState(fs, e.path);
+    for (const w of [d.warning, s.warning]) if (w) warnings.push(w);
+    return { ...e, dirty: d.dirty, workState: s.workState };
+  });
+  emit({ status: 'ok', slots, warnings });
+  return 0;
+}
+
+function main(argv, { git, stdout, stderr, fs } = {}) {
+  const out = stdout || process.stdout;
+  const err = stderr || process.stderr;
+  const o = parseArgs(argv || []);
+  if (o.error) { err.write(o.error + '\n'); return 2; }
+  const fsx = fs || nodeFs;
+  const emit = (obj) => out.write(JSON.stringify(obj) + '\n');
+  const fail = (reason) => { emit({ status: 'error', reason }); return 1; };
+  const ctx = { git: git || defaultGit, fs: fsx, main: realOr(fsx, o.repo), fail, emit };
+  return o.cmd === 'open' ? openSlot(ctx, o) : listSlots(ctx, o);
+}
+
+module.exports = { main, parseArgs, parseWorktrees, hasSubmodule };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}