@ferueda/grove 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grove contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# Grove
+
+> A fast, secure pool of reusable git worktrees
+
+This is the programmatic SDK for Grove.
+
+Please see the [main documentation](https://github.com/ferueda/grove#readme) for full usage instructions and API references!

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveGroveDir(repoRoot: string, root?: string): Promise<string>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAWA,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBtF"}

package/dist/config.js

@@ -0,0 +1,27 @@
+import { join, basename, isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { getRemoteUrl, shortHash } from "./git/index.js";
+function expandEnv(str) {
+    return str.replace(/\$(?:{([A-Za-z_][A-Za-z0-9_]*)}|([A-Za-z_][A-Za-z0-9_]*))/g, (_, n1, n2) => {
+        const name = n1 || n2 || "";
+        return process.env[name] || "";
+    });
+}
+export async function resolveGroveDir(repoRoot, root) {
+    let hashInput = repoRoot;
+    try {
+        hashInput = await getRemoteUrl(repoRoot);
+    }
+    catch { }
+    const repoName = basename(repoRoot);
+    const hash = shortHash(hashInput);
+    const poolName = `${repoName}-${hash}`;
+    if (!root) {
+        return join(homedir(), ".grove", poolName);
+    }
+    let expanded = expandEnv(root);
+    if (!isAbsolute(expanded)) {
+        expanded = join(repoRoot, expanded);
+    }
+    return join(expanded, ".grove", poolName);
+}

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+export type GroveErrorCode = "GROVE_EXHAUSTED" | "WORKTREE_DESTROYING" | "WORKTREE_NOT_MANAGED" | "WORKTREE_IN_USE" | "GIT_NOT_FOUND" | "GIT_COMMAND_FAILED" | "INVALID_GROVE_STATE" | "LOCK_FAILED";
+export declare class GroveError extends Error {
+    readonly code: GroveErrorCode;
+    constructor(message: string, code: GroveErrorCode);
+}
+export declare class GroveExhaustedError extends GroveError {
+    constructor(message?: string);
+}
+export declare class WorktreeDestroyingError extends GroveError {
+    constructor(message?: string);
+}
+export declare class WorktreeNotManagedError extends GroveError {
+    constructor(message?: string);
+}
+export declare class WorktreeInUseError extends GroveError {
+    constructor(message?: string);
+}
+export declare class GitNotFoundError extends GroveError {
+    constructor(message?: string);
+}
+export declare class GitCommandError extends GroveError {
+    stderr: string;
+    constructor(message: string, stderr?: string);
+}
+export declare class InvalidGroveStateError extends GroveError {
+    constructor(message?: string);
+}
+export declare class LockFailedError extends GroveError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GACtB,iBAAiB,GACjB,qBAAqB,GACrB,sBAAsB,GACtB,iBAAiB,GACjB,eAAe,GACf,oBAAoB,GACpB,qBAAqB,GACrB,aAAa,CAAC;AAElB,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAIhD;CACF;AAED,qBAAa,mBAAoB,SAAQ,UAAU;IACjD,YAAY,OAAO,GAAE,MAA0B,EAE9C;CACF;AAED,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,YAAY,OAAO,GAAE,MAAiC,EAErD;CACF;AAED,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,YAAY,OAAO,GAAE,MAA+B,EAEnD;CACF;AAED,qBAAa,kBAAmB,SAAQ,UAAU;IAChD,YAAY,OAAO,GAAE,MAA6B,EAEjD;CACF;AAED,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,YAAY,OAAO,GAAE,MAAwB,EAE5C;CACF;AAED,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,EAG/C;CACF;AAED,qBAAa,sBAAuB,SAAQ,UAAU;IACpD,YAAY,OAAO,GAAE,MAA8B,EAElD;CACF;AAED,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,YAAY,OAAO,GAAE,MAAiC,EAErD;CACF"}

package/dist/errors.js

@@ -0,0 +1,50 @@
+export class GroveError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+    }
+}
+export class GroveExhaustedError extends GroveError {
+    constructor(message = "Grove exhausted") {
+        super(message, "GROVE_EXHAUSTED");
+    }
+}
+export class WorktreeDestroyingError extends GroveError {
+    constructor(message = "Worktree is destroying") {
+        super(message, "WORKTREE_DESTROYING");
+    }
+}
+export class WorktreeNotManagedError extends GroveError {
+    constructor(message = "Worktree not managed") {
+        super(message, "WORKTREE_NOT_MANAGED");
+    }
+}
+export class WorktreeInUseError extends GroveError {
+    constructor(message = "Worktree is in use") {
+        super(message, "WORKTREE_IN_USE");
+    }
+}
+export class GitNotFoundError extends GroveError {
+    constructor(message = "Git not found") {
+        super(message, "GIT_NOT_FOUND");
+    }
+}
+export class GitCommandError extends GroveError {
+    stderr;
+    constructor(message, stderr = "") {
+        super(message, "GIT_COMMAND_FAILED");
+        this.stderr = stderr;
+    }
+}
+export class InvalidGroveStateError extends GroveError {
+    constructor(message = "Invalid grove state") {
+        super(message, "INVALID_GROVE_STATE");
+    }
+}
+export class LockFailedError extends GroveError {
+    constructor(message = "Failed to acquire lock") {
+        super(message, "LOCK_FAILED");
+    }
+}

package/dist/git/branch.d.ts

@@ -0,0 +1,9 @@
+export declare function findRepoRoot(cwd?: string): Promise<string>;
+export declare function findRepoRootFrom(cwd: string): Promise<string>;
+export declare function getDefaultBranch(repoRoot: string): Promise<string>;
+export declare function hasRemote(repoRoot: string, name: string): Promise<boolean>;
+export declare function getRemoteUrl(repoRoot: string): Promise<string>;
+export declare function shortHash(input: string): string;
+export declare function isAncestor(repoRoot: string, a: string, b: string): Promise<boolean>;
+export declare function branchRef(repoRoot: string, branch: string): Promise<string>;
+//# sourceMappingURL=branch.d.ts.map

package/dist/git/branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch.d.ts","sourceRoot":"","sources":["../../src/git/branch.ts"],"names":[],"mappings":"AAGA,wBAAsB,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEhE;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE;AAED,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwCxE;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUhF;AAED,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEpE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzF;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BjF"}

package/dist/git/branch.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { runGit } from "./run.js";
+export async function findRepoRoot(cwd) {
+    return runGit(cwd, ["rev-parse", "--show-toplevel"]);
+}
+export async function findRepoRootFrom(cwd) {
+    return findRepoRoot(cwd);
+}
+export async function getDefaultBranch(repoRoot) {
+    let mainRoot = repoRoot;
+    try {
+        let commonDir = await runGit(repoRoot, ["rev-parse", "--git-common-dir"]);
+        try {
+            commonDir = await runGit(repoRoot, [
+                "rev-parse",
+                "--path-format=absolute",
+                "--git-common-dir",
+            ]);
+        }
+        catch { }
+        if (commonDir.endsWith(".git")) {
+            mainRoot = commonDir.slice(0, -4);
+        }
+    }
+    catch { }
+    try {
+        const out = await runGit(mainRoot, ["symbolic-ref", "refs/remotes/origin/HEAD"]);
+        return out.replace("refs/remotes/origin/", "");
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const out = await runGit(mainRoot, ["symbolic-ref", "HEAD"]);
+        return out.replace("refs/heads/", "");
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const out = await runGit(mainRoot, ["config", "init.defaultBranch"]);
+        if (out)
+            return out;
+    }
+    catch {
+        // ignore
+    }
+    throw new Error("cannot determine default branch: try running 'git fetch' or ensure you are on a branch");
+}
+export async function hasRemote(repoRoot, name) {
+    try {
+        const out = await runGit(repoRoot, ["remote"]);
+        return out
+            .split("\n")
+            .map((r) => r.trim())
+            .includes(name);
+    }
+    catch {
+        return false;
+    }
+}
+export async function getRemoteUrl(repoRoot) {
+    return runGit(repoRoot, ["remote", "get-url", "origin"]);
+}
+export function shortHash(input) {
+    return createHash("sha256").update(input).digest("hex").substring(0, 6);
+}
+export async function isAncestor(repoRoot, a, b) {
+    try {
+        await runGit(repoRoot, ["merge-base", "--is-ancestor", a, b]);
+        return true; // exit code 0 means true
+    }
+    catch {
+        return false; // exit code 1 means false
+    }
+}
+export async function branchRef(repoRoot, branch) {
+    const local = `refs/heads/${branch}`;
+    const remote = `origin/${branch}`;
+    let localExists = false;
+    try {
+        await runGit(repoRoot, ["rev-parse", "--verify", local]);
+        localExists = true;
+    }
+    catch { }
+    let remoteExists = false;
+    try {
+        await runGit(repoRoot, ["rev-parse", "--verify", remote]);
+        remoteExists = true;
+    }
+    catch { }
+    if (localExists && remoteExists) {
+        if (await isAncestor(repoRoot, local, remote)) {
+            return remote; // remote is ahead or equal
+        }
+        if (await isAncestor(repoRoot, remote, local)) {
+            return branch; // local is ahead
+        }
+        return remote; // diverged, prefer remote
+    }
+    if (localExists)
+        return branch;
+    if (remoteExists)
+        return remote;
+    return branch; // fallback
+}

package/dist/git/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./run.js";
+export * from "./branch.js";
+export * from "./worktree.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/git/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/git/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dist/git/index.js

@@ -0,0 +1,3 @@
+export * from "./run.js";
+export * from "./branch.js";
+export * from "./worktree.js";

package/dist/git/run.d.ts

@@ -0,0 +1,2 @@
+export declare function runGit(cwd: string | undefined, args: string[]): Promise<string>;
+//# sourceMappingURL=run.d.ts.map

package/dist/git/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/git/run.ts"],"names":[],"mappings":"AAGA,wBAAsB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAWrF"}

package/dist/git/run.js

@@ -0,0 +1,15 @@
+import { execa } from "execa";
+import { GitCommandError, GitNotFoundError } from "../errors.js";
+export async function runGit(cwd, args) {
+    try {
+        const { stdout } = await execa("git", args, cwd ? { cwd } : undefined);
+        return stdout.trim();
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new GitNotFoundError();
+        }
+        const stderr = error.stderr || error.message || "Unknown git error";
+        throw new GitCommandError(`git ${args.join(" ")} failed`, stderr);
+    }
+}

package/dist/git/worktree.d.ts

@@ -0,0 +1,7 @@
+export declare function addWorktree(repoRoot: string, path: string, branch: string): Promise<void>;
+export declare function removeWorktree(repoRoot: string, path: string): Promise<void>;
+export declare function resetWorktree(path: string, branch: string): Promise<void>;
+export declare function detachWorktree(path: string): Promise<void>;
+export declare function isDirty(path: string): Promise<boolean>;
+export declare function fetchOrigin(repoRoot: string): Promise<void>;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/git/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/git/worktree.ts"],"names":[],"mappings":"AAGA,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG/F;AAED,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS/E;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG5D;AAED,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIjE"}

package/dist/git/worktree.js

@@ -0,0 +1,32 @@
+import { runGit } from "./run.js";
+import { branchRef, hasRemote } from "./branch.js";
+export async function addWorktree(repoRoot, path, branch) {
+    const ref = await branchRef(repoRoot, branch);
+    await runGit(repoRoot, ["worktree", "add", "--detach", "--", path, ref]);
+}
+export async function removeWorktree(repoRoot, path) {
+    await runGit(repoRoot, ["worktree", "remove", "--force", "--", path]);
+}
+export async function resetWorktree(path, branch) {
+    let repoRoot = path;
+    try {
+        repoRoot = await runGit(path, ["rev-parse", "--show-toplevel"]);
+    }
+    catch { }
+    const ref = await branchRef(repoRoot, branch);
+    await runGit(path, ["checkout", "--detach", "--force", ref]);
+    await runGit(path, ["reset", "--hard", ref]);
+    await runGit(path, ["clean", "-fd"]);
+}
+export async function detachWorktree(path) {
+    await runGit(path, ["checkout", "--detach"]);
+}
+export async function isDirty(path) {
+    const status = await runGit(path, ["status", "--porcelain"]);
+    return status.trim().length > 0;
+}
+export async function fetchOrigin(repoRoot) {
+    if (await hasRemote(repoRoot, "origin")) {
+        await runGit(repoRoot, ["fetch", "origin"]);
+    }
+}

package/dist/hooks.d.ts

@@ -0,0 +1,7 @@
+import type { Writable } from "node:stream";
+export interface RunHooksOptions {
+    stdout?: Writable;
+    stderr?: Writable;
+}
+export declare function runHooks(commands: string[], workDir: string, opts?: RunHooksOptions): Promise<void>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB;AAED,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/hooks.js

@@ -0,0 +1,33 @@
+import { execa } from "execa";
+export async function runHooks(commands, workDir, opts = {}) {
+    for (const command of commands) {
+        try {
+            const isWin = process.platform === "win32";
+            const shell = isWin ? process.env.COMSPEC || "cmd.exe" : "/bin/sh";
+            const args = isWin ? ["/d", "/s", "/c", command] : ["-c", command];
+            const child = execa(shell, args, {
+                cwd: workDir,
+                stdout: opts.stdout ? "pipe" : "ignore",
+                stderr: opts.stderr ? "pipe" : "ignore",
+                windowsVerbatimArguments: isWin,
+            });
+            if (opts.stdout) {
+                child.stdout?.pipe(opts.stdout, { end: false });
+            }
+            if (opts.stderr) {
+                child.stderr?.pipe(opts.stderr, { end: false });
+            }
+            await child;
+        }
+        catch (err) {
+            const exitCode = err.exitCode ?? -1;
+            const msg = `🌳 hook command failed: "${command}" (exit ${exitCode}): ${err.message}\n`;
+            if (opts.stderr) {
+                opts.stderr.write(msg);
+            }
+            else {
+                process.stderr.write(msg);
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { Grove } from "./pool.js";
+import type { GroveConfig } from "./schemas.js";
+export { Grove } from "./pool.js";
+export type { AcquiredSlot, WorktreeStatus, WorktreeStatusInfo } from "./pool.js";
+export { GroveConfigSchema } from "./schemas.js";
+export type { GroveConfig, WorktreeEntry, GroveState } from "./schemas.js";
+export { GroveError, GroveExhaustedError, WorktreeDestroyingError, WorktreeNotManagedError, WorktreeInUseError, GitNotFoundError, GitCommandError, InvalidGroveStateError, LockFailedError, } from "./errors.js";
+export type { GroveErrorCode } from "./errors.js";
+export declare function createGrove(configInput: GroveConfig): Promise<Grove>;
+//# 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":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAClC,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE3E,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,wBAAsB,WAAW,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAK1E"}

package/dist/index.js

@@ -0,0 +1,11 @@
+import { resolveGroveDir } from "./config.js";
+import { Grove } from "./pool.js";
+import { GroveConfigSchema } from "./schemas.js";
+export { Grove } from "./pool.js";
+export { GroveConfigSchema } from "./schemas.js";
+export { GroveError, GroveExhaustedError, WorktreeDestroyingError, WorktreeNotManagedError, WorktreeInUseError, GitNotFoundError, GitCommandError, InvalidGroveStateError, LockFailedError, } from "./errors.js";
+export async function createGrove(configInput) {
+    const config = GroveConfigSchema.parse(configInput);
+    const groveDir = config.groveDir || (await resolveGroveDir(config.repoRoot, config.groveRoot || ""));
+    return new Grove(groveDir, config);
+}

package/dist/lock.d.ts

@@ -0,0 +1,3 @@
+import { type LockOptions } from "proper-lockfile";
+export declare function withStateLock<T>(groveDir: string, fn: () => Promise<T>, opts?: LockOptions): Promise<T>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKzD,wBAAsB,aAAa,CAAC,CAAC,EACnC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,CAAC,CAAC,CAsBZ"}

package/dist/lock.js

@@ -0,0 +1,26 @@
+import { lock } from "proper-lockfile";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { LockFailedError } from "./errors.js";
+export async function withStateLock(groveDir, fn, opts) {
+    await mkdir(groveDir, { recursive: true });
+    const lockTarget = join(groveDir, "grove-state.lock");
+    await writeFile(lockTarget, "", { flag: "a" });
+    const lockOpts = {
+        retries: opts?.retries ?? { retries: 300, minTimeout: 500, maxTimeout: 2000 },
+        ...opts,
+    };
+    let release;
+    try {
+        release = await lock(lockTarget, lockOpts);
+    }
+    catch (err) {
+        throw new LockFailedError(err.message);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}

package/dist/pool.d.ts

@@ -0,0 +1,33 @@
+import type { GroveConfig } from "./index.js";
+import type { WorktreeEntry } from "./schemas.js";
+export type WorktreeStatusInfo = "available" | "dirty" | "in-use" | "you're here";
+export interface AcquiredSlot {
+    readonly path: string;
+    readonly name: string;
+}
+export interface WorktreeStatus {
+    name: string;
+    path: string;
+    status: WorktreeStatusInfo;
+    processes: {
+        PID: number;
+        Name?: string;
+    }[];
+}
+export declare class Grove {
+    readonly poolDir: string;
+    private config;
+    constructor(poolDir: string, config: GroveConfig);
+    acquire(): Promise<AcquiredSlot>;
+    release(worktreePath: string): Promise<void>;
+    private nextName;
+    list(): Promise<WorktreeStatus[]>;
+    destroy(worktreePath: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    destroyAll(options?: {
+        force?: boolean;
+    }): Promise<void>;
+    findByPath(worktreePath: string): Promise<WorktreeEntry | null>;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAQlD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,aAAa,CAAC;AAElF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,kBAAkB,CAAC;IAC3B,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7C;AAED,qBAAa,KAAK;aAEE,OAAO,EAAE,MAAM;IAC/B,OAAO,CAAC,MAAM;IAFhB,YACkB,OAAO,EAAE,MAAM,EACvB,MAAM,EAAE,WAAW,EACzB;IAEE,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CA4ErC;IAEK,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BjD;IAED,OAAO,CAAC,QAAQ;IAWV,IAAI,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAuCtC;IAEK,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDhF;IAEK,UAAU,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA6D7D;IAEK,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAQpE;CACF"}

package/dist/pool.js

@@ -0,0 +1,284 @@
+import { join, basename, dirname, isAbsolute, relative } from "node:path";
+import { mkdir, rm } from "node:fs/promises";
+import { getDefaultBranch, addWorktree, resetWorktree, removeWorktree, isDirty, fetchOrigin, } from "./git/index.js";
+import { withStateLock } from "./lock.js";
+import { readState, writeState, healState } from "./state.js";
+import { reserveOwner, ownerAlive, isWorktreeInUse, findInWorktree } from "./process/detect.js";
+import { runHooks } from "./hooks.js";
+import { GroveExhaustedError, WorktreeDestroyingError, WorktreeInUseError, WorktreeNotManagedError, } from "./errors.js";
+export class Grove {
+    poolDir;
+    config;
+    constructor(poolDir, config) {
+        this.poolDir = poolDir;
+        this.config = config;
+    }
+    async acquire() {
+        const branch = await getDefaultBranch(this.config.repoRoot);
+        if (this.config.fetchOnAcquire !== false) {
+            await fetchOrigin(this.config.repoRoot);
+        }
+        let acquiredPath = "";
+        let acquiredName = "";
+        let runPostCreate = false;
+        await withStateLock(this.poolDir, async () => {
+            let state = await readState(this.poolDir);
+            state = await healState(state);
+            for (const wt of state.worktrees) {
+                if (wt.destroying)
+                    continue;
+                const inUse = (await ownerAlive(wt)) || (await isWorktreeInUse(wt.path));
+                if (inUse)
+                    continue;
+                const dirty = await isDirty(wt.path);
+                if (dirty) {
+                    continue; // Do not destructively reset dirty worktrees
+                }
+                try {
+                    await resetWorktree(wt.path, branch); // Always reset clean worktrees to default branch
+                }
+                catch {
+                    continue;
+                }
+                await reserveOwner(wt);
+                await writeState(this.poolDir, state);
+                acquiredPath = wt.path;
+                acquiredName = wt.name;
+                runPostCreate = true;
+                return;
+            }
+            const maxTrees = this.config.maxTrees || 16;
+            if (state.worktrees.length >= maxTrees) {
+                throw new GroveExhaustedError(`Exhausted worktrees (max ${maxTrees})`);
+            }
+            const nextId = this.nextName(state);
+            const repoName = basename(this.config.repoRoot);
+            const wtPath = join(this.poolDir, nextId, repoName);
+            await mkdir(dirname(wtPath), { recursive: true });
+            await addWorktree(this.config.repoRoot, wtPath, branch);
+            const entry = {
+                name: nextId,
+                path: wtPath,
+                created_at: new Date().toISOString(),
+            };
+            await reserveOwner(entry);
+            state.worktrees.push(entry);
+            await writeState(this.poolDir, state);
+            acquiredPath = wtPath;
+            acquiredName = nextId;
+            runPostCreate = true;
+        });
+        if (runPostCreate && this.config.hooks?.postCreate) {
+            try {
+                await runHooks(this.config.hooks.postCreate, acquiredPath, {
+                    stdout: process.stderr,
+                    stderr: process.stderr,
+                });
+            }
+            catch {
+                // hook failure does not fail acquire
+            }
+        }
+        return { path: acquiredPath, name: acquiredName };
+    }
+    async release(worktreePath) {
+        const branch = await getDefaultBranch(this.config.repoRoot);
+        await withStateLock(this.poolDir, async () => {
+            const state = await readState(this.poolDir);
+            const wt = state.worktrees.find((w) => w.path === worktreePath);
+            if (!wt) {
+                throw new WorktreeNotManagedError(`worktree ${worktreePath} is not managed by grove`);
+            }
+            if (wt.destroying) {
+                throw new WorktreeDestroyingError(`worktree ${worktreePath} is being destroyed`);
+            }
+        });
+        await resetWorktree(worktreePath, branch);
+        await withStateLock(this.poolDir, async () => {
+            const state = await readState(this.poolDir);
+            const wt = state.worktrees.find((w) => w.path === worktreePath);
+            if (!wt) {
+                throw new WorktreeNotManagedError(`worktree ${worktreePath} is not managed by grove`);
+            }
+            if (wt.destroying) {
+                throw new WorktreeDestroyingError(`worktree ${worktreePath} is being destroyed`);
+            }
+            wt.owner_pid = undefined;
+            wt.owner_started_at = undefined;
+            await writeState(this.poolDir, state);
+        });
+    }
+    nextName(state) {
+        let max = 0;
+        for (const wt of state.worktrees) {
+            const n = parseInt(wt.name, 10);
+            if (!isNaN(n) && n > max) {
+                max = n;
+            }
+        }
+        return (max + 1).toString();
+    }
+    async list() {
+        const result = [];
+        await withStateLock(this.poolDir, async () => {
+            let state = await readState(this.poolDir);
+            state = await healState(state);
+            await writeState(this.poolDir, state);
+            const cwd = process.cwd();
+            for (const wt of state.worktrees) {
+                if (wt.destroying)
+                    continue;
+                let status = "available";
+                const processes = await findInWorktree(wt.path);
+                const alive = await ownerAlive(wt);
+                if (alive) {
+                    status = "in-use";
+                }
+                else if (processes.length > 0) {
+                    status = "in-use";
+                    if (cwdInWorktree(cwd, wt.path)) {
+                        status = "you're here";
+                    }
+                }
+                else if (await isDirty(wt.path)) {
+                    status = "dirty";
+                }
+                result.push({
+                    name: wt.name,
+                    path: wt.path,
+                    status,
+                    processes,
+                });
+            }
+        });
+        return result;
+    }
+    async destroy(worktreePath, options) {
+        let reserved;
+        await withStateLock(this.poolDir, async () => {
+            const state = await readState(this.poolDir);
+            const idx = state.worktrees.findIndex((wt) => wt.path === worktreePath);
+            const targetWt = state.worktrees[idx];
+            if (!targetWt) {
+                throw new WorktreeNotManagedError(`worktree ${worktreePath} is not managed by grove`);
+            }
+            if (!options?.force) {
+                const inUse = (await ownerAlive(targetWt)) || (await isWorktreeInUse(targetWt.path));
+                if (inUse) {
+                    throw new WorktreeInUseError(`worktree ${worktreePath} is in use by an agent. Use --force to override`);
+                }
+            }
+            targetWt.destroying = true;
+            await reserveOwner(targetWt);
+            reserved = { ...targetWt };
+            await writeState(this.poolDir, state);
+        });
+        if (this.config.hooks?.preDestroy) {
+            try {
+                await runHooks(this.config.hooks.preDestroy, worktreePath, {
+                    stdout: process.stderr,
+                    stderr: process.stderr,
+                });
+            }
+            catch { }
+        }
+        await withStateLock(this.poolDir, async () => {
+            const state = await readState(this.poolDir);
+            const idx = state.worktrees.findIndex((wt) => wt.path === worktreePath);
+            if (idx === -1)
+                return;
+            if (!sameDestroyReservation(state.worktrees[idx], reserved)) {
+                return;
+            }
+            try {
+                await removeWorktree(this.config.repoRoot, worktreePath);
+            }
+            catch { }
+            assertPathWithinPool(this.poolDir, worktreePath);
+            try {
+                await rm(dirname(worktreePath), { recursive: true, force: true });
+            }
+            catch { }
+            state.worktrees.splice(idx, 1);
+            await writeState(this.poolDir, state);
+        });
+    }
+    async destroyAll(options) {
+        let worktrees = [];
+        await withStateLock(this.poolDir, async () => {
+            const state = await readState(this.poolDir);
+            if (!options?.force) {
+                for (const wt of state.worktrees) {
+                    const inUse = (await ownerAlive(wt)) || (await isWorktreeInUse(wt.path));
+                    if (inUse) {
+                        throw new WorktreeInUseError(`worktree ${wt.path} is in use by an agent. Use --force to override`);
+                    }
+                }
+            }
+            for (const wt of state.worktrees) {
+                wt.destroying = true;
+                await reserveOwner(wt);
+            }
+            worktrees = state.worktrees.map((wt) => ({ ...wt }));
+            await writeState(this.poolDir, state);
+        });
+        for (const wt of worktrees) {
+            if (this.config.hooks?.preDestroy) {
+                try {
+                    await runHooks(this.config.hooks.preDestroy, wt.path, {
+                        stdout: process.stderr,
+                        stderr: process.stderr,
+                    });
+                }
+                catch { }
+            }
+        }
+        await withStateLock(this.poolDir, async () => {
+            const state = await readState(this.poolDir);
+            const remove = new Set();
+            for (const wt of worktrees) {
+                const idx = state.worktrees.findIndex((s) => s.path === wt.path);
+                if (idx === -1 || !sameDestroyReservation(state.worktrees[idx], wt)) {
+                    continue;
+                }
+                remove.add(wt.path);
+                try {
+                    await removeWorktree(this.config.repoRoot, wt.path);
+                }
+                catch { }
+                assertPathWithinPool(this.poolDir, wt.path);
+                try {
+                    await rm(dirname(wt.path), { recursive: true, force: true });
+                }
+                catch { }
+            }
+            state.worktrees = state.worktrees.filter((wt) => !remove.has(wt.path));
+            await writeState(this.poolDir, state);
+        });
+    }
+    async findByPath(worktreePath) {
+        const state = await readState(this.poolDir);
+        for (const wt of state.worktrees) {
+            if (wt.path === worktreePath) {
+                return wt;
+            }
+        }
+        return null;
+    }
+}
+function sameDestroyReservation(current, reserved) {
+    return (current.path === reserved.path &&
+        current.destroying &&
+        current.owner_pid === reserved.owner_pid &&
+        current.owner_started_at === reserved.owner_started_at);
+}
+function cwdInWorktree(cwd, worktreePath) {
+    const rel = relative(worktreePath, cwd);
+    return !rel.startsWith("..") && !isAbsolute(rel);
+}
+function assertPathWithinPool(poolDir, targetPath) {
+    const rel = relative(poolDir, targetPath);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error("Security violation: target path is outside the pool boundary");
+    }
+}

package/dist/process/detect.d.ts

@@ -0,0 +1,11 @@
+import type { WorktreeEntry } from "../schemas.js";
+export interface ProcessInfo {
+    PID: number;
+    Name?: string;
+}
+export declare function startedAt(pid: number): Promise<number | null>;
+export declare function reserveOwner(entry: WorktreeEntry): Promise<void>;
+export declare function ownerAlive(entry: WorktreeEntry): Promise<boolean>;
+export declare function findInWorktree(worktreePath: string): Promise<ProcessInfo[]>;
+export declare function isWorktreeInUse(worktreePath: string): Promise<boolean>;
+//# sourceMappingURL=detect.d.ts.map

package/dist/process/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/process/detect.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkBD,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+BnE;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtE;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAsBvE;AAUD,wBAAsB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAgDjF;AAED,wBAAsB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG5E"}

package/dist/process/detect.js

@@ -0,0 +1,147 @@
+import { realpath, readdir, readlink, stat, readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { execa } from "execa";
+let cachedBtime = null;
+const cachedClkTck = 100;
+async function getLinuxBootTime() {
+    if (cachedBtime !== null)
+        return cachedBtime;
+    try {
+        const content = await readFile("/proc/stat", "utf8");
+        const match = content.match(/^btime\s+(\d+)/m);
+        if (match && match[1]) {
+            cachedBtime = parseInt(match[1], 10) * 1000;
+            return cachedBtime;
+        }
+    }
+    catch { }
+    return Date.now() - process.uptime() * 1000;
+}
+export async function startedAt(pid) {
+    try {
+        if (process.platform === "linux") {
+            try {
+                const statContent = await readFile(`/proc/${pid}/stat`, "utf8");
+                const lastParen = statContent.lastIndexOf(")");
+                if (lastParen !== -1) {
+                    const rest = statContent
+                        .slice(lastParen + 2)
+                        .trim()
+                        .split(/\s+/);
+                    const starttimeTicks = parseInt(rest[19], 10);
+                    if (!isNaN(starttimeTicks)) {
+                        const btime = await getLinuxBootTime();
+                        const msSinceBoot = (starttimeTicks / cachedClkTck) * 1000;
+                        return btime + msSinceBoot;
+                    }
+                }
+            }
+            catch {
+                const s = await stat(`/proc/${pid}`);
+                return s.mtimeMs;
+            }
+        }
+        else if (process.platform === "darwin") {
+            const { stdout } = await execa("ps", ["-p", String(pid), "-o", "lstart="]);
+            const parsed = Date.parse(stdout.trim());
+            return Number.isNaN(parsed) ? null : parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function reserveOwner(entry) {
+    entry.owner_pid = process.pid;
+    const start = await startedAt(process.pid);
+    if (start !== null) {
+        entry.owner_started_at = start;
+    }
+}
+export async function ownerAlive(entry) {
+    if (entry.owner_pid === undefined)
+        return false;
+    // Phase 2 stub mock PID handling
+    if (entry.owner_pid === -1)
+        return false;
+    // Quick PID existence check
+    try {
+        process.kill(entry.owner_pid, 0);
+    }
+    catch {
+        return false;
+    }
+    // Exact process match check
+    if (entry.owner_started_at !== undefined) {
+        const start = await startedAt(entry.owner_pid);
+        if (start === null || start !== entry.owner_started_at) {
+            return false;
+        }
+    }
+    return true;
+}
+async function resolvePathSafe(p) {
+    try {
+        return await realpath(p);
+    }
+    catch {
+        return p;
+    }
+}
+export async function findInWorktree(worktreePath) {
+    const absWorktree = await resolvePathSafe(worktreePath);
+    const result = [];
+    if (process.platform === "linux") {
+        let procs = [];
+        try {
+            procs = await readdir("/proc");
+        }
+        catch {
+            return [];
+        }
+        for (const p of procs) {
+            if (!/^\d+$/.test(p))
+                continue;
+            try {
+                const cwd = await readlink(`/proc/${p}/cwd`);
+                const absCwd = await resolvePathSafe(cwd);
+                const rel = relative(absWorktree, absCwd);
+                if (!rel.startsWith("..") && rel !== "..") {
+                    result.push({ PID: parseInt(p, 10) });
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    else if (process.platform === "darwin") {
+        try {
+            const { stdout } = await execa("lsof", ["-F", "pn", "-d", "cwd"], { reject: false });
+            const lines = stdout.split("\n");
+            let currentPid = -1;
+            for (const line of lines) {
+                if (line.startsWith("p")) {
+                    currentPid = parseInt(line.slice(1), 10);
+                }
+                else if (line.startsWith("n") && currentPid !== -1) {
+                    const cwd = line.slice(1);
+                    const absCwd = await resolvePathSafe(cwd);
+                    const rel = relative(absWorktree, absCwd);
+                    if (!rel.startsWith("..") && rel !== "..") {
+                        result.push({ PID: currentPid });
+                    }
+                }
+            }
+        }
+        catch {
+            // lsof returns error code if it finds no files or encounters permission errors.
+        }
+    }
+    return result;
+}
+export async function isWorktreeInUse(worktreePath) {
+    const procs = await findInWorktree(worktreePath);
+    return procs.length > 0;
+}

package/dist/process/terminate.d.ts

@@ -0,0 +1,6 @@
+import { type ProcessInfo } from "./detect.js";
+export declare function parentPID(pid: number): Promise<number>;
+export declare function isAlive(pid: number): boolean;
+export declare function filterProtectedProcesses(procs: ProcessInfo[], currentPID: number): Promise<ProcessInfo[]>;
+export declare function terminateWorktreeProcesses(worktreePath: string, gracePeriodMs: number): Promise<ProcessInfo[]>;
+//# sourceMappingURL=terminate.d.ts.map

package/dist/process/terminate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminate.d.ts","sourceRoot":"","sources":["../../src/process/terminate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/D,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B5D;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO5C;AAgCD,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,WAAW,EAAE,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,EAAE,CAAC,CAaxB;AAED,wBAAsB,0BAA0B,CAC9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,EAAE,CAAC,CAWxB"}

package/dist/process/terminate.js

@@ -0,0 +1,96 @@
+import { findInWorktree } from "./detect.js";
+import { execa } from "execa";
+export async function parentPID(pid) {
+    if (process.platform === "linux") {
+        try {
+            const { readFile } = await import("node:fs/promises");
+            const stat = await readFile(`/proc/${pid}/stat`, "utf8");
+            const lastCloseParen = stat.lastIndexOf(")");
+            if (lastCloseParen !== -1) {
+                const postParen = stat.substring(lastCloseParen + 2);
+                const fields = postParen.split(" ");
+                const ppid = parseInt(fields[1] || "", 10);
+                if (!Number.isNaN(ppid)) {
+                    return ppid;
+                }
+            }
+        }
+        catch {
+            return 0;
+        }
+    }
+    else if (process.platform === "darwin") {
+        try {
+            const { stdout } = await execa("ps", ["-p", String(pid), "-o", "ppid="]);
+            const ppid = parseInt(stdout.trim(), 10);
+            if (!Number.isNaN(ppid)) {
+                return ppid;
+            }
+        }
+        catch {
+            return 0;
+        }
+    }
+    return 0;
+}
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function anyAlive(pids) {
+    return pids.some((pid) => isAlive(pid));
+}
+async function terminate(pids, gracePeriodMs) {
+    for (const pid of pids) {
+        if (isAlive(pid)) {
+            try {
+                process.kill(pid, "SIGTERM");
+            }
+            catch { }
+        }
+    }
+    const deadline = Date.now() + gracePeriodMs;
+    while (Date.now() < deadline) {
+        if (!anyAlive(pids)) {
+            return;
+        }
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    for (const pid of pids) {
+        if (isAlive(pid)) {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch { }
+        }
+    }
+}
+export async function filterProtectedProcesses(procs, currentPID) {
+    const protectedPids = new Set([currentPID]);
+    let pid = currentPID;
+    while (pid > 0) {
+        const parent = await parentPID(pid);
+        if (parent <= 0)
+            break;
+        if (protectedPids.has(parent))
+            break;
+        protectedPids.add(parent);
+        pid = parent;
+    }
+    return procs.filter((p) => !protectedPids.has(p.PID));
+}
+export async function terminateWorktreeProcesses(worktreePath, gracePeriodMs) {
+    const procs = await findInWorktree(worktreePath);
+    const targetProcs = await filterProtectedProcesses(procs, process.pid);
+    if (targetProcs.length === 0) {
+        return [];
+    }
+    const pids = targetProcs.map((p) => p.PID);
+    await terminate(pids, gracePeriodMs);
+    return targetProcs;
+}

package/dist/schemas.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+export declare const WorktreeEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    created_at: z.ZodString;
+    destroying: z.ZodOptional<z.ZodBoolean>;
+    owner_pid: z.ZodOptional<z.ZodNumber>;
+    owner_started_at: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type WorktreeEntry = z.infer<typeof WorktreeEntrySchema>;
+export declare const GroveStateSchema: z.ZodObject<{
+    worktrees: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        created_at: z.ZodString;
+        destroying: z.ZodOptional<z.ZodBoolean>;
+        owner_pid: z.ZodOptional<z.ZodNumber>;
+        owner_started_at: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GroveState = z.infer<typeof GroveStateSchema>;
+export declare const GroveConfigSchema: z.ZodObject<{
+    repoRoot: z.ZodString;
+    groveDir: z.ZodOptional<z.ZodString>;
+    groveRoot: z.ZodOptional<z.ZodString>;
+    maxTrees: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    hooks: z.ZodOptional<z.ZodObject<{
+        postCreate: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        preDestroy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    fetchOnAcquire: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+export type GroveConfig = z.input<typeof GroveConfigSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,mBAAmB;;;;;;;iBAO9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,gBAAgB;;;;;;;;;iBAE3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,iBAAiB;;;;;;;;;;iBAY5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export const WorktreeEntrySchema = z.object({
+    name: z.string(),
+    path: z.string(),
+    created_at: z.string(),
+    destroying: z.boolean().optional(),
+    owner_pid: z.number().optional(),
+    owner_started_at: z.number().optional(),
+});
+export const GroveStateSchema = z.object({
+    worktrees: z.array(WorktreeEntrySchema),
+});
+export const GroveConfigSchema = z.object({
+    repoRoot: z.string(),
+    groveDir: z.string().optional(),
+    groveRoot: z.string().optional(),
+    maxTrees: z.number().optional().default(16),
+    hooks: z
+        .object({
+        postCreate: z.array(z.string()).optional(),
+        preDestroy: z.array(z.string()).optional(),
+    })
+        .optional(),
+    fetchOnAcquire: z.boolean().optional().default(true),
+});

package/dist/state.d.ts

@@ -0,0 +1,6 @@
+import type { GroveState } from "./schemas.js";
+export declare function stateFilePath(groveDir: string): string;
+export declare function readState(groveDir: string): Promise<GroveState>;
+export declare function writeState(groveDir: string, state: GroveState): Promise<void>;
+export declare function healState(state: GroveState): Promise<GroveState>;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAK/C,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAwBrE;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnF;AAED,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAqBtE"}

package/dist/state.js

@@ -0,0 +1,58 @@
+import { readFile, writeFile, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { GroveStateSchema } from "./schemas.js";
+import { InvalidGroveStateError } from "./errors.js";
+import { ownerAlive } from "./process/detect.js";
+import { existsSync } from "node:fs";
+export function stateFilePath(groveDir) {
+    return join(groveDir, "grove-state.json");
+}
+export async function readState(groveDir) {
+    let data;
+    try {
+        data = await readFile(stateFilePath(groveDir), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { worktrees: [] };
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch {
+        throw new InvalidGroveStateError("Invalid JSON format");
+    }
+    const result = GroveStateSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new InvalidGroveStateError("State validation failed");
+    }
+    return result.data;
+}
+export async function writeState(groveDir, state) {
+    const data = JSON.stringify(state, null, 2);
+    const target = stateFilePath(groveDir);
+    const tmp = `${target}.tmp`;
+    await writeFile(tmp, data, { mode: 0o644 });
+    await rename(tmp, target);
+}
+export async function healState(state) {
+    const healed = { worktrees: [] };
+    for (const entry of state.worktrees) {
+        if (!existsSync(entry.path)) {
+            continue; // drop entries where path does not exist on disk
+        }
+        if (entry.owner_pid !== undefined) {
+            if (!(await ownerAlive(entry))) {
+                // clear owner fields
+                const { owner_pid: _p, owner_started_at: _s, destroying: _d, ...rest } = entry;
+                healed.worktrees.push(rest);
+                continue;
+            }
+        }
+        healed.worktrees.push(entry);
+    }
+    return healed;
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@ferueda/grove",
+  "version": "0.1.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "execa": "^9.6.0",
+    "proper-lockfile": "^4.0.0",
+    "zod": "^4.4.0"
+  },
+  "scripts": {
+    "build": "tsgo -p tsconfig.json"
+  }
+}