@intentius/chant 0.58.0 → 0.59.0

package/src/op/gate-name.test.ts

@@ -0,0 +1,65 @@
+/**
+ * The `signalName` -> `gate` rename (#2202) and the one-version bridge that
+ * keeps the old key readable through 0.59.0.
+ */
+import { describe, it, expect } from "vitest";
+import { gateName, usesDeprecatedGateKey, opUsesDeprecatedGateKey } from "./gate-name";
+import type { OpConfig } from "./types";
+
+describe("gateName", () => {
+  it("reads the new key", () => {
+    expect(gateName({ gate: "approve-prod" })).toBe("approve-prod");
+  });
+
+  it("falls back to the deprecated key", () => {
+    expect(gateName({ signalName: "approve-prod" })).toBe("approve-prod");
+  });
+
+  it("prefers the new key when a step somehow carries both", () => {
+    expect(gateName({ gate: "new", signalName: "old" })).toBe("new");
+  });
+});
+
+describe("usesDeprecatedGateKey", () => {
+  it("is true only when the new key is absent", () => {
+    expect(usesDeprecatedGateKey({ signalName: "old" })).toBe(true);
+    expect(usesDeprecatedGateKey({ gate: "new" })).toBe(false);
+    expect(usesDeprecatedGateKey({ gate: "new", signalName: "old" })).toBe(false);
+    expect(usesDeprecatedGateKey({})).toBe(false);
+  });
+});
+
+describe("opUsesDeprecatedGateKey", () => {
+  const op = (phases: OpConfig["phases"], onFailure?: OpConfig["phases"]): OpConfig =>
+    ({ name: "x", overview: "x", phases, ...(onFailure ? { onFailure } : {}) }) as OpConfig;
+
+  it("finds a gate on the old key in a plain phase", () => {
+    expect(opUsesDeprecatedGateKey(op([{ name: "Approve", steps: [{ kind: "gate", signalName: "go" }] }]))).toBe(true);
+  });
+
+  it("finds one nested inside an effect step", () => {
+    const config = op([
+      {
+        name: "Seed",
+        steps: [
+          {
+            kind: "effect",
+            receipt: { name: "seeded", effect: "db-seed", flavor: "hash", inputs: { file: "seed.sql" } },
+            steps: [{ kind: "gate", signalName: "go" }],
+          },
+        ],
+      },
+    ]);
+    expect(opUsesDeprecatedGateKey(config)).toBe(true);
+  });
+
+  it("finds one in an onFailure phase", () => {
+    expect(
+      opUsesDeprecatedGateKey(op([{ name: "Apply", steps: [] }], [{ name: "Undo", steps: [{ kind: "gate", signalName: "go" }] }])),
+    ).toBe(true);
+  });
+
+  it("is false for an Op on the new key", () => {
+    expect(opUsesDeprecatedGateKey(op([{ name: "Approve", steps: [{ kind: "gate", gate: "go" }] }]))).toBe(false);
+  });
+});

package/src/op/gate-name.ts

@@ -0,0 +1,60 @@
+/**
+ * The gate step's name field, and the one-version bridge for the key it used
+ * to carry (chant #2202).
+ *
+ * A gate is a fact on the gate ledger, not a channel: since #2119 nothing is
+ * running and nothing is signalled, so the field that names a gate is called
+ * `gate` — the same word `chant approve <op> <gate>` takes on the command
+ * line. It was called `signalName` through 0.58.0.
+ *
+ * `signalName` is still read, on `GateStep`, on the component `Gate` step and
+ * on the composites' gate options, and a build that sees only the old key
+ * warns once. It goes away in 0.60.0: delete this module's
+ * {@link DEPRECATED_GATE_KEY_WARNING}, {@link usesDeprecatedGateKey}, the
+ * `signalName` branch of {@link gateName}, the optional `signalName` fields
+ * that call it, and the schema's `oneOf` once that release is out, leaving
+ * `gate` as the only key.
+ */
+
+import type { OpConfig, PhaseDefinition, StepDefinition } from "./types";
+
+/** Either spelling of a gate step's name. `gate` since #2202; `signalName` through 0.59.0. */
+export interface GateNamed {
+  gate?: string;
+  /** @deprecated Renamed to `gate` in #2202. Accepted through 0.59.0, removed in 0.60.0. */
+  signalName?: string;
+}
+
+/**
+ * The gate's name, from whichever key carries it. One place reads the old key,
+ * so removing the bridge is a one-file edit rather than a sweep.
+ */
+export function gateName(step: GateNamed): string {
+  return step.gate ?? step.signalName ?? "";
+}
+
+/** True when a step names its gate only with the deprecated key. */
+export function usesDeprecatedGateKey(step: GateNamed): boolean {
+  return step.gate === undefined && typeof step.signalName === "string";
+}
+
+/** What a build prints once when it finds a gate step still using the old key. */
+export const DEPRECATED_GATE_KEY_WARNING =
+  'Gate steps still using "signalName": the key is now "gate" (chant #2202). ' +
+  '"signalName" is accepted through 0.59.0 and removed in 0.60.0.';
+
+/**
+ * True when any gate step in an Op's phases (main or `onFailure`, at any
+ * nesting depth inside an `effect()`) names itself only with the deprecated
+ * key. `chant build` calls this to warn once per build.
+ */
+export function opUsesDeprecatedGateKey(config: OpConfig): boolean {
+  const inStep = (step: StepDefinition): boolean => {
+    if (step.kind === "gate") return usesDeprecatedGateKey(step);
+    if (step.kind === "effect") return step.steps.some(inStep);
+    return false;
+  };
+  const inPhases = (phases: PhaseDefinition[] | undefined): boolean =>
+    (phases ?? []).some((p) => p.steps.some(inStep));
+  return inPhases(config.phases) || inPhases(config.onFailure);
+}

package/src/op/gate-summary.ts

@@ -0,0 +1,84 @@
+/**
+ * The pending-gate block a CI run leaves where people actually look (#2243).
+ *
+ * A gated run already prints the gate, the approve command and the expiry to
+ * stderr (`./local-output.ts`'s `renderHuman`). In CI that lands in a log
+ * nobody opens unless the run is red, which is exactly the run this stops
+ * being red. GitHub Actions, Forgejo Actions and Gitea all give a step a
+ * markdown scratchpad through `GITHUB_STEP_SUMMARY`, rendered at the top of
+ * the run page; anything else that sets the variable gets the same block.
+ *
+ * That is the whole forge coupling: one environment variable, appended to
+ * when it is set, and nothing at all when it is not. No API call, no token,
+ * no flag to turn it on.
+ */
+
+import { appendFileSync } from "node:fs";
+import { gateLedgerPath } from "../lifecycle/gate-ledger";
+import { approveCommand } from "./gate";
+
+/** What a gated run knows about the gate it stopped on. */
+export interface GatedRunSummary {
+  /** The Op (or component) the gate belongs to. */
+  op: string;
+  /** The gate's name — the second argument to `chant approve`. */
+  gate: string;
+  /** The gate's authored description, when it has one. */
+  description?: string;
+  /** ISO-8601 instant the pending fact ages out at. */
+  expiresAt?: string;
+  /** The approval surface the run resolved, when it knew one. */
+  url?: string;
+}
+
+/**
+ * The markdown block itself. Pure, so a test reads what CI would render
+ * without touching a file: op, gate, the exact `chant approve` line, and the
+ * ledger path the pending fact was appended to.
+ */
+export function gatedRunSummaryMarkdown(summary: GatedRunSummary): string {
+  const lines = [
+    `### Waiting on gate \`${summary.gate}\``,
+    "",
+    `Op \`${summary.op}\` reached a gate nobody has approved, recorded the pending fact, and stopped. Nothing failed.`,
+    "",
+  ];
+  if (summary.description) {
+    lines.push(summary.description, "");
+  }
+  lines.push(
+    "Approve it, then re-run this workflow:",
+    "",
+    "```",
+    `${approveCommand(summary.op, summary.gate)} --approver <you>`,
+    "```",
+    "",
+    `Ledger: \`${gateLedgerPath(summary.op)}\` on the \`chant/lifecycle\` branch.`,
+  );
+  if (summary.expiresAt) lines.push(`Expires: ${summary.expiresAt}`);
+  if (summary.url) lines.push(`Approve at: ${summary.url}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Append {@link gatedRunSummaryMarkdown} to the file `GITHUB_STEP_SUMMARY`
+ * names, when the variable is set and the file can be written.
+ *
+ * Returns the path written, or `undefined` when there was nothing to write to.
+ * A write that fails is swallowed: a run that already decided its outcome must
+ * not turn into a different one because a CI scratchpad was read-only.
+ */
+export function writeGatedRunSummary(
+  summary: GatedRunSummary,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const path = env.GITHUB_STEP_SUMMARY;
+  if (!path) return undefined;
+  try {
+    appendFileSync(path, gatedRunSummaryMarkdown(summary));
+    return path;
+  } catch {
+    return undefined;
+  }
+}

package/src/op/index.ts

@@ -52,6 +52,8 @@ export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult, RunOpOptions } from "./local-executor";
 export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand } from "./gate";
 export type { GateLedgerPort, GateCheck, GateCheckInput } from "./gate";
+export { gateName, usesDeprecatedGateKey, DEPRECATED_GATE_KEY_WARNING } from "./gate-name";
+export type { GateNamed } from "./gate-name";
 export { createLocalOpRuntime } from "./runtimes/local";
 export { runStateOf } from "./runtime";
 export type {
@@ -85,9 +87,14 @@ export type {
 } from "./converge-rule";
 export {
   discoverConvergeOps, runOperatorRound, runOperatorForever, formatRoundLine,
-  DEFAULT_OPERATOR_INTERVAL_MS,
+  formatSignalLine, DEFAULT_OPERATOR_INTERVAL_MS,
 } from "./operator";
-export type { OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions } from "./operator";
+export type {
+  OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions,
+  ChangeSubscriber, OperatorSignalEvent,
+} from "./operator";
+export { createChangeSignalGate, DEFAULT_SIGNAL_FLOOR_MS } from "./change-signal";
+export type { ChangeSignalGate, ChangeSignalGateOptions, WakeReason } from "./change-signal";
 export { classifyOpVerbClass, isGated } from "./op-verb-class";
 export type { OpVerbClass } from "./op-verb-class";
 export { takeProfileAndId } from "./builders";

package/src/op/local-executor.test.ts

@@ -284,7 +284,7 @@ describe("runOpLocally — gate as fact (#2119)", () => {
       phases: [
         { name: "P1", steps: [
           { kind: "activity", fn: "before" },
-          { kind: "gate", signalName: "approve-prod", description: "release manager signs off", timeout: "24h" },
+          { kind: "gate", gate: "approve-prod", description: "release manager signs off", timeout: "24h" },
           { kind: "activity", fn: "after" },
         ] },
         { name: "P2", steps: [{ kind: "activity", fn: "later" }] },
@@ -324,6 +324,21 @@ describe("runOpLocally — gate as fact (#2119)", () => {
     ]);
   });
 
+  // #2202: the gate step's name key is `gate`; `signalName` is read through
+  // 0.59.0, so a step still spelling it that way reaches the same ledger entry.
+  test("a gate step still using the deprecated `signalName` key names the same gate", async () => {
+    const { activities } = tracked();
+    const legacy = op({
+      phases: [{ name: "P1", steps: [{ kind: "gate", signalName: "approve-prod" }] }],
+    });
+    const port = memoryGateLedgerPort();
+    const result = await runOpLocally(legacy, activities, PROFILES, undefined, { gates: port, now: NOW });
+
+    expect(result.status).toBe("gated");
+    expect(result.gate).toMatchObject({ op: "test-op", gate: "approve-prod" });
+    expect(result.records.map((r) => r.fn)).toEqual(["gate:approve-prod"]);
+  });
+
   test("onFailure phases do not run on a gated run", async () => {
     const { calls, activities } = tracked();
     await runOpLocally(gatedOp(), activities, PROFILES, undefined, { gates: memoryGateLedgerPort(), now: NOW });

package/src/op/local-executor.ts

@@ -26,6 +26,7 @@ import type { ReceiptReadResult } from "./receipt-store";
 import { isStepOutputRef } from "./step-output-ref";
 import { parseDuration } from "./duration";
 import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
+import { gateName } from "./gate-name";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import { appendRunRecord, buildRunRecord } from "../lifecycle/run-ledger";
 import type { OpRunRecord } from "./runtime";
@@ -342,7 +343,7 @@ function pushRecord(sink: StepRecord[], ctx: GateContext, ...recs: StepRecord[])
 
 /** The record name a gate step lands under, so a reader (and a JSON consumer) can pick it out of `records`. */
 function gateFn(step: GateStep): string {
-  return `gate:${step.signalName}`;
+  return `gate:${gateName(step)}`;
 }
 
 /**
@@ -359,7 +360,7 @@ async function runGateStep(
   const start = Date.now();
   const check = await evaluateGate(gates.port, {
     op: gates.op,
-    gate: step.signalName,
+    gate: gateName(step),
     ...(step.description ? { description: step.description } : {}),
     ...(step.timeout ? { timeout: step.timeout } : {}),
     ...(gates.runId ? { runId: gates.runId } : {}),
@@ -376,7 +377,7 @@ async function runGateStep(
         status: "ok",
         durationMs: Date.now() - start,
         approval: {
-          gate: step.signalName,
+          gate: gateName(step),
           resolvedBy: resolution.resolvedBy,
           timestamp: resolution.timestamp,
           ...(resolution.url ? { url: resolution.url } : {}),

package/src/op/op-ir.test.ts

@@ -126,7 +126,7 @@ describe("op.json IR", () => {
     expect(build.steps[0]).toMatchObject({ kind: "activity", fn: "shellCmd", profile: "fastIdempotent" });
     expect(approve.steps[0]).toMatchObject({
       kind: "gate",
-      signalName: "approve-deploy",
+      gate: "approve-deploy",
       timeout: "24h",
       description: "Release manager sign-off",
     });
@@ -141,6 +141,17 @@ describe("op.json IR", () => {
     expect(ir.onFailure[0].name).toBe("Rollback");
   });
 
+  // #2202: whichever key an authored gate step used, the IR writes `gate`, so
+  // a foreign consumer of op.json never sees the deprecated spelling.
+  it("normalizes a gate step's deprecated `signalName` key onto `gate`", () => {
+    const config = representativeOp();
+    const approve = config.phases.find((p) => p.name === "Approve")!;
+    approve.steps[0] = { kind: "gate", signalName: "approve-deploy", timeout: "24h" };
+    const ir = buildOpIR(config);
+    expect(ir.phases[1].steps[0]).toMatchObject({ kind: "gate", gate: "approve-deploy", timeout: "24h" });
+    expect(serializeOpIR(config)).not.toContain("signalName");
+  });
+
   it("contracts are the injected registry's: empty until a caller supplies one", () => {
     const bare = buildOpIR(representativeOp());
     expect(bare.activityContracts).toEqual({});

package/src/op/op-ir.ts

@@ -95,6 +95,7 @@ import type {
 import type { EffectReceiptRef } from "./receipt-store";
 import type { ActivityContract } from "./activity-contract";
 import { ACTIVITY_PROFILES, type ActivityProfile } from "./activity-profiles";
+import { gateName } from "./gate-name";
 
 /**
  * The op.json IR schema version. Bumped on a breaking change to this
@@ -131,7 +132,8 @@ export interface OpIRActivityStep {
 
 export interface OpIRGateStep {
   kind: "gate";
-  signalName: string;
+  /** The gate's name — `GateStep.gate`, or its deprecated `signalName` spelling (#2202). */
+  gate: string;
   /** Resolved to its effective value — `GateStep.timeout ?? "48h"`. */
   timeout: string;
   description?: string;
@@ -227,7 +229,7 @@ function irActivityStep(step: ActivityStep, contracts: ReadonlyMap<string, Activ
 function irGateStep(step: GateStep): OpIRGateStep {
   return {
     kind: "gate",
-    signalName: step.signalName,
+    gate: gateName(step),
     timeout: step.timeout ?? "48h",
     ...(step.description ? { description: step.description } : {}),
   };
@@ -375,7 +377,7 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
   if (step.kind === "gate") {
     return {
       kind: "gate",
-      signalName: step.signalName,
+      gate: step.gate,
       timeout: step.timeout,
       ...(step.description ? { description: step.description } : {}),
     };

package/src/op/op-verb-class.test.ts

@@ -106,7 +106,7 @@ describe("isGated", () => {
     expect(
       isGated(
         cfg([
-          { name: "Approve", steps: [{ kind: "gate", signalName: "approve-x" }] },
+          { name: "Approve", steps: [{ kind: "gate", gate: "approve-x" }] },
           { name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: {} }] },
         ]),
       ),
@@ -118,7 +118,7 @@ describe("isGated", () => {
       isGated(
         cfg(
           [{ name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: {} }] }],
-          [{ name: "Rollback", steps: [{ kind: "gate", signalName: "approve-rollback" }] }],
+          [{ name: "Rollback", steps: [{ kind: "gate", gate: "approve-rollback" }] }],
         ),
       ),
     ).toBe(true);

package/src/op/op.test.ts

@@ -131,10 +131,10 @@ describe("activity()", () => {
 // ── gate() ────────────────────────────────────────────────────────────────────
 
 describe("gate()", () => {
-  it("returns GateStep with kind 'gate' and signalName", () => {
+  it("returns GateStep with kind 'gate' and the gate name", () => {
     const g = gate("dns-delegation");
     expect(g.kind).toBe("gate");
-    expect(g.signalName).toBe("dns-delegation");
+    expect(g.gate).toBe("dns-delegation");
   });
 
   it("includes timeout when provided", () => {