@lchase/yak 0.3.1 → 0.4.1

package/dist/index.js

@@ -488,6 +488,7 @@ async function validateWorkflow(workflow, cwd = process.cwd(), runIsolation = "n
   checkReservedArtifactNames(flatSteps);
   checkNeedsSatisfied(workflow.steps, producerOf);
   checkNoCycles(workflow.steps, producerOf);
+  checkExprArtifactIdentifiers(workflow.steps, producerOf);
   checkExitCodeReads(workflow.steps, producerOf);
   checkAgentToolNames(flatSteps);
   await checkAgentSchemaKeys(flatSteps, cwd);
@@ -621,6 +622,42 @@ function checkNoCycles(steps, producerOf) {
   }
   for (const step of steps) visit(step, []);
 }
+var JEXL_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function checkExprArtifactIdentifiers(steps, producerOf) {
+  for (const step of steps) {
+    if (step.skipIf !== void 0) checkExprRefs(step.id, "skipIf", step.skipIf, producerOf);
+    if (step.kind === "loop") {
+      const localProducerOf = new Map([...producerOf, ...buildProducerMap(step.body)]);
+      checkExprRefs(step.id, "until", step.until, localProducerOf);
+      if (step.budget.noProgress) {
+        checkExprRefs(step.id, "noProgress.signal", step.budget.noProgress.signal, localProducerOf);
+      }
+      checkExprArtifactIdentifiers(step.body, localProducerOf);
+    }
+    if (step.kind === "map") checkExprArtifactIdentifiers([step.step], producerOf);
+  }
+}
+function checkExprRefs(stepId, field, expr, producerOf) {
+  if (typeof expr !== "string") return;
+  for (const name of producerOf.keys()) {
+    if (JEXL_IDENTIFIER.test(name)) continue;
+    const bounded = new RegExp(`(?<![A-Za-z0-9_$])${escapeRegExp(name)}(?![A-Za-z0-9_$])`);
+    if (!bounded.test(expr)) continue;
+    throw new WorkflowValidationError(
+      `step "${stepId}": ${field} references artifact "${name}", but "${name}" is not a valid jexl identifier \u2014 jexl reads it as an expression ("a-b" parses as "a minus b"), not a name, so the artifact is invisible to ${field}. Rename it to an identifier (e.g. "${toIdentifier(name)}").`
+    );
+  }
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function toIdentifier(name) {
+  const camel = name.replace(
+    /[^A-Za-z0-9]+([A-Za-z0-9])?/g,
+    (_, c) => c ? c.toUpperCase() : ""
+  );
+  return JEXL_IDENTIFIER.test(camel) ? camel : `a${camel}`;
+}
 function checkExitCodeReads(steps, producerOf) {
   const stepsById = new Map(steps.map((s) => [s.id, s]));
   for (const step of steps) {
@@ -768,6 +805,10 @@ async function readJournal(runDir) {
   const contents = await readFile4(journalPath(runDir), "utf8").catch(() => "");
   return contents.split("\n").filter((line) => line.trim().length > 0).map((line) => JSON.parse(line));
 }
+function runTagFromJournal(events) {
+  const started = events.find((e) => e.t === "run.started");
+  return started?.t === "run.started" ? started.tag : void 0;
+}
 function completedStepsFromJournal(events) {
   const started = /* @__PURE__ */ new Map();
   const completed = /* @__PURE__ */ new Map();
@@ -2322,6 +2363,9 @@ function resolveDirs(runsDir, cwd, cacheDir) {
 function worktreePathFor(runsDir, runId) {
   return path15.join(path15.dirname(runsDir), ".yak", "worktrees", runId);
 }
+function worktreeBranchFor(runId) {
+  return `yak/${runId}`;
+}
 function generateRunId() {
   const iso = (/* @__PURE__ */ new Date()).toISOString();
   const [datePart, timePart] = iso.split("T");
@@ -2353,7 +2397,8 @@ async function executeWorkflowFile(workflowPath, opts = {}) {
     workflow: workflow.name,
     inputHash: inputWritten?.hash ?? sha256(JSON.stringify(workflow)),
     adapter,
-    isolation
+    isolation,
+    ...opts.tag !== void 0 ? { tag: opts.tag } : {}
   });
   if (inputWritten) {
     await appendJournalEvent(runDir, runId, {
@@ -2363,11 +2408,16 @@ async function executeWorkflowFile(workflowPath, opts = {}) {
       bytes: inputWritten.bytes
     });
   }
+  await opts.onStart?.({
+    runId,
+    runDir,
+    ...isolation === "worktree" ? { worktreeBranch: worktreeBranchFor(runId) } : {}
+  });
   let stepCwd = cwd;
   if (isolation === "worktree") {
     const worktreePath = worktreePathFor(runsDir, runId);
     try {
-      await createWorktree(cwd, `yak/${runId}`, "HEAD", worktreePath);
+      await createWorktree(cwd, worktreeBranchFor(runId), "HEAD", worktreePath);
     } catch {
       await appendJournalEvent(runDir, runId, { t: "run.finished", status: "failed" });
       return { runId, runDir, status: "failed" };
@@ -2520,7 +2570,8 @@ async function pendingCommand(opts = {}) {
     const last = events.at(-1);
     if (!last || last.t !== "run.finished" || last.status !== "suspended") continue;
     anyPending = true;
-    console.log(`run ${runId} suspended:`);
+    const tag = runTagFromJournal(events);
+    console.log(`run ${runId} suspended${tag !== void 0 ? ` (tag: ${tag})` : ""}:`);
     const openIds = openRequestStepIds(events);
     if (openIds.length === 0) {
       console.log("  (no open request found \u2014 loop budget suspend from before M4, unresumable)");
@@ -2751,7 +2802,16 @@ async function runCommand(workflowPath, opts = {}) {
     result = await executeWorkflowFile(path18.resolve(workflowPath), {
       adapter: opts.adapter,
       isolation: opts.isolation,
-      input: opts.input
+      input: opts.input,
+      tag: opts.tag,
+      // 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
+      // untouched — the terminal-state line there is unchanged.
+      onStart: ({ runId, worktreeBranch }) => {
+        console.error(`run ${runId} started`);
+        if (worktreeBranch) console.error(`  worktree branch ${worktreeBranch}`);
+      }
     });
     while (opts.interactive && result.status === "suspended") {
       await answerOpenRequestsInteractively(result.runId, result.runDir);
@@ -2796,7 +2856,8 @@ async function statusCommand(runId, opts = {}) {
   const events = await readJournal(runDir);
   const statuses = stepStatusesFromJournal(workflow.steps, events);
   const failuresByStep = new Map(failedStepsFromJournal(events).map((f) => [f.stepId, f]));
-  console.log(`run ${resolvedRunId}:`);
+  const tag = runTagFromJournal(events);
+  console.log(`run ${resolvedRunId}${tag !== void 0 ? ` (tag: ${tag})` : ""}:`);
   for (const { stepId, status } of statuses) {
     console.log(`  ${stepId}: ${status}`);
     const step = workflow.steps.find((s) => s.id === stepId);
@@ -2935,13 +2996,14 @@ program.name("yak").description("An agentic workflow engine").version(readVersio
 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(
   "--input <pair...>",
   "workflow input as key=value, repeatable \u2014 validated against the workflow inputSchema"
-).action(
+).option("--tag <string>", "opaque correlation tag, stored on the run and echoed by yak pending/status").action(
   async (workflow, options) => {
     process.exitCode = await runCommand(workflow, {
       adapter: requireAdapterId(options.adapter),
       interactive: options.interactive,
       isolation: requireIsolation(options.isolation),
-      input: parseInputPairs(options.input)
+      input: parseInputPairs(options.input),
+      tag: options.tag
     });
   }
 );

package/package.json

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