@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/worktrees/git.js

@@ -0,0 +1,89 @@
+// Git, run without a shell. Every configured clean/smudge/process filter is disabled so Harness
+// operations never run repository-provided filter code, and git never stops to ask.
+import { spawn } from 'node:child_process';
+import { HarnessError } from "../core/errors.js";
+const QUIET_FILTERS = ['-c', 'filter.lfs.smudge=', '-c', 'filter.lfs.process=', '-c', 'filter.lfs.required=false', '-c', 'core.hooksPath=/dev/null'];
+const FILTER_KEYS = /^filter\.(.*)\.(?:clean|smudge|process|required)$/i;
+function configuredFilters(cwd, env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', ['config', '--null', '--name-only', '--get-regexp', '^filter\\..*\\.(clean|smudge|process|required)$'], {
+            cwd,
+            env,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (chunk) => out.push(chunk));
+        child.stderr.on('data', (chunk) => err.push(chunk));
+        child.once('error', (error) => reject(new HarnessError('git_unavailable', `Git could not be started: ${error.message}`, 'Install git and make sure it is on PATH.')));
+        child.once('close', (code) => {
+            const stdout = Buffer.concat(out).toString('utf8');
+            if (code !== 0 && code !== 1) {
+                const stderr = Buffer.concat(err).toString('utf8').trim();
+                reject(new HarnessError('git_failed', `git config failed: ${stderr || `exit ${code ?? 1}`}`));
+                return;
+            }
+            const filters = new Set();
+            for (const key of stdout.split('\0').filter(Boolean)) {
+                const match = FILTER_KEYS.exec(key);
+                if (match)
+                    filters.add(match[1]);
+            }
+            resolve([...filters].flatMap((filter) => [
+                '-c', `filter.${filter}.clean=`,
+                '-c', `filter.${filter}.smudge=`,
+                '-c', `filter.${filter}.process=`,
+                '-c', `filter.${filter}.required=false`
+            ]));
+        });
+    });
+}
+export async function git(cwd, args, options = {}) {
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_LFS_SKIP_SMUDGE: '1', LC_ALL: 'C', ...options.env };
+    const filters = await configuredFilters(cwd, env);
+    return new Promise((resolve, reject) => {
+        const input = options.input;
+        const hasInput = input !== undefined && input.length > 0;
+        const child = spawn('git', [...QUIET_FILTERS, ...filters, ...args], {
+            cwd,
+            env,
+            stdio: [hasInput ? 'pipe' : 'ignore', 'pipe', 'pipe']
+        });
+        const out = [];
+        const err = [];
+        let timedOut = false;
+        const timer = options.timeoutMs ? setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, options.timeoutMs) : null;
+        child.stdout.on('data', (chunk) => out.push(chunk));
+        child.stderr.on('data', (chunk) => err.push(chunk));
+        child.once('error', (error) => reject(new HarnessError('git_unavailable', `Git could not be started: ${error.message}`, 'Install git and make sure it is on PATH.')));
+        child.once('close', (code) => {
+            if (timer)
+                clearTimeout(timer);
+            if (timedOut) {
+                reject(new HarnessError('git_timeout', `git ${args.join(' ')} took longer than ${options.timeoutMs} ms.`));
+                return;
+            }
+            const result = { code: code ?? 1, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8') };
+            if (result.code !== 0 && !options.allowFail) {
+                reject(new HarnessError('git_failed', `git ${args.join(' ')} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}`));
+                return;
+            }
+            resolve(result);
+        });
+        if (hasInput && child.stdin) {
+            child.stdin.on('error', (error) => {
+                if (error.code !== 'EPIPE')
+                    reject(new HarnessError('git_failed', `git ${args.join(' ')} could not read input: ${error.message}`));
+            });
+            child.stdin.end(input);
+        }
+    });
+}
+/** The trimmed standard output of a git command that must succeed. */
+export async function gitText(cwd, args, options = {}) {
+    return (await git(cwd, args, options)).stdout.trim();
+}
+/** NUL-separated output as a list, without the empty last entry. */
+export function nulList(text) {
+    return text.split('\0').filter(Boolean);
+}

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

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function worktreeServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/worktrees/serverMethods.js

@@ -0,0 +1,30 @@
+import { invalid } from "../core/errors.js";
+import { optional, text } from "../server/params.js";
+export function worktreeServerMethods(harness) {
+    return {
+        'worktrees.list': (params) => harness.worktrees.list(optional(params, 'repo')),
+        'worktrees.removed': (params) => harness.worktrees.removed(optional(params, 'repo')),
+        'worktrees.status': (params) => harness.worktrees.status(text(params, 'id')),
+        'worktrees.create': (params) => harness.worktrees.create({
+            repo: text(params, 'repo'),
+            ...(optional(params, 'name') ? { name: optional(params, 'name') } : {}),
+            ...(optional(params, 'baseRef') ? { baseRef: optional(params, 'baseRef') } : {}),
+            ...(optional(params, 'branch') ? { branch: optional(params, 'branch') } : {}),
+            ...(params.kind === 'permanent' || params.kind === 'managed' ? { kind: params.kind } : {}),
+            ...(typeof params.carryChanges === 'boolean' ? { carryChanges: params.carryChanges } : {}),
+            ...(typeof params.setup === 'boolean' ? { setup: params.setup } : {})
+        }),
+        'worktrees.branch': (params) => harness.worktrees.branch(text(params, 'id'), text(params, 'name')),
+        'worktrees.handoff': (params) => {
+            const direction = text(params, 'direction');
+            if (direction !== 'toSource' && direction !== 'toWorktree')
+                throw invalid('direction is toSource or toWorktree.');
+            return harness.worktrees.handoff(text(params, 'id'), direction, { move: params.move !== false });
+        },
+        'worktrees.remove': (params) => harness.worktrees.remove(text(params, 'id'), { force: params.force === true }),
+        'worktrees.restore': (params) => harness.worktrees.restore(text(params, 'id')),
+        'worktrees.prune': (params) => harness.worktrees.prune({ repo: optional(params, 'repo'), ...(typeof params.keep === 'number' ? { keep: params.keep } : {}) }),
+        'worktrees.adopt': (params) => harness.worktrees.adopt(text(params, 'path')),
+        'worktrees.setup.trust': async (params) => { await harness.worktrees.trustSetup(text(params, 'repo'), text(params, 'hash')); return {}; }
+    };
+}

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

@@ -0,0 +1,73 @@
+import type { CreateWorktreeInput, CreateWorktreeResult, HandoffResult, WorktreeRecord, WorktreesOptions, WorktreeStatus } from "./types.js";
+export declare class Worktrees {
+    readonly root: string;
+    readonly branchPrefix: string;
+    readonly keep: number;
+    private readonly registryFile;
+    private readonly trust;
+    private readonly leaseCounts;
+    private chain;
+    constructor(stateDir: string, options?: WorktreesOptions);
+    private read;
+    private write;
+    private update;
+    /** Runs changes one at a time, so two requests never race on the registry or on git. */
+    private serial;
+    /** Releases leases whose process is gone. At start-up, this process's own leases are stale too. */
+    recover(startup?: boolean): string[];
+    get(id: string): WorktreeRecord;
+    private active;
+    /** The folder for a registered worktree; unknown ids remain opaque to the caller. */
+    pathOf(id: string): string | null;
+    /** The top folder of the repository a folder belongs to (the main checkout, for a linked worktree). */
+    repositoryOf(folder: string): Promise<string>;
+    list(repo?: string | null): Promise<WorktreeRecord[]>;
+    /** Worktrees removed with a snapshot, which `restore` can bring back. */
+    removed(repo?: string | null): WorktreeRecord[];
+    status(id: string): Promise<WorktreeStatus>;
+    private repoKey;
+    private uniqueName;
+    private branchName;
+    create(input: CreateWorktreeInput): Promise<CreateWorktreeResult>;
+    adopt(path: string): Promise<WorktreeRecord>;
+    /** A session starts using a worktree. Another live session's lease refuses it. */
+    acquire(id: string, holder: string): Promise<WorktreeRecord>;
+    release(id: string, holder: string): Promise<void>;
+    branch(id: string, name: string): Promise<WorktreeRecord>;
+    private reachable;
+    /** Records the worktree's commits and working changes under a snapshot ref. */
+    private snapshot;
+    remove(id: string, options?: {
+        force?: boolean;
+    }): Promise<{
+        worktree: WorktreeRecord;
+        snapshot: string | null;
+    }>;
+    private removeNow;
+    restore(id: string): Promise<WorktreeRecord>;
+    /** Keeps the most recently used managed worktrees of each repository and removes the rest, with snapshots. */
+    prune(options?: {
+        repo?: string | null;
+        keep?: number;
+    }): Promise<{
+        removed: {
+            worktree: WorktreeRecord;
+            snapshot: string | null;
+        }[];
+        failed: {
+            id: string;
+            error: string;
+        }[];
+    }>;
+    /**
+     * 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: string, direction: 'toSource' | 'toWorktree', options?: {
+        move?: boolean;
+    }): Promise<HandoffResult>;
+    trustSetup(repo: string, hash: string): Promise<void>;
+}