@cleocode/worktree 2026.4.117

package/dist/compat.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Backward-compatibility shim for callers of `packages/cant/src/worktree.ts`.
+ *
+ * Provides the legacy `WorktreeConfig`-based API surface on top of the new
+ * native SDK. Callers that import from `@cleocode/cant` continue working
+ * unchanged; new callers should use the primary SDK surface in `index.ts`.
+ *
+ * @remarks
+ * These adapters are deprecated and will be removed once all callers have
+ * been migrated to `@cleocode/worktree`.
+ *
+ * @deprecated Use `@cleocode/worktree` directly.
+ * @task T1161
+ */
+/**
+ * Request payload for creating a new git worktree (legacy API).
+ *
+ * @deprecated Use {@link CreateWorktreeOptions} from `@cleocode/worktree`.
+ */
+export interface LegacyWorktreeRequest {
+    /** The base ref to branch from (e.g. "main", "develop", a SHA). */
+    baseRef: string;
+    /** Branch name for the worktree. If absent, derived from taskId. */
+    branchName?: string;
+    /** Task ID driving this worktree. */
+    taskId: string;
+    /** Why this worktree is being created. */
+    reason: 'subagent' | 'experiment' | 'parallel-wave';
+}
+/**
+ * Handle returned after worktree creation (legacy API).
+ *
+ * @deprecated Use {@link CreateWorktreeResult} from `@cleocode/worktree`.
+ */
+export interface LegacyWorktreeHandle {
+    /** Absolute path to the worktree directory. */
+    path: string;
+    /** Branch name created for this worktree. */
+    branch: string;
+    /** The base ref it was branched from. */
+    baseRef: string;
+    /** Task ID. */
+    taskId: string;
+    /** Project hash. */
+    projectHash: string;
+    /** Clean up: remove the worktree and optionally delete the branch. */
+    cleanup(deleteBranch?: boolean): void;
+}
+/**
+ * Configuration for worktree path resolution (legacy API).
+ *
+ * @deprecated Use `projectRoot` directly with the new SDK functions.
+ */
+export interface LegacyWorktreeConfig {
+    /** Root directory for worktrees. Defaults to XDG_DATA_HOME/cleo/worktrees/<projectHash>/ */
+    worktreeRoot?: string;
+    /** Project hash for path scoping. */
+    projectHash: string;
+    /** The project's git root directory. */
+    gitRoot: string;
+}
+/**
+ * Result of a merge operation (legacy API).
+ *
+ * @deprecated Use {@link DestroyWorktreeResult} from `@cleocode/worktree`.
+ */
+export interface LegacyMergeResult {
+    /** Whether the merge succeeded. */
+    success: boolean;
+    /** Error message if the merge failed. */
+    error?: string;
+}
+/**
+ * Entry in the list of active worktrees (legacy API).
+ *
+ * @deprecated Use {@link WorktreeListEntry} from `@cleocode/contracts`.
+ */
+export interface LegacyWorktreeEntry {
+    /** Absolute path to the worktree directory. */
+    path: string;
+    /** Branch checked out in this worktree. */
+    branch: string;
+}
+/**
+ * Resolve the worktree root directory (legacy API).
+ *
+ * @deprecated Use `resolveWorktreeRoot` from `@cleocode/worktree`.
+ * @param config - Legacy worktree config.
+ * @returns Absolute path to the worktree root directory.
+ */
+export declare function legacyResolveWorktreeRoot(config: LegacyWorktreeConfig): string;
+/**
+ * Create a git worktree using the legacy config-based API.
+ *
+ * Wraps the new native SDK but returns a {@link LegacyWorktreeHandle} for
+ * backward compatibility. Callers should migrate to `createWorktree` from
+ * `@cleocode/worktree`.
+ *
+ * @deprecated Use `createWorktree` from `@cleocode/worktree`.
+ * @param request - Legacy worktree request.
+ * @param config - Legacy worktree config.
+ * @returns A legacy handle with a cleanup function.
+ */
+export declare function legacyCreateWorktree(request: LegacyWorktreeRequest, config: LegacyWorktreeConfig): LegacyWorktreeHandle;
+/**
+ * Merge a worktree's branch back into the current branch (legacy API).
+ *
+ * @deprecated Use `destroyWorktree` with `cherryPickFirst: true` from
+ * `@cleocode/worktree`.
+ * @param handle - Legacy worktree handle.
+ * @param config - Legacy worktree config.
+ * @param options - Merge strategy options.
+ * @returns Merge result.
+ */
+export declare function legacyMergeWorktree(handle: LegacyWorktreeHandle, config: LegacyWorktreeConfig, options?: {
+    strategy?: 'ff-only' | 'no-ff';
+}): LegacyMergeResult;
+/**
+ * List active worktrees scoped to the current project (legacy API).
+ *
+ * @deprecated Use `listWorktrees` from `@cleocode/worktree`.
+ * @param config - Legacy worktree config.
+ * @returns Array of legacy worktree entries.
+ */
+export declare function legacyListWorktrees(config: LegacyWorktreeConfig): LegacyWorktreeEntry[];
+//# sourceMappingURL=compat.d.ts.map

package/dist/compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compat.d.ts","sourceRoot":"","sources":["../src/compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,eAAe,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe;IACf,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,OAAO,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAE9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,CAuBtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAA;CAAO,GAC/C,iBAAiB,CAenB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,mBAAmB,EAAE,CA2BvF"}

package/dist/compat.js

@@ -0,0 +1,160 @@
+/**
+ * Backward-compatibility shim for callers of `packages/cant/src/worktree.ts`.
+ *
+ * Provides the legacy `WorktreeConfig`-based API surface on top of the new
+ * native SDK. Callers that import from `@cleocode/cant` continue working
+ * unchanged; new callers should use the primary SDK surface in `index.ts`.
+ *
+ * @remarks
+ * These adapters are deprecated and will be removed once all callers have
+ * been migrated to `@cleocode/worktree`.
+ *
+ * @deprecated Use `@cleocode/worktree` directly.
+ * @task T1161
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { gitSilent, gitSync } from './git.js';
+import { resolveWorktreeRootForHash } from './paths.js';
+// ---------------------------------------------------------------------------
+// Legacy API implementations
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the worktree root directory (legacy API).
+ *
+ * @deprecated Use `resolveWorktreeRoot` from `@cleocode/worktree`.
+ * @param config - Legacy worktree config.
+ * @returns Absolute path to the worktree root directory.
+ */
+export function legacyResolveWorktreeRoot(config) {
+    return resolveWorktreeRootForHash(config.projectHash, config.worktreeRoot);
+}
+/**
+ * Create a git worktree using the legacy config-based API.
+ *
+ * Wraps the new native SDK but returns a {@link LegacyWorktreeHandle} for
+ * backward compatibility. Callers should migrate to `createWorktree` from
+ * `@cleocode/worktree`.
+ *
+ * @deprecated Use `createWorktree` from `@cleocode/worktree`.
+ * @param request - Legacy worktree request.
+ * @param config - Legacy worktree config.
+ * @returns A legacy handle with a cleanup function.
+ */
+export function legacyCreateWorktree(request, config) {
+    const root = legacyResolveWorktreeRoot(config);
+    mkdirSync(root, { recursive: true });
+    const branch = request.branchName ?? `task/${request.taskId}`;
+    const worktreePath = join(root, request.taskId);
+    // Remove stale worktree if it exists.
+    if (existsSync(worktreePath)) {
+        try {
+            gitSilent(['worktree', 'unlock', worktreePath], config.gitRoot);
+            if (!gitSilent(['worktree', 'remove', '--force', worktreePath], config.gitRoot)) {
+                rmSync(worktreePath, { recursive: true, force: true });
+            }
+        }
+        catch {
+            rmSync(worktreePath, { recursive: true, force: true });
+        }
+    }
+    // Create the worktree.
+    gitSync(['worktree', 'add', worktreePath, '-b', branch, request.baseRef], config.gitRoot);
+    return buildLegacyHandle(worktreePath, branch, request.baseRef, request.taskId, config);
+}
+/**
+ * Merge a worktree's branch back into the current branch (legacy API).
+ *
+ * @deprecated Use `destroyWorktree` with `cherryPickFirst: true` from
+ * `@cleocode/worktree`.
+ * @param handle - Legacy worktree handle.
+ * @param config - Legacy worktree config.
+ * @param options - Merge strategy options.
+ * @returns Merge result.
+ */
+export function legacyMergeWorktree(handle, config, options = {}) {
+    const strategy = options.strategy ?? 'ff-only';
+    const mergeFlag = strategy === 'ff-only' ? '--ff-only' : '--no-ff';
+    try {
+        gitSync(['merge', mergeFlag, handle.branch], config.gitRoot);
+        handle.cleanup(true);
+        return { success: true };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            success: false,
+            error: `Merge failed: ${message}. Worktree retained at ${handle.path} for forensics.`,
+        };
+    }
+}
+/**
+ * List active worktrees scoped to the current project (legacy API).
+ *
+ * @deprecated Use `listWorktrees` from `@cleocode/worktree`.
+ * @param config - Legacy worktree config.
+ * @returns Array of legacy worktree entries.
+ */
+export function legacyListWorktrees(config) {
+    try {
+        const output = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+            cwd: config.gitRoot,
+            encoding: 'utf-8',
+        });
+        const entries = [];
+        const root = legacyResolveWorktreeRoot(config);
+        let currentPath = '';
+        let currentBranch = '';
+        for (const line of output.split('\n')) {
+            if (line.startsWith('worktree ')) {
+                currentPath = line.slice('worktree '.length);
+            }
+            else if (line.startsWith('branch ')) {
+                currentBranch = line.slice('branch refs/heads/'.length);
+            }
+            else if (line === '') {
+                if (currentPath.startsWith(root)) {
+                    entries.push({ path: currentPath, branch: currentBranch });
+                }
+                currentPath = '';
+                currentBranch = '';
+            }
+        }
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build a legacy WorktreeHandle with a cleanup closure.
+ * @internal
+ */
+function buildLegacyHandle(worktreePath, branch, baseRef, taskId, config) {
+    return {
+        path: worktreePath,
+        branch,
+        baseRef,
+        taskId,
+        projectHash: config.projectHash,
+        cleanup(deleteBranch = false) {
+            try {
+                gitSilent(['worktree', 'unlock', worktreePath], config.gitRoot);
+                if (!gitSilent(['worktree', 'remove', '--force', worktreePath], config.gitRoot)) {
+                    rmSync(worktreePath, { recursive: true, force: true });
+                }
+            }
+            catch {
+                rmSync(worktreePath, { recursive: true, force: true });
+            }
+            if (deleteBranch) {
+                gitSilent(['branch', '-D', branch], config.gitRoot);
+            }
+        },
+    };
+}
+//# sourceMappingURL=compat.js.map

package/dist/compat.js.map

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

package/dist/git.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Low-level git helpers for @cleocode/worktree.
+ *
+ * All git invocations use `execFileSync` / `execFile` with explicit arg
+ * arrays (never shell interpolation) to prevent command injection.
+ *
+ * @task T1161
+ */
+/**
+ * Run a git command synchronously and return trimmed stdout.
+ *
+ * @param args - Git argument array (do NOT include "git" as first element).
+ * @param cwd - Working directory for the git command.
+ * @returns Trimmed stdout string.
+ * @throws Error if the command exits non-zero.
+ */
+export declare function gitSync(args: string[], cwd: string): string;
+/**
+ * Run a git command synchronously, returning false instead of throwing on error.
+ *
+ * Useful for best-effort cleanup operations where failure is non-fatal.
+ *
+ * @param args - Git argument array.
+ * @param cwd - Working directory.
+ * @returns true on exit 0, false otherwise.
+ */
+export declare function gitSilent(args: string[], cwd: string): boolean;
+/**
+ * Run a git command asynchronously, returning trimmed stdout.
+ *
+ * @param args - Git argument array.
+ * @param cwd - Working directory.
+ * @returns Promise resolving to trimmed stdout.
+ * @throws Error if the command exits non-zero.
+ */
+export declare function gitAsync(args: string[], cwd: string): Promise<string>;
+/**
+ * Determine the git root directory for a given project path.
+ *
+ * @param projectRoot - Absolute path to start the search from.
+ * @returns Absolute path to the git root.
+ * @throws Error if not inside a git repository.
+ */
+export declare function getGitRoot(projectRoot: string): string;
+/**
+ * Resolve the current HEAD ref (branch name or SHA) for a git repository.
+ *
+ * @param gitRoot - Absolute path to the git root.
+ * @param fallback - Value to return if HEAD resolution fails.
+ * @returns Current HEAD ref string.
+ */
+export declare function resolveHeadRef(gitRoot: string, fallback?: string): string;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAO9D;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM3E;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAS,GAAG,MAAM,CAMzE"}

package/dist/git.js

@@ -0,0 +1,90 @@
+/**
+ * Low-level git helpers for @cleocode/worktree.
+ *
+ * All git invocations use `execFileSync` / `execFile` with explicit arg
+ * arrays (never shell interpolation) to prevent command injection.
+ *
+ * @task T1161
+ */
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Run a git command synchronously and return trimmed stdout.
+ *
+ * @param args - Git argument array (do NOT include "git" as first element).
+ * @param cwd - Working directory for the git command.
+ * @returns Trimmed stdout string.
+ * @throws Error if the command exits non-zero.
+ */
+export function gitSync(args, cwd) {
+    return execFileSync('git', args, {
+        cwd,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+}
+/**
+ * Run a git command synchronously, returning false instead of throwing on error.
+ *
+ * Useful for best-effort cleanup operations where failure is non-fatal.
+ *
+ * @param args - Git argument array.
+ * @param cwd - Working directory.
+ * @returns true on exit 0, false otherwise.
+ */
+export function gitSilent(args, cwd) {
+    try {
+        execFileSync('git', args, { cwd, stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run a git command asynchronously, returning trimmed stdout.
+ *
+ * @param args - Git argument array.
+ * @param cwd - Working directory.
+ * @returns Promise resolving to trimmed stdout.
+ * @throws Error if the command exits non-zero.
+ */
+export async function gitAsync(args, cwd) {
+    const { stdout } = await execFileAsync('git', args, {
+        cwd,
+        encoding: 'utf-8',
+    });
+    return stdout.trim();
+}
+/**
+ * Determine the git root directory for a given project path.
+ *
+ * @param projectRoot - Absolute path to start the search from.
+ * @returns Absolute path to the git root.
+ * @throws Error if not inside a git repository.
+ */
+export function getGitRoot(projectRoot) {
+    try {
+        return gitSync(['rev-parse', '--show-toplevel'], projectRoot);
+    }
+    catch {
+        throw new Error(`Not a git repository: ${projectRoot}`);
+    }
+}
+/**
+ * Resolve the current HEAD ref (branch name or SHA) for a git repository.
+ *
+ * @param gitRoot - Absolute path to the git root.
+ * @param fallback - Value to return if HEAD resolution fails.
+ * @returns Current HEAD ref string.
+ */
+export function resolveHeadRef(gitRoot, fallback = 'main') {
+    try {
+        return gitSync(['rev-parse', '--abbrev-ref', 'HEAD'], gitRoot);
+    }
+    catch {
+        return fallback;
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,IAAc,EAAE,GAAW;IACjD,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE;QAC/B,GAAG;QACH,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,IAAc,EAAE,GAAW;IACnD,IAAI,CAAC;QACH,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAc,EAAE,GAAW;IACxD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE;QAClD,GAAG;QACH,QAAQ,EAAE,OAAO;KAClB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,WAAmB;IAC5C,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE,WAAW,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,yBAAyB,WAAW,EAAE,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,QAAQ,GAAG,MAAM;IAC/D,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @cleocode/worktree — Native CLEO worktree backend SDK.
+ *
+ * Formalizes the scattered worktree logic from:
+ *   - `packages/cant/src/worktree.ts`
+ *   - `packages/core/src/spawn/branch-lock.ts`
+ *   - `packages/core/src/sentient/baseline.ts` (integrated via dispatch)
+ *   - `packages/core/src/sentient/merge.ts` (integrated via dispatch)
+ *
+ * Canonical worktree path layout per D029:
+ *   `~/.local/share/cleo/worktrees/<projectHash>/<taskId>/`
+ *
+ * Native lift of worktrunk's two missing features (D030):
+ *   1. Declarative hooks framework (post-create / post-start)
+ *   2. `.cleo/worktree-include` glob pattern support
+ *
+ * Zero worktrunk dependency — all logic is CLEO-native.
+ *
+ * @packageDocumentation
+ * @task T1161
+ * @adr ADR-055
+ */
+export type { CreateWorktreeOptions, CreateWorktreeResult, DestroyWorktreeOptions, DestroyWorktreeResult, ListWorktreesOptions, PruneWorktreesOptions, PruneWorktreesResult, WorktreeHook, WorktreeHookResult, WorktreeIncludePattern, WorktreeListEntry, } from '@cleocode/contracts';
+export type { LegacyMergeResult, LegacyWorktreeConfig, LegacyWorktreeEntry, LegacyWorktreeHandle, LegacyWorktreeRequest, } from './compat.js';
+export { legacyCreateWorktree, legacyListWorktrees, legacyMergeWorktree, legacyResolveWorktreeRoot, } from './compat.js';
+export { createWorktree } from './worktree-create.js';
+export { destroyWorktree } from './worktree-destroy.js';
+export { runWorktreeHooks } from './worktree-hooks.js';
+export { applyIncludePatterns, loadWorktreeIncludePatterns } from './worktree-include.js';
+export { listWorktrees, listWorktreesByProjectRoot, resolveWorktreeRoot, } from './worktree-list.js';
+export { pruneWorktrees } from './worktree-prune.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+/**
+ * @cleocode/worktree — Native CLEO worktree backend SDK.
+ *
+ * Formalizes the scattered worktree logic from:
+ *   - `packages/cant/src/worktree.ts`
+ *   - `packages/core/src/spawn/branch-lock.ts`
+ *   - `packages/core/src/sentient/baseline.ts` (integrated via dispatch)
+ *   - `packages/core/src/sentient/merge.ts` (integrated via dispatch)
+ *
+ * Canonical worktree path layout per D029:
+ *   `~/.local/share/cleo/worktrees/<projectHash>/<taskId>/`
+ *
+ * Native lift of worktrunk's two missing features (D030):
+ *   1. Declarative hooks framework (post-create / post-start)
+ *   2. `.cleo/worktree-include` glob pattern support
+ *
+ * Zero worktrunk dependency — all logic is CLEO-native.
+ *
+ * @packageDocumentation
+ * @task T1161
+ * @adr ADR-055
+ */
+export { legacyCreateWorktree, legacyListWorktrees, legacyMergeWorktree, legacyResolveWorktreeRoot, } from './compat.js';
+export { createWorktree } from './worktree-create.js';
+export { destroyWorktree } from './worktree-destroy.js';
+export { runWorktreeHooks } from './worktree-hooks.js';
+export { applyIncludePatterns, loadWorktreeIncludePatterns } from './worktree-include.js';
+export { listWorktrees, listWorktreesByProjectRoot, resolveWorktreeRoot, } from './worktree-list.js';
+export { pruneWorktrees } from './worktree-prune.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAwBH,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,51 @@
+/**
+ * XDG-compliant worktree path resolution for @cleocode/worktree.
+ *
+ * Canonical layout per D029:
+ *   Linux:   ~/.local/share/cleo/worktrees/<projectHash>/<taskId>/
+ *   macOS:   ~/Library/Application Support/cleo/worktrees/<projectHash>/<taskId>/
+ *   Windows: %LOCALAPPDATA%\cleo\Data\worktrees\<projectHash>\<taskId>\
+ *
+ * All path derivation flows through `resolveWorktreeRootForHash` — never
+ * hardcode `~/.local/share/cleo`. Use env-paths + `CLEO_HOME` env override
+ * matching the convention in `packages/core/src/system/platform-paths.ts`.
+ *
+ * @task T1161
+ */
+/**
+ * Compute a project hash from an absolute project root path.
+ *
+ * Produces a 16-character hex prefix of SHA-256 to stay consistent with
+ * `packages/core/src/spawn/branch-lock.ts#resolveAgentWorktreeRoot`.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @returns 16-character lowercase hex string.
+ */
+export declare function computeProjectHash(projectRoot: string): string;
+/**
+ * Resolve the XDG worktrees root directory for a given project hash.
+ *
+ * Priority order:
+ *   1. `worktreeRoot` arg (explicit override — for tests or config)
+ *   2. `CLEO_HOME` env var (backward-compat with legacy installations)
+ *   3. env-paths XDG data dir (platform-appropriate default)
+ *
+ * Result: `<dataDir>/worktrees/<projectHash>/`
+ *
+ * @param projectHash - 16-char project hash from {@link computeProjectHash}.
+ * @param worktreeRoot - Optional override for the full worktree root.
+ * @returns Absolute path to the project-scoped worktree root directory.
+ */
+export declare function resolveWorktreeRootForHash(projectHash: string, worktreeRoot?: string): string;
+/**
+ * Resolve the worktree directory for a specific task.
+ *
+ * Result: `<worktreeRoot>/<taskId>/`
+ *
+ * @param projectHash - 16-char project hash.
+ * @param taskId - The task ID.
+ * @param worktreeRoot - Optional override for the root directory.
+ * @returns Absolute path to the task-specific worktree directory.
+ */
+export declare function resolveTaskWorktreePath(projectHash: string, taskId: string, worktreeRoot?: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAM7F;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAER"}

package/dist/paths.js

@@ -0,0 +1,66 @@
+/**
+ * XDG-compliant worktree path resolution for @cleocode/worktree.
+ *
+ * Canonical layout per D029:
+ *   Linux:   ~/.local/share/cleo/worktrees/<projectHash>/<taskId>/
+ *   macOS:   ~/Library/Application Support/cleo/worktrees/<projectHash>/<taskId>/
+ *   Windows: %LOCALAPPDATA%\cleo\Data\worktrees\<projectHash>\<taskId>\
+ *
+ * All path derivation flows through `resolveWorktreeRootForHash` — never
+ * hardcode `~/.local/share/cleo`. Use env-paths + `CLEO_HOME` env override
+ * matching the convention in `packages/core/src/system/platform-paths.ts`.
+ *
+ * @task T1161
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import envPaths from 'env-paths';
+const APP_NAME = 'cleo';
+/**
+ * Compute a project hash from an absolute project root path.
+ *
+ * Produces a 16-character hex prefix of SHA-256 to stay consistent with
+ * `packages/core/src/spawn/branch-lock.ts#resolveAgentWorktreeRoot`.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @returns 16-character lowercase hex string.
+ */
+export function computeProjectHash(projectRoot) {
+    return createHash('sha256').update(projectRoot).digest('hex').slice(0, 16);
+}
+/**
+ * Resolve the XDG worktrees root directory for a given project hash.
+ *
+ * Priority order:
+ *   1. `worktreeRoot` arg (explicit override — for tests or config)
+ *   2. `CLEO_HOME` env var (backward-compat with legacy installations)
+ *   3. env-paths XDG data dir (platform-appropriate default)
+ *
+ * Result: `<dataDir>/worktrees/<projectHash>/`
+ *
+ * @param projectHash - 16-char project hash from {@link computeProjectHash}.
+ * @param worktreeRoot - Optional override for the full worktree root.
+ * @returns Absolute path to the project-scoped worktree root directory.
+ */
+export function resolveWorktreeRootForHash(projectHash, worktreeRoot) {
+    if (worktreeRoot)
+        return worktreeRoot;
+    const ep = envPaths(APP_NAME, { suffix: '' });
+    // CLEO_HOME overrides the data path for backward compatibility.
+    const dataDir = process.env['CLEO_HOME'] ?? ep.data;
+    return join(dataDir, 'worktrees', projectHash);
+}
+/**
+ * Resolve the worktree directory for a specific task.
+ *
+ * Result: `<worktreeRoot>/<taskId>/`
+ *
+ * @param projectHash - 16-char project hash.
+ * @param taskId - The task ID.
+ * @param worktreeRoot - Optional override for the root directory.
+ * @returns Absolute path to the task-specific worktree directory.
+ */
+export function resolveTaskWorktreePath(projectHash, taskId, worktreeRoot) {
+    return join(resolveWorktreeRootForHash(projectHash, worktreeRoot), taskId);
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,QAAQ,MAAM,WAAW,CAAC;AAEjC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,0BAA0B,CAAC,WAAmB,EAAE,YAAqB;IACnF,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IACtC,MAAM,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;IAC9C,gEAAgE;IAChE,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC;IACpD,OAAO,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACrC,WAAmB,EACnB,MAAc,EACd,YAAqB;IAErB,OAAO,IAAI,CAAC,0BAA0B,CAAC,WAAW,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC;AAC7E,CAAC"}