@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/worktrees/service.js

@@ -0,0 +1,483 @@
+// Managed git worktrees (PROP-0016). A session can work in its own checkout of a repository so its
+// edits never touch the person's main checkout: managed worktrees are disposable and pruned to the
+// most recent few, permanent ones stay until a person removes them, and nothing with work in it is
+// removed without a snapshot it can be restored from.
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { HarnessError, invalid, notFound } from "../core/errors.js";
+import { newId, now, readJsonOr, writeJson } from "../core/fs.js";
+import { copyFiles, ignoredFiles, includedFiles, untrackedFiles } from "./copy.js";
+import { git, gitText, nulList } from "./git.js";
+import { runSetup, SetupTrust } from "./setup.js";
+const NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const SNAPSHOT_REF = 'refs/xharness/snapshots';
+const IDENTITY = { GIT_AUTHOR_NAME: 'Xingular Harness', GIT_AUTHOR_EMAIL: 'harness@localhost', GIT_COMMITTER_NAME: 'Xingular Harness', GIT_COMMITTER_EMAIL: 'harness@localhost' };
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+function slug(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'repo';
+}
+/** Paths in `git status --porcelain=v1 -z` output; a rename's original path is not counted. */
+function statusPaths(output) {
+    const items = nulList(output);
+    const paths = [];
+    for (let index = 0; index < items.length; index += 1) {
+        const entry = items[index];
+        paths.push(entry.slice(3));
+        if (entry[0] === 'R' || entry[0] === 'C')
+            index += 1;
+    }
+    return paths;
+}
+export class Worktrees {
+    root;
+    branchPrefix;
+    keep;
+    registryFile;
+    trust;
+    leaseCounts = new Map();
+    chain = Promise.resolve();
+    constructor(stateDir, options = {}) {
+        this.root = options.root ?? join(stateDir, 'worktrees');
+        this.branchPrefix = options.branchPrefix ?? 'wt/';
+        this.keep = options.keep ?? 15;
+        this.registryFile = join(stateDir, 'worktrees.json');
+        this.trust = new SetupTrust(join(stateDir, 'worktree-setup-trust.json'));
+        this.recover(true);
+    }
+    // ---- Registry -------------------------------------------------------------------------------
+    read() {
+        const registry = readJsonOr(this.registryFile, { version: 1, worktrees: [] });
+        return Array.isArray(registry.worktrees) ? registry : { version: 1, worktrees: [] };
+    }
+    write(registry) {
+        writeJson(this.registryFile, registry);
+    }
+    update(id, change) {
+        const registry = this.read();
+        const record = registry.worktrees.find((entry) => entry.id === id);
+        if (!record)
+            throw notFound(`Worktree ${id}`);
+        change(record);
+        this.write(registry);
+        return record;
+    }
+    /** Runs changes one at a time, so two requests never race on the registry or on git. */
+    serial(work) {
+        const next = this.chain.then(work, work);
+        this.chain = next.catch(() => undefined);
+        return next;
+    }
+    /** Releases leases whose process is gone. At start-up, this process's own leases are stale too. */
+    recover(startup = false) {
+        const registry = this.read();
+        const released = [];
+        for (const record of registry.worktrees) {
+            if (!record.lease)
+                continue;
+            if (alive(record.lease.pid) && !(startup && record.lease.pid === process.pid))
+                continue;
+            record.lease = null;
+            this.leaseCounts.delete(record.id);
+            released.push(record.id);
+            if (existsSync(record.path))
+                void git(record.path, ['worktree', 'unlock', record.path], { allowFail: true }).catch(() => undefined);
+        }
+        if (released.length)
+            this.write(registry);
+        return released;
+    }
+    get(id) {
+        const record = this.read().worktrees.find((entry) => entry.id === id);
+        if (!record)
+            throw notFound(`Worktree ${id}`);
+        return record;
+    }
+    active(id) {
+        const record = this.get(id);
+        if (record.removed)
+            throw new HarnessError('worktree_removed', `Worktree ${record.name} was removed.`, 'Restore it first.');
+        return record;
+    }
+    /** The folder for a registered worktree; unknown ids remain opaque to the caller. */
+    pathOf(id) {
+        const record = this.read().worktrees.find((entry) => entry.id === id);
+        if (!record)
+            return null;
+        if (record.removed)
+            throw new HarnessError('worktree_removed', `Worktree ${record.name} was removed.`, 'Restore it first.');
+        if (!existsSync(record.path))
+            throw new HarnessError('worktree_missing', `The folder of worktree ${record.name} is gone.`, 'Remove it, or restore it.');
+        return record.path;
+    }
+    /** The top folder of the repository a folder belongs to (the main checkout, for a linked worktree). */
+    async repositoryOf(folder) {
+        const known = this.read().worktrees.find((entry) => !entry.removed && real(entry.path) === real(folder));
+        if (known)
+            return known.repoRoot;
+        const top = await git(folder, ['rev-parse', '--show-toplevel'], { allowFail: true });
+        if (top.code !== 0)
+            throw new HarnessError('not_a_repository', `${folder} is not inside a git repository.`, 'Worktrees need a git repository with at least one commit.');
+        const gitDir = await gitText(folder, ['rev-parse', '--absolute-git-dir']);
+        const common = resolve(top.stdout.trim(), await gitText(folder, ['rev-parse', '--git-common-dir']));
+        if (real(gitDir) === real(common))
+            return real(top.stdout.trim());
+        const main = (await gitText(folder, ['worktree', 'list', '--porcelain'])).split('\n').find((line) => line.startsWith('worktree '));
+        return real(main ? main.slice('worktree '.length) : top.stdout.trim());
+    }
+    async list(repo) {
+        const root = repo ? await this.repositoryOf(repo) : null;
+        return this.read().worktrees.filter((record) => !record.removed && (!root || record.repoRoot === root));
+    }
+    /** Worktrees removed with a snapshot, which `restore` can bring back. */
+    removed(repo) {
+        return this.read().worktrees.filter((record) => record.removed && (!repo || record.repoRoot === real(repo)));
+    }
+    async status(id) {
+        const record = this.get(id);
+        if (record.removed || !existsSync(record.path))
+            return { record, exists: false, head: null, changes: 0, ahead: 0 };
+        const head = (await git(record.path, ['rev-parse', 'HEAD'], { allowFail: true })).stdout.trim() || null;
+        const changes = statusPaths((await git(record.path, ['status', '--porcelain=v1', '-z', '--untracked-files=all'])).stdout).length;
+        const ahead = head ? Number((await git(record.path, ['rev-list', '--count', `${record.baseCommit}..HEAD`], { allowFail: true })).stdout.trim() || 0) : 0;
+        return { record, exists: true, head, changes, ahead };
+    }
+    // ---- Create and adopt -----------------------------------------------------------------------
+    repoKey(repoRoot) {
+        return `${slug(basename(repoRoot))}-${createHash('sha256').update(repoRoot).digest('hex').slice(0, 8)}`;
+    }
+    uniqueName(repoRoot, wanted) {
+        const taken = new Set(this.read().worktrees.filter((record) => record.repoRoot === repoRoot && !record.removed).map((record) => record.name));
+        const folder = join(this.root, this.repoKey(repoRoot));
+        if (wanted !== undefined) {
+            if (!NAME.test(wanted))
+                throw invalid('A worktree name uses lowercase letters, digits and dashes (at most 63).');
+            if (taken.has(wanted) || existsSync(join(folder, wanted)))
+                throw new HarnessError('worktree_exists', `A worktree named ${wanted} already exists.`);
+            return wanted;
+        }
+        for (;;) {
+            const name = `wt-${randomBytes(3).toString('hex')}`;
+            if (!taken.has(name) && !existsSync(join(folder, name)))
+                return name;
+        }
+    }
+    async branchName(repoRoot, name) {
+        const full = `${this.branchPrefix}${name}`;
+        const check = await git(repoRoot, ['check-ref-format', '--branch', full], { allowFail: true });
+        if (check.code !== 0)
+            throw invalid(`${full} is not a valid branch name.`);
+        if ((await git(repoRoot, ['rev-parse', '--verify', '-q', `refs/heads/${full}`], { allowFail: true })).code === 0)
+            throw new HarnessError('branch_exists', `Branch ${full} already exists.`);
+        return full;
+    }
+    create(input) {
+        return this.serial(async () => {
+            if (!input?.repo)
+                throw invalid('A repository folder is required.');
+            const repoRoot = await this.repositoryOf(input.repo);
+            if ((await git(repoRoot, ['rev-parse', '--verify', '-q', 'HEAD^{commit}'], { allowFail: true })).code !== 0) {
+                throw new HarnessError('repository_empty', 'This repository has no commit yet, so a worktree cannot be made from it.');
+            }
+            const name = this.uniqueName(repoRoot, input.name);
+            const baseRef = input.baseRef || 'HEAD';
+            const baseCommit = (await git(repoRoot, ['rev-parse', '--verify', '-q', `${baseRef}^{commit}`], { allowFail: true })).stdout.trim();
+            if (!baseCommit)
+                throw invalid(`${baseRef} does not name a commit.`);
+            const branch = input.branch ? await this.branchName(repoRoot, input.branch) : null;
+            const path = join(this.root, this.repoKey(repoRoot), name);
+            mkdirSync(dirname(path), { recursive: true });
+            await git(repoRoot, ['worktree', 'add', ...(branch ? ['-b', branch] : ['--detach']), path, baseCommit]);
+            const at = now();
+            const record = {
+                id: newId(), repoRoot, path, name, branch, baseRef, baseCommit, kind: input.kind ?? 'managed', origin: 'created',
+                createdAt: at, lastUsedAt: at, lease: null, removed: null
+            };
+            const registry = this.read();
+            registry.worktrees.push(record);
+            this.write(registry);
+            let patched = false;
+            let carried = { copied: [], skipped: [] };
+            if (input.carryChanges ?? baseRef === 'HEAD') {
+                const patch = (await git(repoRoot, ['diff', '--binary', 'HEAD'])).stdout;
+                if (patch.trim())
+                    patched = (await git(path, ['apply', '--binary', '--whitespace=nowarn'], { input: patch, allowFail: true })).code === 0;
+                carried = copyFiles(repoRoot, path, await untrackedFiles(repoRoot));
+            }
+            const included = copyFiles(repoRoot, path, await includedFiles(repoRoot));
+            const setup = input.setup === false
+                ? { state: 'none', hash: null, log: null }
+                : await runSetup({ checkout: path, source: repoRoot, name, repoRoot, logFile: join(this.root, 'logs', `${record.id}.setup.log`), trust: this.trust });
+            return { worktree: record, carried: { ...carried, patched }, included, setup };
+        });
+    }
+    adopt(path) {
+        return this.serial(async () => {
+            if (!path || !isAbsolute(path))
+                throw invalid('An absolute worktree folder is required.');
+            const folder = real(path);
+            const known = this.read().worktrees.find((record) => !record.removed && real(record.path) === folder);
+            if (known)
+                return known;
+            const top = await git(folder, ['rev-parse', '--show-toplevel'], { allowFail: true });
+            if (top.code !== 0 || real(top.stdout.trim()) !== folder)
+                throw new HarnessError('not_a_worktree', `${path} is not the top folder of a git worktree.`);
+            const repoRoot = await this.repositoryOf(folder);
+            if (repoRoot === folder)
+                throw new HarnessError('not_a_worktree', `${path} is a repository's main checkout, not a linked worktree.`);
+            const branch = (await git(folder, ['symbolic-ref', '-q', '--short', 'HEAD'], { allowFail: true })).stdout.trim() || null;
+            const head = await gitText(folder, ['rev-parse', 'HEAD']);
+            const taken = new Set(this.read().worktrees.filter((record) => record.repoRoot === repoRoot && !record.removed).map((record) => record.name));
+            let name = slug(basename(folder)).slice(0, 56) || 'adopted';
+            if (!/^[a-z0-9]/.test(name))
+                name = `w-${name}`;
+            for (let suffix = 2; taken.has(name); suffix += 1)
+                name = `${name.replace(/-\d+$/, '')}-${suffix}`;
+            const at = now();
+            const record = {
+                id: newId(), repoRoot, path: folder, name, branch, baseRef: 'HEAD', baseCommit: head, kind: 'permanent', origin: 'adopted',
+                createdAt: at, lastUsedAt: at, lease: null, removed: null
+            };
+            const registry = this.read();
+            registry.worktrees.push(record);
+            this.write(registry);
+            return record;
+        });
+    }
+    // ---- Use ------------------------------------------------------------------------------------
+    /** A session starts using a worktree. Another live session's lease refuses it. */
+    acquire(id, holder) {
+        return this.serial(async () => {
+            const record = this.active(id);
+            if (!existsSync(record.path))
+                throw new HarnessError('worktree_missing', `The folder of worktree ${record.name} is gone.`, 'Remove it, or restore it.');
+            if (record.lease && record.lease.holder !== holder && alive(record.lease.pid)) {
+                throw new HarnessError('worktree_in_use', `Worktree ${record.name} is in use by another session.`);
+            }
+            const sameLiveLease = record.lease?.holder === holder && alive(record.lease.pid);
+            const previousCount = sameLiveLease ? this.leaseCounts.get(id) ?? 1 : 0;
+            const updated = this.update(id, (entry) => {
+                entry.lease = { holder, pid: process.pid, at: now() };
+                entry.lastUsedAt = now();
+            });
+            this.leaseCounts.set(id, previousCount + 1);
+            try {
+                await git(record.path, ['worktree', 'lock', '--reason', 'in use by a Xingular Harness session', record.path], { allowFail: true });
+            }
+            catch (error) {
+                if (previousCount)
+                    this.leaseCounts.set(id, previousCount);
+                else {
+                    this.leaseCounts.delete(id);
+                    this.update(id, (entry) => { entry.lease = null; });
+                }
+                throw error;
+            }
+            return updated;
+        });
+    }
+    release(id, holder) {
+        return this.serial(async () => {
+            const record = this.read().worktrees.find((entry) => entry.id === id);
+            if (!record?.lease || record.lease.holder !== holder)
+                return;
+            const count = this.leaseCounts.get(id) ?? 1;
+            if (count > 1) {
+                this.leaseCounts.set(id, count - 1);
+                return;
+            }
+            this.leaseCounts.delete(id);
+            this.update(id, (entry) => { entry.lease = null; });
+            if (existsSync(record.path))
+                await git(record.path, ['worktree', 'unlock', record.path], { allowFail: true });
+        });
+    }
+    branch(id, name) {
+        return this.serial(async () => {
+            const record = this.active(id);
+            if (record.branch)
+                throw new HarnessError('branch_exists', `Worktree ${record.name} is already on branch ${record.branch}.`);
+            const full = await this.branchName(record.repoRoot, name);
+            await git(record.path, ['switch', '-c', full]);
+            return this.update(id, (entry) => { entry.branch = full; });
+        });
+    }
+    // ---- Remove, restore, prune -----------------------------------------------------------------
+    async reachable(checkout, commit) {
+        const refs = await git(checkout, ['for-each-ref', '--count=1', `--contains=${commit}`, 'refs/heads', 'refs/tags', 'refs/remotes'], { allowFail: true });
+        return refs.code === 0 && refs.stdout.trim().length > 0;
+    }
+    /** Records the worktree's commits and working changes under a snapshot ref. */
+    async snapshot(record, ignored) {
+        const index = join(tmpdir(), `xharness-index-${record.id}-${randomBytes(4).toString('hex')}`);
+        const env = { ...IDENTITY, GIT_INDEX_FILE: index };
+        try {
+            await git(record.path, ['read-tree', 'HEAD'], { env });
+            await git(record.path, ['add', '-A'], { env });
+            if (ignored.length) {
+                const pathspecs = Buffer.from(ignored.map((path) => `:(literal)${path}\0`).join(''));
+                await git(record.path, ['add', '--force', '--pathspec-from-file=-', '--pathspec-file-nul'], { env, input: pathspecs });
+            }
+            const tree = await gitText(record.path, ['write-tree'], { env });
+            const commit = await gitText(record.path, ['commit-tree', tree, '-p', 'HEAD', '-m', `Xingular Harness snapshot of worktree ${record.name}`], { env });
+            const ref = `${SNAPSHOT_REF}/${record.id}`;
+            await git(record.path, ['update-ref', ref, commit]);
+            return ref;
+        }
+        finally {
+            rmSync(index, { force: true });
+        }
+    }
+    remove(id, options = {}) {
+        return this.serial(() => this.removeNow(id, options.force === true));
+    }
+    async removeNow(id, force) {
+        const record = this.active(id);
+        // Several sessions share one process in an embedding host, so a lease of a live process always counts.
+        if (record.lease && alive(record.lease.pid)) {
+            throw new HarnessError('worktree_in_use', `Worktree ${record.name} is in use by a session.`, 'End that session first.');
+        }
+        let head = record.baseCommit;
+        let snapshot = null;
+        if (existsSync(record.path)) {
+            const ignored = await ignoredFiles(record.path);
+            const status = await this.status(id);
+            head = status.head ?? head;
+            const work = status.changes > 0 || ignored.length > 0 || !(await this.reachable(record.path, head));
+            if (work && !force) {
+                throw new HarnessError('worktree_has_work', `Worktree ${record.name} has ${status.changes} changed path(s), ${ignored.length} ignored file(s), or commits on no branch.`, 'Remove it with force to keep a snapshot you can restore.');
+            }
+            if (work)
+                snapshot = await this.snapshot(record, ignored);
+            await git(record.repoRoot, ['worktree', 'unlock', record.path], { allowFail: true });
+            const removed = await git(record.repoRoot, ['worktree', 'remove', '--force', record.path], { allowFail: true });
+            if (removed.code !== 0 && existsSync(record.path) && record.path.startsWith(this.root + '/'))
+                rmSync(record.path, { recursive: true, force: true });
+        }
+        await git(record.repoRoot, ['worktree', 'prune'], { allowFail: true });
+        const worktree = this.update(id, (entry) => {
+            entry.lease = null;
+            entry.removed = { at: now(), head, snapshot };
+        });
+        this.leaseCounts.delete(id);
+        return { worktree, snapshot };
+    }
+    restore(id) {
+        return this.serial(async () => {
+            const record = this.get(id);
+            if (!record.removed)
+                throw new HarnessError('worktree_active', `Worktree ${record.name} was not removed.`);
+            if (existsSync(record.path))
+                throw new HarnessError('worktree_exists', `${record.path} already exists.`);
+            const { snapshot, head } = record.removed;
+            const start = snapshot ? await gitText(record.repoRoot, ['rev-parse', `${snapshot}^`]) : head;
+            const onBranch = record.branch && (await git(record.repoRoot, ['rev-parse', '--verify', '-q', `refs/heads/${record.branch}`], { allowFail: true })).stdout.trim() === start;
+            mkdirSync(dirname(record.path), { recursive: true });
+            await git(record.repoRoot, ['worktree', 'add', ...(onBranch ? [record.path, record.branch] : ['--detach', record.path, start])]);
+            if (snapshot) {
+                await git(record.path, ['read-tree', '-u', '--reset', snapshot]);
+                await git(record.path, ['reset', '-q']);
+            }
+            return this.update(id, (entry) => {
+                entry.removed = null;
+                entry.branch = onBranch ? entry.branch : null;
+                entry.lastUsedAt = now();
+            });
+        });
+    }
+    /** Keeps the most recently used managed worktrees of each repository and removes the rest, with snapshots. */
+    prune(options = {}) {
+        return this.serial(async () => {
+            const keep = Math.max(0, options.keep ?? this.keep);
+            const root = options.repo ? await this.repositoryOf(options.repo) : null;
+            const groups = new Map();
+            for (const record of this.read().worktrees) {
+                if (record.removed || record.kind !== 'managed' || (root && record.repoRoot !== root))
+                    continue;
+                groups.set(record.repoRoot, [...(groups.get(record.repoRoot) ?? []), record]);
+            }
+            const removed = [];
+            const failed = [];
+            for (const records of groups.values()) {
+                const older = records.sort((left, right) => right.lastUsedAt.localeCompare(left.lastUsedAt)).slice(keep);
+                for (const record of older) {
+                    if (record.lease && alive(record.lease.pid))
+                        continue;
+                    try {
+                        removed.push(await this.removeNow(record.id, true));
+                    }
+                    catch (error) {
+                        failed.push({ id: record.id, error: error instanceof Error ? error.message : String(error) });
+                    }
+                }
+            }
+            return { removed, failed };
+        });
+    }
+    // ---- Handoff --------------------------------------------------------------------------------
+    /**
+     * Moves work between the worktree and the main checkout. `toSource` brings the worktree's changes
+     * since it started (commits and working changes) to the main checkout; `toWorktree` brings the
+     * main checkout's uncommitted changes to the worktree. The target must have no tracked changes,
+     * and nothing changes when the patch does not apply. With `move` (the default), what was handed
+     * off is stashed away from the origin, where `git stash` can bring it back.
+     */
+    handoff(id, direction, options = {}) {
+        return this.serial(async () => {
+            if (direction !== 'toSource' && direction !== 'toWorktree')
+                throw invalid('direction is toSource or toWorktree.');
+            const record = this.active(id);
+            if (!existsSync(record.path))
+                throw new HarnessError('worktree_missing', `The folder of worktree ${record.name} is gone.`);
+            const origin = direction === 'toSource' ? record.path : record.repoRoot;
+            const target = direction === 'toSource' ? record.repoRoot : record.path;
+            const dirty = (await gitText(target, ['status', '--porcelain', '--untracked-files=no'])).length > 0;
+            if (dirty)
+                throw new HarnessError('handoff_target_dirty', `The ${direction === 'toSource' ? 'main checkout' : 'worktree'} has uncommitted changes.`, 'Commit or stash them, then hand off again.');
+            const patch = (await git(origin, ['diff', '--binary', direction === 'toSource' ? record.baseCommit : 'HEAD'])).stdout;
+            const untracked = await untrackedFiles(origin);
+            const collisions = untracked.filter((path) => existsSync(join(target, path)));
+            if (collisions.length)
+                throw new HarnessError('handoff_conflict', `${collisions.length} untracked file(s) already exist in the target, for example ${collisions[0]}.`);
+            if (patch.trim()) {
+                const check = await git(target, ['apply', '--check', '--binary', '--whitespace=nowarn'], { input: patch, allowFail: true });
+                if (check.code !== 0)
+                    throw new HarnessError('handoff_conflict', `The changes do not apply cleanly: ${check.stderr.trim()}`, 'Bring the two checkouts to the same commit, or commit and merge instead.');
+                await git(target, ['apply', '--binary', '--whitespace=nowarn'], { input: patch });
+            }
+            const copied = copyFiles(origin, target, untracked).copied;
+            let stash = null;
+            if (options.move !== false && (patch.trim() || untracked.length)) {
+                const before = (await git(origin, ['rev-parse', '-q', '--verify', 'refs/stash'], { allowFail: true })).stdout.trim();
+                await git(origin, ['stash', 'push', '--include-untracked', '-m', `Xingular Harness handoff of worktree ${record.name}`], { env: IDENTITY, allowFail: true });
+                const after = (await git(origin, ['rev-parse', '-q', '--verify', 'refs/stash'], { allowFail: true })).stdout.trim();
+                stash = after && after !== before ? after : null;
+            }
+            this.update(id, (entry) => { entry.lastUsedAt = now(); });
+            return { direction, patched: patch.trim().length > 0, copied, stash };
+        });
+    }
+    // ---- Setup trust ----------------------------------------------------------------------------
+    async trustSetup(repo, hash) {
+        if (!/^[0-9a-f]{64}$/.test(hash))
+            throw invalid('A setup script hash is 64 hexadecimal characters.');
+        this.trust.trust(await this.repositoryOf(repo), hash);
+    }
+}

package/dist/sdk/worktrees/setup.d.ts

@@ -0,0 +1,23 @@
+import type { SetupReport } from "./types.js";
+export declare const SETUP_SCRIPT = ".xharness/worktree-setup";
+export declare function scriptHash(text: string | Buffer): string;
+export declare class SetupTrust {
+    private readonly file;
+    constructor(file: string);
+    private read;
+    trusted(repoRoot: string, hash: string): boolean;
+    trust(repoRoot: string, hash: string): void;
+}
+/** The setup script a checkout carries, with its hash, or null. */
+export declare function setupScript(checkout: string): {
+    path: string;
+    hash: string;
+} | null;
+export declare function runSetup(input: {
+    checkout: string;
+    source: string;
+    name: string;
+    repoRoot: string;
+    logFile: string;
+    trust: SetupTrust;
+}): Promise<SetupReport>;

package/dist/sdk/worktrees/setup.js

@@ -0,0 +1,65 @@
+// A repository's setup script runs in each new worktree (installing dependencies, say), but only
+// once a person trusted its exact text. The hash is the trust; a changed script asks again.
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { readJsonOr, writeJson } from "../core/fs.js";
+export const SETUP_SCRIPT = '.xharness/worktree-setup';
+const TIMEOUT_MS = 10 * 60 * 1000;
+export function scriptHash(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+export class SetupTrust {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    read() {
+        return readJsonOr(this.file, {});
+    }
+    trusted(repoRoot, hash) {
+        return this.read()[repoRoot]?.includes(hash) ?? false;
+    }
+    trust(repoRoot, hash) {
+        const all = this.read();
+        all[repoRoot] = [...new Set([...(all[repoRoot] ?? []), hash])];
+        writeJson(this.file, all);
+        chmodSync(this.file, 0o600);
+    }
+}
+/** The setup script a checkout carries, with its hash, or null. */
+export function setupScript(checkout) {
+    const path = join(checkout, SETUP_SCRIPT);
+    if (!existsSync(path) || !statSync(path).isFile())
+        return null;
+    return { path, hash: scriptHash(readFileSync(path)) };
+}
+export function runSetup(input) {
+    const script = setupScript(input.checkout);
+    if (!script)
+        return Promise.resolve({ state: 'none', hash: null, log: null });
+    if (!input.trust.trusted(input.repoRoot, script.hash))
+        return Promise.resolve({ state: 'untrusted', hash: script.hash, log: null });
+    mkdirSync(dirname(input.logFile), { recursive: true });
+    const log = openSync(input.logFile, 'w');
+    return new Promise((resolve) => {
+        const child = spawn('/bin/sh', [script.path], {
+            cwd: input.checkout,
+            env: { ...process.env, HARNESS_WORKTREE_PATH: input.checkout, HARNESS_WORKTREE_SOURCE: input.source, HARNESS_WORKTREE_NAME: input.name },
+            stdio: ['ignore', log, log]
+        });
+        const timer = setTimeout(() => child.kill('SIGTERM'), TIMEOUT_MS);
+        let settled = false;
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            closeSync(log);
+            resolve({ state: exitCode === 0 ? 'ran' : 'failed', hash: script.hash, log: input.logFile, exitCode });
+        };
+        child.once('error', () => finish(null));
+        child.once('close', (code) => finish(code));
+    });
+}

package/dist/sdk/worktrees/types.d.ts

@@ -0,0 +1,91 @@
+/** A managed worktree is disposable and pruned; a permanent one is kept until a person removes it. */
+export type WorktreeKind = 'managed' | 'permanent';
+export interface WorktreeLease {
+    /** Who uses the worktree: a session id. */
+    holder: string;
+    /** The process that holds the lease; a lease whose process is gone is released on recovery. */
+    pid: number;
+    at: string;
+}
+export interface WorktreeRecord {
+    id: string;
+    /** The source checkout's top folder. */
+    repoRoot: string;
+    path: string;
+    name: string;
+    /** Null while the worktree is on a detached HEAD. */
+    branch: string | null;
+    baseRef: string;
+    baseCommit: string;
+    kind: WorktreeKind;
+    origin: 'created' | 'adopted';
+    createdAt: string;
+    lastUsedAt: string;
+    lease: WorktreeLease | null;
+    /** Set once the checkout is removed; the record stays so the worktree can be restored. */
+    removed: {
+        at: string;
+        head: string;
+        snapshot: string | null;
+    } | null;
+}
+export interface WorktreeStatus {
+    record: WorktreeRecord;
+    exists: boolean;
+    head: string | null;
+    /** Changed, added or untracked paths in the working tree. */
+    changes: number;
+    /** Commits made since the worktree started. */
+    ahead: number;
+}
+export interface CopyReport {
+    copied: string[];
+    skipped: {
+        path: string;
+        reason: 'exists' | 'symlink' | 'too_large' | 'over_total' | 'not_file';
+    }[];
+}
+export interface SetupReport {
+    state: 'none' | 'untrusted' | 'ran' | 'failed';
+    /** The script's content hash, to trust it with `setup.trust`. */
+    hash: string | null;
+    log: string | null;
+    exitCode?: number | null;
+}
+export interface CreateWorktreeInput {
+    /** Any folder inside the source repository. */
+    repo: string;
+    name?: string;
+    /** What the worktree starts from. Defaults to the source checkout's HEAD. */
+    baseRef?: string;
+    kind?: WorktreeKind;
+    /** A branch to create instead of a detached HEAD. The configured prefix is added. */
+    branch?: string;
+    /** Bring the source checkout's uncommitted changes along (default when starting from HEAD). */
+    carryChanges?: boolean;
+    /** Run the repository's trusted setup script (default yes). */
+    setup?: boolean;
+}
+export interface CreateWorktreeResult {
+    worktree: WorktreeRecord;
+    carried: CopyReport & {
+        patched: boolean;
+    };
+    included: CopyReport;
+    setup: SetupReport;
+}
+export interface HandoffResult {
+    direction: 'toSource' | 'toWorktree';
+    patched: boolean;
+    copied: string[];
+    /** The stash that holds what was moved away from the origin, when `move` was asked. */
+    stash: string | null;
+}
+export interface WorktreesOptions {
+    /** Where checkouts are made. Defaults to `<state dir>/worktrees`. */
+    root?: string;
+    /** Prefix of branches the harness creates. Defaults to `wt/`. */
+    branchPrefix?: string;
+    /** Managed worktrees kept per repository by `prune`. Defaults to 15. */
+    keep?: number;
+}

package/dist/sdk/worktrees/types.js

@@ -0,0 +1 @@
+export {};