@intentius/chant 0.1.14 → 0.1.16

package/src/cli/handlers/run.ts

@@ -4,6 +4,9 @@ import { createConnection } from "node:net";
 import { spawn as spawnChild, type ChildProcess } from "node:child_process";
 import { loadChantConfig } from "../../config";
 import { discoverOps } from "../../op/discover";
+import { loadActivities, loadProfiles } from "../../op/activity-registry";
+import { runOpLocally, findGate, LocalGateUnsupportedError, OpRunFailure } from "../../op/local-executor";
+import { renderHuman, renderJson } from "../../op/local-output";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
 import {
@@ -25,6 +28,21 @@ function workflowFnName(opName: string): string {
   return kebabToCamel(opName) + "Workflow";
 }
 
+/**
+ * Guard for Temporal-only commands (run list/status/log/signal/cancel, --report).
+ * These query durable run state that only exists under Temporal. Returns true
+ * when `--temporal` was passed; otherwise prints an actionable message and the
+ * caller should return non-zero.
+ */
+function requireTemporalMode(ctx: CommandContext, what: string): boolean {
+  if (ctx.args.temporal) return true;
+  console.error(formatError({
+    message: `\`${what}\` is not available in local mode`,
+    hint: "pass --temporal or configure a profile",
+  }));
+  return false;
+}
+
 export async function makeTemporalClient(profileName: string | undefined, projectPath: string) {
   const { config } = await loadChantConfig(projectPath);
   const profile = resolveProfile(config as Record<string, unknown>, profileName);
@@ -37,6 +55,7 @@ export async function makeTemporalClient(profileName: string | undefined, projec
 // ── chant run list ──────────────────────────────────���─────────────────────────
 
 export async function runOpList(ctx: CommandContext): Promise<number> {
+  if (!requireTemporalMode(ctx, "chant run list")) return 1;
   const { ops, errors } = await discoverOps();
 
   for (const err of errors) {
@@ -102,6 +121,7 @@ export async function runOpList(ctx: CommandContext): Promise<number> {
 // ── chant run status <name> ───────────────────────────────────────────────────
 
 export async function runOpStatus(ctx: CommandContext): Promise<number> {
+  if (!requireTemporalMode(ctx, "chant run status")) return 1;
   const name = ctx.args.extraPositional;
   if (!name) {
     console.error(formatError({ message: "Op name is required: chant run status <name>" }));
@@ -141,6 +161,7 @@ export async function runOpStatus(ctx: CommandContext): Promise<number> {
 // ── chant run log <name> ──────────────────────────────────────────────────────
 
 export async function runOpLog(ctx: CommandContext): Promise<number> {
+  if (!requireTemporalMode(ctx, "chant run log")) return 1;
   const name = ctx.args.extraPositional;
   if (!name) {
     console.error(formatError({ message: "Op name is required: chant run log <name>" }));
@@ -186,6 +207,7 @@ export async function runOpLog(ctx: CommandContext): Promise<number> {
 // ── chant run signal <name> <signal> ─────────────────────────────────────────
 
 export async function runOpSignal(ctx: CommandContext): Promise<number> {
+  if (!requireTemporalMode(ctx, "chant run signal")) return 1;
   const name = ctx.args.extraPositional;
   const signalName = ctx.args.extraPositional2;
 
@@ -212,6 +234,7 @@ export async function runOpSignal(ctx: CommandContext): Promise<number> {
 // ── chant run cancel <name> ───────────────────────────────────────────────────
 
 export async function runOpCancel(ctx: CommandContext): Promise<number> {
+  if (!requireTemporalMode(ctx, "chant run cancel")) return 1;
   const name = ctx.args.extraPositional;
   if (!name) {
     console.error(formatError({ message: "Op name is required: chant run cancel <name>" }));
@@ -274,7 +297,107 @@ function renderProgress(opName: string, history: WorkflowHistoryRaw): void {
   );
 }
 
+/**
+ * `chant run <name>` dispatcher.
+ *
+ * Local mode is the default — it runs the Op in-process with no Temporal
+ * server. `--temporal` opts into a cluster (gates, schedules, durable resume).
+ * `--report` reads a past durable run and is therefore Temporal-only.
+ */
 export async function runOp(ctx: CommandContext): Promise<number> {
+  if (ctx.args.local && ctx.args.temporal) {
+    console.error(formatError({
+      message: "--local and --temporal are mutually exclusive",
+      hint: "omit both for local mode (the default), or pass exactly one",
+    }));
+    return 1;
+  }
+  if (ctx.args.report) {
+    if (!requireTemporalMode(ctx, "chant run --report")) return 1;
+    return runOpTemporal(ctx);
+  }
+  return ctx.args.temporal ? runOpTemporal(ctx) : runOpLocal(ctx);
+}
+
+/**
+ * Run an Op in-process via the local executor — no Temporal worker, server, or
+ * built `worker.ts`. Reads the Op config straight from discovery and resolves
+ * activities from the Temporal lexicon package.
+ */
+export async function runOpLocal(ctx: CommandContext): Promise<number> {
+  const opName = ctx.args.path;
+  if (!opName || opName === ".") {
+    console.error(formatError({
+      message: "Op name is required: chant run <name>",
+      hint: "Run `chant run list --temporal` to see available Ops",
+    }));
+    return 1;
+  }
+
+  const { ops, errors } = await discoverOps();
+  for (const err of errors) console.error(formatWarning({ message: err }));
+
+  const discovered = ops.get(opName);
+  if (!discovered) {
+    const names = [...ops.keys()];
+    console.error(formatError({
+      message: `Op "${opName}" not found`,
+      hint: names.length > 0
+        ? `Available: ${names.join(", ")}`
+        : "No *.op.ts files found — create one",
+    }));
+    return 1;
+  }
+
+  const { config } = discovered;
+
+  // Pre-flight: gates/schedules need a durable runtime — fail before any step.
+  const gate = findGate(config);
+  if (gate) {
+    console.error(formatError({
+      message: new LocalGateUnsupportedError(gate.signalName).message,
+    }));
+    return 1;
+  }
+
+  let activities, profiles;
+  try {
+    [activities, profiles] = await Promise.all([loadActivities(), loadProfiles()]);
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+
+  // Ctrl-C aborts in-flight activities (kills their child processes) instead of
+  // orphaning them. The handler is removed in `finally` so it never leaks.
+  const controller = new AbortController();
+  const onSigint = () => {
+    console.error(formatWarning({ message: "interrupted — stopping Op" }));
+    controller.abort();
+  };
+  process.once("SIGINT", onSigint);
+
+  try {
+    const result = await runOpLocally(config, activities, profiles, controller.signal);
+    if (ctx.args.json) renderJson(result); else renderHuman(result);
+    return 0;
+  } catch (err) {
+    if (err instanceof OpRunFailure) {
+      if (ctx.args.json) renderJson(err.result); else renderHuman(err.result);
+      return 1;
+    }
+    if (err instanceof LocalGateUnsupportedError) {
+      console.error(formatError({ message: err.message }));
+      return 1;
+    }
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+  }
+}
+
+async function runOpTemporal(ctx: CommandContext): Promise<number> {
   const opName = ctx.args.path;
 
   if (!opName || opName === ".") {

package/src/cli/main.test.ts

@@ -187,6 +187,8 @@ describe("resolveCommand", () => {
     { name: "init", handler: noop },
     { name: "init lexicon", handler: noop },
     { name: "dev", handler: noop },
+    { name: "lifecycle plan", handler: noop },
+    { name: "lifecycle", handler: noop },
   ];
 
   function makeArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
@@ -256,6 +258,18 @@ describe("resolveCommand", () => {
     expect(result!.compound).toBe(true);
   });
 
+  test("`lc` is an alias for `lifecycle` (compound)", () => {
+    const result = resolveCommand(makeArgs({ command: "lc", path: "plan" }), testRegistry);
+    expect(result!.def.name).toBe("lifecycle plan");
+    expect(result!.compound).toBe(true);
+  });
+
+  test("`lc` is an alias for `lifecycle` (simple)", () => {
+    const result = resolveCommand(makeArgs({ command: "lc" }), testRegistry);
+    expect(result!.def.name).toBe("lifecycle");
+    expect(result!.compound).toBe(false);
+  });
+
   test("resolves run status as compound command", () => {
     const registry: CommandDef[] = [
       { name: "run list", handler: noop },

package/src/cli/main.ts

@@ -13,7 +13,7 @@ import { runServeLsp, runServeMcp, runServeUnknown } from "./handlers/serve";
 import { runInit, runInitLexicon } from "./handlers/init";
 import { runList, runImport, runUpdate, runDoctor } from "./handlers/misc";
 import { runMigrate } from "./handlers/migrate";
-import { runStateSnapshot, runStateShow, runStateDiff, runStateLog, runStateUnknown } from "./handlers/state";
+import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecyclePlan, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runGraph } from "./handlers/graph";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
 
@@ -37,6 +37,9 @@ export function parseArgs(args: string[]): ParsedArgs {
     help: false,
     profile: undefined,
     report: undefined,
+    local: undefined,
+    temporal: undefined,
+    json: undefined,
     live: false,
     migrateFrom: undefined,
     migrateTo: undefined,
@@ -46,6 +49,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     useComposites: false,
     reportFile: undefined,
     skill: undefined,
+    src: undefined,
   };
 
   let i = 0;
@@ -85,7 +89,17 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--live") {
       result.live = true;
     } else if (arg === "--from") {
+      // Shared by `migrate --from <lexicon>` and `import --from <env>`; the
+      // two commands never run together, so one field carries both.
       result.migrateFrom = args[++i];
+    } else if (arg === "--type") {
+      result.selectType = args[++i];
+    } else if (arg === "--name") {
+      result.selectName = args[++i];
+    } else if (arg === "--owned") {
+      result.owned = true;
+    } else if (arg === "--verbatim") {
+      result.verbatim = true;
     } else if (arg === "--to") {
       result.migrateTo = args[++i];
     } else if (arg === "--emit") {
@@ -98,6 +112,14 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.useComposites = true;
     } else if (arg === "--skill") {
       result.skill = args[++i];
+    } else if (arg === "--src") {
+      result.src = args[++i];
+    } else if (arg === "--local") {
+      result.local = true;
+    } else if (arg === "--temporal") {
+      result.temporal = true;
+    } else if (arg === "--json") {
+      result.json = true;
     } else if (!arg.startsWith("-")) {
       if (!result.command) {
         result.command = arg;
@@ -146,12 +168,14 @@ Ops:
 
   graph                 Show Op dependency graph
 
-State:
-  state snapshot <env>  Query API, save metadata to orphan branch
-  state show <env>      Show latest state snapshot
-  state diff <env>      Compare current build against last snapshot
-                        --live: query cloud now and detect drift
-  state log [env]       History of state snapshots
+Lifecycle (alias: lc):
+  lifecycle snapshot <env>  Query API, save metadata to orphan branch
+  lifecycle show <env>      Show latest lifecycle snapshot
+  lifecycle diff <env>      Compare current build against last snapshot
+                            --live: query cloud now and detect drift
+  lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
+                            --json: emit the ChangeSet as JSON
+  lifecycle log [env]       History of lifecycle snapshots
 
 Lexicon development:
   dev generate          Generate lexicon artifacts (+ validate + coverage)
@@ -182,6 +206,9 @@ Options:
   -v, --verbose         Show stack traces on errors
   -h, --help            Show this help message
   -p, --profile <name>  Temporal worker profile to use (run command)
+  --local               Run an Op with the local in-process executor (default)
+  --temporal            Run an Op via a Temporal cluster (gates, schedules, durable resume)
+  --json                Emit the structured run result as JSON (run command)
   --report              Print deployment report instead of running (run command)
                         OR with a path arg: SARIF report destination (migrate)
   --from <name>         Source lexicon for migrate (default: github)
@@ -197,6 +224,7 @@ Examples:
   chant build ./infra/ --format yaml
   chant build ./infra/ --watch
   chant import template.json --output ./infra/
+  chant import --from prod --name my-bucket --output src/
   chant lint ./infra/
   chant lint ./infra/ --format sarif
   chant lint ./infra/ --watch
@@ -261,17 +289,18 @@ const registry: CommandDef[] = [
   { name: "graph", handler: runGraph },
 
   // State subcommands
-  { name: "state snapshot", requiresPlugins: true, handler: runStateSnapshot },
-  { name: "state show", handler: runStateShow },
-  { name: "state diff", requiresPlugins: true, handler: runStateDiff },
-  { name: "state log", handler: runStateLog },
+  { name: "lifecycle snapshot", requiresPlugins: true, handler: runLifecycleSnapshot },
+  { name: "lifecycle show", handler: runLifecycleShow },
+  { name: "lifecycle diff", requiresPlugins: true, handler: runLifecycleDiff },
+  { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
+  { name: "lifecycle log", handler: runLifecycleLog },
 
   // Serve subcommands
   { name: "serve lsp", requiresPlugins: true, handler: runServeLsp },
   { name: "serve mcp", requiresPlugins: true, handler: runServeMcp },
 
   // Fallback for unknown subcommands (must come after compound entries)
-  { name: "state", handler: runStateUnknown },
+  { name: "lifecycle", handler: runLifecycleUnknown },
   { name: "dev", handler: runDevUnknown },
   { name: "serve", handler: runServeUnknown },
 ];
@@ -306,9 +335,14 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
-  // For compound commands (e.g. "run list"), args.path is the subcommand,
-  // so always use "." as the project path. For simple commands, use args.path.
-  const projectPath = match.compound ? (args.extraPositional || ".") : args.path;
+  // For compound commands (e.g. "run list", "lifecycle plan <env>"), the first
+  // positional is a subcommand argument — an environment, op, or lexicon name —
+  // not a project path. Plugins always load from the cwd; the handler reads its
+  // own positionals from args.extraPositional. Using extraPositional as the path
+  // here pointed plugin resolution at e.g. "./local" for `lifecycle plan local`,
+  // which then fell through to import-detection on an empty file set and failed
+  // with "No lexicon detected" even though chant.config.ts lists the lexicons.
+  const projectPath = match.compound ? "." : args.path;
   const plugins = match.def.requiresPlugins
     ? await loadPluginsOrExit(projectPath)
     : [];

package/src/cli/mcp/{state-tools.ts → lifecycle-tools.ts}

@@ -1,23 +1,23 @@
 import { resolve } from "node:path";
 import type { LexiconPlugin } from "../../lexicon";
 import type { ToolDefinition, ToolHandler } from "./types";
-import { readSnapshot } from "../../state/git";
+import { readSnapshot } from "../../lifecycle/git";
 import { build } from "../../build";
-import { computeBuildDigest, diffDigests } from "../../state/digest";
-import { takeSnapshot } from "../../state/snapshot";
-import type { StateSnapshot } from "../../state/types";
+import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
+import { takeSnapshot } from "../../lifecycle/snapshot";
+import type { LifecycleSnapshot } from "../../lifecycle/types";
 export interface ToolRegistration {
   definition: ToolDefinition;
   handler: ToolHandler;
 }
 
 /**
- * Create state-snapshot tool definition and handler
+ * Create lifecycle-snapshot tool definition and handler
  */
 export function createSnapshotTool(plugins: LexiconPlugin[]): ToolRegistration {
   return {
     definition: {
-      name: "state-snapshot",
+      name: "lifecycle-snapshot",
       description: "Capture deployed state for an environment",
       inputSchema: {
         type: "object",
@@ -46,12 +46,12 @@ export function createSnapshotTool(plugins: LexiconPlugin[]): ToolRegistration {
 }
 
 /**
- * Create state-diff tool definition and handler
+ * Create lifecycle-diff tool definition and handler
  */
 export function createDiffTool(plugins: LexiconPlugin[]): ToolRegistration {
   return {
     definition: {
-      name: "state-diff",
+      name: "lifecycle-diff",
       description: "Compare current build declarations against last snapshot's digest",
       inputSchema: {
         type: "object",
@@ -75,7 +75,7 @@ export function createDiffTool(plugins: LexiconPlugin[]): ToolRegistration {
         const content = await readSnapshot(env, lex);
         let previousDigest = undefined;
         if (content) {
-          const snapshot: StateSnapshot = JSON.parse(content);
+          const snapshot: LifecycleSnapshot = JSON.parse(content);
           previousDigest = snapshot.digest;
         }
         results[lex] = diffDigests(currentDigest, previousDigest);

package/src/cli/mcp/op-tools.ts

@@ -3,7 +3,7 @@ import { discoverOps } from "../../op/discover";
 import { makeTemporalClient } from "../handlers/run";
 import { resolveWorkflowId } from "../handlers/run-client";
 import { generateReport } from "../handlers/run-report";
-import type { ToolRegistration } from "./state-tools";
+import type { ToolRegistration } from "./lifecycle-tools";
 
 function workflowFnName(opName: string): string {
   return opName.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase()) + "Workflow";
@@ -63,7 +63,7 @@ export function createOpRunTool(): ToolRegistration {
     definition: {
       name: "op-run",
       description:
-        "Submit an Op workflow to Temporal. The worker must already be running — start it first with `chant run <name>`.",
+        "Submit an Op workflow to Temporal (Temporal mode). A Temporal worker must already be running — start it with `chant run <name> --temporal`.",
       inputSchema: {
         type: "object",
         properties: {

package/src/cli/mcp/resource-handlers.ts

@@ -1,7 +1,7 @@
 import { resolve } from "node:path";
 import type { ResourceDefinition } from "./types";
 import { getContext } from "./resources/context";
-import { readSnapshot, readEnvironmentSnapshots } from "../../state/git";
+import { readSnapshot, readEnvironmentSnapshots } from "../../lifecycle/git";
 import { discoverOps } from "../../op/discover";
 import { makeTemporalClient } from "../handlers/run";
 import { resolveWorkflowId } from "../handlers/run-client";

package/src/cli/mcp/server.test.ts

@@ -1133,9 +1133,9 @@ describe("McpServer", () => {
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
       expect(tools).toHaveLength(13);
       expect(tools.map((t) => t.name).sort()).toEqual([
-        "build", "explain", "import", "lint",
+        "build", "explain", "import", "lifecycle-diff", "lifecycle-snapshot", "lint",
         "op-list", "op-report", "op-run", "op-signal", "op-status",
-        "scaffold", "search", "state-diff", "state-snapshot",
+        "scaffold", "search",
       ]);
 
       const resourcesRes = await s.handleRequest({ jsonrpc: "2.0", id: 3, method: "resources/list" });

package/src/cli/mcp/server.ts

@@ -8,7 +8,7 @@ import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
 import { searchTool, createSearchHandler } from "./tools/search";
 import type { LexiconPlugin } from "../../lexicon";
 import type { McpRequest, McpResponse, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
-import { createSnapshotTool, createDiffTool } from "./state-tools";
+import { createSnapshotTool, createDiffTool } from "./lifecycle-tools";
 import { createOpListTool, createOpRunTool, createOpStatusTool, createOpSignalTool, createOpReportTool } from "./op-tools";
 import { buildResourcesList, handleResourcesRead } from "./resource-handlers";
 

package/src/cli/registry.ts

@@ -20,6 +20,12 @@ export interface ParsedArgs {
   help: boolean;
   profile?: string;
   report?: boolean;
+  /** `chant run` — force the local in-process executor (the default). */
+  local?: boolean;
+  /** `chant run` — run via a Temporal cluster instead of the local executor. */
+  temporal?: boolean;
+  /** `chant run` — emit the structured OpRunResult as JSON on stdout. */
+  json?: boolean;
   live: boolean;
   /** `chant migrate --from <name>` (default "github") */
   migrateFrom?: string;
@@ -37,6 +43,16 @@ export interface ParsedArgs {
   reportFile?: string;
   /** `chant init --skill <name>` filter (added in #95 commit) */
   skill?: string;
+  /** `chant import --type <ResourceType>` selector */
+  selectType?: string;
+  /** `chant import --name <name>` selector */
+  selectName?: string;
+  /** `chant import --owned` — restrict live import to chant-owned resources */
+  owned?: boolean;
+  /** `chant import --verbatim` — keep server-defaulted fields in live import */
+  verbatim?: boolean;
+  /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands */
+  src?: string;
 }
 
 /**
@@ -75,16 +91,21 @@ export interface ResolvedCommand {
  * Supports compound commands like "dev generate" where args.command="dev"
  * and args.path="generate". Falls back to simple command matching.
  */
+/** Short command aliases. `chant lc …` is sugar for `chant lifecycle …`. */
+const COMMAND_ALIASES: Record<string, string> = { lc: "lifecycle" };
+
 export function resolveCommand(args: ParsedArgs, registry: CommandDef[]): ResolvedCommand | null {
+  const command = COMMAND_ALIASES[args.command] ?? args.command;
+
   // Try compound command first: "dev generate", "serve lsp", "init lexicon"
-  const compound = `${args.command} ${args.path}`;
+  const compound = `${command} ${args.path}`;
   const compoundMatch = registry.find((c) => c.name === compound);
   if (compoundMatch) {
     return { def: compoundMatch, compound: true };
   }
 
   // Try simple command
-  const simpleMatch = registry.find((c) => c.name === args.command);
+  const simpleMatch = registry.find((c) => c.name === command);
   if (simpleMatch) {
     return { def: simpleMatch, compound: false };
   }

package/src/codegen/fetch.test.ts

@@ -1,5 +1,5 @@
-import { describe, test, expect } from "vitest";
-import { extractFromTar } from "./fetch";
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { extractFromTar, fetchWithRetry } from "./fetch";
 
 /**
  * Build a minimal valid tar buffer with a single file entry.
@@ -117,3 +117,104 @@ describe("extractFromTar", () => {
     expect(files.get("multi.txt")!.toString()).toBe(content);
   });
 });
+
+describe("fetchWithRetry", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const ok = () => new Response("payload", { status: 200 });
+  const status = (code: number) => new Response("", { status: code });
+
+  test("returns immediately on a successful response", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(ok());
+    vi.stubGlobal("fetch", fetchMock);
+
+    const resp = await fetchWithRetry("https://example.test/x", 4, 1);
+    expect(resp.ok).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("retries a transient status then succeeds", async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(status(504))
+      .mockResolvedValueOnce(status(503))
+      .mockResolvedValueOnce(ok());
+    vi.stubGlobal("fetch", fetchMock);
+
+    const resp = await fetchWithRetry("https://example.test/x", 4, 1);
+    expect(resp.ok).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+
+  test("retries a network error then succeeds", async () => {
+    const fetchMock = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("ECONNRESET"))
+      .mockResolvedValueOnce(ok());
+    vi.stubGlobal("fetch", fetchMock);
+
+    const resp = await fetchWithRetry("https://example.test/x", 4, 1);
+    expect(resp.ok).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  test("does not retry a permanent status", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(status(404));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(fetchWithRetry("https://example.test/x", 4, 1)).rejects.toThrow("returned 404");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("throws after exhausting retries on a transient status", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(status(504));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(fetchWithRetry("https://example.test/x", 2, 1)).rejects.toThrow("returned 504");
+    // initial attempt + 2 retries
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+
+  test("calls fetch with no init argument when none is given", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(ok());
+    vi.stubGlobal("fetch", fetchMock);
+
+    await fetchWithRetry("https://example.test/x", 4, 1);
+    expect(fetchMock).toHaveBeenCalledWith("https://example.test/x");
+  });
+
+  test("passes request init through to fetch", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(ok());
+    vi.stubGlobal("fetch", fetchMock);
+
+    const init = { headers: { Accept: "application/vnd.github+json" } };
+    await fetchWithRetry("https://example.test/x", 4, 1, init);
+    expect(fetchMock).toHaveBeenCalledWith("https://example.test/x", init);
+  });
+
+  test("preserves init across retries on a transient status", async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(status(503))
+      .mockResolvedValueOnce(ok());
+    vi.stubGlobal("fetch", fetchMock);
+
+    const init = { headers: { Accept: "application/vnd.github+json" } };
+    const resp = await fetchWithRetry("https://example.test/x", 4, 1, init);
+    expect(resp.ok).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock).toHaveBeenNthCalledWith(1, "https://example.test/x", init);
+    expect(fetchMock).toHaveBeenNthCalledWith(2, "https://example.test/x", init);
+  });
+
+  test("does not retry a permanent status when init is given", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(status(403));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const init = { headers: { Accept: "application/vnd.github+json" } };
+    await expect(fetchWithRetry("https://example.test/x", 4, 1, init)).rejects.toThrow("returned 403");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});