@fusionkit/workspace 0.1.0

package/dist/git.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared git invocation used across capture, materialization, pull, the
+ * test fixtures, and the compute adapter. `git` is a hard runtime
+ * dependency of this package by design — its entire job is git workspace
+ * capture — so a missing or failing git surfaces as a clear error rather
+ * than a swallowed condition.
+ */
+/** Upper bound on captured git output (bundles/diffs can be large). */
+export declare const GIT_MAX_BUFFER_BYTES: number;
+export type GitOptions = {
+    /** Return stdout even on non-zero exit instead of throwing. */
+    allowFail?: boolean;
+    maxBuffer?: number;
+};
+/** Run git and return stdout as text. */
+export declare function gitText(cwd: string, args: string[], options?: GitOptions): string;
+/** Run git and return stdout as raw bytes (for bundles and binary diffs). */
+export declare function gitBinary(cwd: string, args: string[], options?: GitOptions): Buffer;

package/dist/git.js

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Shared git invocation used across capture, materialization, pull, the
+ * test fixtures, and the compute adapter. `git` is a hard runtime
+ * dependency of this package by design — its entire job is git workspace
+ * capture — so a missing or failing git surfaces as a clear error rather
+ * than a swallowed condition.
+ */
+/** Upper bound on captured git output (bundles/diffs can be large). */
+export const GIT_MAX_BUFFER_BYTES = 256 * 1024 * 1024;
+function fail(args, detail) {
+    throw new Error(`git ${args.join(" ")} failed: ${detail}`);
+}
+/** Run git and return stdout as text. */
+export function gitText(cwd, args, options = {}) {
+    const result = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: options.maxBuffer ?? GIT_MAX_BUFFER_BYTES
+    });
+    if (result.error) {
+        fail(args, result.error.message);
+    }
+    if (result.status !== 0 && !options.allowFail) {
+        fail(args, result.stderr || result.stdout || `exit ${result.status}`);
+    }
+    return result.stdout;
+}
+/** Run git and return stdout as raw bytes (for bundles and binary diffs). */
+export function gitBinary(cwd, args, options = {}) {
+    const result = spawnSync("git", args, {
+        cwd,
+        maxBuffer: options.maxBuffer ?? GIT_MAX_BUFFER_BYTES
+    });
+    if (result.error) {
+        fail(args, result.error.message);
+    }
+    if (result.status !== 0 && !options.allowFail) {
+        fail(args, result.stderr.toString() || `exit ${result.status}`);
+    }
+    return result.stdout;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fusionkit/workspace — git workspace capture, materialization, output
+ * collection, and divergence-safe pull. Shared by the CLI (capture before
+ * a run), the runner (materialize inside a session, collect the output),
+ * and the handoff SDK (checkpoint the workspace before continuation).
+ */
+export { captureWorkspace, collectOutput, materializeWorkspace, pullRun } from "./workspace.js";
+export { gitText } from "./git.js";
+export { parseWorkspaceRelativePath, resolveInsideWorkspace } from "./paths.js";
+export type { CapturedWorkspace, PullResult, WorkspaceOutput } from "./workspace.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @fusionkit/workspace — git workspace capture, materialization, output
+ * collection, and divergence-safe pull. Shared by the CLI (capture before
+ * a run), the runner (materialize inside a session, collect the output),
+ * and the handoff SDK (checkpoint the workspace before continuation).
+ */
+export { captureWorkspace, collectOutput, materializeWorkspace, pullRun } from "./workspace.js";
+export { gitText } from "./git.js";
+export { parseWorkspaceRelativePath, resolveInsideWorkspace } from "./paths.js";

package/dist/paths.d.ts

@@ -0,0 +1,12 @@
+declare const workspaceRootBrand: unique symbol;
+declare const workspaceRelativePathBrand: unique symbol;
+export type WorkspaceRoot = string & {
+    readonly [workspaceRootBrand]: true;
+};
+export type WorkspaceRelativePath = string & {
+    readonly [workspaceRelativePathBrand]: true;
+};
+export declare function parseWorkspaceRoot(path: string): WorkspaceRoot;
+export declare function parseWorkspaceRelativePath(path: string): WorkspaceRelativePath;
+export declare function resolveInsideWorkspace(root: WorkspaceRoot | string, relativePath: WorkspaceRelativePath | string): string;
+export {};

package/dist/paths.js

@@ -0,0 +1,25 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { parseWorkspaceManifestPath } from "@fusionkit/protocol";
+function normalizeSlashes(path) {
+    return path.split("\\").join("/");
+}
+export function parseWorkspaceRoot(path) {
+    if (path.length === 0)
+        throw new Error("workspace root must not be empty");
+    return resolve(path);
+}
+export function parseWorkspaceRelativePath(path) {
+    return parseWorkspaceManifestPath(normalizeSlashes(path));
+}
+export function resolveInsideWorkspace(root, relativePath) {
+    const rootPath = parseWorkspaceRoot(root);
+    const rel = parseWorkspaceRelativePath(String(relativePath));
+    const resolved = resolve(rootPath, rel);
+    const back = relative(rootPath, resolved);
+    if (back === ".." ||
+        back.startsWith(`..${sep}`) ||
+        isAbsolute(back)) {
+        throw new Error(`workspace path escapes root: ${relativePath}`);
+    }
+    return resolved;
+}

package/dist/test/workspace.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/workspace.test.js

@@ -0,0 +1,160 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { sha256Hex } from "@fusionkit/protocol";
+import { captureWorkspace, collectOutput, materializeWorkspace, matchesPattern, pullRun } from "../workspace.js";
+import { resolveInsideWorkspace } from "../paths.js";
+function git(cwd, args) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+    assert.equal(result.status, 0, `git ${args.join(" ")}: ${result.stderr}`);
+    return result.stdout;
+}
+function makeRepo() {
+    const dir = mkdtempSync(join(tmpdir(), "warrant-test-repo-"));
+    git(dir, ["init", "--quiet", "--initial-branch=main"]);
+    git(dir, ["config", "user.email", "test@warrant.local"]);
+    git(dir, ["config", "user.name", "warrant-test"]);
+    writeFileSync(join(dir, "README.md"), "# fixture\n");
+    writeFileSync(join(dir, "src.txt"), "original\n");
+    git(dir, ["add", "-A"]);
+    git(dir, ["commit", "--quiet", "-m", "init"]);
+    return dir;
+}
+test("glob matching", () => {
+    assert.equal(matchesPattern(".env", ".env"), true);
+    assert.equal(matchesPattern("config/.env.local", ".env.*"), true);
+    assert.equal(matchesPattern("keys/server.pem", "*.pem"), true);
+    assert.equal(matchesPattern("notes.md", "*.pem"), false);
+    assert.equal(matchesPattern("a/b/c.txt", "a/**"), true);
+});
+test("workspace path helpers reject traversal and absolute paths", () => {
+    const repo = makeRepo();
+    try {
+        assert.throws(() => resolveInsideWorkspace(repo, "../outside.txt"));
+        assert.throws(() => resolveInsideWorkspace(repo, "/tmp/outside.txt"));
+        assert.equal(readFileSync(resolveInsideWorkspace(repo, "README.md"), "utf8"), "# fixture\n");
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+    }
+});
+test("capture denies secrets, includes allowlisted untracked, records denials", () => {
+    const repo = makeRepo();
+    try {
+        writeFileSync(join(repo, "src.txt"), "modified\n");
+        writeFileSync(join(repo, "notes.md"), "untracked notes\n");
+        writeFileSync(join(repo, ".env"), "SECRET=do-not-capture\n");
+        const captured = captureWorkspace(repo, { allowUntracked: ["*.md"] });
+        assert.equal(captured.manifest.untrackedFiles.length, 1);
+        assert.equal(captured.manifest.untrackedFiles[0]?.path, "notes.md");
+        assert.deepEqual(captured.manifest.deniedPaths, [".env"]);
+        assert.ok(captured.dirtyDiff, "uncommitted change should produce a diff");
+        assert.ok(captured.manifest.dirtyDiffHash);
+        const bundleText = captured.bundle.toString("latin1");
+        assert.ok(!bundleText.includes("do-not-capture"));
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+    }
+});
+test("materialize reproduces the captured workspace; output diff round-trips", async () => {
+    const repo = makeRepo();
+    const sessionDir = mkdtempSync(join(tmpdir(), "warrant-test-session-"));
+    try {
+        writeFileSync(join(repo, "src.txt"), "modified\n");
+        writeFileSync(join(repo, "notes.md"), "untracked notes\n");
+        const captured = captureWorkspace(repo, { allowUntracked: ["*.md"] });
+        const blobs = new Map();
+        blobs.set(sha256Hex(captured.bundle), captured.bundle);
+        if (captured.dirtyDiff) {
+            blobs.set(sha256Hex(captured.dirtyDiff), captured.dirtyDiff);
+        }
+        for (const file of captured.untracked) {
+            blobs.set(file.file.hash, file.content);
+        }
+        const materialized = await materializeWorkspace(sessionDir, captured.manifest, (hash) => {
+            const blob = blobs.get(hash);
+            if (!blob)
+                throw new Error(`missing blob ${hash}`);
+            return Promise.resolve(blob);
+        });
+        assert.equal(readFileSync(join(materialized, "src.txt"), "utf8"), "modified\n");
+        assert.equal(readFileSync(join(materialized, "notes.md"), "utf8"), "untracked notes\n");
+        writeFileSync(join(materialized, "agent-output.txt"), "made by agent\n");
+        const output = collectOutput(materialized, captured.manifest.baseRef);
+        assert.ok(output.diff.length > 0);
+        const paths = output.changedFiles.map((f) => f.path).sort();
+        assert.deepEqual(paths, ["agent-output.txt", "notes.md", "src.txt"]);
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+        rmSync(sessionDir, { recursive: true, force: true });
+    }
+});
+test("materialize rejects manifest paths that escape the workspace", async () => {
+    const repo = makeRepo();
+    const sessionDir = mkdtempSync(join(tmpdir(), "warrant-test-session-"));
+    try {
+        const captured = captureWorkspace(repo);
+        const manifest = {
+            ...captured.manifest,
+            untrackedFiles: [
+                {
+                    path: "../escape.txt",
+                    hash: sha256Hex(Buffer.from("escape", "utf8")),
+                    bytes: 6
+                }
+            ]
+        };
+        const blobs = new Map();
+        blobs.set(sha256Hex(captured.bundle), captured.bundle);
+        blobs.set(sha256Hex(Buffer.from("escape", "utf8")), Buffer.from("escape", "utf8"));
+        await assert.rejects(materializeWorkspace(sessionDir, manifest, (hash) => {
+            const blob = blobs.get(hash);
+            if (!blob)
+                throw new Error(`missing blob ${hash}`);
+            return Promise.resolve(blob);
+        }));
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+        rmSync(sessionDir, { recursive: true, force: true });
+    }
+});
+test("pull applies cleanly at base ref and branches on divergence", () => {
+    const repo = makeRepo();
+    try {
+        const baseRef = git(repo, ["rev-parse", "HEAD"]).trim();
+        const diff = Buffer.from([
+            "diff --git a/pulled.txt b/pulled.txt",
+            "new file mode 100644",
+            "index 0000000..7e55434",
+            "--- /dev/null",
+            "+++ b/pulled.txt",
+            "@@ -0,0 +1 @@",
+            "+pulled content",
+            ""
+        ].join("\n"), "utf8");
+        const clean = pullRun(repo, "run_clean", baseRef, diff);
+        assert.deepEqual(clean, { mode: "applied" });
+        assert.equal(readFileSync(join(repo, "pulled.txt"), "utf8"), "pulled content\n");
+        // Diverge: commit something else, then pull again.
+        writeFileSync(join(repo, "diverged.txt"), "local work\n");
+        git(repo, ["add", "-A"]);
+        git(repo, ["commit", "--quiet", "-m", "local divergence"]);
+        const diverged = pullRun(repo, "run_diverged123", baseRef, diff);
+        assert.equal(diverged.mode, "branch");
+        if (diverged.mode === "branch") {
+            const branches = git(repo, ["branch", "--list", diverged.branch]).trim();
+            assert.ok(branches.includes(diverged.branch));
+            const show = git(repo, ["show", `${diverged.branch}:pulled.txt`]);
+            assert.equal(show, "pulled content\n");
+        }
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+    }
+});

package/dist/workspace.d.ts

@@ -0,0 +1,62 @@
+import type { ManifestFile, WorkspaceManifest } from "@fusionkit/protocol";
+/** Default branch prefix and committer for divergence-safe pulls. */
+export declare const PULL_BRANCH_PREFIX = "warrant/";
+export declare const DEFAULT_PULL_COMMITTER: {
+    name: string;
+    email: string;
+};
+/** Sentinel content hash recorded for files deleted by a run. */
+export declare const DELETED_FILE_HASH: string;
+export declare const DEFAULT_DENY_PATTERNS: string[];
+export declare function matchesPattern(path: string, pattern: string): boolean;
+export type CapturedWorkspace = {
+    manifest: WorkspaceManifest;
+    bundle: Buffer;
+    dirtyDiff?: Buffer;
+    untracked: {
+        file: ManifestFile;
+        content: Buffer;
+    }[];
+};
+export type CaptureOptions = {
+    allowUntracked?: string[];
+    denyPatterns?: string[];
+};
+export declare function captureWorkspace(repoDir: string, options?: CaptureOptions): CapturedWorkspace;
+export type BlobFetcher = (hash: string) => Promise<Buffer>;
+/** Recreate the captured workspace inside a fresh session directory. */
+export declare function materializeWorkspace(sessionDir: string, manifest: WorkspaceManifest, fetchBlob: BlobFetcher): Promise<string>;
+export type WorkspaceOutput = {
+    diff: Buffer;
+    changedFiles: {
+        path: string;
+        contentHash: string;
+    }[];
+};
+/** Collect the session's output as a binary diff against the base ref. */
+export declare function collectOutput(repoDir: string, baseRef: string): WorkspaceOutput;
+export type PullResult = {
+    mode: "applied";
+} | {
+    mode: "branch";
+    branch: string;
+} | {
+    mode: "empty";
+};
+export type PullOptions = {
+    /** Always land results on a dedicated branch; never touch the checkout. */
+    forceBranch?: boolean;
+    /** Branch name prefix for branch-mode pulls. Defaults to "warrant/". */
+    branchPrefix?: string;
+    /** Committer identity for the branch-mode commit. */
+    committer?: {
+        name: string;
+        email: string;
+    };
+};
+/**
+ * Divergence-safe pull: apply the run's output diff directly only when the
+ * local workspace is clean and still at the contract's base ref; otherwise
+ * materialize the result on a dedicated branch and leave the checkout alone.
+ */
+export declare function pullRun(repoDir: string, runId: string, baseRef: string, outDiff: Buffer, options?: PullOptions): PullResult;

package/dist/workspace.js

@@ -0,0 +1,166 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { sha256Hex } from "@fusionkit/protocol";
+import { minimatch } from "minimatch";
+import { gitBinary, gitText } from "./git.js";
+import { parseWorkspaceRelativePath, parseWorkspaceRoot, resolveInsideWorkspace } from "./paths.js";
+/** Default branch prefix and committer for divergence-safe pulls. */
+export const PULL_BRANCH_PREFIX = "warrant/";
+export const DEFAULT_PULL_COMMITTER = {
+    name: "warrant",
+    email: "warrant@localhost"
+};
+/** Sentinel content hash recorded for files deleted by a run. */
+export const DELETED_FILE_HASH = "0".repeat(64);
+export const DEFAULT_DENY_PATTERNS = [
+    ".env",
+    ".env.*",
+    "*.pem",
+    "*.key",
+    "id_rsa*",
+    "id_ed25519*"
+];
+function git(cwd, args, allowFail = false) {
+    return gitText(cwd, args, { allowFail });
+}
+export function matchesPattern(path, pattern) {
+    const target = pattern.includes("/") ? path : path.split("/").pop() ?? path;
+    return minimatch(target, pattern, { dot: true });
+}
+export function captureWorkspace(repoDir, options = {}) {
+    const root = parseWorkspaceRoot(repoDir);
+    const denyPatterns = options.denyPatterns ?? DEFAULT_DENY_PATTERNS;
+    const allowUntracked = options.allowUntracked ?? [];
+    const baseRef = git(repoDir, ["rev-parse", "HEAD"]).trim();
+    const bundlePath = join(mkdtempSync(join(tmpdir(), "warrant-bundle-")), "workspace.bundle");
+    git(repoDir, ["bundle", "create", bundlePath, "HEAD"]);
+    const bundle = readFileSync(bundlePath);
+    rmSync(dirname(bundlePath), { recursive: true, force: true });
+    const dirtyDiffBuffer = gitBinary(repoDir, ["diff", "--binary", "HEAD"]);
+    const dirtyDiff = dirtyDiffBuffer.length > 0 ? dirtyDiffBuffer : undefined;
+    const untrackedPaths = git(repoDir, [
+        "ls-files",
+        "--others",
+        "--exclude-standard"
+    ])
+        .split("\n")
+        .filter((line) => line.length > 0);
+    const deniedPaths = [];
+    const untracked = [];
+    for (const path of untrackedPaths) {
+        const rel = parseWorkspaceRelativePath(path);
+        if (denyPatterns.some((pattern) => matchesPattern(path, pattern))) {
+            deniedPaths.push(rel);
+            continue;
+        }
+        if (!allowUntracked.some((pattern) => matchesPattern(path, pattern))) {
+            continue;
+        }
+        const content = readFileSync(resolveInsideWorkspace(root, rel));
+        untracked.push({
+            file: { path: rel, hash: sha256Hex(content), bytes: content.length },
+            content
+        });
+    }
+    const manifest = {
+        version: "warrant.manifest.v1",
+        baseRef,
+        bundleHash: sha256Hex(bundle),
+        ...(dirtyDiff ? { dirtyDiffHash: sha256Hex(dirtyDiff) } : {}),
+        untrackedFiles: untracked.map((u) => u.file),
+        deniedPatterns: denyPatterns,
+        deniedPaths
+    };
+    return { manifest, bundle, dirtyDiff, untracked };
+}
+/** Recreate the captured workspace inside a fresh session directory. */
+export async function materializeWorkspace(sessionDir, manifest, fetchBlob) {
+    mkdirSync(sessionDir, { recursive: true });
+    const bundlePath = join(sessionDir, "workspace.bundle");
+    writeFileSync(bundlePath, await fetchBlob(manifest.bundleHash));
+    const repoDir = join(sessionDir, "repo");
+    git(sessionDir, ["clone", "--quiet", bundlePath, repoDir]);
+    git(repoDir, ["checkout", "--quiet", manifest.baseRef]);
+    if (manifest.dirtyDiffHash) {
+        const diffPath = join(sessionDir, "dirty.patch");
+        writeFileSync(diffPath, await fetchBlob(manifest.dirtyDiffHash));
+        git(repoDir, ["apply", "--binary", "--whitespace=nowarn", diffPath]);
+    }
+    for (const file of manifest.untrackedFiles) {
+        const rel = parseWorkspaceRelativePath(file.path);
+        const content = await fetchBlob(file.hash);
+        if (sha256Hex(content) !== file.hash) {
+            throw new Error(`blob hash mismatch for ${file.path}`);
+        }
+        const target = resolveInsideWorkspace(repoDir, rel);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content);
+    }
+    return repoDir;
+}
+/** Collect the session's output as a binary diff against the base ref. */
+export function collectOutput(repoDir, baseRef) {
+    git(repoDir, ["add", "-A"]);
+    const diff = gitBinary(repoDir, ["diff", "--binary", "--cached", baseRef]);
+    const changed = git(repoDir, ["diff", "--name-only", "--cached", baseRef])
+        .split("\n")
+        .filter((line) => line.length > 0);
+    const changedFiles = changed.map((path) => {
+        const rel = parseWorkspaceRelativePath(path);
+        const full = resolveInsideWorkspace(repoDir, rel);
+        try {
+            statSync(full);
+            return { path: rel, contentHash: sha256Hex(readFileSync(full)) };
+        }
+        catch {
+            return { path: rel, contentHash: DELETED_FILE_HASH };
+        }
+    });
+    return { diff, changedFiles };
+}
+/**
+ * Divergence-safe pull: apply the run's output diff directly only when the
+ * local workspace is clean and still at the contract's base ref; otherwise
+ * materialize the result on a dedicated branch and leave the checkout alone.
+ */
+export function pullRun(repoDir, runId, baseRef, outDiff, options = {}) {
+    if (outDiff.length === 0)
+        return { mode: "empty" };
+    const head = git(repoDir, ["rev-parse", "HEAD"]).trim();
+    const dirty = git(repoDir, ["status", "--porcelain"]).trim().length > 0;
+    const diffPath = join(mkdtempSync(join(tmpdir(), "warrant-pull-")), "out.patch");
+    writeFileSync(diffPath, outDiff);
+    if (!options.forceBranch && head === baseRef && !dirty) {
+        git(repoDir, ["apply", "--binary", "--whitespace=nowarn", diffPath]);
+        rmSync(dirname(diffPath), { recursive: true, force: true });
+        return { mode: "applied" };
+    }
+    const shortId = runId.replace(/^run_/, "").slice(0, 12);
+    const branch = `${options.branchPrefix ?? PULL_BRANCH_PREFIX}${shortId}`;
+    const committer = options.committer ?? DEFAULT_PULL_COMMITTER;
+    const worktree = mkdtempSync(join(tmpdir(), "warrant-worktree-"));
+    try {
+        git(repoDir, ["worktree", "add", "--detach", worktree, baseRef]);
+        git(worktree, ["apply", "--binary", "--whitespace=nowarn", diffPath]);
+        git(worktree, ["add", "-A"]);
+        git(worktree, [
+            "-c",
+            `user.name=${committer.name}`,
+            "-c",
+            `user.email=${committer.email}`,
+            "commit",
+            "--quiet",
+            "-m",
+            `warrant run ${runId}`
+        ]);
+        const commit = git(worktree, ["rev-parse", "HEAD"]).trim();
+        git(repoDir, ["branch", "-f", branch, commit]);
+    }
+    finally {
+        git(repoDir, ["worktree", "remove", "--force", worktree], true);
+        rmSync(worktree, { recursive: true, force: true });
+        rmSync(dirname(diffPath), { recursive: true, force: true });
+    }
+    return { mode: "branch", branch };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@fusionkit/workspace",
+  "private": false,
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/workspace"
+  },
+  "description": "Workspace capture, materialization, and divergence-safe pull. Shared by the CLI, runner, and handoff SDK.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "minimatch": "10.2.5",
+    "@fusionkit/protocol": "0.1.0"
+  }
+}