Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

11.6 KB
Raw Blame
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import { readFile, writeFile, mkdir, access, realpath, rename, open, unlink, stat } from 'node:fs/promises';
import path from 'node:path';

const run = promisify(execFile);

export const MANIFEST_DIR = '.loop-worktrees';
export const MANIFEST_FILE = path.posix.join(MANIFEST_DIR, 'manifest.json');
const MANIFEST_MUTEX_FILE = path.posix.join(MANIFEST_DIR, '.manifest.mutex');

export type WorktreeStatus = 'active' | 'rejected' | 'escalated' | 'merged' | 'stale';

export const VALID_STATUSES: WorktreeStatus[] = [
  'active',
  'rejected',
  'escalated',
  'merged',
  'stale',
];

/** Terminal states cleanup discards by default; "active" is never swept automatically. */
export const CLEANUP_DEFAULT_STATUSES: WorktreeStatus[] = ['rejected', 'escalated'];

export interface WorktreeEntry {
  id: string;
  /** Repo-relative, posix-style path to the worktree. */
  path: string;
  branch: string;
  baseBranch: string;
  pattern: string;
  createdAt: string;
  status: WorktreeStatus;
}

export interface Manifest {
  version: 1;
  worktrees: WorktreeEntry[];
}

function emptyManifest(): Manifest {
  return { version: 1, worktrees: [] };
}

async function exists(p: string): Promise<boolean> {
  try {
    await access(p);
    return true;
  } catch {
    return false;
  }
}

/** Run git in `cwd`, returning trimmed stdout. Throws a clean Error on failure. */
async function git(args: string[], cwd: string): Promise<string> {
  try {
    const { stdout } = await run('git', args, { cwd, maxBuffer: 10 * 1024 * 1024 });
    return stdout.trim();
  } catch (err) {
    const e = err as { stderr?: string; message?: string };
    const detail = (e.stderr || e.message || '').trim();
    throw new Error(`git ${args.join(' ')} failed: ${detail}`);
  }
}

export async function isGitRepo(cwd: string): Promise<boolean> {
  try {
    const out = await git(['rev-parse', '--is-inside-work-tree'], cwd);
    return out === 'true';
  } catch {
    return false;
  }
}

async function assertGitRepo(root: string): Promise<void> {
  if (!(await isGitRepo(root))) {
    throw new Error(
      `Not a git repository: ${root}. loop-worktree manages git worktrees and must run inside a repo.`,
    );
  }
}

async function withManifestMutex<T>(root: string, fn: () => Promise<T>): Promise<T> {
  const dir = path.join(root, MANIFEST_DIR);
  await mkdir(dir, { recursive: true });
  const mutexPath = path.join(root, MANIFEST_MUTEX_FILE);
  const deadline = Date.now() + 30000;
  for (;;) {
    try {
      const handle = await open(mutexPath, 'wx');
      await handle.close();
      break;
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;

      try {
        const st = await stat(mutexPath);
        if (Date.now() - st.mtimeMs > 30000) {
          await unlink(mutexPath).catch(() => {});
          continue;
        }
      } catch {
        continue;
      }

      if (Date.now() > deadline) {
        throw new Error(
          `Timed out waiting for manifest mutex (${MANIFEST_MUTEX_FILE}). If no other loop-worktree process is running, delete it manually.`,
        );
      }
      await new Promise((resolve) => setTimeout(resolve, 25 + Math.random() * 50));
    }
  }
  try {
    return await fn();
  } finally {
    await unlink(mutexPath).catch(() => {});
  }
}

export async function readManifest(root: string): Promise<Manifest> {
  const file = path.join(root, MANIFEST_FILE);
  if (!(await exists(file))) return emptyManifest();
  const raw = await readFile(file, 'utf8');
  const parsed = JSON.parse(raw) as Manifest;
  if (parsed.version !== 1 || !Array.isArray(parsed.worktrees)) {
    throw new Error(`Invalid manifest at ${MANIFEST_FILE}: expected { version: 1, worktrees: [] }.`);
  }
  return parsed;
}

export async function writeManifest(root: string, manifest: Manifest): Promise<void> {
  const dir = path.join(root, MANIFEST_DIR);
  await mkdir(dir, { recursive: true });
  const file = path.join(root, MANIFEST_FILE);
  const tmpFile = `${file}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`;
  await writeFile(tmpFile, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
  await rename(tmpFile, file);
}

export interface CreateInput {
  root: string;
  runId: string;
  pattern: string;
  base?: string;
}

export async function createWorktree(input: CreateInput): Promise<WorktreeEntry> {
  const { root, runId, pattern } = input;
  const base = input.base ?? 'main';
  await assertGitRepo(root);

  return withManifestMutex(root, async () => {
    const manifest = await readManifest(root);
    const existing = manifest.worktrees.find((w) => w.id === runId);
    if (existing && existing.status === 'active') {
      throw new Error(`Run id "${runId}" already has an active worktree at ${existing.path}.`);
    }

    const relPath = path.posix.join(MANIFEST_DIR, runId);
    const branch = `loop/${runId}`;
    // `git worktree add -b <branch> <path> <base>` creates the branch and checks it
    // out in an isolated worktree. Forward-slash paths are accepted on all platforms.
    await git(['worktree', 'add', '-b', branch, relPath, base], root);

    const entry: WorktreeEntry = {
      id: runId,
      path: relPath,
      branch,
      baseBranch: base,
      pattern,
      createdAt: new Date().toISOString(),
      status: 'active',
    };

    try {
      manifest.worktrees = manifest.worktrees.filter((w) => w.id !== runId);
      manifest.worktrees.push(entry);
      await writeManifest(root, manifest);
    } catch (writeErr) {
      await git(['worktree', 'remove', '--force', relPath], root).catch(() => {});
      await git(['branch', '-D', branch], root).catch(() => {});
      throw writeErr;
    }

    return entry;
  });
}

export interface MarkInput {
  root: string;
  runId: string;
  status: WorktreeStatus;
}

export async function markWorktree(input: MarkInput): Promise<WorktreeEntry> {
  const { root, runId, status } = input;
  if (!VALID_STATUSES.includes(status)) {
    throw new Error(`Invalid status "${status}". Use one of: ${VALID_STATUSES.join(', ')}.`);
  }

  return withManifestMutex(root, async () => {
    const manifest = await readManifest(root);
    const entry = manifest.worktrees.find((w) => w.id === runId);
    if (!entry) {
      throw new Error(`No worktree with run id "${runId}" in ${MANIFEST_FILE}.`);
    }
    entry.status = status;
    await writeManifest(root, manifest);
    return entry;
  });
}

/** Parse a duration like "30m", "24h", "7d" into milliseconds. Shared with lock.ts's --ttl. */
export function parseDurationMs(token: string, flag: string): number {
  const m = /^(\d+)([smhd])$/.exec(token.trim());
  if (!m) {
    throw new Error(`Invalid ${flag} "${token}". Use e.g. 30s, 30m, 24h, 7d.`);
  }
  const n = Number(m[1]);
  const unit = m[2];
  const ms = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;
  return n * ms;
}

export interface CleanupInput {
  root: string;
  statuses?: WorktreeStatus[];
  olderThan?: string;
  force?: boolean;
}

export interface CleanupResult {
  removed: WorktreeEntry[];
  /** Entries git refused to remove (e.g. uncommitted changes) without --force. */
  skipped: { entry: WorktreeEntry; reason: string }[];
}

export async function cleanupWorktrees(input: CleanupInput): Promise<CleanupResult> {
  const { root } = input;
  await assertGitRepo(root);

  return withManifestMutex(root, async () => {
    const statuses = input.statuses ?? CLEANUP_DEFAULT_STATUSES;
    const cutoff = input.olderThan ? Date.now() - parseDurationMs(input.olderThan, '--older-than') : undefined;

    const manifest = await readManifest(root);
    const removed: WorktreeEntry[] = [];
    const skipped: { entry: WorktreeEntry; reason: string }[] = [];

    for (const entry of manifest.worktrees) {
      if (!statuses.includes(entry.status)) continue;
      if (cutoff !== undefined && Date.parse(entry.createdAt) > cutoff) continue;

      const args = ['worktree', 'remove', entry.path];
      if (input.force) args.push('--force');
      try {
        // Without --force, git refuses to remove a worktree with uncommitted or
        // untracked changes. We surface that refusal instead of forcing data loss.
        await git(args, root);
        removed.push(entry);
      } catch (err) {
        skipped.push({ entry, reason: (err as Error).message });
      }
    }

    const removedIds = new Set(removed.map((e) => e.id));
    manifest.worktrees = manifest.worktrees.filter((w) => !removedIds.has(w.id));
    await writeManifest(root, manifest);
    return { removed, skipped };
  });
}

/** Paths (repo-relative, posix) of every worktree git currently knows about. */
async function gitWorktreePaths(root: string): Promise<string[]> {
  const rootReal = await realpath(root);
  const out = await git(['worktree', 'list', '--porcelain', '-z'], root);
  const paths: string[] = [];
  for (const line of out.split('\0')) {
    if (!line.startsWith('worktree ')) continue;
    const abs = line.slice('worktree '.length);
    let absReal: string;
    try {
      absReal = await realpath(abs);
    } catch (err) {
      // git keeps listing a worktree (as "prunable") even after its directory
      // was removed out-of-band -- a manual `rm -rf`, a crash mid-cleanup, a
      // container wipe -- rather than via `git worktree remove`. realpath()
      // on that now-missing path throws ENOENT, which used to propagate out
      // of gc() entirely and abort the exact reconciliation it exists to do.
      // Treat a missing directory as simply absent from disk so it still
      // surfaces as a `dropped` manifest entry instead of crashing gc().
      if ((err as NodeJS.ErrnoException).code === 'ENOENT') continue;
      throw err;
    }
    const rel = path.relative(rootReal, absReal).split(path.sep).join('/');
    paths.push(rel);
  }
  return paths;
}

export interface GcInput {
  root: string;
  force?: boolean;
}

export interface GcResult {
  /** On disk under .loop-worktrees but absent from the manifest. */
  orphans: string[];
  /** In the manifest but no longer on disk; dropped from the manifest. */
  dropped: WorktreeEntry[];
  /** Orphans actually removed (only when force is set). */
  removedOrphans: string[];
}

export async function gc(input: GcInput): Promise<GcResult> {
  const { root } = input;
  await assertGitRepo(root);

  return withManifestMutex(root, async () => {
    const manifest = await readManifest(root);
    const onDisk = await gitWorktreePaths(root);
    const managedOnDisk = onDisk.filter((p) => p.startsWith(`${MANIFEST_DIR}/`));
    const manifestPaths = new Set(manifest.worktrees.map((w) => w.path));

    const orphans = managedOnDisk.filter((p) => !manifestPaths.has(p));
    const dropped = manifest.worktrees.filter((w) => !onDisk.includes(w.path));

    const removedOrphans: string[] = [];
    if (input.force) {
      for (const orphan of orphans) {
        try {
          await git(['worktree', 'remove', '--force', orphan], root);
          removedOrphans.push(orphan);
        } catch {
          // Leave it reported as an orphan if git still refuses.
        }
      }
    }

    if (dropped.length > 0) {
      const droppedIds = new Set(dropped.map((e) => e.id));
      manifest.worktrees = manifest.worktrees.filter((w) => !droppedIds.has(w.id));
      await writeManifest(root, manifest);
    }

    return { orphans, dropped, removedOrphans };
  });
}

export interface ListInput {
  root: string;
  status?: WorktreeStatus;
}

export async function listWorktrees(input: ListInput): Promise<WorktreeEntry[]> {
  const manifest = await readManifest(input.root);
  if (!input.status) return manifest.worktrees;
  return manifest.worktrees.filter((w) => w.status === input.status);
}