@intentius/chant 0.70.1 → 0.71.1

package/src/op/activities/shell.ts

@@ -9,18 +9,93 @@ export interface ShellCmdArgs {
   env?: Record<string, string>;
   /** Working directory. Default: process.cwd(). */
   cwd?: string;
+  /**
+   * Exit codes that count as success. Default `[0]`.
+   *
+   * Without this, `exitCode` in the result could only ever be `0` (#2413):
+   * every other code rejects, so nothing downstream can read it. Naming the
+   * codes a command uses to report a result — `diff`'s 1, `grep`'s 1,
+   * a migration tool's "nothing to do" — turns them into a value a later
+   * step can branch on instead of a failed Op.
+   */
+  okExit?: number[];
+}
+
+/**
+ * How much stdout a command may produce, matching every other exec site in
+ * the tree (`../activities/apply.ts`, the terraform lexicon's activities,
+ * `../../components/verbs/process-runner.ts`).
+ *
+ * Node's default is 1 MiB, and this was the only exec call leaving it unset
+ * (#2412) — on the one activity whose output chant cannot predict, because
+ * the command is the author's. A verbose test run, a playbook or a wide plan
+ * passes 1 MiB without trying, and the overflow is a rejection rather than a
+ * truncation, so the step fails for a reason that has nothing to do with the
+ * command.
+ */
+const MAX_STDOUT_BYTES = 64 * 1024 * 1024;
+
+/**
+ * What a shell step publishes to the steps after it (#2413).
+ *
+ * `stdout` and `stderr` are trimmed, because the value an author wants from
+ * `echo $(terraform output -raw host)` is the host, not the host plus a
+ * newline, and a trailing newline in an `env` value or a gate argument is a
+ * bug that is very hard to see.
+ *
+ * `stderr` is here as well as on the console. It was captured and dropped
+ * before, so a command that reports on stderr — every tool that prints
+ * progress there — had no route to a later step at all.
+ */
+export interface ShellCmdResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/** Node hangs the exit status off the error as `code`, and a signal kill as `signal`. */
+interface ExecFailure extends Error {
+  code?: number | string;
+  signal?: string;
+  killed?: boolean;
+  stdout?: string;
+  stderr?: string;
 }
 
 /**
  * Run an arbitrary shell command.
- * Uses fastIdempotent profile — 5m timeout, 3 retries.
+ *
+ * Runs under the `atMostOnce` profile by default (#2411): one attempt, since
+ * nothing here can know whether repeating the author's command is safe.
  */
-export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promise<string> {
-  const { stdout, stderr } = await execAsync(args.cmd, {
-    cwd: args.cwd,
-    env: { ...process.env, ...args.env },
-    signal,
-  });
-  if (stderr) console.error(stderr);
-  return stdout.trim();
+export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promise<ShellCmdResult> {
+  const okExit = args.okExit ?? [0];
+  try {
+    const { stdout, stderr } = await execAsync(args.cmd, {
+      cwd: args.cwd,
+      env: { ...process.env, ...args.env },
+      maxBuffer: MAX_STDOUT_BYTES,
+      signal,
+    });
+    if (stderr) console.error(stderr);
+    return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 };
+  } catch (err) {
+    const failure = err as ExecFailure;
+    const exitCode = typeof failure.code === "number" ? failure.code : undefined;
+    // A signal kill (Ctrl-C, the profile's timeout, a maxBuffer overflow) is
+    // not an exit status the author declared anything about, so it rethrows
+    // even if `okExit` happens to contain the code.
+    const died = failure.killed === true || typeof failure.signal === "string" || signal?.aborted === true;
+    if (exitCode !== undefined && !died && okExit.includes(exitCode)) {
+      const stderrText = (failure.stderr ?? "").trim();
+      if (stderrText) console.error(stderrText);
+      return { stdout: (failure.stdout ?? "").trim(), stderr: stderrText, exitCode };
+    }
+    if (exitCode !== undefined && !died) {
+      // `local-executor` records `error` as message text, so the code has to
+      // be in the message or it is gone (#2413).
+      failure.message = `command exited ${exitCode} (expected ${okExit.join(", ")}): ${failure.message}`;
+    }
+    throw failure;
+  }
 }

package/src/op/activity-profiles.test.ts

@@ -10,12 +10,26 @@ import { activity } from "./builders";
  * in an in-process step, so it did not come along.
  */
 describe("ACTIVITY_PROFILES", () => {
-  test("carries the six named profiles", () => {
+  test("carries the seven named profiles", () => {
     expect(Object.keys(ACTIVITY_PROFILES).sort()).toEqual(
-      ["argoSync", "fastIdempotent", "humanGate", "k8sWait", "longInfra", "policyCheck"],
+      ["argoSync", "atMostOnce", "fastIdempotent", "humanGate", "k8sWait", "longInfra", "policyCheck"],
     );
   });
 
+  test("atMostOnce runs once, and is the only non-gate profile that does (#2411)", () => {
+    expect(ACTIVITY_PROFILES.atMostOnce.retry.maximumAttempts).toBe(1);
+    // The two other single-attempt profiles carry semantics a shell step must
+    // not borrow: a gate's single attempt is about not re-asking a human, and
+    // a policy check's is about not re-running an evaluation. A run ledger
+    // that called a shell step either of those would be saying something
+    // false about what ran.
+    const singleAttempt = Object.entries(ACTIVITY_PROFILES)
+      .filter(([, p]) => p.retry.maximumAttempts === 1)
+      .map(([name]) => name)
+      .sort();
+    expect(singleAttempt).toEqual(["atMostOnce", "humanGate", "policyCheck"]);
+  });
+
   test("every profile has a timeout, and none has a worker-era field", () => {
     for (const [name, profile] of Object.entries(ACTIVITY_PROFILES)) {
       expect(typeof profile.timeout, `${name}.timeout`).toBe("string");

package/src/op/activity-profiles.ts

@@ -72,6 +72,24 @@ export const ACTIVITY_PROFILES = {
     },
   },
 
+  /**
+   * A command chant did not write and cannot know is safe to repeat (#2411).
+   *
+   * `shellCmd` is the escape hatch: its whole purpose is to run something
+   * outside the model, so nothing here can judge whether a second attempt is
+   * harmless or a second deployment. Every other activity carrying a retrying
+   * profile is one chant authored and knows the shape of.
+   *
+   * Twenty minutes, because a shell step is as likely to be a long build as a
+   * quick script, and one attempt, because retrying is the claim that needs
+   * evidence. An author who knows their command is idempotent names
+   * `fastIdempotent` or `longInfra` and gets retries back.
+   */
+  atMostOnce: {
+    timeout: "20m",
+    retry: { maximumAttempts: 1 },
+  },
+
   /**
    * Human-gate steps: waiting for an operator action (DNS delegation, approval).
    * Very long timeout, single attempt — no retry on human-gate timeouts.

package/src/op/builders.ts

@@ -306,16 +306,34 @@ export const lifecycleSnapshot = (env: string, opts?: { id?: string }): NamedAct
   activity("lifecycleSnapshot", { env } satisfies LifecycleSnapshotArgs, opts?.id ? { id: opts.id } : undefined);
 
 /**
- * Run an arbitrary shell command. Tag long-running commands with a `profile`
- * (e.g. `longInfra` for a multi-GB image push) so they get the right
- * start-to-close timeout on whichever runtime hosts the run.
+ * Run an arbitrary shell command.
+ *
+ * Defaults to the `atMostOnce` profile: twenty minutes, one attempt (#2411).
+ * This is the one activity chant cannot know is idempotent, because its
+ * purpose is to run something chant does not model, so a failed command is
+ * not repeated unless the author says it may be. Name `fastIdempotent` or
+ * `longInfra` to get retries back for a command that is safe to repeat.
+ *
+ * Give the step an `id` and later steps can read what it produced —
+ * `sh.out.stdout`, `sh.out.stderr`, `sh.out.exitCode` (#2413) — and a value
+ * from an earlier step reaches the command through `env` (#2414):
+ *
+ * ```ts
+ * const host = shell("terraform output -raw host", { id: "host" });
+ * shell("./smoke.sh", { env: { HOST: host.out.stdout } });
+ * ```
+ *
+ * `cmd` stays a plain `string` and takes no references. A value spliced into
+ * a command line is a quoting decision chant would then be making on the
+ * author's behalf, and `env` carries the same value into the same command
+ * with the shell's own rules intact.
  */
 export const shell = (
   cmd: string,
   opts?: WithStepRefs<Omit<ShellCmdArgs, "cmd">> & StepOpts,
 ): NamedActivityStep => {
   const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
-  return activity("shellCmd", { cmd, ...args }, { ...(profile ? { profile } : {}), ...(id ? { id } : {}) });
+  return activity("shellCmd", { cmd, ...args }, { profile: profile ?? "atMostOnce", ...(id ? { id } : {}) });
 };
 
 /**

package/src/op/gate-name.ts

@@ -18,6 +18,17 @@
 
 import type { OpConfig, PhaseDefinition, StepDefinition } from "./types";
 
+/**
+ * The op name a `chant components fan-out` gate is recorded under (#2420).
+ *
+ * A fan-out is a command rather than an authored `*.op.ts`, so `chant approve`
+ * has nothing to discover for this name and must not report that as a problem.
+ * It lives here, next to the other thing that decides what a gate is called,
+ * so both the command that records the pending fact and the command that
+ * answers it read one constant instead of agreeing by hand.
+ */
+export const FAN_OUT_GATE_OP = "fan-out";
+
 /** Either spelling of a gate step's name. `gate` since #2202; `signalName` through 0.59.0. */
 export interface GateNamed {
   gate?: string;

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

@@ -123,7 +123,10 @@ describe("op.json IR", () => {
 
     expect(ir.name).toBe("full-deploy");
     const [build, approve, deploy, seed, verify] = ir.phases;
-    expect(build.steps[0]).toMatchObject({ kind: "activity", fn: "shellCmd", profile: "fastIdempotent" });
+    // A shell step carries `atMostOnce` since #2411: the IR records the
+    // profile the builder named, and the builder names one precisely so a
+    // command chant cannot judge does not inherit a retrying default.
+    expect(build.steps[0]).toMatchObject({ kind: "activity", fn: "shellCmd", profile: "atMostOnce" });
     expect(approve.steps[0]).toMatchObject({
       kind: "gate",
       gate: "approve-deploy",

package/src/op/op.test.ts

@@ -266,10 +266,15 @@ describe("profile routing (opts.profile sets the step profile, never leaks into
     expect("profile" in (a.args ?? {})).toBe(false);
   });
 
-  it("shell() without profile leaves the step unprofiled (defaults apply downstream)", () => {
+  it("shell() without profile names atMostOnce, so the retrying default cannot apply (#2411)", () => {
+    // It used to leave the step unprofiled and let the executor's default
+    // apply, which meant the one activity chant cannot know is idempotent
+    // inherited three attempts by omission. The builder names its profile now,
+    // the way terraformPlan and terraformApply already did.
     const a = shell("echo hi", { env: { A: "1" } });
-    expect("profile" in a).toBe(false);
+    expect(a.profile).toBe("atMostOnce");
     expect(a.args?.env).toEqual({ A: "1" });
+    expect("profile" in (a.args ?? {})).toBe(false);
   });
 
   it("build() accepts a profile override and does not leak it into args", () => {

package/src/op/step-output-ref.ts

@@ -112,15 +112,36 @@ export interface StepOutputRef {
 }
 
 /**
- * `T` with every own property additionally accepting a {@link StepOutputRef}
- * in its place (chant #1288 Stage 2) — the authoring-time counterpart of
- * `args` accepting a reference anywhere in the structure (#1290): a typed
- * step-builder wrapper whose opts type is `WithStepRefs<SomeActivityArgs>`
- * lets an author pass `diff.out.driftedStacks` for any field without an
- * `as` cast, while runtime validation of the reference itself is still
- * `validateStepOutputRefs`' job, not this type's.
+ * `V`, or a {@link StepOutputRef} in its place, at every position inside it.
+ *
+ * Recurses through arrays and plain objects — including an index signature,
+ * which is the case that motivated it (#2414): `shell()`'s `env` is a
+ * `Record<string, string>`, and a reference in one of its values resolves at
+ * run time (`local-executor`'s `resolveStepOutputRefs` deep-walks `args`) and
+ * passes OPS012 (`activity-contract.ts` skips a reference at the issue path),
+ * so the compiler was the only one of the three layers rejecting it.
+ *
+ * Functions are left alone rather than mapped — nothing in an activity's args
+ * is callable, and mapping one would silently strip its call signature.
+ */
+type StepRefAt<V> =
+  | StepOutputRef
+  | (V extends Function ? V
+    : V extends readonly (infer E)[] ? (V extends unknown[] ? StepRefAt<E>[] : readonly StepRefAt<E>[])
+    : V extends object ? { [K in keyof V]: StepRefAt<V[K]> }
+    : V);
+
+/**
+ * `T` with every property — at any depth — additionally accepting a {@link
+ * StepOutputRef} in its place (chant #1288 Stage 2, deepened in #2414) — the
+ * authoring-time counterpart of `args` accepting a reference anywhere in the
+ * structure (#1290): a typed step-builder wrapper whose opts type is
+ * `WithStepRefs<SomeActivityArgs>` lets an author pass
+ * `diff.out.driftedStacks` for any field without an `as` cast, while runtime
+ * validation of the reference itself is still `validateStepOutputRefs`' job,
+ * not this type's.
  */
-export type WithStepRefs<T> = { [K in keyof T]: T[K] | StepOutputRef };
+export type WithStepRefs<T> = { [K in keyof T]: StepRefAt<T[K]> };
 
 /** Structural guard for a value produced by {@link stepOutput} (or `activity()`'s `.out`). */
 export function isStepOutputRef(value: unknown): value is StepOutputRef {