@intentius/chant 0.50.0 → 0.52.0

package/src/cli/handlers/run.test.ts

@@ -50,6 +50,9 @@ vi.mock("./run-client", () => ({
   connectionOptions: (profile: { address: string }) => ({ address: profile.address }),
   resolveProfile: (...args: unknown[]) => resolveProfileMock(...args),
   resolveWorkflowId: (name: string) => `chant-op-${name}`,
+  // Test fixtures already use the short event-type form fetchNormalizedHistory
+  // produces (see mock-temporal-client.ts) — a passthrough keeps them valid.
+  fetchNormalizedHistory: (handle: { fetchHistory(): Promise<unknown> }) => handle.fetchHistory(),
 }));
 vi.mock("node:fs", async () => {
   const actual = await vi.importActual<typeof import("node:fs")>("node:fs");
@@ -297,6 +300,54 @@ describe("runOpStatus", () => {
     expect(out).toContain("COMPLETED");
     expect(out).toContain("1/2 completed");
   });
+
+  test("a pending gate prints a Gate line via the gateState query (#1676)", async () => {
+    setupTemporalClient(createMockTemporalClient({
+      describeByWorkflowId: {
+        "chant-op-alb-deploy": {
+          workflowId: "chant-op-alb-deploy", runId: "r1",
+          status: { name: "RUNNING" },
+          startTime: new Date("2026-05-01T00:00:00Z"),
+          taskQueue: "alb-deploy", type: { name: "albDeployWorkflow" },
+        },
+      },
+      historyByWorkflowId: { "chant-op-alb-deploy": [] },
+      queryResultByWorkflowId: {
+        "chant-op-alb-deploy:gateState": {
+          signalName: "gate-dns-delegation",
+          description: "Approve DNS delegation",
+          since: "2026-05-01T00:05:00.000Z",
+        },
+      },
+    }));
+    const stdout = makeStdoutSpy();
+    const exit = await runOpStatus({ args: makeArgs({ extraPositional: "alb-deploy" }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    const out = stdout.join("\n");
+    expect(out).toContain("Gate");
+    expect(out).toContain("gate-dns-delegation");
+    expect(out).toContain("Approve DNS delegation");
+    expect(out).toContain("2026-05-01T00:05:00.000Z");
+  });
+
+  test("an Op with no pending gate (query unregistered or answers null) prints no Gate line", async () => {
+    setupTemporalClient(createMockTemporalClient({
+      describeByWorkflowId: {
+        "chant-op-alb-deploy": {
+          workflowId: "chant-op-alb-deploy", runId: "r1",
+          status: { name: "COMPLETED" },
+          startTime: new Date("2026-05-01T00:00:00Z"),
+          closeTime: new Date("2026-05-01T01:00:00Z"),
+          taskQueue: "alb-deploy", type: { name: "albDeployWorkflow" },
+        },
+      },
+      historyByWorkflowId: { "chant-op-alb-deploy": [] },
+    }));
+    const stdout = makeStdoutSpy();
+    const exit = await runOpStatus({ args: makeArgs({ extraPositional: "alb-deploy" }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    expect(stdout.join("\n")).not.toContain("Gate");
+  });
 });
 
 // ── chant run status <name> --components (#599) ─────────────────────────────
@@ -731,6 +782,99 @@ describe("runOp", () => {
     }
   });
 
+  // ── --progress-json (#1676) ──────────────────────────────────────────────
+
+  test("--progress-json streams one NDJSON StepRecord per settled step, plus a final skipped record", async () => {
+    vi.useFakeTimers();
+    try {
+      discoverOpsMock.mockResolvedValue({
+        ops: new Map([[
+          "alb-deploy",
+          {
+            config: {
+              name: "alb-deploy", overview: "o",
+              phases: [
+                { name: "Build", steps: [{ kind: "activity", fn: "build" }] },
+                { name: "Deploy", steps: [{ kind: "activity", fn: "deploy" }] },
+              ],
+            },
+          },
+        ]]),
+        errors: [],
+      });
+      setupTemporalClient(createMockTemporalClient({
+        describeByWorkflowId: {
+          "chant-op-alb-deploy": {
+            workflowId: "chant-op-alb-deploy", runId: "r1",
+            status: { name: "COMPLETED" }, startTime: new Date(),
+            taskQueue: "alb-deploy", type: { name: "albDeployWorkflow" },
+          },
+        },
+        historyByWorkflowId: {
+          "chant-op-alb-deploy": [
+            { eventId: "1", eventType: "ActivityTaskScheduled", activityTaskScheduledEventAttributes: { activityId: "1", activityType: { name: "build" } } },
+            { eventType: "ActivityTaskCompleted", activityTaskCompletedEventAttributes: { scheduledEventId: "1" } },
+          ],
+        },
+      }));
+      existsSyncMock.mockReturnValue(true);
+      const { proc } = makeFakeChildProcess();
+      spawnChildMock.mockReturnValue(proc);
+      generateReportMock.mockReturnValue("# Report");
+      writeReportMock.mockReturnValue("/tmp/report.md");
+      vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+      const stdoutLines: string[] = [];
+      const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation((chunk) => { stdoutLines.push(String(chunk)); return true; });
+
+      const promise = runOp({ args: makeArgs({ path: "alb-deploy", progressJson: true }), plugins: [], serializers: [] });
+      await vi.advanceTimersByTimeAsync(5000);
+      const exit = await promise;
+
+      expect(exit).toBe(0);
+      const records = stdoutLines.filter((l) => l.trim()).map((l) => JSON.parse(l));
+      expect(records).toEqual([
+        { phase: "Build", fn: "build", status: "ok", durationMs: 0 },
+        { phase: "Deploy", fn: "deploy", status: "skipped", durationMs: 0 },
+      ]);
+      stdoutSpy.mockRestore();
+    } finally {
+      vi.useRealTimers();
+    }
+  }, 10_000);
+
+  test("without --progress-json, nothing is written to stdout during the poll loop", async () => {
+    vi.useFakeTimers();
+    try {
+      discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("alb-deploy")]), errors: [] });
+      setupTemporalClient(createMockTemporalClient({
+        describeByWorkflowId: {
+          "chant-op-alb-deploy": {
+            workflowId: "chant-op-alb-deploy", runId: "r1",
+            status: { name: "COMPLETED" }, startTime: new Date(),
+            taskQueue: "alb-deploy", type: { name: "albDeployWorkflow" },
+          },
+        },
+        historyByWorkflowId: { "chant-op-alb-deploy": [] },
+      }));
+      existsSyncMock.mockReturnValue(true);
+      const { proc } = makeFakeChildProcess();
+      spawnChildMock.mockReturnValue(proc);
+      generateReportMock.mockReturnValue("# Report");
+      writeReportMock.mockReturnValue("/tmp/report.md");
+      vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+      const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+
+      const promise = runOp({ args: makeArgs({ path: "alb-deploy" }), plugins: [], serializers: [] });
+      await vi.advanceTimersByTimeAsync(5000);
+      await promise;
+
+      expect(stdoutSpy).not.toHaveBeenCalled();
+      stdoutSpy.mockRestore();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   test("workflow ends in FAILED → exit 1, worker still killed", async () => {
     vi.useFakeTimers();
     try {
@@ -843,6 +987,102 @@ describe("runOp dispatcher", () => {
   });
 });
 
+/**
+ * chant #2003 — `--sandbox` is a global flag and `../main.ts` arms the
+ * process-wide policy latch off it for every command, so `chant run <op>
+ * --sandbox` on an Op with a `policyGate` step used to reach `loadPolicyChecks`
+ * mid-run and show the user a message written for a chant maintainer ("This is
+ * a chant bug"). At the CLI level, not on `loadPolicyChecks`: the defect was
+ * that the combination got that far, not what the refusal says.
+ */
+describe("runOp: --sandbox with a policyGate step (chant #2003)", () => {
+  const policyGateOp = (name: string) =>
+    localOp(name, [{ kind: "activity", fn: "policyGate", args: { path: "." } }]);
+
+  beforeEach(() => {
+    discoverOpsMock.mockReset();
+    loadTemporalClientMock.mockReset();
+    loadChantConfigMock.mockReset();
+    resolveProfileMock.mockReset();
+    existsSyncMock.mockReset();
+    spawnChildMock.mockReset();
+  });
+
+  test("local mode → refuses before any phase runs, naming the combination", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([policyGateOp("gate")]), errors: [] });
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: false, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    const out = stderr.join("\n");
+    expect(out).toContain("policyGate");
+    expect(out).toContain("--sandbox");
+    // The message the user used to get instead.
+    expect(out).not.toContain("This is a chant bug");
+  });
+
+  test("--temporal → the same refusal, as a CLI error rather than an activity failure", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([policyGateOp("gate")]), errors: [] });
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: true, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("policyGate");
+    // Refused before the project config is even loaded — nothing is scheduled.
+    expect(loadChantConfigMock).not.toHaveBeenCalled();
+    expect(loadTemporalClientMock).not.toHaveBeenCalled();
+  });
+
+  test("a policyGate nested in an effect step is found too", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([
+        localOp("gate", [
+          { kind: "effect", steps: [{ kind: "activity", fn: "policyGate", args: { path: "." } }] },
+        ]),
+      ]),
+      errors: [],
+    });
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: false, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("policyGate");
+  });
+
+  test("without --sandbox the same Op is not refused", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([policyGateOp("gate")]), errors: [] });
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveProfileMock.mockReturnValue({ address: "localhost:7233", namespace: "default", taskQueue: "q" });
+    existsSyncMock.mockReturnValue(false);
+    const stderr = makeStderrSpy();
+
+    // The Temporal path, so the run stops at the missing worker.ts rather than
+    // actually building a project: reaching that point proves the pre-flight
+    // let it through.
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("worker.ts not found");
+    expect(loadChantConfigMock).toHaveBeenCalled();
+  });
+
+  test("--sandbox on an Op with no policyGate step is untouched", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("hello", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
+      errors: [],
+    });
+    const stderrWrite = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    const exit = await runOp({ args: makeArgs({ path: "hello", temporal: false, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    stderrWrite.mockRestore();
+  });
+});
+
 describe("Temporal-only subcommand guards", () => {
   const cases: Array<[string, (ctx: { args: ParsedArgs; plugins: never[]; serializers: never[] }) => Promise<number>]> = [
     ["list", runOpList],

package/src/cli/handlers/run.ts

@@ -4,8 +4,9 @@ import { createConnection } from "node:net";
 import { spawn as spawnChild, type ChildProcess } from "node:child_process";
 import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
 import { discoverOps } from "../../op/discover";
+import type { OpConfig } from "../../op/types";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
-import { runOpLocally, findGate, LocalGateUnsupportedError, OpRunFailure } from "../../op/local-executor";
+import { runOpLocally, findGate, findPolicyGateStep, LocalGateUnsupportedError, OpRunFailure, type StepRecord } from "../../op/local-executor";
 import { renderHuman, renderJson } from "../../op/local-output";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
@@ -15,11 +16,13 @@ import {
   connectionOptions,
   resolveWorkflowId,
   resolveProfile,
+  fetchNormalizedHistory,
   type WorkflowHandleRaw,
   type WorkflowExecutionDescription,
   type WorkflowHistoryRaw,
 } from "./run-client";
 import { generateReport, writeReport } from "./run-report";
+import { extractStepRecords, countActivities, queryGateState } from "./op-progress";
 import { runComponents, resolveComponentTargets, findComponentGate, listComponents } from "../../components/cli-support";
 import { renderDriverHuman, renderDriverJson } from "../../components/driver-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
@@ -250,12 +253,12 @@ export async function runOpStatus(ctx: CommandContext): Promise<number> {
   if (ctx.args.components) return runComponentStatus(ctx, name);
 
   const projectPath = resolve(".");
-  let client, desc: WorkflowExecutionDescription, history: WorkflowHistoryRaw;
+  let client, desc: WorkflowExecutionDescription, history: WorkflowHistoryRaw, handle: WorkflowHandleRaw;
   try {
     ({ client } = await makeTemporalClient(ctx.args.profile, projectPath));
-    const handle = client.workflow.getHandle(resolveWorkflowId(name));
+    handle = client.workflow.getHandle(resolveWorkflowId(name));
     desc = await handle.describe();
-    history = await handle.fetchHistory();
+    history = await fetchNormalizedHistory(handle);
   } catch (err) {
     console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
     return 1;
@@ -269,13 +272,19 @@ export async function runOpStatus(ctx: CommandContext): Promise<number> {
   console.log(`  Started     : ${desc.startTime.toISOString()}`);
   if (desc.closeTime) console.log(`  Closed      : ${desc.closeTime.toISOString()}`);
 
-  const events = history.events ?? [];
-  const completed = events.filter((e) => e.eventType === "ActivityTaskCompleted").length;
-  const scheduled = events.filter((e) => e.eventType === "ActivityTaskScheduled").length;
+  const { completed, scheduled } = countActivities(history);
   if (scheduled > 0) {
     console.log(`  Activities  : ${completed}/${scheduled} completed`);
   }
 
+  // Queryable gate state (#1676) — undefined means the query itself failed
+  // (an ungated Op never registers a "gateState" handler), so print nothing;
+  // null means the query answered "no gate pending" — also nothing to print.
+  const gate = await queryGateState(handle);
+  if (gate) {
+    console.log(`  Gate        : ${gate.signalName}${gate.description ? ` — ${gate.description}` : ""} (waiting since ${gate.since})`);
+  }
+
   return 0;
 }
 
@@ -293,7 +302,7 @@ async function runComponentStatus(ctx: CommandContext, name: string): Promise<nu
     ({ client } = await makeTemporalClient(ctx.args.profile, projectPath));
     const handle = client.workflow.getHandle(componentWorkflowId(name));
     desc = await handle.describe();
-    history = await handle.fetchHistory();
+    history = await fetchNormalizedHistory(handle);
   } catch (err) {
     console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
     return 1;
@@ -307,9 +316,7 @@ async function runComponentStatus(ctx: CommandContext, name: string): Promise<nu
   console.log(`  Started     : ${desc.startTime.toISOString()}`);
   if (desc.closeTime) console.log(`  Closed      : ${desc.closeTime.toISOString()}`);
 
-  const events = history.events ?? [];
-  const completed = events.filter((e) => e.eventType === "ActivityTaskCompleted").length;
-  const scheduled = events.filter((e) => e.eventType === "ActivityTaskScheduled").length;
+  const { completed, scheduled } = countActivities(history);
   if (scheduled > 0) {
     console.log(`  Activities  : ${completed}/${scheduled} completed`);
   }
@@ -528,9 +535,7 @@ async function waitForTemporalServer(address: string, maxWaitMs = 30_000): Promi
 }
 
 function renderProgress(opName: string, history: WorkflowHistoryRaw): void {
-  const events = history.events ?? [];
-  const completed = events.filter((e) => e.eventType === "ActivityTaskCompleted").length;
-  const scheduled = events.filter((e) => e.eventType === "ActivityTaskScheduled").length;
+  const { completed, scheduled } = countActivities(history);
   process.stderr.write(
     `\r${formatInfo(`[${opName}]`)} ${completed}/${scheduled} activities completed`,
   );
@@ -557,6 +562,32 @@ function renderProgress(opName: string, history: WorkflowHistoryRaw): void {
  * live reaching an actual cloud shell-out. Erroring here is the safe minimum
  * called out on the issue; a real preview is future work.
  */
+/**
+ * Pre-flight for `chant run <op> --sandbox` on an Op containing a `policyGate`
+ * step (chant #2003). `--sandbox` is a global flag, and `../main.ts` arms the
+ * process-wide policy latch off it for every command — so the gate's
+ * `loadPolicyChecks` refuses mid-run with a message addressed to a chant
+ * maintainer ("This is a chant bug"), or, under `--temporal`, as a
+ * non-retryable activity failure inside the workflow. Neither is an answer a
+ * user can act on. Refuse here instead, before anything runs, naming the
+ * combination and what to do about it.
+ *
+ * Keyed on the flag rather than on whether the project declares
+ * `lint.policies`: the flag is what arms the latch, and a gate that builds the
+ * project in this process is a divergence from what `--sandbox` promises
+ * whether or not a policy module happens to be declared. Returns true when the
+ * caller should stop.
+ */
+function refusesPolicyGateUnderSandbox(ctx: CommandContext, config: OpConfig, opName: string): boolean {
+  if (!ctx.args.sandbox) return false;
+  if (!findPolicyGateStep(config)) return false;
+  console.error(formatError({
+    message: `Op "${opName}" has a policyGate step, which cannot run under --sandbox: the gate builds this project and imports its lint.policies in the chant process, which --sandbox forbids.`,
+    hint: "Re-run without --sandbox, or drop the policyGate step from this Op. Running the gate itself inside the sandbox boundary is tracked on chant#1157.",
+  }));
+  return true;
+}
+
 export async function runOp(ctx: CommandContext): Promise<number> {
   if (ctx.args.components && ctx.args.report) {
     console.error(formatError({
@@ -954,7 +985,7 @@ async function runComponentTemporal(
     while (true) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
       const desc = await handle.describe();
-      const history = await handle.fetchHistory();
+      const history = await fetchNormalizedHistory(handle);
       renderProgress(component.name, history);
       if (TERMINAL_STATUSES.has(desc.status.name)) {
         process.stderr.write("\n");
@@ -1057,6 +1088,9 @@ export async function runOpLocal(ctx: CommandContext): Promise<number> {
 
   const { config } = discovered;
 
+  // Pre-flight: --sandbox cannot cover a policyGate step (#2003).
+  if (refusesPolicyGateUnderSandbox(ctx, config, opName)) return 1;
+
   // Pre-flight: gates/schedules need a durable runtime — fail before any step.
   const gate = findGate(config);
   if (gate) {
@@ -1141,6 +1175,12 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
   }
 
   const { config } = discovered;
+
+  // Pre-flight: --sandbox cannot cover a policyGate step (#2003). Refused here
+  // too, so the durable path fails as a CLI error rather than as a
+  // non-retryable activity failure buried in workflow history.
+  if (refusesPolicyGateUnderSandbox(ctx, config, opName)) return 1;
+
   const projectPath = resolve(".");
 
   // Load config + profile
@@ -1160,7 +1200,7 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
       ({ client } = await makeTemporalClient(ctx.args.profile, projectPath));
       const handle = client.workflow.getHandle(resolveWorkflowId(opName));
       desc = await handle.describe();
-      history = await handle.fetchHistory();
+      history = await fetchNormalizedHistory(handle);
     } catch (err) {
       console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
       return 1;
@@ -1248,7 +1288,23 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
-  // Poll for progress until terminal state
+  // Poll for progress until terminal state.
+  //
+  // `--progress-json` (chant #1676): stream one NDJSON StepRecord per line to
+  // stdout as each declared step settles — the durable-path counterpart to
+  // `chant run <name> --json`'s local-executor record shape (op-progress.ts).
+  // Purely additive: when the flag is absent `emitProgress` stays undefined
+  // and every `emitProgress?.(...)` call is a no-op, so poll-loop behavior
+  // is unchanged. `extractStepRecords` is stable and append-only across
+  // polls (same declared order, a growing history), so a plain emitted-count
+  // watermark is enough to emit only what's new each round.
+  const emitProgress = ctx.args.progressJson ? ndjsonProgressSink<StepRecord>() : undefined;
+  let emittedCount = 0;
+  const emitNewRecords = (records: StepRecord[]) => {
+    for (const record of records.slice(emittedCount)) emitProgress?.(record);
+    emittedCount = records.length;
+  };
+
   let finalDesc: WorkflowExecutionDescription | undefined;
   let finalHistory: WorkflowHistoryRaw | undefined;
 
@@ -1256,12 +1312,14 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
     while (true) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
       const desc = await handle.describe();
-      const history = await handle.fetchHistory();
+      const history = await fetchNormalizedHistory(handle);
 
       renderProgress(opName, history);
+      if (emitProgress) emitNewRecords(extractStepRecords(config, history));
 
       if (TERMINAL_STATUSES.has(desc.status.name)) {
         process.stderr.write("\n");
+        if (emitProgress) emitNewRecords(extractStepRecords(config, history, { final: true }));
         finalDesc = desc;
         finalHistory = history;
         break;