@north-light/crouter 0.3.255 → 0.3.256

package/dist/core/worktree-landing.d.ts

@@ -0,0 +1,44 @@
+/** Tracked-but-modified and untracked paths from `git status --porcelain`. */
+export interface CheckoutStatus {
+    /** Paths with modifications to a tracked file (staged, unstaged, or both). */
+    tracked: string[];
+    /** Paths Git does not track at all. */
+    untracked: string[];
+}
+/** Split `git status --porcelain` (v1 format) into tracked modifications and
+ *  untracked paths. A rename entry (`R  old -> new`) reports the destination:
+ *  that is the path an incoming commit would collide with. */
+export declare function parseStatusPorcelain(porcelain: string): CheckoutStatus;
+export type LandPlan = 
+/** Nothing local overlaps the incoming commits — fast-forward directly. */
+{
+    kind: 'direct';
+}
+/** Local modifications touch incoming files; land underneath them. */
+ | {
+    kind: 'stash';
+    overlapping: string[];
+}
+/** An incoming commit adds a path that already exists here, untracked. */
+ | {
+    kind: 'refuse';
+    collisions: string[];
+};
+/** How to fast-forward a base checkout that may hold local changes.
+ *
+ *  Git is less fragile than it looks here: a fast-forward refuses only when an
+ *  incoming commit touches a file with local modifications, so DISJOINT local
+ *  changes are carried along fine and need no stash at all. Overlap is the
+ *  blocker, not dirt.
+ *
+ *  Untracked files are different. They also do not block a fast-forward unless
+ *  an incoming commit adds the same path — and that collision is a refusal
+ *  rather than a stash, because sweeping a person's untracked file into a stash
+ *  to make room for a commit is not a trade this code may make on their behalf. */
+export declare function planLandIntoCheckout(status: CheckoutStatus, incoming: readonly string[]): LandPlan;
+/** The `git update-ref --stdin` body that deletes a managed branch ONLY while
+ *  the ref that proved its content already landed is still at the exact SHA the
+ *  proof inspected. Compare-and-delete is the whole ownership guard: a branch
+ *  or base someone else moved between the proof and this transaction aborts it
+ *  instead of losing the work. */
+export declare function refDeleteTransactionStdin(branch: string, branchSha: string, containingRef: string, containingSha: string): string;

package/dist/core/worktree-landing.js

@@ -0,0 +1,56 @@
+// The judgment shared by every path that lands a managed worktree onto its
+// base branch. These functions run no subprocesses and touch no filesystem:
+// they decide from Git output that the caller already has in hand.
+//
+// Two callers execute the same decision in two forms — `worktree.ts`'s
+// synchronous `close` (an API handler, already blocking) and
+// `worktree-sweep.ts`'s asynchronous daemon sweep (which must never block the
+// event loop). Only the process plumbing differs; the rules that decide whether
+// local work is at risk live here once, so the two can never drift.
+/** Split `git status --porcelain` (v1 format) into tracked modifications and
+ *  untracked paths. A rename entry (`R  old -> new`) reports the destination:
+ *  that is the path an incoming commit would collide with. */
+export function parseStatusPorcelain(porcelain) {
+    const tracked = [];
+    const untracked = [];
+    for (const line of porcelain.split('\n')) {
+        if (line.length < 4)
+            continue;
+        const code = line.slice(0, 2);
+        const rest = line.slice(3);
+        const path = rest.includes(' -> ') ? rest.slice(rest.indexOf(' -> ') + 4) : rest;
+        const unquoted = path.startsWith('"') && path.endsWith('"') ? path.slice(1, -1) : path;
+        if (code === '??')
+            untracked.push(unquoted);
+        else if (code !== '!!')
+            tracked.push(unquoted);
+    }
+    return { tracked, untracked };
+}
+/** How to fast-forward a base checkout that may hold local changes.
+ *
+ *  Git is less fragile than it looks here: a fast-forward refuses only when an
+ *  incoming commit touches a file with local modifications, so DISJOINT local
+ *  changes are carried along fine and need no stash at all. Overlap is the
+ *  blocker, not dirt.
+ *
+ *  Untracked files are different. They also do not block a fast-forward unless
+ *  an incoming commit adds the same path — and that collision is a refusal
+ *  rather than a stash, because sweeping a person's untracked file into a stash
+ *  to make room for a commit is not a trade this code may make on their behalf. */
+export function planLandIntoCheckout(status, incoming) {
+    const arriving = new Set(incoming);
+    const collisions = status.untracked.filter((path) => arriving.has(path));
+    if (collisions.length > 0)
+        return { kind: 'refuse', collisions };
+    const overlapping = status.tracked.filter((path) => arriving.has(path));
+    return overlapping.length > 0 ? { kind: 'stash', overlapping } : { kind: 'direct' };
+}
+/** The `git update-ref --stdin` body that deletes a managed branch ONLY while
+ *  the ref that proved its content already landed is still at the exact SHA the
+ *  proof inspected. Compare-and-delete is the whole ownership guard: a branch
+ *  or base someone else moved between the proof and this transaction aborts it
+ *  instead of losing the work. */
+export function refDeleteTransactionStdin(branch, branchSha, containingRef, containingSha) {
+    return `verify ${containingRef} ${containingSha}\ndelete refs/heads/${branch} ${branchSha}\n`;
+}

package/dist/core/worktree-quarantine.d.ts

@@ -0,0 +1,19 @@
+export interface QuarantinedWorktree {
+    node_id: string;
+    path: string;
+    branch: string;
+    repo_root: string;
+    /** Structured code for the refusal that quarantined this record. */
+    reason: string;
+    detail?: string;
+    /** Consecutive sweep passes that examined it without completing cleanup. */
+    attempts: number;
+    /** ISO timestamp of the most recent examination. */
+    last_attempt: string;
+    /** Bytes the checkout occupies, or null when the path is gone or unreadable. */
+    size_bytes: number | null;
+}
+/** Every managed worktree the sweep has flagged as needing attention, oldest
+ *  refusal first. Reads node records only — a checkout crtr did not create has
+ *  no node record and is never reported. */
+export declare function listQuarantinedManagedWorktrees(): Promise<QuarantinedWorktree[]>;

package/dist/core/worktree-quarantine.js

@@ -0,0 +1,54 @@
+// Read-only inventory of managed worktrees the daemon sweep could not
+// reconcile. Its whole purpose is turning an invisible accumulation into a
+// short, explained list a human can act on, so it reports the recorded refusal
+// reason alongside the resources still held: the checkout path, its branch, and
+// what that checkout costs on disk.
+//
+// Nothing here mutates. Disposal belongs to the sweep
+// (`worktree-sweep.ts`), which is the one authority for removing a checkout.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { getNode, listNodes } from './canvas/index.js';
+/** Disk usage of one directory in bytes, or null when it cannot be measured.
+ *  `du` is spawned asynchronously: a managed checkout can be tens of gigabytes,
+ *  and this runs inside the daemon, which must never block its event loop. */
+async function directorySizeBytes(path) {
+    if (!existsSync(path))
+        return null;
+    return new Promise((resolve) => {
+        const child = spawn('du', ['-sk', path]);
+        let stdout = '';
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        child.stderr.on('data', () => { });
+        child.on('error', () => resolve(null));
+        child.on('close', (status) => {
+            if (status !== 0)
+                return resolve(null);
+            const kb = Number(stdout.trim().split(/\s+/)[0]);
+            resolve(Number.isSafeInteger(kb) ? kb * 1024 : null);
+        });
+    });
+}
+/** Every managed worktree the sweep has flagged as needing attention, oldest
+ *  refusal first. Reads node records only — a checkout crtr did not create has
+ *  no node record and is never reported. */
+export async function listQuarantinedManagedWorktrees() {
+    const found = [];
+    for (const row of listNodes()) {
+        const wt = getNode(row.node_id)?.managed_worktree;
+        if (wt?.sweep?.quarantined !== true)
+            continue;
+        found.push({
+            node_id: row.node_id,
+            path: wt.path,
+            branch: wt.branch,
+            repo_root: wt.repo_root,
+            reason: wt.sweep.reason,
+            ...(wt.sweep.detail === undefined ? {} : { detail: wt.sweep.detail }),
+            attempts: wt.sweep.attempts,
+            last_attempt: wt.sweep.last_attempt,
+        });
+    }
+    found.sort((a, b) => a.last_attempt.localeCompare(b.last_attempt));
+    return Promise.all(found.map(async (entry) => ({ ...entry, size_bytes: await directorySizeBytes(entry.path) })));
+}

package/dist/core/worktree-sweep.d.ts

@@ -0,0 +1,60 @@
+import { type ManagedWorktree } from './canvas/index.js';
+export type SweepOutcome = 
+/** The checkout and branch are gone and the record is marked complete. */
+{
+    status: 'complete';
+    stash?: string;
+}
+/** Nothing to do: no record, already reconciled, or the node came back. */
+ | {
+    status: 'skipped';
+    reason: string;
+}
+/** A safety rule says this record must survive. Visible, retried, never fatal. */
+ | {
+    status: 'refused';
+    reason: string;
+    detail?: string;
+    unchanged?: true;
+}
+/** Git or the repository could not answer. Transient; retried. */
+ | {
+    status: 'failed';
+    reason: string;
+    detail?: string;
+};
+/** A record this sweep still owns: open, or closed without proven cleanup. An
+ *  abandoned record is deliberately out of scope — abandon already removed the
+ *  checkout and retains its branch for a person on purpose. */
+export declare function isReconcilable(wt: ManagedWorktree | null | undefined): boolean;
+/** Whether the sweep should examine this record on a pass starting at `now`. A
+ *  record with no recorded refusal is always due. */
+export declare function isDueForSweep(wt: ManagedWorktree, now: number): boolean;
+export interface ReconcileGuard {
+    /** Is the owning node STILL gone? Consulted synchronously immediately before
+     *  each Git mutation and before any metadata write — not once per pass.
+     *
+     *  The repository lock serializes worktree operations, NOT node lifecycle: a
+     *  revive can land in any of the awaits between the proof and the removal,
+     *  and it would then be running in the very checkout about to be deleted. So
+     *  every destructive step re-asks, and a false answer stops the pass where it
+     *  stands, leaving the record incomplete for a later pass to resume. The
+     *  implementation must not spawn a subprocess: this runs inside crtrd. */
+    stillEligible: () => boolean;
+}
+/** Dispose of one node's managed worktree, or explain why it must survive.
+ *
+ *  Ownership is proved from crouter's own node record, never from
+ *  `git worktree list`: a checkout the user or another tool created has no node
+ *  record and is never reachable from here. Under the repository lock the
+ *  recorded path is confirmed REGISTERED to the recorded branch — a path match
+ *  alone is not ownership — and removal is `git worktree remove <recorded
+ *  path>` without `--force`. `git worktree prune` is never run: it is
+ *  repo-wide and would touch administrative entries for worktrees crouter does
+ *  not own.
+ *
+ *  Effects are ordered checkout → branch → metadata so every interruption is
+ *  resumable: a crash before removal retries from pending; after removal but
+ *  before the branch delete, the branch is still an intact ref the next pass
+ *  finds; after both, the next pass observes both absent and marks complete. */
+export declare function reconcileManagedWorktree(nodeId: string, guard: ReconcileGuard, now?: number): Promise<SweepOutcome>;