@jakobm/peacekeeper 0.0.0-stage → 0.12.1

package/scripts/cleanup-merged-branches.js

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+
+/**
+ * Remove local and remote branches that are fully merged into the locally known
+ * the configured remote default branch. A worktree on an eligible local branch is removed first when it
+ * has no tracked or untracked changes.
+ *
+ * Recommended usage:
+ *
+ *   npm exec --no -- peacekeeper cleanup-merged-branches             # Dry-run (default).
+ *   npm exec --no -- peacekeeper cleanup-merged-branches --dry-run   # Explicit dry-run.
+ *   npm exec --no -- peacekeeper cleanup-merged-branches --execute   # Apply the displayed cleanup.
+ *
+ * Every run fetches the configured remote, including dry-runs, so the cleanup
+ * plan uses current remote references. Dry-run does not remove anything,
+ * but this fetch still updates local remote references. The script never deletes
+ * the configured default branch. It skips the current worktree, locked worktrees,
+ * and worktrees with tracked or untracked changes. Ignored files do not count as
+ * changes. Local and remote deletions are guarded by the exact commit IDs
+ * observed while building the cleanup plan, so a branch changed concurrently is
+ * preserved.
+ */
+
+const { execFileSync, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { projectConfig } = require('./project-config');
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+function runGit(args, options = {}) {
+  const result = spawnSync('git', args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    stdio: options.stdio || ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (result.status !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim();
+    throw new Error(detail || `git ${args.join(' ')} failed`);
+  }
+
+  return result.stdout;
+}
+
+function parseArguments(args) {
+  let execute = false;
+
+  for (const argument of args) {
+    if (argument === '--execute') {
+      execute = true;
+    } else if (argument === '--dry-run') {
+      execute = false;
+    } else if (argument === '--help' || argument === '-h') {
+      console.log('Usage: cleanup-merged-branches.js [--dry-run | --execute]');
+      console.log('');
+      console.log('Dry-run is the default. Use --execute to remove eligible worktrees and branches.');
+      process.exit(0);
+    } else {
+      fail(`unknown argument: ${argument}`);
+    }
+  }
+
+  return { execute };
+}
+
+function mergedBranches(repositoryRoot, namespace) {
+  const { remote, defaultBranch } = projectConfig(repositoryRoot).git;
+  const output = runGit([
+    'for-each-ref',
+    `--merged=refs/remotes/${remote}/${defaultBranch}`,
+    '--format=%(refname)\t%(objectname)\t%(symref)',
+    namespace,
+  ], { cwd: repositoryRoot });
+
+  return output
+    .trimEnd()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => line.split('\t'))
+    .filter(([, , symbolicTarget]) => !symbolicTarget)
+    .map(([refName, objectId]) => ({ refName, objectId }));
+}
+
+function listWorktrees(repositoryRoot) {
+  const fields = runGit(['worktree', 'list', '--porcelain', '-z'], {
+    cwd: repositoryRoot,
+  }).split('\0');
+  const worktrees = [];
+  let current = null;
+
+  for (const field of fields) {
+    if (field === '') {
+      if (current) {
+        worktrees.push(current);
+        current = null;
+      }
+      continue;
+    }
+
+    const separator = field.indexOf(' ');
+    const key = separator === -1 ? field : field.slice(0, separator);
+    const value = separator === -1 ? '' : field.slice(separator + 1);
+
+    if (key === 'worktree') {
+      current = { path: value };
+    } else if (current) {
+      current[key] = value;
+    }
+  }
+
+  return worktrees;
+}
+
+function samePath(first, second) {
+  try {
+    return fs.realpathSync(first) === fs.realpathSync(second);
+  } catch {
+    return path.resolve(first) === path.resolve(second);
+  }
+}
+
+function branchNameFromLocalRef(refName) {
+  return refName.slice('refs/heads/'.length);
+}
+
+function branchNameFromRemoteRef(refName, remote) {
+  return refName.slice(`refs/remotes/${remote}/`.length);
+}
+
+function buildPlan(repositoryRoot) {
+  const { remote, defaultBranch } = projectConfig(repositoryRoot).git;
+  const localBranches = new Map(
+    mergedBranches(repositoryRoot, 'refs/heads')
+      .map(({ refName, objectId }) => [branchNameFromLocalRef(refName), objectId]),
+  );
+  const remoteBranches = new Map(
+    mergedBranches(repositoryRoot, `refs/remotes/${remote}`)
+      .map(({ refName, objectId }) => [branchNameFromRemoteRef(refName, remote), objectId])
+      .filter(([branch]) => branch !== 'HEAD'),
+  );
+
+  localBranches.delete(defaultBranch);
+  remoteBranches.delete(defaultBranch);
+
+  const currentRoot = runGit(['rev-parse', '--show-toplevel'], {
+    cwd: repositoryRoot,
+  }).trim();
+  const worktrees = listWorktrees(repositoryRoot);
+  const names = [...new Set([...localBranches.keys(), ...remoteBranches.keys()])].sort();
+
+  return names.map((branch) => {
+    const branchWorktrees = localBranches.has(branch)
+      ? worktrees.filter((worktree) => worktree.branch === `refs/heads/${branch}`)
+      : [];
+    let skipReason = null;
+
+    for (const worktree of branchWorktrees) {
+      if (samePath(worktree.path, currentRoot)) {
+        skipReason = `it is checked out in the current worktree: ${worktree.path}`;
+        break;
+      }
+      if (Object.hasOwn(worktree, 'locked')) {
+        skipReason = `its worktree is locked: ${worktree.path}`;
+        break;
+      }
+
+      try {
+        const status = runGit(
+          ['status', '--porcelain', '--untracked-files=all'],
+          { cwd: worktree.path },
+        );
+        if (status !== '') {
+          skipReason = `its worktree has changes: ${worktree.path}`;
+          break;
+        }
+      } catch (error) {
+        skipReason = `its worktree could not be inspected: ${worktree.path} (${error.message})`;
+        break;
+      }
+    }
+
+    return {
+      branch,
+      local: localBranches.has(branch),
+      localObjectId: localBranches.get(branch),
+      remote: remoteBranches.has(branch),
+      remoteObjectId: remoteBranches.get(branch),
+      worktrees: branchWorktrees,
+      skipReason,
+    };
+  });
+}
+
+function printAction(execute, dryRunText, executeText, log) {
+  log(execute ? executeText : `Would ${dryRunText}`);
+}
+
+function localPlanChangedReason(repositoryRoot, item) {
+  if (!item.local) return null;
+  try {
+    const branchRef = `refs/heads/${item.branch}`;
+    const tip = runGit(['rev-parse', '--verify', branchRef], { cwd: repositoryRoot }).trim();
+    if (tip !== item.localObjectId) return 'its local branch changed after planning';
+
+    const current = listWorktrees(repositoryRoot);
+    const attached = current.filter((worktree) => worktree.branch === branchRef);
+    if (attached.length !== item.worktrees.length) return 'its worktrees changed after planning';
+
+    for (const planned of item.worktrees) {
+      const worktree = current.find((candidate) => samePath(candidate.path, planned.path));
+      if (!worktree || worktree.branch !== branchRef || worktree.HEAD !== item.localObjectId) {
+        return `its worktree changed after planning: ${planned.path}`;
+      }
+      if (Object.hasOwn(worktree, 'locked')) return `its worktree is locked: ${planned.path}`;
+      if (samePath(worktree.path, repositoryRoot)) return `it is checked out in the current worktree: ${planned.path}`;
+      if (runGit(['status', '--porcelain', '--untracked-files=all'], { cwd: planned.path }) !== '') {
+        return `its worktree has changes: ${planned.path}`;
+      }
+    }
+  } catch (error) {
+    return `its local state could not be verified: ${error.message}`;
+  }
+  return null;
+}
+
+function applyPlan(repositoryRoot, plan, execute, log = console.log) {
+  const { remote } = projectConfig(repositoryRoot).git;
+  let removedWorktrees = 0;
+  let deletedLocalBranches = 0;
+  let deletedRemoteBranches = 0;
+  let skippedBranches = 0;
+
+  items: for (const item of plan) {
+    const skipReason = item.skipReason || (execute && localPlanChangedReason(repositoryRoot, item));
+    if (skipReason) {
+      log(`Skip ${item.branch}: ${skipReason}`);
+      skippedBranches += 1;
+      continue;
+    }
+
+    for (const [index, worktree] of item.worktrees.entries()) {
+      printAction(
+        execute,
+        `remove worktree ${worktree.path} (branch ${item.branch})`,
+        `Removing worktree ${worktree.path} (branch ${item.branch})`,
+        log,
+      );
+      if (execute) {
+        const changedReason = localPlanChangedReason(repositoryRoot, {
+          ...item, worktrees: item.worktrees.slice(index),
+        });
+        if (changedReason) {
+          log(`Skip ${item.branch}: ${changedReason}`);
+          skippedBranches += 1;
+          continue items;
+        }
+        runGit(['worktree', 'remove', worktree.path], { cwd: repositoryRoot });
+      }
+      removedWorktrees += 1;
+    }
+
+    if (item.local) {
+      printAction(
+        execute,
+        `delete local branch ${item.branch}`,
+        `Deleting local branch ${item.branch}`,
+        log,
+      );
+      if (execute) {
+        const changedReason = localPlanChangedReason(repositoryRoot, { ...item, worktrees: [] });
+        if (changedReason) {
+          log(`Skip ${item.branch}: ${changedReason}`);
+          skippedBranches += 1;
+          continue;
+        }
+        runGit([
+          'update-ref',
+          '-d',
+          `refs/heads/${item.branch}`,
+          item.localObjectId,
+        ], { cwd: repositoryRoot });
+
+        const configResult = spawnSync(
+          'git',
+          ['config', '--remove-section', `branch.${item.branch}`],
+          { cwd: repositoryRoot, encoding: 'utf8' },
+        );
+        if (configResult.status !== 0 && configResult.status !== 5) {
+          console.warn(
+            `Warning: could not remove configuration for branch ${item.branch}: `
+              + configResult.stderr.trim(),
+          );
+        }
+      }
+      deletedLocalBranches += 1;
+    }
+
+    if (item.remote) {
+      printAction(
+        execute,
+        `delete remote branch ${remote}/${item.branch}`,
+        `Deleting remote branch ${remote}/${item.branch}`,
+        log,
+      );
+      if (execute) {
+        runGit([
+          'push',
+          `--force-with-lease=refs/heads/${item.branch}:${item.remoteObjectId}`,
+          remote,
+          `:refs/heads/${item.branch}`,
+        ], {
+          cwd: repositoryRoot,
+        });
+      }
+      deletedRemoteBranches += 1;
+    }
+  }
+
+  log('');
+  log(
+    `${execute ? 'Removed' : 'Would remove'} ${removedWorktrees} worktree(s), `
+      + `${deletedLocalBranches} local branch(es), and ${deletedRemoteBranches} remote branch(es).`,
+  );
+  if (skippedBranches > 0) {
+    log(`Skipped ${skippedBranches} branch(es).`);
+  }
+  if (!execute) {
+    log('');
+    log('To apply this cleanup, run:');
+    log('  npm exec --no -- peacekeeper cleanup-merged-branches --execute');
+  }
+}
+
+function main() {
+  const { execute } = parseArguments(process.argv.slice(2));
+
+  try {
+    execFileSync('git', ['--version'], { stdio: 'ignore' });
+  } catch {
+    fail('required command not found: git');
+  }
+
+  let repositoryRoot;
+  try {
+    repositoryRoot = runGit(['rev-parse', '--show-toplevel']).trim();
+    runGit(['remote', 'get-url', projectConfig(repositoryRoot).git.remote], { cwd: repositoryRoot });
+  } catch (error) {
+    fail(error.message);
+  }
+
+  console.log(execute ? 'Execute mode.' : 'Dry-run mode. No worktrees or branches will be removed.');
+  console.log(`Fetching and pruning ${projectConfig(repositoryRoot).git.remote} before building the cleanup plan.`);
+
+  try {
+    const { remote, defaultBranch } = projectConfig(repositoryRoot).git;
+    runGit(['fetch', '--prune', remote], { cwd: repositoryRoot });
+    runGit(['show-ref', '--verify', '--quiet', `refs/remotes/${remote}/${defaultBranch}`], {
+      cwd: repositoryRoot,
+    });
+  } catch (error) {
+    fail(error.message);
+  }
+
+  console.log('');
+
+  try {
+    const plan = buildPlan(repositoryRoot);
+    applyPlan(repositoryRoot, plan, execute);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { applyPlan, buildPlan, listWorktrees, parseArguments };

package/scripts/install-hooks.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { repositoryRoot } = require('./project-config');
+
+const DEFINITIONS = [
+  ['SessionStart', 'checkpoint-codex-session-start', 30, 'Loading Codex checkpoint instructions'],
+  ['Stop', 'checkpoint-codex-stop', 30, 'Checking for an uncommitted Codex checkpoint'],
+  ['SessionEnd', 'cleanup-ended-session', 3, 'Scheduling merged branch cleanup'],
+];
+const COMMANDS = DEFINITIONS.map(([, command]) => command);
+
+// Recognize complete, standalone invocations only. Shell composition, arguments,
+// environment assignments, and wrappers require inspection instead of replacement.
+function classifyCommand(command) {
+  if (typeof command !== 'string') return 'other';
+  const related = /peacekeeper|checkpoint-codex-(?:stop|session-start)|cleanup-ended-session/.test(command);
+  if (!related) return 'other';
+  const text = command.trim();
+  const action = COMMANDS.find((name) => text.endsWith(` ${name}`) || text.endsWith(`\t${name}`));
+  if (!action) {
+    const legacy = /^(?:node\s+)(?:\.\/)?(?:node_modules\/@jakobm\/peacekeeper\/)?scripts\/(checkpoint-codex-stop|checkpoint-codex-session-start|cleanup-ended-session)\.js$/;
+    return legacy.test(text) ? 'owned' : 'ambiguous';
+  }
+  const executable = text.slice(0, -action.length).trim();
+  if (/^(?:peacekeeper|npm\s+exec\s+--no\s+--\s+peacekeeper|npx\s+--no-install\s+peacekeeper)$/.test(executable)) {
+    return 'owned';
+  }
+  // Accept the documented Git-root resolution with optional path quotes.
+  const gitRoot = '\\$\\(git\\s+rev-parse\\s+--show-toplevel\\)';
+  const binPath = '(?:/node_modules/@jakobm/peacekeeper)?/bin/peacekeeper\\.js';
+  const relativePath = '(?:\\./)?(?:node_modules/@jakobm/peacekeeper/)?bin/peacekeeper\\.js';
+  const paths = [gitRoot + binPath, relativePath];
+  const invocations = paths.flatMap((value) => [`"${value}"`, value]);
+  invocations.push(`'${relativePath}'`);
+  const directPath = new RegExp(`^node\\s+(?:${invocations.join('|')})$`);
+  if (directPath.test(executable)) return 'owned';
+  return 'ambiguous';
+}
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function planHooks(document, localSource = false) {
+  if (!object(document) || (document.hooks !== undefined && !object(document.hooks))) {
+    throw new Error('hooks.json must contain an object with an optional hooks object');
+  }
+  const result = structuredClone(document);
+  result.hooks ??= {};
+  const changes = [];
+  for (const [event, groups] of Object.entries(result.hooks)) {
+    if (!Array.isArray(groups)) throw new Error(`hooks.${event} must be an array`);
+    const keptGroups = [];
+    for (const group of groups) {
+      if (!object(group) || !Array.isArray(group.hooks)) {
+        throw new Error(`hooks.${event} contains an invalid hook group`);
+      }
+      const kept = [];
+      for (const handler of group.hooks) {
+        if (!object(handler)) throw new Error(`hooks.${event} contains an invalid handler`);
+        if (classifyCommand(handler.commandWindows) !== 'other') {
+          throw new Error(`Review Windows-specific peacekeeper hook in ${event}: ${handler.commandWindows}`);
+        }
+        const classification = classifyCommand(handler.command);
+        if (classification === 'ambiguous') {
+          throw new Error(`Review possible peacekeeper hook in ${event}: ${handler.command}`);
+        }
+        if (classification === 'owned') {
+          const allowed = ['type', 'command', 'timeout', 'statusMessage'];
+          if (handler.type !== 'command' || Object.keys(handler).some((key) => !allowed.includes(key))) {
+            throw new Error(`Review customized peacekeeper hook in ${event}: ${handler.command}`);
+          }
+          changes.push(`Replace existing peacekeeper hook in ${event}`);
+        } else {
+          kept.push(handler);
+        }
+      }
+      if (kept.length || group.hooks.length === 0) keptGroups.push({ ...group, hooks: kept });
+    }
+    result.hooks[event] = keptGroups;
+  }
+  const prefix = localSource ? '' : 'node_modules/@jakobm/peacekeeper/';
+  for (const [event, command, timeout, statusMessage] of DEFINITIONS) {
+    result.hooks[event] ??= [];
+    result.hooks[event].push({ hooks: [{
+      type: 'command',
+      command: `node "$(git rev-parse --show-toplevel)/${prefix}bin/peacekeeper.js" ${command}`,
+      timeout,
+      statusMessage,
+    }] });
+    changes.push(`Install ${event}: ${command}`);
+  }
+  return { document: result, changes };
+}
+
+function install({ cwd = process.cwd(), dryRun = false, log = console.log } = {}) {
+  const root = repositoryRoot(cwd);
+  const file = path.join(root, '.codex', 'hooks.json');
+  let original = null;
+  try {
+    if (fs.lstatSync(file).isSymbolicLink()) throw new Error('refusing to replace a symlink hooks.json');
+    original = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const localSource = fs.realpathSync(root) === fs.realpathSync(path.resolve(__dirname, '..'));
+  const plan = planHooks(original === null ? {} : JSON.parse(original), localSource);
+  const serialized = `${JSON.stringify(plan.document, null, 2)}\n`;
+  if (original !== null && JSON.stringify(JSON.parse(original)) === JSON.stringify(plan.document)) {
+    log('Peacekeeper hooks are already up to date.');
+    return;
+  }
+  for (const change of plan.changes) log(change);
+  if (dryRun) {
+    log(`Would update ${file}`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(temporary, serialized, {
+      flag: 'wx', mode: original === null ? 0o644 : fs.statSync(file).mode & 0o777,
+    });
+    // Avoid overwriting edits made while constructing the plan.
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+    if (current !== original) throw new Error('hooks.json changed during installation; retry');
+    fs.renameSync(temporary, file);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+  log(`Updated ${file}. Review and trust the hooks with /hooks in Codex.`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    console.log('Usage: peacekeeper install-hooks [--dry-run]');
+    return;
+  }
+  if (args.length > 1 || (args.length === 1 && args[0] !== '--dry-run')) {
+    throw new Error('Usage: peacekeeper install-hooks [--dry-run]');
+  }
+  install({ dryRun: args.includes('--dry-run') });
+}
+
+if (require.main === module) {
+  try { main(); } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { classifyCommand, planHooks, install };

package/scripts/log-script-invocation.js

@@ -0,0 +1,80 @@
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { projectConfig } = require('./project-config');
+
+function runGit(args, cwd) {
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (result.status !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim();
+    throw new Error(detail || `git ${args.join(' ')} failed`);
+  }
+
+  return result.stdout;
+}
+
+function sourceRepositoryRoot(cwd) {
+  const output = runGit(['worktree', 'list', '--porcelain', '-z'], cwd);
+  const firstField = output.split('\0').find((field) => field.startsWith('worktree '));
+
+  if (!firstField) {
+    throw new Error('could not find the primary Git worktree');
+  }
+
+  return firstField.slice('worktree '.length);
+}
+
+function samePath(first, second) {
+  try {
+    return fs.realpathSync(first) === fs.realpathSync(second);
+  } catch {
+    return path.resolve(first) === path.resolve(second);
+  }
+}
+
+function isPrimaryWorktree(cwd) {
+  const repositoryRoot = runGit(['rev-parse', '--show-toplevel'], cwd).trim();
+  return samePath(repositoryRoot, sourceRepositoryRoot(cwd));
+}
+
+function shellQuote(argument) {
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(argument)) {
+    return argument;
+  }
+
+  return `'${argument.replaceAll("'", `'"'"'`)}'`;
+}
+
+function filesystemTimestamp(date) {
+  return date.toISOString().replaceAll(':', '-');
+}
+
+function logScriptInvocation(options = {}) {
+  const argv = options.argv || process.argv;
+  const cwd = options.cwd || process.cwd();
+  const date = options.date || new Date();
+  const processId = options.processId || process.pid;
+  const repositoryRoot = sourceRepositoryRoot(cwd);
+  const logDirectory = path.join(repositoryRoot, projectConfig(repositoryRoot).loggingDirectory);
+  const scriptName = path.basename(argv[1] || 'unknown-script');
+  const fileName = `${filesystemTimestamp(date)}-${scriptName}-${processId}.log`;
+  const commandLine = argv.map(shellQuote).join(' ');
+
+  fs.mkdirSync(logDirectory, { recursive: true });
+  const logPath = path.join(logDirectory, fileName);
+  fs.writeFileSync(logPath, `${commandLine}\n`, { flag: 'wx' });
+  return logPath;
+}
+
+module.exports = {
+  filesystemTimestamp,
+  isPrimaryWorktree,
+  logScriptInvocation,
+  shellQuote,
+  sourceRepositoryRoot,
+};