@pithy-sh/cli 0.1.0

package/src/rootFlags.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The root flags `bin.ts` answers before citty ever parses. Kept here, dependency-free, so the rule is a
+ * pure function with its own tests — `bin.ts` is an entry script with top-level side effects and cannot
+ * be imported.
+ */
+
+/** Everything after this separator is payload for a child process, never a Pithy flag. */
+const PASSTHROUGH = "--";
+
+const VERSION_FLAGS = new Set(["--version", "-v"]);
+const HELP_FLAGS = new Set(["--help", "-h"]);
+
+/**
+ * Every spelling this module answers to, for anything that has to enumerate the CLI's flags.
+ *
+ * Exported so `docs/catalog.ts` composes the docs catalog's `globalFlags` from the sets that decide,
+ * rather than restating them. These four are in no command's `args` — citty answers one builtin and
+ * this module answers the other, both before a command is dispatched — so a walk of the command tree
+ * finds neither, and a check reading only that walk would call `pithy add --help` a typo.
+ */
+export const ROOT_FLAGS: readonly string[] = [...HELP_FLAGS, ...VERSION_FLAGS];
+
+/**
+ * Whether this invocation is asking for the version, on any command.
+ *
+ * citty ships a version builtin but answers it only when it is the **sole** argument
+ * (`rawArgs.length === 1`), so `pithy add --version` runs `add` instead — it prints `add`'s "name a
+ * capability" error and exits 1. docs/CLI.md §1.2 promises the flag works anywhere `--help` does, so the
+ * bin answers it itself.
+ *
+ * **The rule is "anywhere before `--`", matching how citty already resolves `--help`.** The alternative —
+ * root-level only, before the subcommand — cannot satisfy §1.2, since the flag's whole point is that it
+ * follows a command. What keeps that from swallowing real input is that a caller always has two escapes,
+ * and both are honored here: `--` for opaque payload, and the `--flag=--version` form for a value that is
+ * literally the string. Only a bare, exactly-matching token counts, so `--set version=2`, `--versions`,
+ * and a positional named `version` all pass through untouched.
+ *
+ * Help wins when both appear, because citty checks help first and this must not change that ordering.
+ */
+export function wantsVersion(argv: string[]): boolean {
+  const separator = argv.indexOf(PASSTHROUGH);
+  const flags = separator === -1 ? argv : argv.slice(0, separator);
+  if (flags.some((arg) => HELP_FLAGS.has(arg))) return false;
+  return flags.some((arg) => VERSION_FLAGS.has(arg));
+}

package/src/seed/drivers.ts

@@ -0,0 +1,423 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { D1Database, KVNamespace, R2Bucket } from "@cloudflare/workers-types";
+import { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import type { CloudflareKVManager } from "@pithy-sh/cloudflare/src/kv/kvManager";
+import type { CloudflareImageManager } from "@pithy-sh/cloudflare/src/media/imageManager";
+import type { CloudflareStreamManager } from "@pithy-sh/cloudflare/src/media/streamManager";
+import { R2Credentials } from "@pithy-sh/cloudflare/src/r2/r2Credentials";
+import type { CloudflareR2Manager } from "@pithy-sh/cloudflare/src/r2/r2Manager";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { parse } from "comment-json";
+import { Miniflare } from "miniflare";
+import { type CloudflareAccountSelection, cloudflareCredentials, cloudflareEnv } from "../cloudflare/config";
+import { wranglerConfigPath } from "../provision/featureConfig";
+
+/**
+ * The seed driver resolves each backend a seed set touches to a live handle — the only thing that
+ * differs between a local (`dev`) run and a live (`staging`/`prod`) one, exactly as the migration
+ * driver does for D1. `dev` resolves D1, KV, and R2 from the same Miniflare stores `wrangler dev` uses
+ * under `.wrangler/state`; other environments resolve them from `@pithy-sh/cloudflare` REST managers,
+ * with ids read from the target env's `wrangler.jsonc` block and credentials from `cloudflareEnv`.
+ *
+ * Images and Stream have no local emulation, so they are **always** remote: the driver builds them from
+ * credentials regardless of `--env`, and only when a set actually has media (the clients are lazy, so a
+ * `dev` run with no media never needs credentials).
+ *
+ * Every remote handle is built through an injectable factory seam (mirroring migrate's `remoteD1`), so
+ * tests substitute in-memory or faked managers for the network clients.
+ */
+
+/** Test seam: build the remote D1 for a binding instead of the default REST-backed client. */
+export type RemoteD1Factory = (args: { binding: string; databaseId: string }) => D1Database;
+
+/** Test seam: build the remote KV manager for a binding instead of the default REST-backed client. */
+export type RemoteKvFactory = (args: { binding: string; namespaceId: string }) => CloudflareKVManager;
+
+/** Test seam: build the remote R2 manager for a binding instead of the default REST-backed client. */
+export type RemoteR2Factory = (args: { binding: string; bucketName: string }) => CloudflareR2Manager;
+
+/** Test seam: build the (always-remote) Images manager instead of the default account client. */
+export type ImagesFactory = () => CloudflareImageManager;
+
+/** Test seam: build the (always-remote) Stream manager instead of the default account client. */
+export type StreamFactory = () => CloudflareStreamManager;
+
+/**
+ * A resolved KV target. Local runs get a live Miniflare {@link KVNamespace} (wrap it in `TypedKv`);
+ * remote runs get the REST {@link CloudflareKVManager}, whose surface differs from a binding — the
+ * caller writes through it directly. The `kind` tag lets the writer branch without a type assertion.
+ */
+export type KvSeedTarget =
+  | { readonly kind: "local"; readonly namespace: KVNamespace }
+  | { readonly kind: "remote"; readonly manager: CloudflareKVManager };
+
+/**
+ * A resolved R2 target. Local runs get a live Miniflare {@link R2Bucket}; remote runs get the REST
+ * {@link CloudflareR2Manager} (S3-signed uploads). The `kind` tag lets the writer branch without a cast.
+ */
+export type R2SeedTarget =
+  | { readonly kind: "local"; readonly bucket: R2Bucket }
+  | { readonly kind: "remote"; readonly manager: CloudflareR2Manager };
+
+/** A resolved set of backends to seed — the only thing that differs between local and remote — plus teardown. */
+export interface SeedDriver {
+  /** The D1 for a binding (Kysely-wrappable). Local Miniflare store, or the remote REST-backed database. */
+  d1(binding: string): D1Database;
+  /** The KV target for a binding — a local namespace or the remote manager. */
+  kv(binding: string): KvSeedTarget;
+  /** The R2 target for a binding — a local bucket or the remote manager. */
+  r2(binding: string): R2SeedTarget;
+  /** The always-remote Images manager. Built from credentials on first use. */
+  images(): CloudflareImageManager;
+  /** The always-remote Stream manager. Built from credentials on first use. */
+  stream(): CloudflareStreamManager;
+  /** Release the driver's resources (the Miniflare instance locally; a no-op remotely). */
+  dispose(): Promise<void>;
+}
+
+/** Options for {@link openSeedDriver}. */
+export interface SeedDriverOptions {
+  /**
+   * The Worker's directory — its `wrangler.jsonc` supplies the D1/KV/R2 bindings and their ids. Bindings
+   * are per-Worker because a Worker's resources are declared on the Worker that uses them.
+   */
+  workerDir: string;
+  /**
+   * The project root — the owner of the `.wrangler/state` stores `wrangler dev` uses, and of the one
+   * repo-wide `.dev.vars` the remote clients read their credentials from. Persistence is deliberately
+   * project-scoped, not Worker-scoped: two Workers that declare the same binding share one local store,
+   * which a per-Worker persistence directory would silently split in two.
+   */
+  persistRoot: string;
+  /** Target environment. `dev` resolves locally via Miniflare; other environments resolve over REST. */
+  env: string;
+  /**
+   * The Cloudflare account this project belongs to. A remote seed writes rows into a real D1 and objects
+   * into a real R2; the wrong account's credentials write this project's fixtures into another company's
+   * tenant (#206). Required (#234) — of the six declarations #226 measured, this is the one with the
+   * most to lose, and both of its non-test callers (`seed/run.ts`, `dashboard/registry.ts`) omitted it.
+   */
+  account: CloudflareAccountSelection | null;
+  /** Test seam for the remote D1 client. */
+  remoteD1?: RemoteD1Factory;
+  /** Test seam for the remote KV client. */
+  remoteKv?: RemoteKvFactory;
+  /** Test seam for the remote R2 client. */
+  remoteR2?: RemoteR2Factory;
+  /** Test seam for the (always-remote) Images client. */
+  images?: ImagesFactory;
+  /** Test seam for the (always-remote) Stream client. */
+  stream?: StreamFactory;
+}
+
+/**
+ * One D1 binding entry in wrangler.jsonc — the fields the seed driver reads to resolve a store.
+ * `database_name` is not among them: wrangler ignores it when binding a local D1 (see
+ * {@link resolveStoreIds}), so seeding must ignore it too. Leaving it off the type makes reading it a
+ * compile error.
+ */
+interface D1Binding {
+  binding: string;
+  database_id?: string;
+}
+
+/** One KV namespace binding entry in wrangler.jsonc. */
+interface KvBinding {
+  binding: string;
+  id?: string;
+}
+
+/** One R2 bucket binding entry in wrangler.jsonc. */
+interface R2Binding {
+  binding: string;
+  bucket_name?: string;
+}
+
+/** The bindings block wrangler.jsonc carries at the top level and inside each `env`. */
+interface WranglerBindings {
+  d1_databases?: D1Binding[];
+  kv_namespaces?: KvBinding[];
+  r2_buckets?: R2Binding[];
+}
+
+/** The wrangler.jsonc slice the seed driver reads: the local (top-level) bindings and each env's bindings. */
+interface WranglerSeedConfig extends WranglerBindings {
+  env?: Record<string, WranglerBindings | undefined>;
+}
+
+/**
+ * Read and parse the config that describes this Worker in this environment. A missing file yields an
+ * empty config.
+ *
+ * Through {@link wranglerConfigPath}: a feature environment's ids live in the generated config under
+ * `.wrangler/`, never in the tracked `wrangler.jsonc` (#242), so the path is a function of the
+ * environment rather than a constant.
+ */
+async function readWranglerConfig(workerDir: string, env: string): Promise<WranglerSeedConfig> {
+  try {
+    const raw = await readFile(wranglerConfigPath(workerDir, env), "utf8");
+    return parse(raw) as unknown as WranglerSeedConfig;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * One Worker's backends, by binding, as the **identity of the store each binding resolves to** for an
+ * environment — the same fallback chain the drivers themselves use (locally the id else the binding;
+ * remotely the target env stanza's id). It resolves ids only: no Miniflare instance, no REST client, no
+ * credentials.
+ *
+ * The fan-out needs this before it opens anything. Workers share a resource by declaring the same
+ * binding, so the same fixture composed into two Workers normally writes to one store and must run once —
+ * but "same binding" is not "same store": two Workers can point one binding at two different databases,
+ * a wiring `pithy migrate` supports and migrates separately. Deduping a seed set on its key alone would
+ * then skip the second store and report it as already seeded. A binding with no id resolves to its own
+ * name, which is exactly what the local driver persists under; remotely the driver raises the real
+ * missing-id error at write time.
+ */
+export interface ResolvedStoreIds {
+  /** D1 binding → resolved database identity. */
+  d1: Map<string, string>;
+  /** KV binding → resolved namespace identity. */
+  kv: Map<string, string>;
+  /** R2 binding → resolved bucket identity. */
+  r2: Map<string, string>;
+}
+
+/** Read one Worker's `wrangler.jsonc` and resolve every D1/KV/R2 binding's store identity for `env`. */
+export async function resolveStoreIds(options: { workerDir: string; env: string }): Promise<ResolvedStoreIds> {
+  const config = await readWranglerConfig(options.workerDir, options.env);
+  const bindings: WranglerBindings = options.env === "dev" ? config : (config.env?.[options.env] ?? {});
+
+  const ids: ResolvedStoreIds = { d1: new Map(), kv: new Map(), r2: new Map() };
+  for (const entry of bindings.d1_databases ?? []) {
+    // Locally a store persists under `database_id` else the binding, because that is what wrangler binds:
+    // `d1DatabaseEntry({ binding, database_id, preview_database_id })` computes
+    // `getRemoteId(preview_database_id ?? database_id) ?? binding` and never destructures `database_name`.
+    // `pithy add` writes `database_name` with no id, so folding the name in here would key a store the
+    // Worker never opens — seeded rows would vanish and migrate/seed would disagree. Remotely only a real
+    // `database_id` counts.
+    ids.d1.set(entry.binding, entry.database_id ?? entry.binding);
+  }
+  for (const entry of bindings.kv_namespaces ?? []) ids.kv.set(entry.binding, entry.id ?? entry.binding);
+  for (const entry of bindings.r2_buckets ?? []) ids.r2.set(entry.binding, entry.bucket_name ?? entry.binding);
+  return ids;
+}
+
+/** Return the cached handle for `binding`, or an actionable error naming the missing wrangler binding. */
+function resolveLocal<T>(cache: Map<string, T>, binding: string, kind: string): T {
+  const handle = cache.get(binding);
+  if (!handle) {
+    throw new ValidationError({
+      message: `wrangler.jsonc declares no ${kind} binding "${binding}".`,
+      action: `Add the "${binding}" ${kind} binding to wrangler.jsonc. Run pithy seed again.`,
+    });
+  }
+  return handle;
+}
+
+/**
+ * The local driver: the same D1/KV/R2 stores `wrangler dev` uses, under `.wrangler/state`, via
+ * Miniflare. Every top-level binding is resolved up front so the driver's accessors stay synchronous
+ * (Miniflare's `get*` are async). Images/Stream are still remote — resolved lazily by `assets`.
+ */
+async function openLocalDriver(options: SeedDriverOptions, assets: RemoteAssets): Promise<SeedDriver> {
+  const config = await readWranglerConfig(options.workerDir, options.env);
+  const d1Ids: Record<string, string> = {};
+  // `database_id` else the binding — wrangler's own local chain; see {@link resolveStoreIds} for why
+  // `database_name` must never join it.
+  for (const entry of config.d1_databases ?? []) d1Ids[entry.binding] = entry.database_id ?? entry.binding;
+  const kvIds: Record<string, string> = {};
+  for (const entry of config.kv_namespaces ?? []) kvIds[entry.binding] = entry.id ?? entry.binding;
+  const r2Ids: Record<string, string> = {};
+  for (const entry of config.r2_buckets ?? []) r2Ids[entry.binding] = entry.bucket_name ?? entry.binding;
+
+  const state = join(options.persistRoot, ".wrangler", "state", "v3");
+  const miniflare = new Miniflare({
+    modules: true,
+    script: "export default {};",
+    d1Databases: d1Ids,
+    kvNamespaces: kvIds,
+    r2Buckets: r2Ids,
+    d1Persist: join(state, "d1"),
+    kvPersist: join(state, "kv"),
+    r2Persist: join(state, "r2"),
+  });
+
+  const d1Cache = new Map<string, D1Database>();
+  for (const binding of Object.keys(d1Ids)) {
+    d1Cache.set(binding, (await miniflare.getD1Database(binding)) as unknown as D1Database);
+  }
+  const kvCache = new Map<string, KVNamespace>();
+  for (const binding of Object.keys(kvIds)) {
+    kvCache.set(binding, (await miniflare.getKVNamespace(binding)) as unknown as KVNamespace);
+  }
+  const r2Cache = new Map<string, R2Bucket>();
+  for (const binding of Object.keys(r2Ids)) {
+    r2Cache.set(binding, (await miniflare.getR2Bucket(binding)) as unknown as R2Bucket);
+  }
+
+  return {
+    d1: (binding) => resolveLocal(d1Cache, binding, "D1"),
+    kv: (binding) => ({ kind: "local", namespace: resolveLocal(kvCache, binding, "KV") }),
+    r2: (binding) => ({ kind: "local", bucket: resolveLocal(r2Cache, binding, "R2") }),
+    images: assets.images,
+    stream: assets.stream,
+    dispose: () => miniflare.dispose(),
+  };
+}
+
+/** Find one binding's id in a wrangler bindings block, or an actionable error naming the env and binding. */
+function remoteId(
+  entries: { binding: string }[] | undefined,
+  binding: string,
+  read: (entry: { binding: string }) => string | undefined,
+  env: string,
+  kind: string,
+  idField: string,
+): string {
+  const entry = entries?.find((candidate) => candidate.binding === binding);
+  const value = entry ? read(entry) : undefined;
+  if (!value) {
+    throw new ValidationError({
+      message: `wrangler.jsonc env.${env} has no ${idField} for the "${binding}" ${kind} binding.`,
+      action: `Provision the ${env} ${kind} and set its ${idField} on ${binding}. Run pithy seed --env ${env} again.`,
+    });
+  }
+  return value;
+}
+
+/**
+ * The remote driver: each backend resolved over REST through `@pithy-sh/cloudflare`. Ids come from the
+ * target env's `wrangler.jsonc` block; the REST clients are the only thing that differs from local.
+ * Every handle is built through a factory seam (the default wraps the shared, credential-lazy clients),
+ * so tests substitute in-memory managers without touching the network or credentials.
+ */
+function openRemoteDriver(options: SeedDriverOptions, clients: LazyClients, assets: RemoteAssets): SeedDriver {
+  const config = clients.config;
+  const stanza = (): WranglerBindings => config.env?.[options.env] ?? {};
+
+  const d1: RemoteD1Factory =
+    options.remoteD1 ?? (({ databaseId }) => clients.get().d1(databaseId) as unknown as D1Database);
+  const kv: RemoteKvFactory = options.remoteKv ?? (({ namespaceId }) => clients.get().kv(namespaceId));
+  const r2: RemoteR2Factory =
+    options.remoteR2 ?? (({ bucketName }) => clients.get().r2({ bucketName, ...clients.r2Credentials() }));
+
+  return {
+    d1: (binding) => {
+      const databaseId = remoteId(
+        stanza().d1_databases,
+        binding,
+        (e) => (e as D1Binding).database_id,
+        options.env,
+        "D1",
+        "database_id",
+      );
+      return d1({ binding, databaseId });
+    },
+    kv: (binding) => {
+      const namespaceId = remoteId(
+        stanza().kv_namespaces,
+        binding,
+        (e) => (e as KvBinding).id,
+        options.env,
+        "KV",
+        "id",
+      );
+      return { kind: "remote", manager: kv({ binding, namespaceId }) };
+    },
+    r2: (binding) => {
+      const bucketName = remoteId(
+        stanza().r2_buckets,
+        binding,
+        (e) => (e as R2Binding).bucket_name,
+        options.env,
+        "R2",
+        "bucket_name",
+      );
+      return { kind: "remote", manager: r2({ binding, bucketName }) };
+    },
+    images: assets.images,
+    stream: assets.stream,
+    dispose: async () => {},
+  };
+}
+
+/** A lazily-built, credential-checked {@link CloudflareClients} plus the parsed wrangler config it shares. */
+interface LazyClients {
+  /** The parsed wrangler.jsonc (read once). */
+  config: WranglerSeedConfig;
+  /** Build (or return the memoized) clients, failing with an actionable error if credentials are missing. */
+  get(): CloudflareClients;
+  /** Parse the R2 S3 credential pair from the environment, failing clearly if absent or malformed. */
+  r2Credentials(): R2Credentials;
+}
+
+/** Build the credential-lazy clients accessor shared by the remote resources and the always-remote assets. */
+function lazyClients(config: WranglerSeedConfig, account: CloudflareAccountSelection | null): LazyClients {
+  let clients: CloudflareClients | undefined;
+  let vars: Record<string, string> | undefined;
+  const env = (): Record<string, string> => {
+    vars ??= cloudflareEnv({ account });
+    return vars;
+  };
+  return {
+    config,
+    get() {
+      if (clients) return clients;
+      // Both refusals — the account mismatch and the empty pair — belong to `cloudflareCredentials`, so
+      // this driver and anything that settles the account ahead of a fan-out say them the same way (#236).
+      clients = new CloudflareClients(cloudflareCredentials({ account }));
+      return clients;
+    },
+    r2Credentials() {
+      const raw = env().R2_CREDENTIALS;
+      if (!raw) {
+        throw new ValidationError({
+          message: "R2 credentials are missing.",
+          action: "Set R2_CREDENTIALS (the S3 access-key/secret-key pair) to seed R2 objects.",
+        });
+      }
+      try {
+        return R2Credentials.parse(JSON.parse(raw));
+      } catch {
+        throw new ValidationError({
+          message: "R2_CREDENTIALS is not a valid access-key/secret-key pair.",
+          action: "Set R2_CREDENTIALS to a JSON object with accessKeyId and secretAccessKey.",
+        });
+      }
+    },
+  };
+}
+
+/** The always-remote asset accessors — Images and Stream, built from credentials (or a test seam). */
+interface RemoteAssets {
+  images: () => CloudflareImageManager;
+  stream: () => CloudflareStreamManager;
+}
+
+/** Build the always-remote Images/Stream accessors: a test seam if given, else the credential-lazy client. */
+function remoteAssets(options: SeedDriverOptions, clients: LazyClients): RemoteAssets {
+  return {
+    images: options.images ?? (() => clients.get().images()),
+    stream: options.stream ?? (() => clients.get().stream()),
+  };
+}
+
+/**
+ * Open the seed driver for a project and environment — the backend-resolution seam behind `pithy seed`.
+ * `dev` resolves D1/KV/R2 from local Miniflare stores; other environments resolve them over the REST
+ * managers keyed by the env's `wrangler.jsonc` ids. Images and Stream are always remote, built lazily
+ * from credentials so a local run with no media never needs them.
+ */
+export async function openSeedDriver(options: SeedDriverOptions): Promise<SeedDriver> {
+  const config = await readWranglerConfig(options.workerDir, options.env);
+  const clients = lazyClients(config, options.account);
+  const assets = remoteAssets(options, clients);
+  return options.env === "dev" ? openLocalDriver(options, assets) : openRemoteDriver(options, clients, assets);
+}

package/src/seed/media.ts

@@ -0,0 +1,187 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { ConflictError, InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { buildAssetMetadata } from "@pithy-sh/core/src/seed/metadata";
+import type { MediaSeedItem } from "@pithy-sh/core/src/seed/seed";
+import { z } from "zod";
+import { writeFileAtomic } from "../project/atomic";
+import { readOptionalFile } from "../project/readOptionalFile";
+
+/**
+ * The filesystem side of media seeding — the only part of `pithy seed` that reads fixture bytes and
+ * writes a minted UUID back. Core defines the {@link MediaSeedItem} type; this module reads the item's
+ * bytes and its `ref` sidecar, uploads through an injected {@link MediaUploader}, and (for a `once`
+ * asset) records the minted id atomically so later runs skip the upload.
+ *
+ * Both the filesystem and the uploader are injectable seams so the orchestrator's tests drive the
+ * once/always/idempotent logic against a temp sidecar and a fake minter, with no live account.
+ */
+
+/** The `ref` sidecar's shape: the minted asset UUID, recorded after a `once` upload. */
+const MediaRef = z
+  .object({
+    /** The minted Images id or Stream uid, recorded so a later run references it instead of re-uploading. */
+    id: z.string().describe("The minted asset UUID (Images id or Stream uid) recorded by the first run."),
+  })
+  .partial()
+  .describe("The JSON sidecar a `once` media seed writes to record its minted asset UUID.");
+type MediaRef = z.output<typeof MediaRef>;
+
+/**
+ * The byte uploads media seeding needs, one per shared store. Injectable so tests substitute a fake
+ * minter; the default (built by the orchestrator from the driver's managers) wraps the
+ * `@pithy-sh/cloudflare` seed helpers. Each returns the minted id to record — Stream's `uid` is
+ * normalized to `id` so the sidecar shape is one field for both stores.
+ */
+export interface MediaUploader {
+  /** Upload image bytes with the given metadata; resolve the minted Images id. */
+  images(bytes: Uint8Array, metadata: Record<string, string>): Promise<{ id: string }>;
+  /** Upload video bytes with the given metadata; resolve the minted Stream uid (as `id`). */
+  stream(bytes: Uint8Array, metadata: Record<string, string>): Promise<{ id: string }>;
+}
+
+/**
+ * The filesystem operations media seeding performs. Injectable so tests supply an in-memory fake and
+ * assert the write-back without touching disk; the default {@link nodeMediaFs} uses `node:fs`.
+ */
+export interface MediaFs {
+  /** Read a fixture's bytes. */
+  readBytes(path: string): Promise<Uint8Array>;
+  /** Read the sidecar's text, or `null` when it does not exist yet (a never-uploaded `once` asset). */
+  readText(path: string): Promise<string | null>;
+  /** Write the sidecar's text atomically, so a crash never leaves a torn file. */
+  writeTextAtomic(path: string, text: string): Promise<void>;
+}
+
+/**
+ * The default {@link MediaFs}: `node:fs`, with the sidecar written through {@link writeFileAtomic}.
+ *
+ * It used to roll its own temp-file-plus-rename — a UUID name, a plain `writeFile`, a `rename` — and so
+ * got none of what the primitive does: no exclusive create, so anything already at the temp path was
+ * written through rather than refused; no ownership check on the links it followed, so a planted symlink
+ * decided where the write landed; no mode; and no sweep of the file a killed run leaves behind. The
+ * payload here is an asset-id sidecar rather than a credential, which changes what it costs, not whether
+ * it is the same shape. One writer, one place to get it wrong.
+ */
+export const nodeMediaFs: MediaFs = {
+  readBytes: (path) => readFile(path),
+  readText: (path) =>
+    // A missing sidecar is the expected first-run state — not an error. Anything else refuses, and which
+    // errno is which is {@link readOptionalFile}'s decision rather than this module's: a sidecar that is
+    // there and will not open reading as "never uploaded" means `writeTextAtomic` renames a fresh id over
+    // the one recorded in it. It used to rethrow node's own error, which reached an adopter as a bare
+    // errno and a stack from the middle of a seed run (#203); the sentence below is what it says now.
+    readOptionalFile(path, {
+      unreadable: ({ code, cause }) =>
+        new ConflictError(
+          {
+            message: `Can't read the media sidecar ${path}.`,
+            action: "Fix the file's permissions, or move it aside, and run pithy seed again.",
+            detail: `${code ?? "unknown error"} while reading ${path}`,
+          },
+          { cause },
+        ),
+    }),
+  writeTextAtomic: (path, text) => writeFileAtomic(path, text),
+};
+
+/** What seeding one media item did this run — the same shape a dry-run plan reports per asset. */
+export interface SeedMediaResult {
+  /** The shared asset store the item targeted. */
+  store: MediaSeedItem["store"];
+  /** The item's upload policy. */
+  mode: MediaSeedItem["mode"];
+  /** What this run did: `upload` (first `once`), `skip` (recorded `once`), or `reupload` (`always`). */
+  action: "upload" | "skip" | "reupload";
+  /** The minted (or recorded) asset UUID, when there is one — absent only on a dry-run first `once`. */
+  id?: string;
+}
+
+/** Options for {@link seedMediaItem}. */
+export interface SeedMediaOptions {
+  /** The environment being seeded — stamped into the standard asset-metadata block on upload. */
+  env: string;
+  /**
+   * The directory `file`/`ref` are resolved against when they are not absolute — the set's own
+   * `baseDir` (the seed module directory), or the project root when the set declares none.
+   */
+  baseDir: string;
+  /** The byte uploader. Required for a real run; omitted for a dry-run (which never uploads). */
+  uploader?: MediaUploader;
+  /** The filesystem seam. Defaults to {@link nodeMediaFs}. */
+  fs?: MediaFs;
+  /** Plan only: resolve the action from the sidecar without reading bytes, uploading, or writing back. */
+  dryRun?: boolean;
+}
+
+/** Resolve a fixture path: absolute paths pass through, relative paths join the base directory. */
+function resolvePath(baseDir: string, path: string): string {
+  return isAbsolute(path) ? path : join(baseDir, path);
+}
+
+/** Read the recorded UUID from a sidecar, or `undefined` when none is recorded (or the file is absent). */
+async function readRecordedId(fs: MediaFs, refPath: string): Promise<string | undefined> {
+  const text = await fs.readText(refPath);
+  if (text === null || text.trim() === "") return undefined;
+  let parsed: MediaRef;
+  try {
+    parsed = MediaRef.parse(JSON.parse(text));
+  } catch {
+    throw new ValidationError({
+      message: `The media sidecar "${refPath}" is not a valid ref file.`,
+      action: 'Delete the sidecar to re-mint the asset, or restore it to a { "id": "…" } JSON object.',
+    });
+  }
+  return parsed.id;
+}
+
+/** Upload the item's bytes through the store's uploader, or fail loudly if no uploader was provided. */
+async function upload(
+  item: MediaSeedItem,
+  bytes: Uint8Array,
+  metadata: Record<string, string>,
+  uploader?: MediaUploader,
+): Promise<string> {
+  if (!uploader) {
+    throw new InternalError({ detail: `Media upload attempted for "${item.file}" without a configured uploader.` });
+  }
+  const result =
+    item.store === "images" ? await uploader.images(bytes, metadata) : await uploader.stream(bytes, metadata);
+  return result.id;
+}
+
+/**
+ * Seed one media item into the shared Images/Stream store, idempotently.
+ *
+ * `once` (the default) uploads only the first time: if the `ref` sidecar already records a UUID the
+ * upload is skipped and the recorded id is returned; otherwise the bytes are uploaded with the
+ * standard asset-metadata block (built by the caller) and the minted UUID is written back to the
+ * sidecar **atomically**, so a later run skips it. `always` re-uploads every run, scoped by metadata,
+ * and never writes a UUID back. A `dryRun` resolves the action from the sidecar alone — it reads no
+ * bytes, uploads nothing, and writes nothing.
+ */
+export async function seedMediaItem(item: MediaSeedItem, options: SeedMediaOptions): Promise<SeedMediaResult> {
+  const fs = options.fs ?? nodeMediaFs;
+  const refPath = resolvePath(options.baseDir, item.ref);
+  const filePath = resolvePath(options.baseDir, item.file);
+
+  if (item.mode === "once") {
+    const recorded = await readRecordedId(fs, refPath);
+    if (recorded !== undefined) return { store: item.store, mode: item.mode, action: "skip", id: recorded };
+    if (options.dryRun) return { store: item.store, mode: item.mode, action: "upload" };
+
+    const metadata = buildAssetMetadata(options.env, item.metadata);
+    const id = await upload(item, await fs.readBytes(filePath), metadata, options.uploader);
+    await fs.writeTextAtomic(refPath, `${JSON.stringify({ id }, null, 2)}\n`);
+    return { store: item.store, mode: item.mode, action: "upload", id };
+  }
+
+  // `always`: re-upload every run, scoped by metadata, and never record a UUID.
+  if (options.dryRun) return { store: item.store, mode: item.mode, action: "reupload" };
+  const metadata = buildAssetMetadata(options.env, item.metadata);
+  const id = await upload(item, await fs.readBytes(filePath), metadata, options.uploader);
+  return { store: item.store, mode: item.mode, action: "reupload", id };
+}