@cleocode/worktree 2026.4.117

package/dist/worktree-list.js

@@ -0,0 +1,110 @@
+/**
+ * Worktree listing operations for @cleocode/worktree.
+ *
+ * `listWorktrees` and `listWorktreesByProjectRoot` scan the CLEO XDG worktrees
+ * directory to return structured entries.
+ *
+ * @task T1161
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import envPaths from 'env-paths';
+import { computeProjectHash, resolveWorktreeRootForHash } from './paths.js';
+const APP_NAME = 'cleo';
+/**
+ * Resolve the worktree root directory for a given project hash.
+ *
+ * Exported so callers can inspect the canonical path without creating a worktree.
+ *
+ * @param projectHash - 16-char project hash.
+ * @param worktreeRoot - Optional explicit override for the root path.
+ * @returns Absolute path to the worktrees root directory for this project.
+ */
+export function resolveWorktreeRoot(projectHash, worktreeRoot) {
+    return resolveWorktreeRootForHash(projectHash, worktreeRoot);
+}
+/**
+ * List all active CLEO worktrees scoped to a specific project hash.
+ *
+ * Scans the XDG worktrees filesystem directory. Entries without a valid
+ * worktree path on disk are omitted.
+ *
+ * @param options - Listing options including optional project hash filter.
+ * @returns Array of worktree entries.
+ */
+export function listWorktrees(options = {}) {
+    const ep = envPaths(APP_NAME, { suffix: '' });
+    const dataDir = process.env['CLEO_HOME'] ?? ep.data;
+    const worktreesBase = join(dataDir, 'worktrees');
+    if (!existsSync(worktreesBase))
+        return [];
+    const entries = [];
+    let projectHashes;
+    try {
+        projectHashes = readdirSync(worktreesBase);
+    }
+    catch {
+        return [];
+    }
+    for (const hash of projectHashes) {
+        // Filter by project hash when provided
+        if (options.projectHash && hash !== options.projectHash)
+            continue;
+        const hashDir = join(worktreesBase, hash);
+        let taskDirs;
+        try {
+            taskDirs = readdirSync(hashDir);
+        }
+        catch {
+            continue;
+        }
+        for (const taskId of taskDirs) {
+            const worktreePath = join(hashDir, taskId);
+            if (!existsSync(worktreePath))
+                continue;
+            const branch = resolveWorktreeBranch(worktreePath) ?? `task/${taskId}`;
+            entries.push({
+                path: worktreePath,
+                branch,
+                taskId,
+                projectHash: hash,
+            });
+        }
+    }
+    return entries;
+}
+/**
+ * List all active CLEO worktrees for a specific project root.
+ *
+ * Computes the project hash from the project root, then delegates to
+ * {@link listWorktrees} with the computed hash as filter.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns Array of worktree list entries for this project.
+ */
+export function listWorktreesByProjectRoot(projectRoot) {
+    const projectHash = computeProjectHash(projectRoot);
+    return listWorktrees({ projectHash });
+}
+/**
+ * Resolve the current branch for a worktree directory by invoking git.
+ *
+ * Returns null if the path is not a valid git worktree or git fails.
+ *
+ * @param worktreePath - Absolute path to the worktree directory.
+ * @returns Branch name string, or null if not determinable.
+ * @internal
+ */
+function resolveWorktreeBranch(worktreePath) {
+    try {
+        return execFileSync('git', ['-C', worktreePath, 'rev-parse', '--abbrev-ref', 'HEAD'], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=worktree-list.js.map

package/dist/worktree-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-list.js","sourceRoot":"","sources":["../src/worktree-list.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,QAAQ,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE5E,MAAM,QAAQ,GAAG,MAAM,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB,EAAE,YAAqB;IAC5E,OAAO,0BAA0B,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,UAAgC,EAAE;IAC9D,MAAM,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC;IACpD,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAEjD,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,EAAE,CAAC;IAE1C,MAAM,OAAO,GAAwB,EAAE,CAAC;IAExC,IAAI,aAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,aAAa,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,uCAAuC;QACvC,IAAI,OAAO,CAAC,WAAW,IAAI,IAAI,KAAK,OAAO,CAAC,WAAW;YAAE,SAAS;QAElE,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QAED,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC3C,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;gBAAE,SAAS;YAExC,MAAM,MAAM,GAAG,qBAAqB,CAAC,YAAY,CAAC,IAAI,QAAQ,MAAM,EAAE,CAAC;YACvE,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,YAAY;gBAClB,MAAM;gBACN,MAAM;gBACN,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,WAAmB;IAC5D,MAAM,WAAW,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;IACpD,OAAO,aAAa,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,qBAAqB,CAAC,YAAoB;IACjD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE;YACpF,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/worktree-prune.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Worktree prune operation for @cleocode/worktree.
+ *
+ * Removes orphaned worktrees: worktree directories whose task ID is NOT in
+ * the provided `preserveTaskIds` set, and optionally runs `git worktree prune`
+ * to clean up stale git administrative entries.
+ *
+ * Called periodically by `cleo sentient tick` via `worktree-dispatch.ts`.
+ *
+ * @task T1161
+ */
+import type { PruneWorktreesOptions, PruneWorktreesResult } from '@cleocode/contracts';
+/**
+ * Prune orphaned agent worktrees for a project.
+ *
+ * Algorithm:
+ * 1. Optionally run `git worktree prune` to clean up stale git admin entries.
+ * 2. Read all subdirectory entries under the project's worktree root.
+ * 3. For each entry NOT in `preserveTaskIds`, unlock and remove the worktree.
+ *
+ * @param options - Prune options with project root and optional preserve list.
+ * @returns Result listing removed paths and any errors.
+ *
+ * @task T1161
+ */
+export declare function pruneWorktrees(options: PruneWorktreesOptions): PruneWorktreesResult;
+//# sourceMappingURL=worktree-prune.d.ts.map

package/dist/worktree-prune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-prune.d.ts","sourceRoot":"","sources":["../src/worktree-prune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAIvF;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,oBAAoB,CA+DnF"}

package/dist/worktree-prune.js

@@ -0,0 +1,91 @@
+/**
+ * Worktree prune operation for @cleocode/worktree.
+ *
+ * Removes orphaned worktrees: worktree directories whose task ID is NOT in
+ * the provided `preserveTaskIds` set, and optionally runs `git worktree prune`
+ * to clean up stale git administrative entries.
+ *
+ * Called periodically by `cleo sentient tick` via `worktree-dispatch.ts`.
+ *
+ * @task T1161
+ */
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { getGitRoot, gitSilent } from './git.js';
+import { computeProjectHash, resolveWorktreeRootForHash } from './paths.js';
+/**
+ * Prune orphaned agent worktrees for a project.
+ *
+ * Algorithm:
+ * 1. Optionally run `git worktree prune` to clean up stale git admin entries.
+ * 2. Read all subdirectory entries under the project's worktree root.
+ * 3. For each entry NOT in `preserveTaskIds`, unlock and remove the worktree.
+ *
+ * @param options - Prune options with project root and optional preserve list.
+ * @returns Result listing removed paths and any errors.
+ *
+ * @task T1161
+ */
+export function pruneWorktrees(options) {
+    const { projectRoot, preserveTaskIds, gitPrune = true } = options;
+    const projectHash = computeProjectHash(projectRoot);
+    const worktreeRoot = resolveWorktreeRootForHash(projectHash);
+    const removed = [];
+    const errors = [];
+    let gitPruneRan = false;
+    // Step 1: Run git worktree prune if requested.
+    if (gitPrune) {
+        try {
+            const gitRoot = getGitRoot(projectRoot);
+            gitSilent(['worktree', 'prune'], gitRoot);
+            gitPruneRan = true;
+        }
+        catch {
+            // Non-fatal: project root may not be a git repo in some edge cases.
+            gitPruneRan = false;
+        }
+    }
+    // Step 2: Remove orphaned worktree directories.
+    if (preserveTaskIds !== undefined && existsSync(worktreeRoot)) {
+        let entries;
+        try {
+            entries = readdirSync(worktreeRoot);
+        }
+        catch {
+            return { removed: 0, removedPaths: [], errors, gitPruneRan };
+        }
+        let gitRoot;
+        try {
+            gitRoot = getGitRoot(projectRoot);
+        }
+        catch {
+            // If there's no git root, we can still remove dirs — just skip git cmds.
+            gitRoot = projectRoot;
+        }
+        for (const entry of entries) {
+            if (preserveTaskIds.has(entry))
+                continue;
+            const worktreePath = join(worktreeRoot, entry);
+            // Try git-aware removal first.
+            gitSilent(['worktree', 'unlock', worktreePath], gitRoot);
+            if (gitSilent(['worktree', 'remove', '--force', worktreePath], gitRoot)) {
+                removed.push(worktreePath);
+            }
+            else {
+                // Fall back to rmSync for directories that aren't registered worktrees.
+                try {
+                    rmSync(worktreePath, { recursive: true, force: true });
+                    removed.push(worktreePath);
+                }
+                catch (err) {
+                    errors.push({
+                        path: worktreePath,
+                        reason: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+    }
+    return { removed: removed.length, removedPaths: removed, errors, gitPruneRan };
+}
+//# sourceMappingURL=worktree-prune.js.map

package/dist/worktree-prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-prune.js","sourceRoot":"","sources":["../src/worktree-prune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE5E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,QAAQ,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAElE,MAAM,WAAW,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,YAAY,GAAG,0BAA0B,CAAC,WAAW,CAAC,CAAC;IAC7D,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,MAAM,GAA4C,EAAE,CAAC;IAC3D,IAAI,WAAW,GAAG,KAAK,CAAC;IAExB,+CAA+C;IAC/C,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;YACxC,SAAS,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;YAC1C,WAAW,GAAG,IAAI,CAAC;QACrB,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;YACpE,WAAW,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,IAAI,eAAe,KAAK,SAAS,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9D,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAC/D,CAAC;QAED,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;YACzE,OAAO,GAAG,WAAW,CAAC;QACxB,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,SAAS;YAEzC,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;YAE/C,+BAA+B;YAC/B,SAAS,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;YACzD,IAAI,SAAS,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC;gBACxE,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC7B,CAAC;iBAAM,CAAC;gBACN,wEAAwE;gBACxE,IAAI,CAAC;oBACH,MAAM,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;oBACvD,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;gBAC7B,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,YAAY;wBAClB,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;qBACzD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACjF,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@cleocode/worktree",
+  "version": "2026.4.117",
+  "private": false,
+  "type": "module",
+  "description": "Native CLEO worktree backend SDK — createWorktree, destroyWorktree, listWorktrees, pruneWorktrees with XDG path canon and declarative hooks (T1161)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "cleo",
+    "worktree",
+    "git",
+    "agent",
+    "sdk",
+    "isolation"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "author": "CLEO Code <hello@cleocode.dev>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cleocode/contracts": "workspace:*",
+    "env-paths": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  }
+}