@switchyardhq/git-fleet 0.1.0

package/dist/commands/pr.js

@@ -0,0 +1,50 @@
+import { FleetError } from '../lib/errors.js';
+import { dim, ok } from '../lib/format.js';
+import { getMainRepoRoot, gitAt, verifyBranch } from '../lib/git.js';
+import { runFile } from '../lib/proc.js';
+import { getAgent, readState } from '../lib/state.js';
+/**
+ * Push an agent's branch to `origin` and open a pull request via the GitHub
+ * CLI — the review-based alternative to a local `fleet merge`. gh is invoked
+ * as an external binary, never bundled; its availability is verified before
+ * anything is pushed.
+ */
+export async function pr(name, options = {}) {
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const git = gitAt(repoRoot);
+    const state = readState(repoRoot);
+    const record = getAgent(state, name);
+    await verifyBranch(git, record.branch, 'Agent');
+    const base = options.base ?? record.baseBranch;
+    const remotes = await git.getRemotes();
+    if (!remotes.some((r) => r.name === 'origin')) {
+        throw new FleetError('No "origin" remote is configured, so there is nowhere to push the branch.\n' +
+            'Add one with `git remote add origin <url>` and re-run.');
+    }
+    // FLEET_GH exists for tests, which substitute a recording stub for the real
+    // gh binary (network CLIs can't run against a throwaway repo).
+    const [ghBin = 'gh', ...ghPrefix] = (process.env.FLEET_GH ?? 'gh').split(' ');
+    if ((await runFile(ghBin, [...ghPrefix, '--version'], repoRoot, { quiet: true })) !== 0) {
+        throw new FleetError('GitHub CLI (gh) not found. Install it from https://cli.github.com, ' +
+            'or push and open the PR manually:\n' +
+            `  git push -u origin ${record.branch}`);
+    }
+    await git.raw(['push', '-u', 'origin', record.branch]);
+    console.log(ok(`Pushed ${record.branch} to origin.`));
+    const args = [...ghPrefix, 'pr', 'create', '--head', record.branch, '--base', base];
+    if (options.title) {
+        args.push('--title', options.title, '--body', '');
+    }
+    else {
+        args.push('--fill');
+    }
+    if (options.draft)
+        args.push('--draft');
+    console.log(dim(`$ ${ghBin} ${args.join(' ')}`));
+    const exitCode = await runFile(ghBin, args, repoRoot);
+    if (exitCode !== 0) {
+        throw new FleetError(`gh pr create failed (exit ${exitCode}). The branch was pushed — ` +
+            'you can re-run, or open the PR in the browser.');
+    }
+    return { branch: record.branch, base, pushed: true, created: true };
+}

package/dist/commands/remove.js

@@ -0,0 +1,61 @@
+import { existsSync } from 'node:fs';
+import { FleetError } from '../lib/errors.js';
+import { dim, ok, plural } from '../lib/format.js';
+import { branchExists, deleteBranch, getMainRepoRoot, gitAt, isMergedInto, pruneWorktrees, removeWorktree, uncommittedFiles, } from '../lib/git.js';
+import { getAgent, readState, worktreeAbsPath, writeState } from '../lib/state.js';
+export async function remove(name, options = {}) {
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const git = gitAt(repoRoot);
+    const state = readState(repoRoot);
+    const record = getAgent(state, name);
+    const abs = worktreeAbsPath(repoRoot, record);
+    const force = options.force ?? false;
+    // Validate everything before touching anything, so a refusal leaves the
+    // agent fully intact.
+    if (existsSync(abs) && !force) {
+        const dirty = await uncommittedFiles(abs);
+        if (dirty.length > 0) {
+            throw new FleetError(`Agent "${name}" has ${plural(dirty.length, 'uncommitted change')} in ${abs}.\n` +
+                'Commit them in the worktree first, or pass --force to discard them.');
+        }
+    }
+    const branchStillExists = await branchExists(git, record.branch);
+    if (options.deleteBranch && branchStillExists && !force) {
+        const baseExists = await branchExists(git, record.baseBranch);
+        const merged = baseExists && (await isMergedInto(git, record.branch, record.baseBranch));
+        if (!merged) {
+            throw new FleetError(`Branch "${record.branch}" is not fully merged into ${record.baseBranch}.\n` +
+                'Merge it first, or pass --force to delete it anyway (this discards its commits).');
+        }
+    }
+    let worktreeRemoved = false;
+    if (existsSync(abs)) {
+        await removeWorktree(git, abs, force);
+        worktreeRemoved = true;
+    }
+    else {
+        // Directory was deleted manually; clear git's stale bookkeeping so the
+        // branch is no longer considered checked out.
+        await pruneWorktrees(git);
+    }
+    let branchDeleted = false;
+    if (options.deleteBranch && branchStillExists) {
+        // Merge safety was verified above (or --force was passed), so -D is safe here.
+        await deleteBranch(git, record.branch, true);
+        branchDeleted = true;
+    }
+    delete state.agents[name];
+    writeState(repoRoot, state);
+    console.log(ok(`Removed agent ${name}.`));
+    console.log(`  worktree: ${worktreeRemoved ? 'removed' : 'already gone (pruned)'}`);
+    if (branchDeleted) {
+        console.log(`  branch:   ${record.branch} deleted`);
+    }
+    else if (!branchStillExists) {
+        console.log(`  branch:   ${record.branch} was already deleted`);
+    }
+    else {
+        console.log(`  branch:   ${record.branch} kept ${dim('(use --delete-branch to delete it)')}`);
+    }
+    return { name, worktreeRemoved, branchDeleted };
+}

package/dist/commands/spawn.js

@@ -0,0 +1,105 @@
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { readConfig } from '../lib/config.js';
+import { FleetError } from '../lib/errors.js';
+import { bold, dim, ok, warn } from '../lib/format.js';
+import { runShell } from '../lib/proc.js';
+import { addWorktree, branchExists, currentBranch, ensureFleetExcluded, getMainRepoRoot, gitAt, verifyBranch, } from '../lib/git.js';
+import { readState, worktreesDir, writeState } from '../lib/state.js';
+// Names become branch names and directory names, so keep them filesystem- and
+// ref-safe: no slashes, no leading dots, no whitespace.
+const AGENT_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+// Windows refuses these as file names (even with an extension), which would
+// break the worktree directory. Rejected on every platform so a fleet set up
+// on macOS/Linux stays usable from Windows checkouts of the same repo.
+const WINDOWS_RESERVED_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)/i;
+function validateAgentName(name) {
+    if (!AGENT_NAME_RE.test(name)) {
+        throw new FleetError(`Invalid agent name "${name}". Use letters, digits, ".", "_" or "-" ` +
+            '(max 64 chars, starting with a letter or digit).');
+    }
+    // git check-ref-format rules the character set alone doesn't catch: catching
+    // them here gives a clean error instead of a raw `git worktree add` failure.
+    if (name.includes('..') || name.endsWith('.') || name.endsWith('.lock')) {
+        throw new FleetError(`Invalid agent name "${name}". It must form a valid branch name: ` +
+            'no "..", and no trailing "." or ".lock".');
+    }
+    if (WINDOWS_RESERVED_RE.test(name)) {
+        throw new FleetError(`Invalid agent name "${name}". It is a reserved device name on Windows ` +
+            '(CON, PRN, AUX, NUL, COM1-9, LPT1-9) and cannot be a worktree directory.');
+    }
+}
+export async function spawn(name, options = {}) {
+    validateAgentName(name);
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const git = gitAt(repoRoot);
+    const state = readState(repoRoot);
+    const branch = `fleet/${name}`;
+    const existing = state.agents[name];
+    if (existing) {
+        throw new FleetError(`Agent "${name}" already exists (branch ${existing.branch}, worktree ${existing.worktreePath}).\n` +
+            `Pick a different name, or remove it first with \`fleet remove ${name}\`.`);
+    }
+    if (await branchExists(git, branch)) {
+        throw new FleetError(`Branch "${branch}" already exists but is not tracked by Switchyard.\n` +
+            `Delete it (\`git branch -d ${branch}\`) or pick a different agent name.`);
+    }
+    const worktreeAbs = path.join(worktreesDir(repoRoot), name);
+    if (existsSync(worktreeAbs)) {
+        throw new FleetError(`Worktree directory already exists: ${worktreeAbs}\n` +
+            'Remove it or pick a different agent name.');
+    }
+    const config = readConfig(repoRoot);
+    // Precedence: --from flag > .fleetrc.json defaultBase > current branch.
+    let base = options.from ?? config.defaultBase;
+    if (base) {
+        await verifyBranch(git, base, 'Base');
+    }
+    else {
+        base = (await currentBranch(git)) ?? undefined;
+        if (!base) {
+            throw new FleetError('HEAD is detached, so there is no branch to base the agent on. ' +
+                'Pass one explicitly with --from <branch>.');
+        }
+    }
+    await ensureFleetExcluded(repoRoot);
+    mkdirSync(worktreesDir(repoRoot), { recursive: true });
+    await addWorktree(git, worktreeAbs, branch, base);
+    const record = {
+        name,
+        branch,
+        baseBranch: base,
+        worktreePath: path.relative(repoRoot, worktreeAbs).split(path.sep).join('/'),
+        createdAt: new Date().toISOString(),
+    };
+    state.agents[name] = record;
+    writeState(repoRoot, state);
+    console.log(ok(`Spawned agent ${bold(name)}`));
+    console.log(`  branch:   ${branch} ${dim(`(from ${base})`)}`);
+    console.log(`  worktree: ${worktreeAbs}`);
+    // Provision the worktree: gitignored essentials first, then the hook, so
+    // e.g. `postSpawn: "npm ci"` can rely on a copied .npmrc or .env.
+    const copied = [];
+    for (const entry of config.copyOnSpawn ?? []) {
+        const source = path.join(repoRoot, entry);
+        if (!existsSync(source)) {
+            console.log(dim(`  copyOnSpawn: ${entry} not found in the repo root — skipped`));
+            continue;
+        }
+        cpSync(source, path.join(worktreeAbs, entry), { recursive: true });
+        copied.push(entry);
+        console.log(`  copied:   ${entry}`);
+    }
+    let postSpawnExitCode;
+    if (config.postSpawn) {
+        console.log(dim(`  postSpawn: ${config.postSpawn}`));
+        postSpawnExitCode = await runShell(config.postSpawn, worktreeAbs);
+        if (postSpawnExitCode !== 0) {
+            console.log(warn(`  postSpawn hook failed (exit ${postSpawnExitCode}) — the worktree was kept; finish setting it up manually.`));
+        }
+    }
+    console.log('');
+    console.log('Point your agent at it:');
+    console.log(`  cd ${worktreeAbs}`);
+    return { record, worktreePath: worktreeAbs, copied, postSpawnExitCode };
+}

package/dist/commands/status.js

@@ -0,0 +1,46 @@
+import { existsSync } from 'node:fs';
+import { bold, dim, ok, warn } from '../lib/format.js';
+import { aheadBehind, getMainRepoRoot, gitAt, uncommittedFiles, verifyBranch, } from '../lib/git.js';
+import { getAgent, readState, worktreeAbsPath } from '../lib/state.js';
+export async function status(name, options = {}) {
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const git = gitAt(repoRoot);
+    const state = readState(repoRoot);
+    const record = getAgent(state, name);
+    const abs = worktreeAbsPath(repoRoot, record);
+    const worktreeMissing = !existsSync(abs);
+    await verifyBranch(git, record.branch, 'Agent');
+    await verifyBranch(git, record.baseBranch, 'Base');
+    const { ahead, behind } = await aheadBehind(git, record.baseBranch, record.branch);
+    const diffStat = (await git.raw(['diff', '--stat', `${record.baseBranch}...${record.branch}`])).trimEnd();
+    const uncommitted = worktreeMissing ? [] : await uncommittedFiles(abs);
+    const result = { record, ahead, behind, uncommitted, diffStat, worktreeMissing };
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return result;
+    }
+    console.log(bold(`Agent ${record.name}`));
+    console.log(`  branch:   ${record.branch}`);
+    console.log(`  base:     ${record.baseBranch} (${ahead} ahead, ${behind} behind)`);
+    console.log(`  worktree: ${abs}${worktreeMissing ? ` ${warn('(missing)')}` : ''}`);
+    console.log(`  created:  ${record.createdAt}`);
+    console.log('');
+    if (uncommitted.length > 0) {
+        console.log(bold(`Uncommitted changes (${uncommitted.length}):`));
+        for (const f of uncommitted) {
+            console.log(`  ${warn(f.status.padEnd(2))} ${f.path}`);
+        }
+    }
+    else if (!worktreeMissing) {
+        console.log(ok('Working tree clean.'));
+    }
+    console.log('');
+    if (diffStat) {
+        console.log(bold(`Committed changes vs ${record.baseBranch}:`));
+        console.log(diffStat);
+    }
+    else {
+        console.log(dim(`No committed changes vs ${record.baseBranch} yet.`));
+    }
+    return result;
+}

package/dist/commands/sync.js

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import { FleetError } from '../lib/errors.js';
+import { ok, plural } from '../lib/format.js';
+import { aheadBehind, getMainRepoRoot, gitAt, verifyBranch } from '../lib/git.js';
+import { getAgent, readState, worktreeAbsPath } from '../lib/state.js';
+/**
+ * Catch an agent's branch up with its base by merging the base into the
+ * agent's worktree. Same safety contract as `fleet merge`: a conflicted merge
+ * is aborted before the error is reported, never left half-done.
+ */
+export async function sync(name, options = {}) {
+    const repoRoot = await getMainRepoRoot(options.cwd ?? process.cwd());
+    const git = gitAt(repoRoot);
+    const state = readState(repoRoot);
+    const record = getAgent(state, name);
+    await verifyBranch(git, record.branch, 'Agent');
+    await verifyBranch(git, record.baseBranch, 'Base');
+    const abs = worktreeAbsPath(repoRoot, record);
+    if (!existsSync(abs)) {
+        throw new FleetError(`Agent "${name}" has no worktree on disk (${abs}).\n` +
+            'Run `fleet doctor --fix` to reconcile state, or `fleet remove` the agent.');
+    }
+    const wtGit = gitAt(abs);
+    const wtStatus = await wtGit.status();
+    if (wtStatus.conflicted.length > 0) {
+        throw new FleetError(`Agent "${name}" has an unresolved merge in its worktree. Resolve or abort it first.`);
+    }
+    if (wtStatus.files.length > 0) {
+        throw new FleetError(`Agent "${name}" has ${plural(wtStatus.files.length, 'uncommitted change')} in ${abs}.\n` +
+            'Commit them in the worktree first, then re-run `fleet sync`.');
+    }
+    const { behind } = await aheadBehind(git, record.baseBranch, record.branch);
+    if (behind === 0) {
+        console.log(ok(`${record.branch} is already up to date with ${record.baseBranch}.`));
+        return { name, branch: record.branch, base: record.baseBranch, behind: 0, updated: false };
+    }
+    try {
+        await wtGit.merge([record.baseBranch]);
+    }
+    catch (err) {
+        const status = await wtGit.status();
+        if (status.conflicted.length > 0) {
+            // Never leave the worktree mid-merge: abort before reporting.
+            await wtGit.raw(['merge', '--abort']);
+            throw new FleetError(`Merging ${record.baseBranch} into ${record.branch} conflicts in ${plural(status.conflicted.length, 'file')}:\n` +
+                status.conflicted.map((f) => `  ${f}`).join('\n') +
+                `\nThe merge was aborted — ${record.branch} is unchanged. Resolve manually inside ${abs} when ready.`);
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new FleetError(`git merge failed before starting: ${message}`);
+    }
+    console.log(ok(`Merged ${record.baseBranch} into ${record.branch}`) +
+        ` (caught up ${plural(behind, 'commit')}).`);
+    return { name, branch: record.branch, base: record.baseBranch, behind, updated: true };
+}

package/dist/commands/watch.js

@@ -0,0 +1,46 @@
+import { DEFAULT_WATCH_INTERVAL, readConfig } from '../lib/config.js';
+import { FleetError } from '../lib/errors.js';
+import { CLEAR_SCREEN, dim } from '../lib/format.js';
+import { getMainRepoRoot } from '../lib/git.js';
+import { buildListTable, collectListings } from './list.js';
+/** Precedence: --interval flag > .fleetrc.json watchInterval > built-in default. */
+export function resolveWatchInterval(flag, config) {
+    if (flag !== undefined && (!Number.isFinite(flag) || flag <= 0)) {
+        throw new FleetError('Invalid --interval. Pass a positive number of seconds, e.g. --interval 5.');
+    }
+    return flag ?? config.watchInterval ?? DEFAULT_WATCH_INTERVAL;
+}
+/** One frame of `fleet watch`: a header plus the exact table `fleet list` prints. */
+export async function renderWatchFrame(options = {}, now = new Date()) {
+    const listings = await collectListings(options);
+    const header = dim(`fleet watch — ${now.toISOString().slice(11, 19)} UTC — Ctrl+C to exit`);
+    const body = listings.length === 0
+        ? 'No active agents. Run `fleet spawn <name>` to create one.'
+        : buildListTable(listings);
+    return `${header}\n${body}`;
+}
+/** Re-render `fleet list` on an interval until Ctrl+C. */
+export async function watch(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const repoRoot = await getMainRepoRoot(cwd);
+    const config = readConfig(repoRoot);
+    const intervalSeconds = resolveWatchInterval(options.interval, config);
+    const render = async () => {
+        const frame = await renderWatchFrame({ cwd });
+        process.stdout.write(CLEAR_SCREEN);
+        console.log(frame);
+        console.log(dim(`refreshing every ${intervalSeconds}s`));
+    };
+    await render();
+    // Chained timeouts rather than setInterval, so a render that takes longer
+    // than the interval can never overlap the next one. Resolves never; the
+    // process ends on Ctrl+C (or the promise rejects on a render error).
+    return new Promise((_resolve, reject) => {
+        const scheduleNext = () => {
+            setTimeout(() => {
+                render().then(scheduleNext, reject);
+            }, intervalSeconds * 1000);
+        };
+        scheduleNext();
+    });
+}

package/dist/lib/config.js

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { FleetError } from './errors.js';
+export const CONFIG_FILE = '.fleetrc.json';
+export const DEFAULT_WATCH_INTERVAL = 3;
+export const DEFAULT_AUTO_CLEAN = false;
+const VALID_KEYS = 'defaultBase, watchInterval, autoClean, copyOnSpawn, postSpawn, preMerge';
+export function configPath(repoRoot) {
+    return path.join(repoRoot, CONFIG_FILE);
+}
+/** Read and validate `.fleetrc.json`. A missing file is fine; a broken one is not. */
+export function readConfig(repoRoot) {
+    const file = configPath(repoRoot);
+    if (!existsSync(file)) {
+        return {};
+    }
+    // Strip a UTF-8 BOM: Windows editors add one and JSON.parse rejects it.
+    const raw = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new FleetError(`Config file is not valid JSON: ${file}\nFix the syntax or delete the file to fall back to defaults.`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new FleetError(`Config file must contain a JSON object: ${file}`);
+    }
+    const config = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        switch (key) {
+            case '$schema':
+                // Editor-only pointer to a JSON schema (shipped as schema/fleetrc.schema.json).
+                if (typeof value !== 'string') {
+                    throw new FleetError(`"$schema" in ${CONFIG_FILE} must be a string (schema URL).`);
+                }
+                break;
+            case 'defaultBase':
+                if (typeof value !== 'string' || value.trim() === '') {
+                    throw new FleetError(`"defaultBase" in ${CONFIG_FILE} must be a non-empty string (branch name).`);
+                }
+                config.defaultBase = value;
+                break;
+            case 'watchInterval':
+                if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+                    throw new FleetError(`"watchInterval" in ${CONFIG_FILE} must be a positive number of seconds.`);
+                }
+                config.watchInterval = value;
+                break;
+            case 'autoClean':
+                if (typeof value !== 'boolean') {
+                    throw new FleetError(`"autoClean" in ${CONFIG_FILE} must be true or false.`);
+                }
+                config.autoClean = value;
+                break;
+            case 'copyOnSpawn': {
+                if (!Array.isArray(value) || value.some((v) => typeof v !== 'string' || v.trim() === '')) {
+                    throw new FleetError(`"copyOnSpawn" in ${CONFIG_FILE} must be an array of non-empty path strings.`);
+                }
+                const entries = value;
+                for (const entry of entries) {
+                    if (path.isAbsolute(entry) || entry.split(/[\\/]/).includes('..')) {
+                        throw new FleetError(`"copyOnSpawn" entry "${entry}" in ${CONFIG_FILE} must be a relative path inside the repository.`);
+                    }
+                }
+                config.copyOnSpawn = entries;
+                break;
+            }
+            case 'postSpawn':
+                if (typeof value !== 'string' || value.trim() === '') {
+                    throw new FleetError(`"postSpawn" in ${CONFIG_FILE} must be a non-empty command string.`);
+                }
+                config.postSpawn = value;
+                break;
+            case 'preMerge':
+                if (typeof value !== 'string' || value.trim() === '') {
+                    throw new FleetError(`"preMerge" in ${CONFIG_FILE} must be a non-empty command string.`);
+                }
+                config.preMerge = value;
+                break;
+            default:
+                throw new FleetError(`Unknown key "${key}" in ${CONFIG_FILE}. Valid keys: ${VALID_KEYS}.`);
+        }
+    }
+    return config;
+}

package/dist/lib/errors.js

@@ -0,0 +1,10 @@
+/**
+ * An expected, user-facing failure (bad input, missing agent, dirty worktree, …).
+ * The CLI prints the message in red and exits 1 — no stack trace.
+ */
+export class FleetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FleetError';
+    }
+}

package/dist/lib/format.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+export function table(head, rows) {
+    const t = new Table({
+        head: head.map((h) => chalk.bold(h)),
+        style: { head: [], border: [] },
+        wordWrap: true,
+    });
+    t.push(...rows);
+    return t.toString();
+}
+/** ANSI clear screen + scrollback + cursor home; used between `fleet watch` frames. */
+export const CLEAR_SCREEN = '\x1b[2J\x1b[3J\x1b[H';
+export const ok = (msg) => chalk.green(msg);
+export const warn = (msg) => chalk.yellow(msg);
+export const fail = (msg) => chalk.red(msg);
+export const dim = (msg) => chalk.dim(msg);
+export const bold = (msg) => chalk.bold(msg);
+export function plural(n, singular, pluralForm = `${singular}s`) {
+    return `${n} ${n === 1 ? singular : pluralForm}`;
+}
+/** "just now", "5m ago", "3h ago", "2d ago", then a date for anything older. */
+export function relativeTime(iso, now = new Date()) {
+    if (!iso)
+        return '—';
+    const then = new Date(iso);
+    if (Number.isNaN(then.getTime()))
+        return '—';
+    const seconds = Math.round((now.getTime() - then.getTime()) / 1000);
+    if (seconds < 0)
+        return then.toISOString();
+    if (seconds < 60)
+        return 'just now';
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.round(hours / 24);
+    if (days < 30)
+        return `${days}d ago`;
+    return then.toISOString().slice(0, 10);
+}

package/dist/lib/git.js

@@ -0,0 +1,142 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { simpleGit } from 'simple-git';
+import { FleetError } from './errors.js';
+export function gitAt(dir) {
+    return simpleGit({ baseDir: dir });
+}
+/**
+ * Resolve the root of the *main* repository from any directory inside it —
+ * including from inside a linked worktree, so every `fleet` command works when
+ * run from `.fleet/worktrees/<agent>/`.
+ */
+export async function getMainRepoRoot(cwd) {
+    let out;
+    try {
+        out = await simpleGit({ baseDir: cwd }).raw([
+            'rev-parse',
+            '--path-format=absolute',
+            '--show-toplevel',
+            '--git-common-dir',
+        ]);
+    }
+    catch {
+        throw new FleetError(`Not inside a git repository: ${cwd}\n` +
+            'Switchyard manages worktrees of an existing repository. ' +
+            '`cd` into one (or run `git init`) and try again.');
+    }
+    const [toplevel, commonDir] = out
+        .trim()
+        .split('\n')
+        .map((line) => line.trim());
+    if (!toplevel) {
+        throw new FleetError(`Could not resolve the repository root from ${cwd}.`);
+    }
+    // In a linked worktree, --show-toplevel is the worktree itself; the main
+    // repo root is the parent of the shared .git directory.
+    if (commonDir && path.basename(commonDir) === '.git') {
+        return path.resolve(path.dirname(commonDir));
+    }
+    return path.resolve(toplevel);
+}
+export async function branchExists(git, branch) {
+    // Decide from stdout, not the exit code: quiet git commands exit non-zero
+    // with empty stderr, which simple-git does not surface as an error.
+    const out = await git.raw(['branch', '--list', branch, '--format=%(refname:short)']);
+    return out.trim().length > 0;
+}
+export async function verifyBranch(git, branch, label) {
+    if (!(await branchExists(git, branch))) {
+        throw new FleetError(`${label} branch "${branch}" does not exist in this repository.`);
+    }
+}
+/** Current branch name, or null when HEAD is detached. */
+export async function currentBranch(git) {
+    const name = (await git.revparse(['--abbrev-ref', 'HEAD'])).trim();
+    return name === 'HEAD' ? null : name;
+}
+/** Fall back to main/master when an agent has no recorded base branch. */
+export async function defaultBaseBranch(git) {
+    for (const candidate of ['main', 'master']) {
+        if (await branchExists(git, candidate))
+            return candidate;
+    }
+    throw new FleetError('Could not find a "main" or "master" branch to diff against. Pass one explicitly with --base <branch>.');
+}
+export async function addWorktree(git, worktreePath, branch, base) {
+    await git.raw(['worktree', 'add', worktreePath, '-b', branch, base]);
+}
+export async function removeWorktree(git, worktreePath, force) {
+    const args = ['worktree', 'remove'];
+    if (force)
+        args.push('--force');
+    args.push(worktreePath);
+    await git.raw(args);
+}
+/** Clear git's bookkeeping for worktrees whose directories were deleted manually. */
+export async function pruneWorktrees(git) {
+    await git.raw(['worktree', 'prune']);
+}
+export async function deleteBranch(git, branch, force) {
+    await git.raw(['branch', force ? '-D' : '-d', branch]);
+}
+/** Commits on `branch` not on `base` (ahead) and vice versa (behind). */
+export async function aheadBehind(git, base, branch) {
+    const out = await git.raw(['rev-list', '--left-right', '--count', `${base}...${branch}`]);
+    const parts = out.trim().split(/\s+/);
+    return { behind: Number(parts[0] ?? 0), ahead: Number(parts[1] ?? 0) };
+}
+/** Files changed by commits on `branch` since it diverged from `base` (merge-base diff). */
+export async function changedFilesVsBase(git, base, branch) {
+    const out = await git.raw(['diff', '--name-only', `${base}...${branch}`]);
+    return out
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+/** Modified, staged, and untracked files in a worktree. */
+export async function uncommittedFiles(worktreeDir) {
+    const status = await gitAt(worktreeDir).status();
+    return status.files.map((f) => ({
+        path: f.path,
+        status: `${f.index}${f.working_dir}`.trim(),
+    }));
+}
+/** ISO timestamp of the last commit on `ref`, or null if the ref has no commits. */
+export async function lastCommitISO(git, ref) {
+    try {
+        const out = await git.raw(['log', '-1', '--format=%cI', ref, '--']);
+        return out.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when every commit on `branch` is already reachable from `base`. */
+export async function isMergedInto(git, branch, base) {
+    // Not `merge-base --is-ancestor`: it answers via exit code with empty
+    // stderr, which simple-git does not surface as an error. Count commits on
+    // `branch` that `base` can't reach instead — zero means fully merged.
+    const out = await git.raw(['rev-list', '--count', `${base}..${branch}`]);
+    return Number(out.trim()) === 0;
+}
+/**
+ * Ensure `.fleet/` is ignored via `.git/info/exclude` so Switchyard never dirties
+ * the repos it manages — even ones whose .gitignore doesn't mention it.
+ */
+export async function ensureFleetExcluded(repoRoot) {
+    const commonDirRaw = await gitAt(repoRoot).raw([
+        'rev-parse',
+        '--path-format=absolute',
+        '--git-common-dir',
+    ]);
+    const infoDir = path.join(commonDirRaw.trim(), 'info');
+    const excludeFile = path.join(infoDir, 'exclude');
+    const entry = '.fleet/';
+    const current = existsSync(excludeFile) ? readFileSync(excludeFile, 'utf8') : '';
+    if (current.split(/\r?\n/).some((line) => line.trim() === entry))
+        return;
+    mkdirSync(infoDir, { recursive: true });
+    const prefix = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
+    appendFileSync(excludeFile, `${prefix}# added by fleet\n${entry}\n`, 'utf8');
+}