@openfleet-tools/cli 0.0.0-stage → 0.1.0

package/dist/extensions.d.ts

@@ -0,0 +1,71 @@
+import { type Workspace } from "./workspace.js";
+export declare const MANIFEST = "openfleet.extension.json";
+export declare const SLOTS: readonly ["pre-spec", "post-plan", "post-test", "post-run"];
+export declare const ROLES: readonly ["coordinator", "planner", "implementer", "tester"];
+export declare const PERMISSIONS: readonly ["read", "write", "shell", "web"];
+export declare const BUILTIN_COMMANDS: string[];
+export type Slot = (typeof SLOTS)[number];
+export type ExtRole = (typeof ROLES)[number];
+export type Permission = (typeof PERMISSIONS)[number];
+export interface ExtensionManifest {
+    name: string;
+    version: string;
+    description?: string;
+    /** Semver range of compatible @openfleet-tools/cli core versions. */
+    core: string;
+    mode: "phase" | "augment";
+    /** Required for mode "phase". */
+    slot?: Slot;
+    /** Required for mode "augment". */
+    role?: ExtRole;
+    /** Markdown instructions (relative path). Defaults to "instructions.md". */
+    instructions?: string;
+    /** CLI command name -> Markdown skill (relative path). */
+    commands?: Record<string, string>;
+    /** Defaults to ["read"]. */
+    permissions?: Permission[];
+}
+export interface LockEntry {
+    name: string;
+    /** Git URL or absolute local path the extension was installed from. */
+    source: string;
+    /** Pinned commit SHA (git sources) or "local". */
+    sha: string;
+    /** sha256 of installed contents. */
+    hash: string;
+    version: string;
+    enabled: boolean;
+    disabledReason?: string;
+    installedAt: string;
+}
+export interface LockFile {
+    v: 1;
+    extensions: LockEntry[];
+}
+export declare function emptyLock(): LockFile;
+export declare function readLock(ws: Workspace): LockFile;
+export declare function writeLock(ws: Workspace, lock: LockFile): void;
+/** Extensions are instruction-only: reject anything that could execute. */
+export declare function assertInstructionOnly(dir: string): void;
+export declare function validateManifest(dir: string): ExtensionManifest;
+export declare function permissionsOf(m: ExtensionManifest): Permission[];
+/** Map declared permissions to a Copilot custom-agent tool allow-list. */
+export declare function toolsFor(perms: Permission[]): string[];
+export declare function describePermissions(m: ExtensionManifest): string;
+export declare function isCompatible(m: ExtensionManifest, coreVersion: string): boolean;
+export interface AddResult {
+    entry: LockEntry;
+    manifest: ExtensionManifest;
+    replaced: boolean;
+}
+export declare function addExtension(ws: Workspace, source: string, coreVersion: string, cwd?: string): AddResult;
+export declare function removeExtension(ws: Workspace, name: string): void;
+export interface LoadedExtension {
+    entry: LockEntry;
+    manifest: ExtensionManifest;
+    dir: string;
+}
+/** Enabled, valid extensions in lock order. Invalid ones are reported via `warn`. */
+export declare function loadExtensions(ws: Workspace, warn?: (msg: string) => void): LoadedExtension[];
+/** Disable extensions whose `core` range excludes `coreVersion`. Returns names disabled. */
+export declare function disableIncompatible(ws: Workspace, coreVersion: string): string[];

package/dist/extensions.js

@@ -0,0 +1,297 @@
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import semver from "semver";
+import { copyDir, isDir, isFile, isInside, readJson, readJsonOr, writeJson } from "./fsutil.js";
+import { headSha, isGitRepo } from "./git.js";
+import { UserError } from "./workspace.js";
+export const MANIFEST = "openfleet.extension.json";
+export const SLOTS = ["pre-spec", "post-plan", "post-test", "post-run"];
+export const ROLES = ["coordinator", "planner", "implementer", "tester"];
+export const PERMISSIONS = ["read", "write", "shell", "web"];
+export const BUILTIN_COMMANDS = [
+    "init",
+    "update",
+    "new",
+    "resume",
+    "status",
+    "list",
+    "clean",
+    "add",
+    "remove",
+    "extensions",
+    "event",
+    "state",
+    "worktree",
+    "help",
+    "version",
+];
+const NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const ALLOWED_EXT = new Set([".md", ".json", ".txt", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"]);
+const ALLOWED_BARE = new Set(["LICENSE", "LICENCE", "NOTICE", "COPYING", ".gitignore", ".gitattributes"]);
+export function emptyLock() {
+    return { v: 1, extensions: [] };
+}
+export function readLock(ws) {
+    return readJsonOr(ws.lockFile, emptyLock());
+}
+export function writeLock(ws, lock) {
+    writeJson(ws.lockFile, lock);
+}
+function fail(dir, msg) {
+    throw new UserError(`Invalid extension at ${dir}: ${msg}`);
+}
+function relFile(dir, rel, field) {
+    if (typeof rel !== "string" || !rel)
+        fail(dir, `"${field}" must be a relative path`);
+    const abs = path.resolve(dir, rel);
+    if (!isInside(dir, abs))
+        fail(dir, `"${field}" escapes the extension folder`);
+    if (!isFile(abs))
+        fail(dir, `"${field}" file not found: ${rel}`);
+    if (path.extname(abs) !== ".md")
+        fail(dir, `"${field}" must be a Markdown file`);
+    return rel;
+}
+function walk(dir, base = dir, out = []) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === ".git")
+            continue;
+        const abs = path.join(dir, entry.name);
+        if (entry.isSymbolicLink())
+            fail(base, `symlinks are not allowed (${path.relative(base, abs)})`);
+        if (entry.isDirectory())
+            walk(abs, base, out);
+        else
+            out.push(abs);
+    }
+    return out;
+}
+/** Extensions are instruction-only: reject anything that could execute. */
+export function assertInstructionOnly(dir) {
+    for (const file of walk(dir)) {
+        const rel = path.relative(dir, file);
+        const base = path.basename(file);
+        const ext = path.extname(file).toLowerCase();
+        if (!ALLOWED_EXT.has(ext) && !ALLOWED_BARE.has(base)) {
+            fail(dir, `only Markdown/JSON/text/image files are allowed; found ${rel}`);
+        }
+        if ((fs.statSync(file).mode & 0o111) !== 0)
+            fail(dir, `executable files are not allowed (${rel})`);
+    }
+}
+export function validateManifest(dir) {
+    const file = path.join(dir, MANIFEST);
+    if (!isFile(file))
+        fail(dir, `missing ${MANIFEST}`);
+    let m;
+    try {
+        m = readJson(file);
+    }
+    catch (err) {
+        fail(dir, `${MANIFEST} is not valid JSON (${err.message})`);
+    }
+    if (typeof m.name !== "string" || !NAME.test(m.name))
+        fail(dir, `"name" must match ${NAME}`);
+    if (typeof m.version !== "string" || !semver.valid(m.version))
+        fail(dir, `"version" must be a semver version`);
+    if (typeof m.core !== "string" || !semver.validRange(m.core))
+        fail(dir, `"core" must be a semver range`);
+    if (m.description !== undefined && typeof m.description !== "string")
+        fail(dir, `"description" must be a string`);
+    if (m.mode !== "phase" && m.mode !== "augment")
+        fail(dir, `"mode" must be "phase" or "augment"`);
+    if (m.mode === "phase" && !SLOTS.includes(m.slot))
+        fail(dir, `"slot" must be one of ${SLOTS.join(", ")}`);
+    if (m.mode === "augment" && !ROLES.includes(m.role))
+        fail(dir, `"role" must be one of ${ROLES.join(", ")}`);
+    if (m.mode === "phase" && m.role !== undefined)
+        fail(dir, `"role" is only valid for mode "augment"`);
+    if (m.mode === "augment" && m.slot !== undefined)
+        fail(dir, `"slot" is only valid for mode "phase"`);
+    relFile(dir, m.instructions ?? "instructions.md", "instructions");
+    if (m.commands !== undefined) {
+        if (typeof m.commands !== "object" || m.commands === null || Array.isArray(m.commands)) {
+            fail(dir, `"commands" must be an object of name -> skill.md`);
+        }
+        for (const [cmd, skill] of Object.entries(m.commands)) {
+            if (!NAME.test(cmd))
+                fail(dir, `command name "${cmd}" must match ${NAME}`);
+            if (BUILTIN_COMMANDS.includes(cmd))
+                fail(dir, `command "${cmd}" collides with a built-in command`);
+            relFile(dir, skill, `commands.${cmd}`);
+        }
+    }
+    if (m.permissions !== undefined) {
+        if (!Array.isArray(m.permissions) || !m.permissions.every((p) => PERMISSIONS.includes(p))) {
+            fail(dir, `"permissions" must be a subset of ${PERMISSIONS.join(", ")}`);
+        }
+    }
+    assertInstructionOnly(dir);
+    return m;
+}
+export function permissionsOf(m) {
+    const set = new Set(["read", ...(m.permissions ?? [])]);
+    return PERMISSIONS.filter((p) => set.has(p));
+}
+/** Map declared permissions to a Copilot custom-agent tool allow-list. */
+export function toolsFor(perms) {
+    const tools = ["read", "search"];
+    if (perms.includes("write"))
+        tools.push("edit");
+    if (perms.includes("shell"))
+        tools.push("execute");
+    if (perms.includes("web"))
+        tools.push("web");
+    return tools;
+}
+export function describePermissions(m) {
+    const perms = permissionsOf(m);
+    const lines = perms.map((p) => {
+        switch (p) {
+            case "read":
+                return "  - read: read and search files";
+            case "write":
+                return "  - write: create and edit files";
+            case "shell":
+                return "  - shell: run shell commands";
+            case "web":
+                return "  - web: fetch URLs / search the web";
+        }
+    });
+    return lines.join("\n");
+}
+export function isCompatible(m, coreVersion) {
+    return semver.satisfies(coreVersion, m.core, { includePrerelease: true });
+}
+function hashDir(dir) {
+    const h = crypto.createHash("sha256");
+    for (const file of walk(dir).sort()) {
+        h.update(path.relative(dir, file).split(path.sep).join("/"));
+        h.update("\0");
+        h.update(fs.readFileSync(file));
+        h.update("\0");
+    }
+    return h.digest("hex");
+}
+function looksLikePath(source) {
+    return (source.startsWith(".") ||
+        source.startsWith("/") ||
+        source.startsWith("~") ||
+        /^[A-Za-z]:[\\/]/.test(source) ||
+        isDir(path.resolve(source)));
+}
+function fetchSource(source, cwd) {
+    if (looksLikePath(source)) {
+        const abs = path.resolve(cwd, source.replace(/^~(?=$|\/)/, os.homedir()));
+        if (!isDir(abs))
+            throw new UserError(`Extension path not found: ${abs}`);
+        const sha = isGitRepo(abs) ? (headSha(abs) ?? "local") : "local";
+        return { dir: abs, source: abs, sha, cleanup: () => { } };
+    }
+    const [url, ref] = source.split("#");
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "openfleet-ext-"));
+    const cleanup = () => fs.rmSync(tmp, { recursive: true, force: true });
+    try {
+        execFileSync("git", ["clone", "--quiet", url, tmp], { stdio: ["ignore", "ignore", "pipe"] });
+        if (ref)
+            execFileSync("git", ["checkout", "--quiet", ref], { cwd: tmp, stdio: ["ignore", "ignore", "pipe"] });
+        const sha = headSha(tmp);
+        if (!sha)
+            throw new Error("could not resolve HEAD");
+        return { dir: tmp, source: url, sha, cleanup };
+    }
+    catch (err) {
+        cleanup();
+        const stderr = String(err.stderr ?? err.message).trim();
+        throw new UserError(`Failed to fetch extension from ${source}: ${stderr}`);
+    }
+}
+export function addExtension(ws, source, coreVersion, cwd = process.cwd()) {
+    const fetched = fetchSource(source, cwd);
+    try {
+        const manifest = validateManifest(fetched.dir);
+        if (!isCompatible(manifest, coreVersion)) {
+            throw new UserError(`Extension "${manifest.name}" requires core ${manifest.core}, but installed core is ${coreVersion}.`);
+        }
+        const dest = path.join(ws.extensions, manifest.name);
+        fs.rmSync(dest, { recursive: true, force: true });
+        copyDir(fetched.dir, dest, (rel) => rel === ".git" || rel.startsWith(`.git${path.sep}`));
+        const lock = readLock(ws);
+        const entry = {
+            name: manifest.name,
+            source: fetched.source,
+            sha: fetched.sha,
+            hash: hashDir(dest),
+            version: manifest.version,
+            enabled: true,
+            installedAt: new Date().toISOString(),
+        };
+        const idx = lock.extensions.findIndex((e) => e.name === manifest.name);
+        if (idx >= 0)
+            lock.extensions[idx] = entry;
+        else
+            lock.extensions.push(entry);
+        writeLock(ws, lock);
+        return { entry, manifest, replaced: idx >= 0 };
+    }
+    finally {
+        fetched.cleanup();
+    }
+}
+export function removeExtension(ws, name) {
+    const lock = readLock(ws);
+    const idx = lock.extensions.findIndex((e) => e.name === name);
+    if (idx < 0 && !isDir(path.join(ws.extensions, name))) {
+        throw new UserError(`Extension "${name}" is not installed.`);
+    }
+    if (idx >= 0)
+        lock.extensions.splice(idx, 1);
+    writeLock(ws, lock);
+    fs.rmSync(path.join(ws.extensions, name), { recursive: true, force: true });
+}
+/** Enabled, valid extensions in lock order. Invalid ones are reported via `warn`. */
+export function loadExtensions(ws, warn = () => { }) {
+    const out = [];
+    for (const entry of readLock(ws).extensions) {
+        if (!entry.enabled)
+            continue;
+        const dir = path.join(ws.extensions, entry.name);
+        try {
+            out.push({ entry, manifest: validateManifest(dir), dir });
+        }
+        catch (err) {
+            warn(`Skipping extension "${entry.name}": ${err.message}`);
+        }
+    }
+    return out;
+}
+/** Disable extensions whose `core` range excludes `coreVersion`. Returns names disabled. */
+export function disableIncompatible(ws, coreVersion) {
+    const lock = readLock(ws);
+    const disabled = [];
+    for (const entry of lock.extensions) {
+        if (!entry.enabled)
+            continue;
+        const dir = path.join(ws.extensions, entry.name);
+        let reason;
+        try {
+            const m = validateManifest(dir);
+            if (!isCompatible(m, coreVersion))
+                reason = `requires core ${m.core}, installed core is ${coreVersion}`;
+        }
+        catch (err) {
+            reason = err.message;
+        }
+        if (reason) {
+            entry.enabled = false;
+            entry.disabledReason = reason;
+            disabled.push(entry.name);
+        }
+    }
+    if (disabled.length)
+        writeLock(ws, lock);
+    return disabled;
+}

package/dist/fsutil.d.ts

@@ -0,0 +1,12 @@
+export declare function readJson<T>(file: string): T;
+export declare function readJsonOr<T>(file: string, fallback: T): T;
+/** Write via temp file + rename so readers never observe a half-written file. */
+export declare function writeFileAtomic(file: string, content: string): void;
+export declare function writeJson(file: string, value: unknown): void;
+export declare function copyDir(src: string, dest: string, skip?: (rel: string) => boolean): void;
+export declare function isDir(p: string): boolean;
+export declare function isFile(p: string): boolean;
+/** True when `child` is `parent` or nested inside it. */
+/** Resolve symlinks in the longest existing prefix of `p` (the rest may not exist yet). */
+export declare function realish(p: string): string;
+export declare function isInside(parent: string, child: string): boolean;

package/dist/fsutil.js

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import path from "node:path";
+export function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+export function readJsonOr(file, fallback) {
+    try {
+        return readJson(file);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return fallback;
+        throw err;
+    }
+}
+/** Write via temp file + rename so readers never observe a half-written file. */
+export function writeFileAtomic(file, content) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, content);
+    fs.renameSync(tmp, file);
+}
+export function writeJson(file, value) {
+    writeFileAtomic(file, JSON.stringify(value, null, 2) + "\n");
+}
+export function copyDir(src, dest, skip = () => false) {
+    fs.cpSync(src, dest, {
+        recursive: true,
+        filter: (from) => !skip(path.relative(src, from)),
+    });
+}
+export function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function isFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `child` is `parent` or nested inside it. */
+/** Resolve symlinks in the longest existing prefix of `p` (the rest may not exist yet). */
+export function realish(p) {
+    const abs = path.resolve(p);
+    const rest = [];
+    let cur = abs;
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync.native(cur), ...rest.reverse());
+        }
+        catch {
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return abs;
+            rest.push(path.basename(cur));
+            cur = parent;
+        }
+    }
+}
+export function isInside(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}

package/dist/git.d.ts

@@ -0,0 +1,27 @@
+import { type ExecFileSyncOptions } from "node:child_process";
+export declare function git(cwd: string, args: string[], opts?: ExecFileSyncOptions): string;
+export declare function tryGit(cwd: string, args: string[]): string | undefined;
+export declare function isGitRepo(dir: string): boolean;
+export declare function headSha(dir: string): string | undefined;
+export type FileKind = "added" | "edited" | "deleted";
+export interface FileChange {
+    path: string;
+    kind: FileKind;
+    added: number;
+    removed: number;
+    binary?: boolean;
+}
+export interface Snapshot {
+    files: FileChange[];
+    patch: string;
+}
+/**
+ * Diff of a worktree against `base` (default HEAD), including untracked
+ * files, without touching the real index.
+ */
+export declare function snapshotWorktree(worktree: string, base?: string): Snapshot;
+/** Patch for a single file vs HEAD (handles untracked files). */
+export declare function filePatch(worktree: string, file: string): string;
+export declare function addWorktree(repoPath: string, worktree: string, branch: string, base?: string): void;
+export declare function removeWorktree(repoPath: string, worktree: string, force?: boolean): void;
+export declare function deleteBranch(repoPath: string, branch: string, force?: boolean): void;

package/dist/git.js

@@ -0,0 +1,97 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function git(cwd, args, opts = {}) {
+    return execFileSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: 256 * 1024 * 1024,
+        ...opts,
+    });
+}
+export function tryGit(cwd, args) {
+    try {
+        return git(cwd, args);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isGitRepo(dir) {
+    return tryGit(dir, ["rev-parse", "--is-inside-work-tree"])?.trim() === "true";
+}
+export function headSha(dir) {
+    return tryGit(dir, ["rev-parse", "HEAD"])?.trim();
+}
+function parseNumstat(out) {
+    const m = new Map();
+    for (const line of out.split("\n")) {
+        if (!line)
+            continue;
+        const [a, r, ...rest] = line.split("\t");
+        const file = rest.join("\t");
+        const binary = a === "-" || r === "-";
+        m.set(file, { added: binary ? 0 : Number(a), removed: binary ? 0 : Number(r), binary });
+    }
+    return m;
+}
+/**
+ * Diff of a worktree against `base` (default HEAD), including untracked
+ * files, without touching the real index.
+ */
+export function snapshotWorktree(worktree, base = "HEAD") {
+    const tmpIndex = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "openfleet-idx-")), "index");
+    const env = { ...process.env, GIT_INDEX_FILE: tmpIndex };
+    try {
+        git(worktree, ["read-tree", base], { env });
+        git(worktree, ["add", "-A", "--", "."], { env });
+        const status = git(worktree, ["diff", "--cached", "--name-status", "--no-renames", base], { env });
+        const numstat = parseNumstat(git(worktree, ["diff", "--cached", "--numstat", "--no-renames", base], { env }));
+        const patch = git(worktree, ["diff", "--cached", "--binary", "--no-renames", base], { env });
+        const files = [];
+        for (const line of status.split("\n")) {
+            if (!line)
+                continue;
+            const [code, ...rest] = line.split("\t");
+            const file = rest.join("\t");
+            const kind = code === "A" ? "added" : code === "D" ? "deleted" : "edited";
+            const n = numstat.get(file) ?? { added: 0, removed: 0, binary: false };
+            files.push({ path: file, kind, added: n.added, removed: n.removed, ...(n.binary ? { binary: true } : {}) });
+        }
+        return { files, patch };
+    }
+    finally {
+        fs.rmSync(path.dirname(tmpIndex), { recursive: true, force: true });
+    }
+}
+/** Patch for a single file vs HEAD (handles untracked files). */
+export function filePatch(worktree, file) {
+    const rel = path.isAbsolute(file) ? path.relative(worktree, file) : file;
+    const tracked = tryGit(worktree, ["ls-files", "--error-unmatch", "--", rel]) !== undefined;
+    if (tracked)
+        return tryGit(worktree, ["diff", "HEAD", "--", rel]) ?? "";
+    try {
+        git(worktree, ["diff", "--no-index", "--", "/dev/null", rel]);
+        return "";
+    }
+    catch (err) {
+        // `git diff --no-index` exits 1 when files differ; stdout holds the patch.
+        return String(err.stdout ?? "");
+    }
+}
+export function addWorktree(repoPath, worktree, branch, base) {
+    fs.mkdirSync(path.dirname(worktree), { recursive: true });
+    const exists = tryGit(repoPath, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]) !== undefined;
+    if (exists)
+        git(repoPath, ["worktree", "add", worktree, branch]);
+    else
+        git(repoPath, ["worktree", "add", "-b", branch, worktree, ...(base ? [base] : [])]);
+}
+export function removeWorktree(repoPath, worktree, force = false) {
+    git(repoPath, ["worktree", "remove", ...(force ? ["--force"] : []), worktree]);
+}
+export function deleteBranch(repoPath, branch, force = false) {
+    git(repoPath, ["branch", force ? "-D" : "-d", branch]);
+}

package/dist/hooks/handlers.d.ts

@@ -0,0 +1,43 @@
+import { type FileKind } from "../git.js";
+import { type Workspace } from "../workspace.js";
+export interface HookPayload {
+    sessionId?: string;
+    timestamp?: number | string;
+    cwd?: string;
+    source?: string;
+    reason?: string;
+    toolName?: string;
+    toolArgs?: unknown;
+    agentId?: string;
+    agentName?: string;
+    agentDisplayName?: string;
+    agentType?: string;
+    response?: string;
+    [k: string]: unknown;
+}
+export interface HookContext {
+    ws: Workspace;
+    /** Project from OPENFLEET_PROJECT, if the session was launched by the CLI. */
+    project?: string;
+}
+export interface HookOutput {
+    additionalContext?: string;
+}
+/** Hooks are a no-op unless the session is inside (or launched for) an OpenFleet workspace. */
+export declare function resolveContext(payload: HookPayload, env?: NodeJS.ProcessEnv): HookContext | undefined;
+export declare function onSessionStart(ctx: HookContext, payload: HookPayload): HookOutput;
+export declare function onSessionEnd(ctx: HookContext, payload: HookPayload): HookOutput;
+export declare function onSubagentStart(ctx: HookContext, payload: HookPayload): HookOutput;
+export declare function onSubagentStop(ctx: HookContext, payload: HookPayload): HookOutput;
+interface ToolFileChange {
+    path: string;
+    kind: FileKind;
+    added: number;
+    removed: number;
+}
+/** Extract file changes from a postToolUse payload. Only file-mutating tools are recognised. */
+export declare function fileChangesFromTool(toolName: string | undefined, rawArgs: unknown): ToolFileChange[];
+export declare function onPostToolUse(ctx: HookContext, payload: HookPayload): HookOutput;
+export declare const HANDLERS: Record<string, (ctx: HookContext, payload: HookPayload) => HookOutput>;
+export declare function runHook(event: string, payload: HookPayload, env?: NodeJS.ProcessEnv): HookOutput;
+export {};