@marcomigozzi/trailhead 0.14.0 → 0.16.0

package/plugins/trailhead/templates/trailhead-isolation-answer.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead isolation answer (self-contained, ships in templates/ so it reaches
+// every install channel: bin/trailhead.js copies templates/ wholesale for
+// Claude/npm and Codex). Remembers the answer to the work-start concurrency ask
+// under `isolation: auto` in <project root>/.trailhead/isolation-answer.json, so
+// later work-starts of the same working stretch reuse it. #245.
+//
+// CLI:
+//   node trailhead-isolation-answer.js check  [--repo <dir>] --others <csv|none|unavailable>
+//   node trailhead-isolation-answer.js record [--repo <dir>] --answer yes|no --others <csv|none>
+//   node trailhead-isolation-answer.js clear  [--repo <dir>]
+// --repo defaults to cwd. It is canonicalised to the project root: inside a
+// linked worktree it resolves to the main worktree (git common dir), so a call
+// from a trailhead/t<n> worktree reads the same record; on a git failure (or not
+// a git repo) the given dir is used as is.
+// File shape: { answer: "yes"|"no", others: [ticket numbers], recordedAt, usedAt }
+// `others` is the live-claims fingerprint (open issues assigned to @me minus the
+// current ticket), sorted and deduplicated; `none` is the empty set.
+// A session is a working stretch: it ends after 8 hours without a work-start
+// (sliding idle window; each reuse refreshes usedAt).
+// check prints:
+//   {"status":"reuse","answer","recordedAt","path"}   (only after usedAt was refreshed)
+//   {"status":"ask","reason":"absent|expired|claims-changed|invalid|unavailable","path"}
+// record prints {"status":"written","path","record"}; clear prints
+// {"status":"cleared|absent","path"}.
+// Exit 0 on every normal outcome and on any unexpected I/O error (status
+// skipped with a message, which the caller treats as ask); exit 2 only on a
+// usage error (nothing is written).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+const STATE_DIR = '.trailhead';
+const STATE_FILE = 'isolation-answer.json';
+const IDLE_WINDOW_MS = 8 * 60 * 60 * 1000;
+const ANSWERS = ['yes', 'no'];
+
+const isPosInt = (v) => Number.isInteger(v) && v > 0;
+
+// Sorted, deduplicated copy of a list of ticket numbers.
+const normalise = (list) => [...new Set(list)].sort((a, b) => a - b);
+
+// Strict parse of the --others value. Returns a sorted deduplicated array,
+// the string "unavailable" (when allowed), or null if invalid.
+function parseOthers(text, { allowUnavailable }) {
+  if (text === 'none') return [];
+  if (text === 'unavailable') return allowUnavailable ? 'unavailable' : null;
+  if (typeof text !== 'string' || !/^[1-9]\d*(,[1-9]\d*)*$/.test(text)) return null;
+  return normalise(text.split(',').map(Number));
+}
+
+// Strict ISO-8601 timestamp (as written by toISOString) -> epoch ms, or null.
+function parseTime(text) {
+  if (typeof text !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(text)) return null;
+  const ms = Date.parse(text);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+// Valid record or null (malformed or future timestamp, answer not yes/no,
+// others not an array of positive integers).
+function validateRecord(raw, nowMs) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (!ANSWERS.includes(raw.answer)) return null;
+  if (!Array.isArray(raw.others) || !raw.others.every(isPosInt)) return null;
+  const recordedAt = parseTime(raw.recordedAt);
+  const usedAt = parseTime(raw.usedAt);
+  if (recordedAt === null || usedAt === null) return null;
+  if (recordedAt > nowMs || usedAt > nowMs) return null;
+  return { answer: raw.answer, others: normalise(raw.others), recordedAt: raw.recordedAt, usedAt, usedAtText: raw.usedAt };
+}
+
+// Pure decision: reuse the record or ask again, and why.
+// record: parsed file content (null/undefined = absent); others: array or "unavailable".
+function decide(record, others, now) {
+  if (others === 'unavailable') return { status: 'ask', reason: 'unavailable' };
+  if (record === null || record === undefined) return { status: 'ask', reason: 'absent' };
+  const valid = validateRecord(record, now.getTime());
+  if (valid === null) return { status: 'ask', reason: 'invalid' };
+  if (now.getTime() - valid.usedAt > IDLE_WINDOW_MS) return { status: 'ask', reason: 'expired' };
+  const want = normalise(others);
+  const same = want.length === valid.others.length && want.every((n, i) => n === valid.others[i]);
+  if (!same) return { status: 'ask', reason: 'claims-changed' };
+  return { status: 'reuse', answer: valid.answer, recordedAt: valid.recordedAt };
+}
+
+function parseArgs(argv) {
+  const command = argv[0];
+  if (command !== 'check' && command !== 'record' && command !== 'clear') {
+    return { error: `usage: expected "check", "record" or "clear", got: ${command === undefined ? '(nothing)' : command}` };
+  }
+  const allowed = command === 'check' ? ['--repo', '--others']
+    : command === 'record' ? ['--repo', '--answer', '--others'] : ['--repo'];
+  let repo = null;
+  let answer;
+  let others;
+  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 value = argv[i];
+    if (flag === '--repo') repo = value;
+    else if (flag === '--answer') {
+      if (!ANSWERS.includes(value)) return { error: `usage: --answer must be yes or no, got: ${value}` };
+      answer = value;
+    } else if (flag === '--others') {
+      others = parseOthers(value, { allowUnavailable: command === 'check' });
+      if (others === null) {
+        return { error: `usage: --others must be comma-separated positive integers, "none"${command === 'check' ? ' or "unavailable"' : ''}, got: ${value}` };
+      }
+    }
+  }
+  if (command === 'check' && others === undefined) return { error: 'usage: check needs --others' };
+  if (command === 'record' && answer === undefined) return { error: 'usage: record needs --answer' };
+  if (command === 'record' && others === undefined) return { error: 'usage: record needs --others' };
+  return { command, repo, answer, others };
+}
+
+// Project root: the main worktree when dir is inside a linked worktree, else
+// dir as given (also on any git failure or when not a git repo).
+function resolveProjectRoot(dir) {
+  try {
+    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (common && path.basename(common) === '.git') return path.dirname(common);
+    return dir;
+  } catch {
+    return dir;
+  }
+}
+
+// Reads and parses the file; missing = null, corrupt = {} (invalid, never a crash).
+function readRecord(file, fsMod) {
+  let text;
+  try {
+    text = fsMod.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}
+
+// Atomic write: a unique temp in the same dir, then rename over the file
+// (never an in-place truncate); the temp is removed if anything fails.
+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 { /* best-effort cleanup */ }
+    throw err;
+  }
+}
+
+function writeResult(stdout, result) {
+  stdout.write(JSON.stringify(result) + '\n');
+}
+
+function main(argv, { cwd, stdout, fs: fsMod, now } = {}) {
+  const cwd_ = cwd || process.cwd();
+  const out = stdout || process.stdout;
+  const fs_ = fsMod || fs;
+  const now_ = now || new Date();
+
+  const parsed = parseArgs(argv || []);
+  if (parsed.error) {
+    process.stderr.write(parsed.error + '\n');
+    return 2;
+  }
+
+  const repoDir = parsed.repo ? path.resolve(cwd_, parsed.repo) : cwd_;
+  const root = resolveProjectRoot(repoDir);
+  const dir = path.join(root, STATE_DIR);
+  const file = path.join(dir, STATE_FILE);
+  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;
+    }
+
+    if (parsed.command === 'record') {
+      const record = { answer: parsed.answer, others: parsed.others, recordedAt: now_.toISOString(), usedAt: now_.toISOString() };
+      writeAtomic(dir, file, JSON.stringify(record, null, 2) + '\n', fs_);
+      writeResult(out, { status: 'written', path: file, record });
+      return 0;
+    }
+
+    const raw = readRecord(file, fs_);
+    const decision = decide(raw, parsed.others, now_);
+    if (decision.status !== 'reuse') {
+      writeResult(out, { ...decision, path: file });
+      return 0;
+    }
+    // Slide the idle window first: reuse is only reported once it is persisted.
+    // No lock: a concurrent record landing between read and write is overwritten,
+    // which at worst leaves a stale fingerprint that re-asks, never a blind reuse.
+    const refreshed = { ...raw, usedAt: now_.toISOString() };
+    writeAtomic(dir, file, JSON.stringify(refreshed, null, 2) + '\n', fs_);
+    writeResult(out, { ...decision, path: file });
+    return 0;
+  } catch (err) {
+    writeResult(out, { status: 'skipped', path: file, message: 'error: ' + (err && err.message ? err.message : String(err)) });
+    return 0;
+  }
+}
+
+module.exports = { IDLE_WINDOW_MS, decide, parseOthers, parseArgs, resolveProjectRoot, main };
+
+if (require.main === module) {
+  const code = main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout });
+  process.exit(code);
+}

package/plugins/trailhead/templates/trailhead-isolation-copy.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead isolation copy (self-contained, ships in templates/ so it reaches every
+// install channel: bin/trailhead.js copies templates/ wholesale for Claude/npm
+// and Codex). Copies the gitignored files an app needs to run (env files, local
+// config) from the main checkout into a fresh worktree or clone. #242.
+//
+// CLI:
+//   node trailhead-isolation-copy.js --from <main-checkout> --to <workspace>
+// The list lives in `isolation.copy` of .trailhead/config.json: an array of
+// repo-relative paths (file or directory, no globs), nested ({"isolation":
+// {"copy":[...]}}) or flat ({"isolation.copy":[...]}); nested wins when a file
+// carries both (a warning says so). The project file wins over the global one
+// (${CLAUDE_CONFIG_DIR:-~/.claude}/trailhead/config.json) as a whole value: the
+// global list applies only when the project file has no isolation.copy at all.
+// Rules: a destination that already exists is never overwritten (reported
+// `present`); absolute paths, `..`, any `.git` segment, and paths whose parent
+// directory resolves outside its root (checked on both sides) are `rejected`;
+// a final symlink is copied as a symlink, never followed; nested `.git` entries
+// are skipped inside copied directories. An invalid config (bad JSON, non-array,
+// non-string or empty entry) copies nothing and offers no hint.
+// When the key is unset, tracked `*.example` / `*.sample` files whose stripped
+// sibling exists in the main checkout and is gitignored are listed in
+// `suggestions` (never copied).
+// Prints one JSON line:
+//   {"status","copied":[],"present":[],"missing":[],"rejected":[],"suggestions":[],"warnings":[],"message"?}
+//   status: copied | nothing | unset | invalid | skipped
+// Exit 0 on every normal outcome and on any unexpected I/O error (it must never
+// block the caller: status skipped with the message); exit 2 only on a usage
+// error (missing --from/--to, unknown flag).
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const CONFIG_REL = path.join('.trailhead', 'config.json');
+const SUFFIXES = ['.example', '.sample'];
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--from' || a === '--to') {
+      const v = argv[++i];
+      if (v === undefined || v.startsWith('--')) return { error: `usage: ${a} needs a value` };
+      out[a.slice(2)] = v;
+    } else {
+      return { error: `usage: unknown argument ${a}` };
+    }
+  }
+  if (!out.from) return { error: 'usage: missing --from <main-checkout>' };
+  if (!out.to) return { error: 'usage: missing --to <workspace>' };
+  return out;
+}
+
+// Returns null when the repo-relative entry is acceptable, else the reason.
+function checkRelPath(rel) {
+  if (typeof rel !== 'string' || rel === '') return 'empty path';
+  if (path.isAbsolute(rel) || path.win32.isAbsolute(rel)) return 'absolute path';
+  const segments = rel.split(/[\\/]+/).filter(Boolean);
+  if (segments.length === 0 || segments.every((s) => s === '.')) return 'empty path';
+  if (segments.includes('..')) return 'parent segment';
+  if (segments.includes('.git')) return '.git segment';
+  return null;
+}
+
+// Reads the copy list out of one config file.
+// { state: 'unset' } | { state: 'set', list, warnings } | { state: 'invalid', message }
+function readCopyList(file, fs_) {
+  let text;
+  try {
+    text = fs_.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { state: 'unset' };
+    return { state: 'invalid', message: `cannot read ${file}: ${err && err.message ? err.message : err}` };
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(text);
+  } catch (err) {
+    return { state: 'invalid', message: `${file} is not valid JSON` };
+  }
+  if (cfg === null || typeof cfg !== 'object' || Array.isArray(cfg)) {
+    return { state: 'invalid', message: `${file} is not a JSON object` };
+  }
+  const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+  const nested = cfg.isolation !== null && typeof cfg.isolation === 'object' && !Array.isArray(cfg.isolation) && has(cfg.isolation, 'copy');
+  const flat = has(cfg, 'isolation.copy');
+  if (!nested && !flat) return { state: 'unset' };
+  const warnings = [];
+  if (nested && flat) warnings.push(`${file} sets isolation.copy in both nested and flat form; the nested form wins`);
+  const value = nested ? cfg.isolation.copy : cfg['isolation.copy'];
+  if (!Array.isArray(value)) return { state: 'invalid', message: `isolation.copy in ${file} must be an array of paths` };
+  if (value.some((e) => typeof e !== 'string' || e.trim() === '')) {
+    return { state: 'invalid', message: `isolation.copy in ${file} must hold only non-empty strings` };
+  }
+  return { state: 'set', list: value, warnings };
+}
+
+function globalConfigPath(env) {
+  const base = env.CLAUDE_CONFIG_DIR || path.join(env.HOME || os.homedir(), '.claude');
+  return path.join(base, 'trailhead', 'config.json');
+}
+
+// realpath of the deepest existing ancestor of p (p itself included).
+function deepestReal(p, fs_) {
+  let cur = p;
+  for (;;) {
+    try {
+      return fs_.realpathSync(cur);
+    } catch (err) {
+      const up = path.dirname(cur);
+      if (up === cur) return cur;
+      cur = up;
+    }
+  }
+}
+
+// True when the parent directory of root/rel resolves inside realRoot.
+function parentInside(root, realRoot, rel, fs_) {
+  const real = deepestReal(path.dirname(path.join(root, rel)), fs_);
+  return real === realRoot || real.startsWith(realRoot + path.sep);
+}
+
+const exists = (p, fs_) => {
+  try { fs_.lstatSync(p); return true; } catch (err) { return false; }
+};
+
+// Tracked *.example / *.sample files whose stripped sibling is present and ignored.
+function suggest(from, fs_) {
+  let tracked;
+  try {
+    tracked = execFileSync('git', ['-C', from, 'ls-files', '-z'], { stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 })
+      .toString().split('\0').filter(Boolean);
+  } catch (err) {
+    return [];
+  }
+  const out = [];
+  for (const file of tracked) {
+    const suffix = SUFFIXES.find((s) => file.endsWith(s) && file.length > s.length);
+    if (!suffix) continue;
+    const sibling = file.slice(0, -suffix.length);
+    if (out.includes(sibling) || checkRelPath(sibling) !== null || !exists(path.join(from, sibling), fs_)) continue;
+    try {
+      execFileSync('git', ['-C', from, 'check-ignore', '-q', '--', sibling], { stdio: 'ignore' });
+      out.push(sibling);
+    } catch (err) {
+      // not ignored (exit 1) or git error: not a suggestion
+    }
+  }
+  return out;
+}
+
+function copyEntries(list, from, to, fs_) {
+  const result = { copied: [], present: [], missing: [], rejected: [], warnings: [] };
+  const realFrom = fs_.realpathSync(from);
+  const realTo = fs_.realpathSync(to);
+  for (const rel of list) {
+    if (checkRelPath(rel) !== null || !parentInside(from, realFrom, rel, fs_)) {
+      result.rejected.push(rel);
+      continue;
+    }
+    const src = path.join(from, rel);
+    const dst = path.join(to, rel);
+    if (!exists(src, fs_)) { result.missing.push(rel); continue; }
+    if (!parentInside(to, realTo, rel, fs_)) { result.rejected.push(rel); continue; }
+    if (exists(dst, fs_)) { result.present.push(rel); continue; }
+    try {
+      fs_.mkdirSync(path.dirname(dst), { recursive: true });
+      // Re-check after creating parents: nothing may have been redirected meanwhile.
+      if (!parentInside(to, realTo, rel, fs_)) { result.rejected.push(rel); continue; }
+      fs_.cpSync(src, dst, {
+        recursive: true,
+        force: false,
+        errorOnExist: true,
+        verbatimSymlinks: true,
+        filter: (s) => path.basename(s) !== '.git',
+      });
+      result.copied.push(rel);
+    } catch (err) {
+      result.warnings.push(`could not copy ${rel}: ${err && err.message ? err.message : err}`);
+      // This run created the destination (it did not exist before): drop any
+      // partial copy so the next run retries instead of reporting it present.
+      try {
+        fs_.rmSync(dst, { recursive: true, force: true });
+      } catch (cleanupErr) {
+        result.warnings.push(`could not clean up partial ${rel}: ${cleanupErr && cleanupErr.message ? cleanupErr.message : cleanupErr}`);
+      }
+    }
+  }
+  return result;
+}
+
+function writeResult(out, fields) {
+  const result = { status: 'skipped', copied: [], present: [], missing: [], rejected: [], suggestions: [], warnings: [], ...fields };
+  out.write(JSON.stringify(result) + '\n');
+}
+
+function main(argv, { cwd, stdout, env, fs: fsMod } = {}) {
+  const cwd_ = cwd || process.cwd();
+  const out = stdout || process.stdout;
+  const env_ = env || process.env;
+  const fs_ = fsMod || fs;
+
+  const parsed = parseArgs(argv || []);
+  if (parsed.error) {
+    process.stderr.write(parsed.error + '\n');
+    return 2;
+  }
+  const from = path.resolve(cwd_, parsed.from);
+  const to = path.resolve(cwd_, parsed.to);
+  try {
+    let cfg = readCopyList(path.join(from, CONFIG_REL), fs_);
+    if (cfg.state === 'unset') cfg = readCopyList(globalConfigPath(env_), fs_);
+    if (cfg.state === 'invalid') {
+      writeResult(out, { status: 'invalid', message: cfg.message });
+      return 0;
+    }
+    if (cfg.state === 'unset') {
+      writeResult(out, { status: 'unset', suggestions: suggest(from, fs_) });
+      return 0;
+    }
+    const res = copyEntries(cfg.list, from, to, fs_);
+    res.warnings = [...cfg.warnings, ...res.warnings];
+    writeResult(out, { ...res, status: res.copied.length > 0 ? 'copied' : 'nothing' });
+    return 0;
+  } catch (err) {
+    writeResult(out, { status: 'skipped', message: 'error: ' + (err && err.message ? err.message : String(err)) });
+    return 0;
+  }
+}
+
+module.exports = { checkRelPath, readCopyList, parseArgs, main };
+
+if (require.main === module) {
+  const code = main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout, env: process.env });
+  process.exit(code);
+}