@intentius/chant 0.57.0 → 0.58.0

package/src/op/activities/env-teardown.ts

@@ -0,0 +1,171 @@
+/**
+ * `envTeardown` — the durable form of `chant lifecycle teardown <env> --yes`
+ * (#1222).
+ *
+ * Wraps core's {@link executeTeardown}: enumerate the live resources whose
+ * ownership marker carries this project's `ownership.stack` + the requested
+ * environment, delete them through each lexicon's `executeTeardown`
+ * capability, run core's one bounded retry pass, and fail the activity loudly
+ * when any candidate is still `failed` afterwards. Selection is marker-scoped
+ * by construction — the same engine the CLI verb drives, reached in-process
+ * rather than through a shell.
+ *
+ * The guards are the CLI's guards, unchanged:
+ * - an environment the project does not declare is refused;
+ * - a project with no `ownership.stack` is refused — teardown has nothing to
+ *   select on;
+ * - a production-like environment name (`prod`, `production`, `prod-eu`, ...)
+ *   is refused unless the step's args carry an explicit `confirmProd: true`.
+ *   An Op is non-interactive, so there is no re-type-the-name prompt to fall
+ *   back to — the confirmation must be authored into the Op.
+ *
+ * All three refusals throw before any live read, so a refused teardown
+ * touches nothing at all. They are configuration errors, not transient ones —
+ * no retry can make `prod` stop looking like production.
+ *
+ * Distinct from {@link chantTeardown} (`npm run teardown`), which runs
+ * whatever script a project wired under that name. This activity is
+ * product-agnostic: it imports core only, and core reaches each product
+ * through the lexicons the project configures.
+ */
+
+import { resolve } from "node:path";
+import { loadChantConfig, resolveOwnershipStack, type ChantConfig } from "../../config";
+import { unknownEnvError, isProdLikeEnvironment } from "../../env";
+import { applyLiveEndpoint } from "../../live-endpoint";
+import { executeTeardown, type TeardownReport } from "../../lifecycle/teardown";
+import type { ObservationLexicon } from "../../lexicon";
+
+export interface EnvTeardownArgs {
+  /** The environment to tear down — the marker env core selects on. */
+  env: string;
+  /**
+   * Required (as an explicit `true`) when `env` looks production-like.
+   * The Op's counterpart of the CLI's `--confirm-prod`: activities never
+   * prompt, so the confirmation is authored, reviewed, and versioned with
+   * the Op instead.
+   */
+  confirmProd?: boolean;
+  /** Path to the chant project (where chant.config.ts lives). Default: the chant process's cwd. */
+  path?: string;
+}
+
+/** What a completed (fully successful) teardown reports back to the run. */
+export interface EnvTeardownResult {
+  environment: string;
+  /** The ownership stack everything was selected on. */
+  stack: string;
+  deleted: number;
+  /** Deliberately refused by a lexicon, with the reason in the report. */
+  notPrunable: number;
+  /** Planned candidates whose lexicon implements no execution yet. */
+  skipped: number;
+  /** Kinds that could not be read (#1089) — the plan was incomplete, not clean. */
+  holes: number;
+  /** The full per-candidate report core produced. */
+  report: TeardownReport;
+}
+
+/** Injectable seams for testing — production loads both from the project. */
+export interface EnvTeardownDeps {
+  /** Pre-loaded project config (skips reading chant.config.ts). */
+  config?: ChantConfig;
+  /** Pre-loaded lexicon plugins (skips resolving + importing lexicon packages). */
+  plugins?: ObservationLexicon[];
+}
+
+/**
+ * Load the project's lexicon plugins through core's own resolution: the
+ * `lexicons` list in chant.config, falling back to source-file detection.
+ * A dynamic import so this module does not pull the whole CLI surface in at
+ * load time — the registry imports every activity module eagerly.
+ */
+async function loadProjectPlugins(projectPath: string): Promise<ObservationLexicon[]> {
+  const { loadPlugins, resolveProjectLexicons } = await import("../../cli/plugins");
+  return loadPlugins(await resolveProjectLexicons(projectPath));
+}
+
+/**
+ * Tear down one environment's marker-owned resources through the core
+ * teardown engine. Uses the `longInfra` profile — deletion waits on the
+ * target's own pace. Safe to retry: the engine re-plans from live markers on
+ * every run, and a resource already gone is simply no longer a candidate.
+ */
+export async function envTeardown(
+  args: EnvTeardownArgs,
+  _signal?: AbortSignal,
+  deps?: EnvTeardownDeps,
+): Promise<EnvTeardownResult> {
+  const projectPath = resolve(args.path ?? ".");
+  const config = deps?.config ?? (await loadChantConfig(projectPath)).config;
+
+  // Refuse an env the project does not declare — a typo here is the
+  // difference between tearing down `dev` and tearing down `prod`.
+  const envErr = unknownEnvError(args.env, config.environments);
+  if (envErr) throw new Error(`envTeardown: ${envErr}`);
+
+  // Teardown selects on the ownership marker; a project that stamps none has
+  // nothing to key on, and "delete what looks like mine" is not a fallback.
+  const stack = resolveOwnershipStack(config);
+  if (stack === undefined) {
+    throw new Error(
+      "envTeardown: this project declares no ownership.stack — teardown is marker-scoped and has nothing to select on. " +
+        'Set `ownership: { stack: "<name>" }` in chant.config.ts and deploy, so resources carry the marker teardown keys on.',
+    );
+  }
+
+  // The prod guard (#1222). Checked before any live read, so a refused
+  // teardown touches nothing at all.
+  if (isProdLikeEnvironment(args.env) && args.confirmProd !== true) {
+    throw new Error(
+      `envTeardown: "${args.env}" looks like a production environment — ` +
+        "add `confirmProd: true` to the envTeardown step's args to tear it down from an Op.",
+    );
+  }
+
+  const plugins = deps?.plugins ?? (await loadProjectPlugins(projectPath));
+
+  // #1166 — teardown is a live read and a live write, so an environment's
+  // declared endpoint applies here too, unless the ambient shell already set it.
+  const reading = plugins.filter((p) => p.teardownOwned || p.describeResources || p.executeTeardown);
+  const endpoint = applyLiveEndpoint(config.environments, args.env, reading);
+  if (endpoint.notice) console.log(endpoint.notice);
+
+  let report: TeardownReport;
+  try {
+    report = await executeTeardown({ environment: args.env, stack, plugins });
+  } finally {
+    endpoint.restore();
+  }
+
+  const count = (outcome: string) => report.outcomes.filter((o) => o.outcome === outcome).length;
+  const deleted = count("deleted");
+  const failed = report.outcomes.filter((o) => o.outcome === "failed");
+  const notPrunable = count("not-prunable");
+  const skipped = count("skipped");
+
+  console.log(
+    `envTeardown ${args.env} (stack ${stack}): ${deleted} deleted, ${failed.length} failed, ` +
+      `${notPrunable} not-prunable, ${skipped} skipped, ${report.plan.holes.length} hole(s)`,
+  );
+
+  // Failures that survived core's bounded retry pass fail the activity —
+  // silence is never success. A failed step is what the executor aborts the
+  // phase on and what the Op's `onFailure` compensation runs for.
+  if (failed.length > 0) {
+    const names = failed.map((o) => `${o.lexicon}/${o.name}${o.detail ? ` (${o.detail})` : ""}`).join(", ");
+    throw new Error(
+      `envTeardown: ${failed.length} of ${report.outcomes.length} candidate(s) still failed after the retry pass: ${names}`,
+    );
+  }
+
+  return {
+    environment: args.env,
+    stack,
+    deleted,
+    notPrunable,
+    skipped,
+    holes: report.plan.holes.length,
+    report,
+  };
+}

package/src/op/activities/guard-validate.test.ts

@@ -0,0 +1,139 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import { resolve } from "node:path";
+import type { NonRetryableActivityError } from "../activity-failure";
+
+// guardValidate reaches cfn-guard through the runtime adapter's spawn (not
+// node:child_process), so the I/O seam is the runtime-adapter module — same
+// pattern `lexicons/aws/src/import/live-export-io.test.ts` uses for the aws
+// plugin's own spawn calls. Partial mock (`importOriginal`) rather than a
+// full replacement, for the same reason that test gives: the module is
+// reachable from other real exports this file's own imports touch
+// transitively, so replacing it wholesale would break more than `spawn`.
+const spawnMock = vi.fn();
+vi.mock("../../runtime-adapter", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../runtime-adapter")>();
+  return { ...actual, getRuntime: () => ({ ...actual.getRuntime(), spawn: spawnMock }) };
+});
+
+import { guardValidate, parseGuardFindings } from "./guard-validate";
+
+const CLEAN = JSON.stringify([{ name: "template.json", not_compliant: [], compliant: [{ Rule: { name: "s3_bucket_ok" } }] }]);
+
+const ONE_VIOLATION = JSON.stringify([
+  {
+    name: "template.json",
+    not_compliant: [
+      {
+        Rule: {
+          name: "s3_bucket_public_read_prohibited",
+          messages: { error: "PublicAccessBlockConfiguration is missing" },
+          checks: [{ Clause: { Unary: { check: { UnResolved: { path: "/Resources/MyBucket/Properties/PublicAccessBlockConfiguration" } } } } }],
+        },
+      },
+    ],
+    compliant: [],
+  },
+]);
+
+describe("guardValidate activity (#522)", () => {
+  beforeEach(() => spawnMock.mockReset());
+
+  test("spawns cfn-guard validate with -r/-d/--output-format json; template defaults to <path>/template.json", async () => {
+    spawnMock.mockResolvedValue({ stdout: CLEAN, stderr: "", exitCode: 0 });
+    await guardValidate({ rules: "rules.guard", path: "proj" });
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    const argv = spawnMock.mock.calls[0][0] as string[];
+    expect(argv).toEqual([
+      "cfn-guard", "validate",
+      "-r", "rules.guard",
+      "-d", resolve("proj", "template.json"),
+      "--output-format", "json",
+    ]);
+  });
+
+  test("an explicit template/binary override both take", async () => {
+    spawnMock.mockResolvedValue({ stdout: CLEAN, stderr: "", exitCode: 0 });
+    await guardValidate({ rules: "rules.guard", template: "dist/out.json", binary: "/opt/bin/cfn-guard" });
+    const argv = spawnMock.mock.calls[0][0] as string[];
+    expect(argv).toEqual(["/opt/bin/cfn-guard", "validate", "-r", "rules.guard", "-d", "dist/out.json", "--output-format", "json"]);
+  });
+
+  test("a clean run resolves with no findings", async () => {
+    spawnMock.mockResolvedValue({ stdout: CLEAN, stderr: "", exitCode: 0 });
+    await expect(guardValidate({ rules: "rules.guard" })).resolves.toEqual({
+      findings: [],
+      summary: expect.stringContaining("compliant"),
+    });
+  });
+
+  test("a violation throws (non-retryable) and names the rule and the entity", async () => {
+    spawnMock.mockResolvedValue({ stdout: ONE_VIOLATION, stderr: "", exitCode: 5 });
+    await expect(guardValidate({ rules: "rules.guard" })).rejects.toThrow(
+      /s3_bucket_public_read_prohibited.*MyBucket/s,
+    );
+  });
+
+  test("the thrown failure is a non-retryable activity failure typed GuardViolation — same shape policyGate uses for PolicyViolation", async () => {
+    spawnMock.mockResolvedValue({ stdout: ONE_VIOLATION, stderr: "", exitCode: 5 });
+    try {
+      await guardValidate({ rules: "rules.guard" });
+      expect.unreachable("guardValidate should have thrown");
+    } catch (err) {
+      expect((err as NonRetryableActivityError).type).toBe("GuardViolation");
+      expect((err as NonRetryableActivityError).nonRetryable).toBe(true);
+    }
+  });
+
+  test("cfn-guard producing no output at all (binary missing / failed to run) is a setup error, not a clean pass", async () => {
+    spawnMock.mockResolvedValue({ stdout: "", stderr: "spawn cfn-guard ENOENT", exitCode: 1 });
+    await expect(guardValidate({ rules: "rules.guard" })).rejects.toThrow(/cfn-guard.*no output/i);
+  });
+
+  test("onFinding other than \"report\" is refused rather than silently ignored", async () => {
+    // @ts-expect-error — the type only admits "report"; a dynamically loaded
+    // Op config could still pass through an unsupported value at runtime.
+    await expect(guardValidate({ rules: "rules.guard", onFinding: "issue" })).rejects.toThrow(
+      /onFinding "issue" is not implemented/,
+    );
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("parseGuardFindings (#522 — pure mapping, no spawn)", () => {
+  test("no not_compliant entries → no findings", () => {
+    expect(parseGuardFindings(CLEAN)).toEqual([]);
+  });
+
+  test("maps a not_compliant entry to a finding with rule, message, and entity", () => {
+    const findings = parseGuardFindings(ONE_VIOLATION);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      rule: "s3_bucket_public_read_prohibited",
+      severity: "error",
+      entity: "MyBucket",
+    });
+    expect(findings[0].message).toContain("PublicAccessBlockConfiguration is missing");
+  });
+
+  test("a single (non-array) file report is accepted", () => {
+    const single = JSON.stringify({ name: "template.json", not_compliant: [{ Rule: { name: "r1" } }] });
+    expect(parseGuardFindings(single)).toEqual([{ rule: "r1", severity: "error", message: 'cfn-guard rule "r1" violated' }]);
+  });
+
+  test("a rule violation with no recognizable message field still produces a finding, not a silent drop", () => {
+    const noMessage = JSON.stringify([{ not_compliant: [{ Rule: { name: "r2" } }] }]);
+    expect(parseGuardFindings(noMessage)).toEqual([{ rule: "r2", severity: "error", message: 'cfn-guard rule "r2" violated' }]);
+  });
+
+  test("multiple violations across multiple file reports are all collected", () => {
+    const multi = JSON.stringify([
+      { name: "a.json", not_compliant: [{ Rule: { name: "r1" } }] },
+      { name: "b.json", not_compliant: [{ Rule: { name: "r2" } }, { Rule: { name: "r3" } }] },
+    ]);
+    expect(parseGuardFindings(multi).map((f) => f.rule)).toEqual(["r1", "r2", "r3"]);
+  });
+
+  test("non-JSON stdout throws a clear setup error rather than reporting zero violations", () => {
+    expect(() => parseGuardFindings("cfn-guard: error: rules file not found")).toThrow(/did not return parseable JSON/);
+  });
+});

package/src/op/activities/guard-validate.ts

@@ -0,0 +1,223 @@
+/**
+ * guardValidate — chant #522: reuse an existing CloudFormation Guard rules
+ * pack as a first-class Op step, instead of reimplementing compliance packs
+ * as native `WAW` rules.
+ *
+ * chant already emits standard CloudFormation `template.json` (no
+ * chant-specific translation), so an org's existing `.guard` files run
+ * against it unchanged: this activity is a thin shell around
+ * `cfn-guard validate -r <rules> -d <template> --output-format json`, run
+ * through the runtime adapter's `spawn` (never `node:child_process`
+ * directly — see `lexicons/aws/src/plugin.ts`'s `exportResources` for the
+ * same seam, and `../../import/live-export-io.test.ts` for how a test mocks
+ * it). `cfn-guard` is an operational dependency, not a `chant build`
+ * dependency — nothing here runs inside the pure core.
+ *
+ * Mirrors `./policy.ts`'s `policyGate`: `report` is the only finding-mode
+ * today (the type only admits that one value; `issue`/`pull-request` modes
+ * are a follow-up, chant #522), and an error-severity finding throws
+ * (a non-retryable activity failure) so the run exits non-zero — the same gate
+ * CI relies on to fail the pipeline — and the same activity blocks an `ApplyOp`
+ * when placed before it.
+ */
+import { resolve } from "node:path";
+import { nonRetryableFailure } from "../activity-failure";
+
+export interface GuardValidateArgs {
+  /**
+   * Path to a `.guard` rules file or directory, passed to `cfn-guard validate
+   * -r`. No chant-specific rule format — these are ordinary cfn-guard rules,
+   * the same ones CDK's `CfnGuardValidator` would run.
+   */
+  rules: string;
+  /**
+   * Path to the built CloudFormation template to validate. Default:
+   * `<path>/template.json` — the convention `chant build -o template.json`
+   * writes to (see the aws lexicon's own examples and the native-output
+   * policy docs).
+   */
+  template?: string;
+  /** Project directory `template` is resolved relative to, when `template` is not given. Default ".". */
+  path?: string;
+  /**
+   * What to produce on a finding. Only `"report"` runs today — it prints a
+   * summary and throws on any finding, no external service involved.
+   * `issue`/`pull-request` modes (reusing the audit-Op finding-mode
+   * plumbing) are left to a follow-up. Default: `"report"`.
+   */
+  onFinding?: "report";
+  /** Path to (or name of) the `cfn-guard` binary. Default: `"cfn-guard"`, resolved via `PATH`. */
+  binary?: string;
+}
+
+/** One cfn-guard rule violation, mapped to a chant-shaped diagnostic. */
+export interface GuardFinding {
+  /** The cfn-guard rule name that failed. */
+  rule: string;
+  /** Always `"error"` today — a cfn-guard non-compliant result is a policy violation, the same weight `policyGate` gives a violation. */
+  severity: "error";
+  /** Human-readable violation message. */
+  message: string;
+  /** Best-effort CloudFormation logical id the violation is about, when cfn-guard's output names one. */
+  entity?: string;
+}
+
+export interface GuardValidateResult {
+  findings: GuardFinding[];
+  summary: string;
+}
+
+type JsonValue = unknown;
+
+/**
+ * Recursively collect message-shaped string values anywhere inside a parsed
+ * cfn-guard `not_compliant` entry. cfn-guard's exact JSON nesting for a
+ * violation's human message has shifted across versions (Unary/Clause/Check
+ * wrappers, `messages.custom_message` vs `messages.error`, …); rather than
+ * betting on one fixed path that a version bump silently breaks, this walks
+ * the whole entry and takes every message-shaped string it finds — the same
+ * "degrade, don't false-negative" instinct `defaultGitlabRefResolver`
+ * (`./pipeline-audit.ts`) uses for a resolver failure.
+ */
+function collectMessages(value: JsonValue, out: string[] = [], seen = new Set<string>()): string[] {
+  if (typeof value !== "object" || value === null) return out;
+  if (Array.isArray(value)) {
+    for (const v of value) collectMessages(v, out, seen);
+    return out;
+  }
+  for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof v === "string" && /^(message|custom_message|error)$/i.test(key) && v.trim() && !seen.has(v)) {
+      seen.add(v);
+      out.push(v);
+    } else {
+      collectMessages(v, out, seen);
+    }
+  }
+  return out;
+}
+
+/** Collect every string value found under a `*path*`-shaped key, anywhere in the entry. */
+function collectPaths(value: JsonValue, out: string[] = []): string[] {
+  if (typeof value !== "object" || value === null) return out;
+  if (Array.isArray(value)) {
+    for (const v of value) collectPaths(v, out);
+    return out;
+  }
+  for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof v === "string" && /path/i.test(key)) out.push(v);
+    else collectPaths(v, out);
+  }
+  return out;
+}
+
+/**
+ * Best-effort CloudFormation logical id for a violation: cfn-guard reports
+ * the offending property as a template path such as
+ * `/Resources/MyBucket/Properties/...`. Pull the segment right after
+ * `Resources` from the first path-shaped string found, if any.
+ */
+function findEntity(value: JsonValue): string | undefined {
+  for (const p of collectPaths(value)) {
+    const m = /Resources[./]([A-Za-z0-9]+)/.exec(p);
+    if (m) return m[1];
+  }
+  return undefined;
+}
+
+/**
+ * Map cfn-guard's `--output-format json` report to chant-shaped findings.
+ * Exported and tested directly (independent of `spawn`) — same split
+ * `collectPipelineRefs`/`pipelineSupplyChainAudit` (`./pipeline-audit.ts`)
+ * use between pure mapping and the orchestrating activity.
+ *
+ * Throws if `stdout` is not parseable JSON — a cfn-guard invocation that
+ * didn't run with `--output-format json` (a bad rules path, a version too
+ * old to support it) is a setup problem, not "zero violations"; reporting
+ * a clean run here would be a false negative.
+ */
+export function parseGuardFindings(stdout: string): GuardFinding[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    throw new Error(
+      `cfn-guard did not return parseable JSON (guardValidate always passes --output-format json) — ` +
+        `${err instanceof Error ? err.message : String(err)}\nraw output:\n${stdout}`,
+    );
+  }
+
+  const fileReports = Array.isArray(parsed) ? parsed : [parsed];
+  const findings: GuardFinding[] = [];
+  for (const report of fileReports) {
+    const notCompliant = (report as { not_compliant?: unknown[] } | null)?.not_compliant ?? [];
+    for (const entry of notCompliant) {
+      const rule =
+        (entry as { Rule?: { name?: string }; name?: string } | null)?.Rule?.name ??
+        (entry as { name?: string } | null)?.name ??
+        "unknown-rule";
+      const messages = collectMessages(entry);
+      const message = messages.length > 0 ? `cfn-guard rule "${rule}" violated: ${messages.join("; ")}` : `cfn-guard rule "${rule}" violated`;
+      const entity = findEntity(entry);
+      findings.push({ rule, severity: "error", message, ...(entity ? { entity } : {}) });
+    }
+  }
+  return findings;
+}
+
+function renderSummary(findings: GuardFinding[], template: string, rules: string): string {
+  if (findings.length === 0) return `## cfn-guard\n\n${template} is compliant with ${rules}.\n`;
+  let out = `## cfn-guard\n\n${findings.length} violation(s) in ${template} against ${rules}:\n\n`;
+  out += "| Rule | Entity | Message |\n|---|---|---|\n";
+  for (const f of findings) out += `| ${f.rule} | ${f.entity ?? ""} | ${f.message} |\n`;
+  return out;
+}
+
+/**
+ * Run an external CloudFormation Guard rules pack against the project's
+ * built CloudFormation template. `report` mode: prints a summary, and
+ * throws (non-retryable) when any rule is violated, so the local executor
+ * (`chant run`) exits non-zero and CI fails the pipeline — the same shape
+ * `policyGate` uses to block an apply. A clean run passes through.
+ *
+ * A plain activity on every runtime, not a `gate` step.
+ */
+export async function guardValidate(args: GuardValidateArgs, _signal?: AbortSignal): Promise<GuardValidateResult> {
+  const mode = args.onFinding ?? "report";
+  if (mode !== "report") {
+    throw new Error(
+      `guardValidate: onFinding "${mode}" is not implemented — only "report" runs today ` +
+        `(chant #522 leaves issue/pull-request modes to a follow-up).`,
+    );
+  }
+
+  const projectPath = args.path ?? ".";
+  const template = args.template ?? resolve(projectPath, "template.json");
+  const binary = args.binary ?? "cfn-guard";
+
+  const { getRuntime } = await import("../../runtime-adapter");
+  const rt = getRuntime();
+  const result = await rt.spawn([binary, "validate", "-r", args.rules, "-d", template, "--output-format", "json"]);
+
+  if (result.stdout.trim() === "" && result.stderr.trim() !== "") {
+    throw new Error(
+      `cfn-guard ("${binary}") produced no output — ${result.stderr.trim()}\n` +
+        `Install cfn-guard (https://github.com/aws-cloudformation/cloudformation-guard) or pass { binary } ` +
+        `to point at an existing install.`,
+    );
+  }
+
+  const findings = parseGuardFindings(result.stdout);
+  const summary = renderSummary(findings, template, args.rules);
+
+  if (findings.length > 0) {
+    console.log(summary);
+    const detail = findings.map((f) => `[${f.rule}]${f.entity ? ` ${f.entity}:` : ""} ${f.message}`).join("; ");
+    throw nonRetryableFailure(
+      `cfn-guard blocked the build — ${findings.length} violation(s) against ${args.rules}: ${detail}`,
+      "GuardViolation",
+    );
+  }
+
+  console.log(`[guard] ${template} is compliant with ${args.rules}`);
+  return { findings, summary };
+}

package/src/op/activities/http-check.test.ts

@@ -0,0 +1,48 @@
+import { describe, test, expect } from "vitest";
+import { httpCheck, statusOk, type HttpFetch } from "./http-check";
+
+const res = (status: number, body = "") => ({ status, text: async () => body });
+
+describe("statusOk (#typed-verify)", () => {
+  test("any 2xx when no expectation, exact match otherwise", () => {
+    expect(statusOk(200)).toBe(true);
+    expect(statusOk(204)).toBe(true);
+    expect(statusOk(404)).toBe(false);
+    expect(statusOk(404, 404)).toBe(true);
+    expect(statusOk(200, 201)).toBe(false);
+  });
+});
+
+describe("httpCheck (#typed-verify)", () => {
+  test("passes on 2xx and returns the status", async () => {
+    const fetchFn: HttpFetch = async () => res(200);
+    expect(await httpCheck({ url: "http://x" }, undefined, fetchFn)).toEqual({ status: 200 });
+  });
+
+  test("throws when the status doesn't match", async () => {
+    const fetchFn: HttpFetch = async () => res(500, "boom");
+    await expect(httpCheck({ url: "http://x" }, undefined, fetchFn)).rejects.toThrow(/status 500 \(want 2xx\)/);
+  });
+
+  test("checks a body substring when `contains` is set", async () => {
+    const fetchFn: HttpFetch = async () => res(200, '{"name":"trio-bucket"}');
+    expect(await httpCheck({ url: "http://x", contains: "trio-bucket" }, undefined, fetchFn)).toEqual({ status: 200 });
+    await expect(
+      httpCheck({ url: "http://x", contains: "missing" }, undefined, fetchFn),
+    ).rejects.toThrow(/body missing "missing"/);
+  });
+
+  test("retries then succeeds", async () => {
+    let n = 0;
+    const fetchFn: HttpFetch = async () => (++n < 3 ? res(503) : res(200));
+    expect(await httpCheck({ url: "http://x", retries: 3, intervalMs: 1 }, undefined, fetchFn)).toEqual({ status: 200 });
+    expect(n).toBe(3);
+  });
+
+  test("surfaces a fetch (connection) error", async () => {
+    const fetchFn: HttpFetch = async () => {
+      throw new Error("ECONNREFUSED");
+    };
+    await expect(httpCheck({ url: "http://x" }, undefined, fetchFn)).rejects.toThrow(/ECONNREFUSED/);
+  });
+});

package/src/op/activities/http-check.ts

@@ -0,0 +1,55 @@
+import { sleep } from "../activity-runtime";
+
+export interface HttpCheckArgs {
+  /** URL to GET (or `method`). */
+  url: string;
+  /** HTTP method. Default: `GET`. */
+  method?: string;
+  /** Exact expected status. Default: any 2xx. */
+  status?: number;
+  /** Substring the response body must contain. */
+  contains?: string;
+  /** Retries before failing, for a resource that may lag. Default: `0`. */
+  retries?: number;
+  /** Delay between retries in ms. Default: `1000`. */
+  intervalMs?: number;
+}
+
+/** Injectable fetch — the response shape `httpCheck` needs. Defaults to global `fetch`. */
+export type HttpFetch = (url: string, init?: { method?: string; signal?: AbortSignal }) => Promise<{ status: number; text(): Promise<string> }>;
+
+/** Whether a status satisfies the expectation (exact if given, else any 2xx). Pure. */
+export function statusOk(status: number, expected?: number): boolean {
+  return expected === undefined ? status >= 200 && status < 300 : status === expected;
+}
+
+/**
+ * Assert an HTTP endpoint responds as expected — a typed verify step, the modeled
+ * replacement for `shell("curl -fs ...")`. Fails (throwing) if the status or body
+ * doesn't match after the allowed retries. `fetchFn` is injectable for tests.
+ * Uses fastIdempotent profile — 5m timeout.
+ */
+export async function httpCheck(args: HttpCheckArgs, signal?: AbortSignal, fetchFn: HttpFetch = fetch): Promise<{ status: number }> {
+  const retries = args.retries ?? 0;
+  const intervalMs = args.intervalMs ?? 1_000;
+  let lastErr = "";
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (signal?.aborted) throw new Error("httpCheck aborted");
+    try {
+      const res = await fetchFn(args.url, { method: args.method ?? "GET", signal });
+      const body = args.contains !== undefined ? await res.text() : "";
+      if (!statusOk(res.status, args.status)) {
+        lastErr = `status ${res.status} (want ${args.status ?? "2xx"})`;
+      } else if (args.contains !== undefined && !body.includes(args.contains)) {
+        lastErr = `body missing "${args.contains}"`;
+      } else {
+        console.log(`httpCheck OK: ${args.url} (${res.status})`);
+        return { status: res.status };
+      }
+    } catch (e) {
+      lastErr = e instanceof Error ? e.message : String(e);
+    }
+    if (attempt < retries) await sleep(intervalMs, signal);
+  }
+  throw new Error(`httpCheck failed for ${args.url}: ${lastErr}`);
+}