@lchase/yak 0.6.0 → 0.7.0

package/README.md

@@ -46,8 +46,11 @@ bug) for a guided walkthrough — also live at
   and journals a clean `failed`/`cancelled` terminal state, so any
   out-of-process supervisor has a supported kill.
 - **Worktree isolation:** `yak run --isolation worktree` runs the whole
-  workflow inside a fresh git worktree; `map` steps can additionally
-  isolate each item into its own sibling worktree.
+  workflow inside a fresh git worktree forked from `HEAD`. `--from <ref>`
+  forks that worktree from another commit (`origin/main`, a branch, a
+  SHA) without moving the checkout; the ref is resolved once and resume
+  reuses that commit. `map` steps can additionally isolate each item
+  into its own sibling worktree forked from the run worktree.
 - **Introspection:** `yak graph <workflow>` emits a workflow's DAG as
   Mermaid; `yak watch [<run-id>]` live-tails a run's step statuses in a
   terminal UI; `yak artifacts [<run-id>]` lists a `map` step's per-item

package/dist/index.js

@@ -68,7 +68,7 @@ async function writeRejectedOutput(runDir, stepId, attempt, content) {
 
 // src/engine/run.ts
 import { randomBytes as randomBytes2 } from "crypto";
-import { mkdir as mkdir6, readdir as readdir2, readFile as readFile9, writeFile as writeFile4 } from "fs/promises";
+import { access, mkdir as mkdir6, readdir as readdir2, readFile as readFile9, writeFile as writeFile4 } from "fs/promises";
 import path15 from "path";
 import { z as z9 } from "zod";
 
@@ -344,7 +344,7 @@ import { promisify } from "util";
 import jexl from "jexl";
 var PLACEHOLDER_RE = /\{\{\s*([^}]+?)\s*\}\}/g;
 var IDENTIFIER = /[A-Za-z_$][A-Za-z0-9_$]*/y;
-var NOT_A_ROOT = /* @__PURE__ */ new Set(["true", "false", "in"]);
+var NOT_A_ROOT = /* @__PURE__ */ new Set(["true", "false", "in", "null", "undefined"]);
 function extractTemplateRoots(template) {
   const roots = [];
   const seen = /* @__PURE__ */ new Set();
@@ -1158,6 +1158,9 @@ import { promisify as promisify2 } from "util";
 var execFileAsync2 = promisify2(execFile2);
 var WorktreeCreationError = class extends Error {
 };
+var UnknownRefError = class extends Error {
+  name = "UnknownRefError";
+};
 var ENGINE_AUTHOR = ["-c", "user.name=yak", "-c", "user.email=engine@yak.local"];
 async function commitAllIfDirty(repoRoot, message) {
   const { stdout } = await execFileAsync2("git", ["status", "--porcelain"], { cwd: repoRoot });
@@ -1188,6 +1191,37 @@ async function createWorktree(repoRoot, branchName, baseRef, worktreePath) {
     }
   }
 }
+async function resolveCommit(repoRoot, ref) {
+  try {
+    const { stdout } = await execFileAsync2("git", ["rev-parse", "--verify", `${ref}^{commit}`], { cwd: repoRoot });
+    const sha = stdout.trim();
+    if (sha === "") throw new UnknownRefError(`unknown ref "${ref}"`);
+    return sha;
+  } catch (err) {
+    if (err instanceof UnknownRefError) throw err;
+    throw new UnknownRefError(`unknown ref "${ref}"`);
+  }
+}
+async function localBranchExists(repoRoot, branchName) {
+  try {
+    await execFileAsync2("git", ["rev-parse", "--verify", "--quiet", `refs/heads/${branchName}`], {
+      cwd: repoRoot
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function attachWorktree(repoRoot, branchName, worktreePath) {
+  try {
+    await execFileAsync2("git", ["worktree", "add", worktreePath, branchName], { cwd: repoRoot });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new WorktreeCreationError(
+      `failed to attach worktree at "${worktreePath}" on existing branch "${branchName}": ${message}`
+    );
+  }
+}
 
 // src/engine/scheduler.ts
 import path14 from "path";
@@ -2612,6 +2646,25 @@ function worktreePathFor(runsDir, runId) {
 function worktreeBranchFor(runId) {
   return `yak/${runId}`;
 }
+async function pathExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function materializeRunWorktree(repoRoot, runsDir, runId, worktreeBase) {
+  const worktreePath = worktreePathFor(runsDir, runId);
+  if (await pathExists(worktreePath)) return;
+  if (worktreeBase === void 0) return;
+  const branchName = worktreeBranchFor(runId);
+  if (await localBranchExists(repoRoot, branchName)) {
+    await attachWorktree(repoRoot, branchName, worktreePath);
+    return;
+  }
+  await createWorktree(repoRoot, branchName, worktreeBase, worktreePath);
+}
 function generateRunId() {
   const iso = (/* @__PURE__ */ new Date()).toISOString();
   const [datePart, timePart] = iso.split("T");
@@ -2623,10 +2676,14 @@ async function executeWorkflowFile(workflowPath, opts = {}) {
   const { runsDir, cwd, cacheDir } = resolveDirs(opts.runsDir, opts.cwd, opts.cacheDir);
   const adapter = opts.adapter ?? DEFAULT_ADAPTER;
   const isolation = opts.isolation ?? "none";
+  if (opts.from !== void 0 && isolation !== "worktree") {
+    throw new Error("--from requires --isolation worktree");
+  }
   const raw = await loadWorkflowYaml(workflowPath);
   const workflow = normalizeWorkflow(raw);
   await validateWorkflow(workflow, cwd, isolation);
   const inputValue = await resolveRunInput(workflow, opts.input, cwd);
+  const worktreeBase = opts.from !== void 0 ? await resolveCommit(cwd, opts.from) : void 0;
   const runId = generateRunId();
   const runDir = path15.join(runsDir, runId);
   await mkdir6(runDir, { recursive: true });
@@ -2645,7 +2702,8 @@ async function executeWorkflowFile(workflowPath, opts = {}) {
     adapter,
     isolation,
     pid: process.pid,
-    ...opts.tag !== void 0 ? { tag: opts.tag } : {}
+    ...opts.tag !== void 0 ? { tag: opts.tag } : {},
+    ...worktreeBase !== void 0 ? { worktreeBase } : {}
   });
   if (inputWritten) {
     await appendJournalEvent(runDir, runId, {
@@ -2664,7 +2722,7 @@ async function executeWorkflowFile(workflowPath, opts = {}) {
   if (isolation === "worktree") {
     const worktreePath = worktreePathFor(runsDir, runId);
     try {
-      await createWorktree(cwd, worktreeBranchFor(runId), "HEAD", worktreePath);
+      await createWorktree(cwd, worktreeBranchFor(runId), worktreeBase ?? "HEAD", worktreePath);
     } catch {
       await appendJournalEvent(runDir, runId, { t: "run.finished", status: "failed" });
       return { runId, runDir, status: "failed" };
@@ -2751,6 +2809,9 @@ async function resumeRun(runId, opts = {}) {
       `run ${runId} started with isolation "${persistedIsolation}" \u2014 cannot resume with isolation "${opts.isolation}"`
     );
   }
+  if (persistedIsolation === "worktree") {
+    await materializeRunWorktree(cwd, runsDir, runId, startedEvent?.worktreeBase);
+  }
   const stepCwd = persistedIsolation === "worktree" ? worktreePathFor(runsDir, runId) : cwd;
   const seedArtifactHashes = await seedInputHash(runDir);
   const status = await runEligibleSteps(
@@ -3145,6 +3206,7 @@ async function runCommand(workflowPath, opts = {}) {
       isolation: opts.isolation,
       input: opts.input,
       tag: opts.tag,
+      from: opts.from,
       // yak#23: emit the run id (and worktree branch) to stderr the moment
       // `run.started` is journalled, so an out-of-process launcher can
       // capture it without waiting for a terminal state. stdout is
@@ -3335,6 +3397,9 @@ function requireIsolation(value) {
 var program = new Command();
 program.name("yak").description("An agentic workflow engine").version(readVersion());
 program.command("run").description("Run a workflow YAML file").argument("<workflow>", "path to the workflow YAML file").option("--adapter <adapter>", "agent adapter to use", "claude-code").option("--interactive", "prompt inline for gate answers instead of exiting to resume later", false).option("--isolation <mode>", 'run inside a fresh git worktree ("worktree") or the plain cwd ("none")', "none").option(
+  "--from <ref>",
+  "fork the isolation worktree from this ref instead of HEAD (requires --isolation worktree)"
+).option(
   "--input <pair...>",
   "workflow input as key=value, repeatable \u2014 validated against the workflow inputSchema"
 ).option("--tag <string>", "opaque correlation tag, stored on the run and echoed by yak pending/status").action(
@@ -3343,6 +3408,7 @@ program.command("run").description("Run a workflow YAML file").argument("<workfl
       adapter: requireAdapterId(options.adapter),
       interactive: options.interactive,
       isolation: requireIsolation(options.isolation),
+      from: options.from,
       input: parseInputPairs(options.input),
       tag: options.tag
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lchase/yak",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "An agentic workflow engine",
   "license": "MIT",
   "type": "module",