@intentius/chant 0.70.1 → 0.71.0

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 {