taskflow-core 0.1.0

package/dist/workspace.js

@@ -0,0 +1,178 @@
+/**
+ * Per-phase workspace isolation ("worktree isolation", STRATEGY H2).
+ *
+ * By default a phase's `cwd` is a literal path (or inherited from the run).
+ * Three reserved keywords ask the runtime to ALLOCATE an isolated working
+ * directory for the phase's subagent(s) and tear it down afterwards:
+ *
+ *   - `"temp"`      — an ephemeral dir under the OS tmpdir; removed when the
+ *                     phase finishes (success or failure). For scratch work that
+ *                     must not touch the main tree.
+ *   - `"dedicated"` — a persistent dir under the run's own state directory
+ *                     (`<runs>/ws/<runId>/<phaseId>`); kept after the phase so
+ *                     its artifacts survive for inspection / downstream reuse.
+ *                     Idempotent across resume (same path for the same phase).
+ *   - `"worktree"`  — a real `git worktree` on a throwaway branch, rooted at the
+ *                     run's git repo; removed (`git worktree remove --force`)
+ *                     when the phase finishes. For changes you want to diff /
+ *                     commit / discard in isolation. Falls back to a `temp` dir
+ *                     (fail-open) when the base dir is not a git work tree.
+ *
+ * Invariants honoured (AGENTS.md "Critical invariants"):
+ *  - Fail-open: any allocation/teardown error degrades gracefully and never
+ *    sinks the phase (a failed allocation falls back to the base cwd).
+ *  - No new deps: OS tmpdir via `fs.mkdtemp`, git via `child_process` (already
+ *    a peer of the runner). No third-party libraries.
+ *  - Resume-safe: `dedicated` is deterministic per (runId, phaseId) so a resume
+ *    reuses the same dir; `temp`/`worktree` are re-allocated cleanly.
+ *  - Path containment: `dedicated` dirs are contained under the run dir;
+ *    sanitized phase ids prevent traversal.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** The reserved `cwd` keywords that trigger workspace allocation. */
+export const WORKSPACE_KEYWORDS = ["temp", "dedicated", "worktree"];
+export function isWorkspaceKeyword(cwd) {
+    return cwd === "temp" || cwd === "dedicated" || cwd === "worktree";
+}
+/** A no-op workspace: the phase runs in `baseCwd` and nothing is torn down. */
+function inherited(baseCwd, note) {
+    return { dir: baseCwd, kind: "inherited", note, teardown() { } };
+}
+/** Sanitize a phase id for use as a path segment (mirrors safeFlowDirName). */
+function safeSegment(id) {
+    const cleaned = id.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "_");
+    return cleaned.slice(0, 100) || "phase";
+}
+/**
+ * Best-effort recursive delete, restricted to dirs we ourselves allocate
+ * (under the OS tmpdir or a run's `ws/` tree). The containment check is
+ * defense-in-depth: every `dir` passed here is already constructed by this
+ * module, but guarding ensures a future caller can't turn `rmrf` into an
+ * arbitrary-path delete.
+ */
+function rmrf(dir, allowedRoots) {
+    try {
+        const resolved = path.resolve(dir);
+        const roots = [path.resolve(os.tmpdir()), ...(allowedRoots ?? []).map((r) => path.resolve(r))];
+        const contained = roots.some((root) => resolved === root || resolved.startsWith(root + path.sep));
+        if (!contained)
+            return; // refuse to delete outside our own allocation roots
+        fs.rmSync(resolved, { recursive: true, force: true });
+    }
+    catch {
+        /* fail-open: best-effort cleanup */
+    }
+}
+/** Is `dir` inside a git work tree? (cheap, no network, fail-closed to false) */
+function isGitRepo(dir) {
+    try {
+        const r = spawnSync("git", ["-C", dir, "rev-parse", "--is-inside-work-tree"], {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        return r.status === 0 && String(r.stdout).trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/** The absolute toplevel of the git work tree containing `dir`, or undefined. */
+function gitToplevel(dir) {
+    try {
+        const r = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        if (r.status === 0)
+            return String(r.stdout).trim() || undefined;
+    }
+    catch {
+        /* fall through */
+    }
+    return undefined;
+}
+/**
+ * Allocate an isolated workspace for a phase. Always returns a usable handle:
+ * on any failure it falls back to the base cwd (fail-open) with a `note`.
+ */
+export function allocateWorkspace(kind, opts) {
+    const { baseCwd, runId, phaseId, runsRoot } = opts;
+    const seg = safeSegment(phaseId);
+    if (kind === "temp") {
+        try {
+            const dir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-tf-ws-${seg}-`));
+            return { dir, kind: "temp", teardown: () => rmrf(dir) };
+        }
+        catch (e) {
+            return inherited(baseCwd, `temp workspace alloc failed: ${errMsg(e)}`);
+        }
+    }
+    if (kind === "dedicated") {
+        try {
+            // Deterministic per (runId, phaseId) → resume reuses the same dir.
+            const dir = path.join(runsRoot, "ws", safeSegment(runId), seg);
+            fs.mkdirSync(dir, { recursive: true });
+            // Persistent by design: teardown is a no-op (kept for inspection).
+            return { dir, kind: "dedicated", teardown() { } };
+        }
+        catch (e) {
+            return inherited(baseCwd, `dedicated workspace alloc failed: ${errMsg(e)}`);
+        }
+    }
+    // kind === "worktree"
+    if (!isGitRepo(baseCwd)) {
+        // Fail-open: not a git repo → degrade to an ephemeral temp dir so the
+        // phase still gets isolation (just without git semantics).
+        const fb = allocateWorkspace("temp", opts);
+        return { ...fb, note: "worktree requested but base cwd is not a git work tree; used a temp dir instead" };
+    }
+    const top = gitToplevel(baseCwd) ?? baseCwd;
+    const branch = `tf/${safeSegment(runId)}/${seg}-${Date.now().toString(36)}`;
+    let dir;
+    try {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-tf-wt-${seg}-`));
+    }
+    catch (e) {
+        const fb = allocateWorkspace("temp", opts);
+        return { ...fb, note: `worktree temp path alloc failed: ${errMsg(e)}` };
+    }
+    // `git worktree add -b <branch> <dir>` creates the dir's contents itself, so
+    // remove the empty mkdtemp dir first and let git recreate it.
+    rmrf(dir);
+    const add = spawnSync("git", ["-C", top, "worktree", "add", "-b", branch, dir, "HEAD"], {
+        encoding: "utf-8",
+        timeout: 60000,
+    });
+    if (add.status !== 0) {
+        rmrf(dir);
+        const fb = allocateWorkspace("temp", opts);
+        return {
+            ...fb,
+            note: `git worktree add failed (${String(add.stderr).trim().slice(0, 200)}); used a temp dir instead`,
+        };
+    }
+    const teardown = () => {
+        // Remove the worktree, then delete its throwaway branch. Both best-effort.
+        try {
+            spawnSync("git", ["-C", top, "worktree", "remove", "--force", dir], { timeout: 30000 });
+        }
+        catch {
+            /* fall through to rmrf */
+        }
+        rmrf(dir);
+        try {
+            spawnSync("git", ["-C", top, "branch", "-D", branch], { timeout: 10000 });
+        }
+        catch {
+            /* fail-open: leftover branch is harmless */
+        }
+    };
+    return { dir, kind: "worktree", branch, teardown };
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

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

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "taskflow-core",
+  "version": "0.1.0",
+  "description": "Host-neutral engine for declarative, verifiable task-DAG orchestration — the runtime, DSL, cache, and verification shared by pi-taskflow and codex-taskflow.",
+  "keywords": ["taskflow", "dag", "orchestration", "subagents", "workflow"],
+  "license": "MIT",
+  "author": "heggria <bshengtao@gmail.com>",
+  "homepage": "https://github.com/heggria/pi-taskflow#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heggria/pi-taskflow.git",
+    "directory": "packages/taskflow-core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "development": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/copy-agents.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "typebox": "*"
+  }
+}