crewly 1.20.152 → 1.20.153

package/dist/backend/backend/src/services/worktree/worktree-janitor.git.js

@@ -0,0 +1,238 @@
+/**
+ * Worktree janitor — low-level helpers.
+ *
+ * A command runner that never throws, a parser for `git worktree list
+ * --porcelain`, path helpers, and the process-cwd probe used to tell whether
+ * anything is still working inside a worktree. Kept apart from the service so
+ * each piece can be tested on its own.
+ *
+ * @module services/worktree/worktree-janitor.git
+ */
+import { execFile } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { WORKTREE_JANITOR_CONSTANTS } from '../../constants.js';
+/**
+ * Run a command without a shell and never throw.
+ *
+ * Git and gh are told never to prompt (no credential dialogs, no pager), so a
+ * periodic background job cannot hang on input.
+ *
+ * @param file - Executable (e.g. `git`, `gh`, or an absolute path)
+ * @param args - Arguments
+ * @param options - cwd / timeout / env
+ * @returns Exit code and output; `code` is null on spawn failure or timeout
+ *
+ * @example
+ * ```typescript
+ * const r = await runCommand('git', ['-C', repo, 'status', '--porcelain']);
+ * if (r.code === 0 && r.stdout === '') console.log('clean');
+ * ```
+ */
+export function runCommand(file, args, options = {}) {
+    return new Promise((resolve) => {
+        try {
+            execFile(file, args, {
+                cwd: options.cwd,
+                timeout: options.timeoutMs ?? WORKTREE_JANITOR_CONSTANTS.GIT_TIMEOUT_MS,
+                maxBuffer: WORKTREE_JANITOR_CONSTANTS.MAX_OUTPUT_BYTES,
+                env: {
+                    ...process.env,
+                    GIT_TERMINAL_PROMPT: '0',
+                    GIT_PAGER: 'cat',
+                    GH_PROMPT_DISABLED: '1',
+                    GH_NO_UPDATE_NOTIFIER: '1',
+                    ...(options.env ?? {}),
+                },
+            }, (error, stdout, stderr) => {
+                const out = typeof stdout === 'string' ? stdout : String(stdout ?? '');
+                const err = typeof stderr === 'string' ? stderr : String(stderr ?? '');
+                if (!error) {
+                    resolve({ code: 0, stdout: out, stderr: err });
+                    return;
+                }
+                const errCode = error.code;
+                const code = typeof errCode === 'number' && !error.killed ? errCode : null;
+                resolve({ code, stdout: out, stderr: err || error.message });
+            });
+        }
+        catch (spawnErr) {
+            resolve({ code: null, stdout: '', stderr: spawnErr instanceof Error ? spawnErr.message : String(spawnErr) });
+        }
+    });
+}
+/**
+ * Parse `git worktree list --porcelain` output.
+ *
+ * Entries are separated by blank lines; the first entry is the main worktree.
+ *
+ * @param output - Raw porcelain output
+ * @returns Parsed entries in git's order
+ *
+ * @example
+ * ```typescript
+ * parsePorcelainWorktrees('worktree /r\nHEAD abc\nbranch refs/heads/main\n');
+ * // [{ path: '/r', head: 'abc', branch: 'main', isMain: true, ... }]
+ * ```
+ */
+export function parsePorcelainWorktrees(output) {
+    const result = [];
+    let current = null;
+    for (const rawLine of output.split('\n')) {
+        const line = rawLine.replace(/\r$/, '');
+        if (line.startsWith('worktree ')) {
+            current = {
+                path: line.slice('worktree '.length),
+                head: null,
+                branch: null,
+                bare: false,
+                detached: false,
+                locked: false,
+                prunable: false,
+                isMain: result.length === 0,
+            };
+            result.push(current);
+            continue;
+        }
+        if (!current || line === '')
+            continue;
+        if (line.startsWith('HEAD '))
+            current.head = line.slice('HEAD '.length);
+        else if (line.startsWith('branch '))
+            current.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+        else if (line === 'bare')
+            current.bare = true;
+        else if (line === 'detached')
+            current.detached = true;
+        else if (line === 'locked' || line.startsWith('locked ')) {
+            current.locked = true;
+            const reason = line.slice('locked'.length).trim();
+            if (reason)
+                current.lockReason = reason;
+        }
+        else if (line === 'prunable' || line.startsWith('prunable '))
+            current.prunable = true;
+    }
+    return result;
+}
+/**
+ * Real path of `p`, or its resolved form when it does not exist.
+ *
+ * @param p - Path
+ * @returns Canonical path for comparisons
+ */
+export function canonicalPath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * Whether `child` is `parent` or inside it (both canonicalised first).
+ *
+ * @param child - Candidate path
+ * @param parent - Directory
+ * @returns True when child === parent or child is under parent
+ *
+ * @example
+ * ```typescript
+ * isPathInside('/r/.claude/worktrees/a/src', '/r/.claude/worktrees/a'); // true
+ * isPathInside('/r/.claude/worktrees/ab', '/r/.claude/worktrees/a');    // false
+ * ```
+ */
+export function isPathInside(child, parent) {
+    const c = canonicalPath(child);
+    const p = canonicalPath(parent);
+    if (c === p)
+        return true;
+    const withSep = p.endsWith(path.sep) ? p : p + path.sep;
+    return c.startsWith(withSep);
+}
+/**
+ * Latest modification time (ms) of a worktree: the directory itself plus its
+ * private git dir's `index`, `HEAD` and `logs/HEAD` — every commit, checkout,
+ * stage or reset touches one of those. Uncommitted edits are caught by the
+ * dirty check instead.
+ *
+ * @param worktreePath - Worktree root
+ * @param gitDir - Its private git dir (`.git/worktrees/<name>`), when known
+ * @returns Newest mtime in ms, or null when nothing could be stat'ed
+ */
+export function latestWorktreeMtimeMs(worktreePath, gitDir) {
+    const candidates = [worktreePath, path.join(worktreePath, '.git')];
+    if (gitDir) {
+        candidates.push(gitDir, path.join(gitDir, 'index'), path.join(gitDir, 'HEAD'), path.join(gitDir, 'logs', 'HEAD'));
+    }
+    let newest = null;
+    for (const c of candidates) {
+        try {
+            const m = fs.lstatSync(c).mtimeMs;
+            if (newest === null || m > newest)
+                newest = m;
+        }
+        catch {
+            // missing — ignore
+        }
+    }
+    return newest;
+}
+/**
+ * Current working directories of every process this user can see.
+ *
+ * macOS: `lsof -a -d cwd -u <uid> -Fn`. Linux: `/proc/<pid>/cwd`. Returns
+ * null when the probe cannot run, so the caller can treat "unknown" as busy.
+ *
+ * @returns Absolute cwd paths (deduplicated), or null when unavailable
+ */
+export async function listProcessCwds() {
+    if (process.platform === 'linux') {
+        try {
+            const out = new Set();
+            for (const entry of fs.readdirSync('/proc')) {
+                if (!/^\d+$/.test(entry))
+                    continue;
+                try {
+                    out.add(fs.readlinkSync(path.join('/proc', entry, 'cwd')));
+                }
+                catch {
+                    // other user's process or already gone
+                }
+            }
+            return [...out];
+        }
+        catch {
+            return null;
+        }
+    }
+    if (process.platform === 'win32')
+        return null;
+    const uid = typeof process.getuid === 'function' ? String(process.getuid()) : String(os.userInfo().uid);
+    const r = await runCommand('lsof', ['-a', '-d', 'cwd', '-u', uid, '-Fn', '-w'], {
+        timeoutMs: WORKTREE_JANITOR_CONSTANTS.CWD_PROBE_TIMEOUT_MS,
+    });
+    // lsof exits 1 when some listed item had no match; the output is still valid.
+    if (r.code === null || !r.stdout)
+        return null;
+    const out = new Set();
+    for (const line of r.stdout.split('\n')) {
+        if (line.startsWith('n/'))
+            out.add(line.slice(1));
+    }
+    return out.size > 0 ? [...out] : null;
+}
+/**
+ * Whether the kill switch disables the janitor.
+ *
+ * @param env - Environment (defaults to process.env)
+ * @returns True when `CREWLY_WORKTREE_JANITOR` is `0`/`off`/`false`/`no`
+ */
+export function isJanitorDisabled(env = process.env) {
+    const raw = env[WORKTREE_JANITOR_CONSTANTS.ENV_VAR];
+    if (raw === undefined)
+        return false;
+    return WORKTREE_JANITOR_CONSTANTS.DISABLED_VALUES.includes(raw.trim().toLowerCase());
+}
+//# sourceMappingURL=worktree-janitor.git.js.map

package/dist/backend/backend/src/services/worktree/worktree-janitor.git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-janitor.git.js","sourceRoot":"","sources":["../../../../../../backend/src/services/worktree/worktree-janitor.git.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/worktree/worktree-janitor.service.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Worktree janitor — removes git worktrees whose work has landed.
+ *
+ * Agents create a worktree per code task (`<repo>/.claude/worktrees/<name>`,
+ * `/tmp/crewly-worktrees/<session>-<slug>`) and never delete it; a busy Mac
+ * collected 30+ of them, tens of GB. Owner decision: once the PR is merged the
+ * worktree goes away by itself.
+ *
+ * ## Which repos
+ * Every registered project path (projects store) that is inside a git repo,
+ * plus the Crewly package root when it is a dev checkout. Repos are
+ * de-duplicated by their main worktree.
+ *
+ * ## Removal rules — a worktree is removed only when ALL hold
+ * 1. It is not the main worktree, not bare, and not `prunable` (a missing
+ *    directory is left to `git worktree prune`).
+ * 2. It is not locked (`git worktree lock`; Claude Code locks the worktree of
+ *    a running subagent).
+ * 3. It is not under `<repo>/.crewly/worktrees/` — that directory belongs to
+ *    the per-WorkItem worktree feature (#814), which does its own
+ *    WorkItem-aware cleanup.
+ * 4. It is an agent worktree: its path is under `<main>/.claude/worktrees/`
+ *    or `<tmp>/crewly-worktrees/` (`/tmp` and `os.tmpdir()`), OR its branch
+ *    starts with an agent-only prefix (`worktree-agent-`, Claude Code's
+ *    automatic subagent branch). Human-made worktrees such as
+ *    `../crewly-wt-805` on `fix/...` are never touched. Deliberately narrow:
+ *    a false "keep" costs disk, a false "remove" costs work.
+ * 5. Nothing is working in it: no Crewly agent session was started in it and
+ *    no process of this user (PTY shells, runtimes, editors, test runners)
+ *    has its cwd inside it. If the process probe fails, everything is kept.
+ * 6. It was last touched more than 2 hours ago (newest mtime of the
+ *    directory and its git dir's index / HEAD / logs/HEAD).
+ * 7. `git status --porcelain --untracked-files=all` is empty: no tracked
+ *    change and no untracked file. Ignored files (node_modules, dist) do not
+ *    count. A failing status keeps it.
+ * 8. Its work has landed: HEAD is an ancestor of `origin/<default branch>`
+ *    after a quiet `git fetch` (fetch errors ignored), OR — when `gh` is
+ *    installed and authenticated — a MERGED PR has this branch as head AND
+ *    its head commit equals the worktree HEAD (squash merges; commits made
+ *    after the merge keep the worktree).
+ *
+ * ## Removal
+ * `git worktree remove <path>` without `--force`. If git refuses although
+ * the status is still clean (only ignored output left) and the worktree has
+ * no submodules, it is retried once with `--force`. Then the local branch is
+ * deleted (never a protected name), and `git worktree prune` runs per repo.
+ *
+ * Runs every 30 minutes (first run 10 minutes after boot). Kill switch:
+ * `CREWLY_WORKTREE_JANITOR=0`. Never throws; logs one summary line per run.
+ *
+ * @module services/worktree/worktree-janitor.service
+ */
+/** Why a worktree is kept, or why it may go. */
+export type WorktreeReason = 'main-worktree' | 'bare' | 'prunable' | 'locked' | 'managed-by-workitem-worktrees' | 'not-agent-worktree' | 'agent-session-inside' | 'process-inside' | 'cwd-probe-failed' | 'recent' | 'dirty' | 'status-failed' | 'not-merged' | 'merged' | 'pr-merged';
+/** Verdict for one worktree (the dry-run output). */
+export interface WorktreeVerdict {
+    /** Main worktree of the repo this worktree belongs to */
+    repo: string;
+    /** Worktree path */
+    path: string;
+    /** Branch, or null when detached */
+    branch: string | null;
+    /** HEAD commit */
+    head: string | null;
+    /** What the janitor would do */
+    decision: 'remove' | 'keep';
+    /** The deciding rule */
+    reason: WorktreeReason;
+    /** Human-readable detail (lock reason, dirty file count, PR number, …) */
+    detail?: string;
+    /** Ms since last touched, when computed */
+    idleMs?: number;
+}
+/** Outcome of acting on one verdict. */
+export interface WorktreeOutcome extends WorktreeVerdict {
+    /** True when the worktree directory was removed */
+    removed: boolean;
+    /** True when `--force` was needed (only ignored files were in the way) */
+    forced: boolean;
+    /** True when the local branch was deleted */
+    branchDeleted: boolean;
+    /** Error text when removal failed (the worktree is then counted as kept) */
+    error?: string;
+}
+/** Result of one janitor pass. */
+export interface JanitorRunSummary {
+    /** ISO start time */
+    startedAt: string;
+    /** Duration in ms */
+    durationMs: number;
+    /** True when the kill switch stopped the pass */
+    disabled: boolean;
+    /** True when this was a dry run (nothing removed) */
+    dryRun: boolean;
+    /** Repos (main worktrees) examined */
+    repos: string[];
+    /** Worktrees removed */
+    removed: number;
+    /** Dry run only: worktrees a real pass would remove */
+    wouldRemove: number;
+    /** Worktrees kept */
+    kept: number;
+    /** Kept worktrees by reason (removal failures under `remove-failed`) */
+    keptReasons: Record<string, number>;
+    /** Per-worktree results */
+    worktrees: WorktreeOutcome[];
+}
+/** A place a live process or agent is working in. */
+export interface BusyCwd {
+    /** Absolute directory */
+    cwd: string;
+    /** `agent-session` for Crewly sessions, `process` for anything else */
+    source: 'agent-session' | 'process';
+}
+/** Minimal logger surface (a ComponentLogger fits). */
+export interface JanitorLogger {
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+}
+/** Injectable dependencies (defaults talk to the real backend). */
+export interface WorktreeJanitorOptions {
+    /** Candidate repo/project paths (default: projects store + dev checkout) */
+    listRepoPaths?: () => Promise<string[]>;
+    /** Where Crewly agents and processes are working; null = probe failed (default: sessions + lsof) */
+    listBusyCwds?: () => Promise<BusyCwd[] | null>;
+    /** git executable (default `git`) */
+    gitBin?: string;
+    /** gh executable (default `gh`); set to null to never use gh */
+    ghBin?: string | null;
+    /** Clock (default Date.now) */
+    now?: () => number;
+    /** Minimum idle time before removal (default 2 h) */
+    minIdleMs?: number;
+    /** Temp roots whose `crewly-worktrees/` holds agent worktrees (default `/tmp` + os.tmpdir()) */
+    tmpRoots?: string[];
+    /** Environment for the kill switch (default process.env) */
+    env?: NodeJS.ProcessEnv;
+    /** Logger (default: component logger `WorktreeJanitor`) */
+    logger?: JanitorLogger;
+}
+/**
+ * Periodic cleaner of finished agent worktrees. See the module JSDoc for the
+ * exact rules.
+ *
+ * @example
+ * ```typescript
+ * const janitor = WorktreeJanitorService.getInstance();
+ * janitor.start();                 // first pass in 10 min, then every 30 min
+ * const plan = await janitor.plan(); // dry run: verdict per worktree
+ * const summary = await janitor.run(); // one real pass now
+ * ```
+ */
+export declare class WorktreeJanitorService {
+    private static instance;
+    private readonly opts;
+    private firstRunTimer;
+    private intervalTimer;
+    private inFlight;
+    private ghUsable;
+    private lastSummary;
+    private loggerInstance;
+    /**
+     * @param options - Injectable dependencies; defaults use the live backend
+     */
+    constructor(options?: WorktreeJanitorOptions);
+    /**
+     * Process-wide instance used by the server and the HTTP routes.
+     *
+     * @returns The singleton
+     */
+    static getInstance(): WorktreeJanitorService;
+    /** Reset the singleton (tests). */
+    static resetInstance(): void;
+    /**
+     * Whether the kill switch is on.
+     *
+     * @returns True when `CREWLY_WORKTREE_JANITOR` disables the janitor
+     */
+    isDisabled(): boolean;
+    /**
+     * Schedule the periodic pass: first after FIRST_RUN_DELAY_MS, then every
+     * INTERVAL_MS. No-op when disabled or already started. Timers are unref'd.
+     *
+     * @returns True when scheduled
+     */
+    start(): boolean;
+    /** Cancel scheduled passes. */
+    stop(): void;
+    /**
+     * Summary of the last completed real pass, if any.
+     *
+     * @returns Last summary or null
+     */
+    getLastSummary(): JanitorRunSummary | null;
+    /**
+     * Dry run: the verdict for every worktree of every known repo. Removes
+     * nothing (it may `git fetch`).
+     *
+     * @returns Summary with per-worktree verdicts
+     */
+    plan(): Promise<JanitorRunSummary>;
+    /**
+     * One real pass. Concurrent calls share the pass in flight. Never throws.
+     * Honours the kill switch.
+     *
+     * @returns Summary of what was removed and kept
+     */
+    run(): Promise<JanitorRunSummary>;
+    private get logger();
+    private git;
+    private pass;
+    private resolveRepos;
+    private safeBusyCwds;
+    private isAgentWorktree;
+    /**
+     * Apply the removal rules to one worktree (read-only apart from fetch).
+     */
+    private evaluate;
+    /** `origin/<default>` after one quiet fetch per repo per pass; null when there is no origin. */
+    private defaultRef;
+    /** Number of a MERGED PR whose head is `branch` at exactly `head`, or null. */
+    private mergedPrFor;
+    /** Remove one worktree whose verdict is `remove`, then its branch. Never throws. */
+    private remove;
+}
+/**
+ * Default repo candidates: every registered project path, plus the running
+ * Crewly package root when it is a git checkout.
+ *
+ * @returns Paths (may include non-git paths; those are skipped)
+ */
+export declare function defaultListRepoPaths(): Promise<string[]>;
+/**
+ * Default busy-cwd probe: the start directory of every live Crewly session,
+ * plus the cwd of every process of this user (which covers the PTY shells,
+ * the agent runtimes under them, and anything the owner has open).
+ *
+ * @returns Busy directories, or null when the process probe failed
+ */
+export declare function defaultListBusyCwds(): Promise<BusyCwd[] | null>;
+//# sourceMappingURL=worktree-janitor.service.d.ts.map

package/dist/backend/backend/src/services/worktree/worktree-janitor.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-janitor.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/worktree/worktree-janitor.service.ts"],"names":[],"mappings":"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"}