@codepress/design-kit 0.8.0 → 0.9.0

package/README.md

@@ -191,6 +191,77 @@ start command, sign-in, a missing Storybook. It never overwrites an existing
 file without `--force` (a repository with a `design-kit.config.json` exits 1,
 "already set up") and never writes a secret.
 
+## Where the kit is stored
+
+The config's `storage` key says where the workflow puts each kit and where
+`design-kit fetch` and `ci-check` read it. Agents and CI use the same commands
+whichever you pick. Choose one at setup with
+`init --storage github|codepress|s3|r2`, or later with
+`init --workflow-only --force --storage <type>`, which sets the key and
+rewrites the workflow in the same run.
+
+| `storage`                                          | Where                         | Upload                                | Reading                               |
+| -------------------------------------------------- | ----------------------------- | ------------------------------------- | ------------------------------------- |
+| absent, or `{"type": "github"}`                    | a GitHub Actions artifact     | the workflow's `upload-artifact` step | `gh`, signed in to the repository     |
+| `{"type": "codepress"}`                            | CodePress                     | `design-kit upload`, no secret        | a CodePress API key                   |
+| `{"type": "s3", "bucket", "region"?, "prefix"?}`   | your own AWS S3 bucket        | `design-kit upload`, two secrets      | the `aws` CLI with read access        |
+| `{"type": "r2", "accountId", "bucket", "prefix"?}` | your own Cloudflare R2 bucket | `design-kit upload`, two secrets      | the `aws` CLI with an R2 token's keys |
+
+**GitHub** (the default). Nothing to set up. Each kit is a `design-kit`
+artifact, kept 90 days on a public repository (the workflow rebuilds before
+then) and read through the `gh` CLI.
+
+**CodePress.** CodePress keeps the newest kit of each branch for as long as
+the repository is connected. Connect the repository in
+[CodePress](https://codepress.dev), then add
+`"storage": {"type": "codepress"}`. No secret is needed: the build job has
+`permissions: id-token: write`, and `design-kit upload` signs in with the
+workflow's GitHub OIDC token, which proves which repository and branch it
+comes from. To read a kit, set `CODEPRESS_API_KEY` to an API key of an
+organization that connected the repository, or pass `--token-file <path>`
+(a file holding the key alone, or a `CODEPRESS_API_KEY=` line). The daily
+check reads the newest kit with the key when the repository has a
+`CODEPRESS_API_KEY` secret, and otherwise with its own OIDC token (its job
+gets `id-token: write` too); when the read fails, it builds. `url` (default
+`https://codepress.dev`) and `apiUrl` (default
+`https://api.codepress.dev/v1`) point at another CodePress. This needs
+CodePress's kit storage, which is on codepress.dev; a repository that is not
+connected is refused with `repo_not_connected`.
+
+**Your own S3 bucket.** Create the bucket and an IAM user that may read and
+write it, add `"storage": {"type": "s3", "bucket": "my-kits", "region":
+"us-east-1"}`, and add the user's keys as the `AWS_ACCESS_KEY_ID` and
+`AWS_SECRET_ACCESS_KEY` repository secrets (Settings > Secrets and variables
+
+> Actions). `endpoint` points at another S3-compatible store.
+
+**Your own Cloudflare R2 bucket.** Create the bucket, then an R2 API token
+with **Object Read & Write** on it (R2 > Manage API tokens). Add
+`"storage": {"type": "r2", "accountId": "<your account id>", "bucket":
+"my-kits"}`; the endpoint (`https://<accountId>.r2.cloudflarestorage.com`) and
+region (`auto`) follow from the account id. Add the token's keys as the
+`R2_ACCESS_KEY_ID` and `R2_SECRET_ACCESS_KEY` repository secrets; the
+workflow passes them to the `aws` CLI as `AWS_ACCESS_KEY_ID` and
+`AWS_SECRET_ACCESS_KEY`.
+
+In a bucket, each kit is `<prefix>/<branch>/<sha>.zip`, and
+`<prefix>/<branch>/latest.json` names the newest; an upload writes the zip
+first and `latest.json` last. Older zips stay until you delete them, for
+example with a lifecycle rule on the prefix. `s3` and `r2` need the `aws` CLI,
+which GitHub's Ubuntu runners have; elsewhere a missing `aws` is an error
+that says so.
+
+**GitHub Enterprise Server.** `codepress` storage works only for
+repositories on github.com: CodePress connects github.com repositories and
+accepts only github.com's OIDC tokens. On GitHub Enterprise Server, use
+`github`, `s3` or `r2`, and pass `--repo <owner/name>` where the commands
+cannot read it from `GITHUB_REPOSITORY`.
+
+**Adding `storage` by hand?** Bump the pinned version too:
+`DESIGN_KIT_PACKAGE` in the workflow and the version in the config's
+`$schema`. Versions before `storage` existed reject the key as unknown, so an
+older pin fails the run. `init --storage` does both for you.
+
 ## Configuration
 
 The commands read `design-kit.config.json` from the working directory or the
@@ -317,6 +388,11 @@ value>]` then replaces `slots`.
 
 ```bash
 design-kit init            [--root dir] [--dry-run] [--force] [--workflow-only]
+                           [--storage github|codepress|s3|r2]
+design-kit upload          --dir kit [--config f] [--branch b] [--sha commit]
+design-kit fetch           [--branch b] [--out dir] [--config f] [--repo owner/name]
+                           [--token-file f]
+design-kit latest          [--branch b] [--config f] [--repo owner/name] [--token-file f]
 design-kit capture stories [--config f] [--out dir] [--storybook-dir dir]
                            [--only id,... | --only-file f] [--base previous-kit]
 design-kit capture pages   [--config f] [--out dir] [--base-url url] [--only name,...]
@@ -330,8 +406,20 @@ design-kit setup-guide
 design-kit storybook-guide
 ```
 
-`ci-check` and `ci-cleanup` are the workflow's steps. `ci-check` finds the
-newest unexpired `design-kit` artifact on the branch (through `gh`, from
+`upload`, `fetch` and `latest` work with the configured storage (see
+[Where the kit is stored](#where-the-kit-is-stored)). `upload` sends a built
+kit (`codepress`, `s3` and `r2`; with `github` it exits 2, since the
+workflow's upload step does it). `fetch` downloads the newest kit once per
+commit, into `$TMPDIR/design-kit-<sha>` unless `--out` says otherwise, and
+prints `path=`, `sha=` and `branch=`; a second `fetch` of the same commit
+downloads nothing. `latest` prints the newest kit's `sha=` and `created=`.
+Without `--branch` they read the default branch. A store's refusal keeps its
+name (`forbidden`, `no_kit`, `repo_not_connected`, …), a store that cannot be
+reached is `kit_storage_unavailable`, and both exit 1.
+
+`ci-check` and `ci-cleanup` are the workflow's steps. `ci-check` gets the
+newest kit on the branch from the storage's `latest` (for `github`, the
+newest unexpired `design-kit` artifact through `gh`; from
 `GITHUB_REPOSITORY` and `GITHUB_REF_NAME`, or `--repo` and `--branch`), or
 takes it from `--since` and `--kit-created`. It fetches that commit (shallow,
 no file contents) and compares the git tree or blob id of each `watch` path
@@ -340,8 +428,8 @@ counts as changed. It prints `build=true` or `build=false` and the reason
 (`changed: src`, `watched files unchanged since 3f2a9c1`, `refresh before
 expiry: …`, `no kit yet on this branch`, `forced …`, `an explicit package was
 given …`) and writes them to `$GITHUB_OUTPUT` and the step summary. A kit
-that cannot be looked up or fetched builds. `ci-cleanup` deletes the
-branch's kits older than `--keep` and warns about any it could not delete;
+that cannot be looked up or fetched builds. `ci-cleanup` (`github` storage
+only) deletes the branch's kits older than `--keep` and warns about any it could not delete;
 both always exit 0 unless the config is invalid.
 
 `setup-guide` prints the agent skill for setting a kit up in a repository

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Capture your Storybook and real app pages as a static design kit, and compose self-contained mockups from it",
   "type": "module",
   "bin": {
@@ -50,7 +50,8 @@
   "devDependencies": {
     "@playwright/test": "1.58.2",
     "oxlint": "^1.51.0",
-    "prettier": "^3.8.1"
+    "prettier": "^3.8.1",
+    "yaml": "2.8.3"
   },
   "keywords": [
     "design-kit",

package/schema/design-kit.config.schema.json

@@ -31,11 +31,59 @@
       },
       "description": "The paths whose change rebuilds the kit in CI (`design-kit ci-check`), relative to the repository root. A run where none of them changed since the newest kit's commit builds nothing. Without it, any change in the repository rebuilds. `init` writes the Storybook and app folders, the workspace packages they use, global styles, this file, the lockfile and the workflow."
     },
+    "storage": { "$ref": "#/$defs/storage" },
     "theme": { "$ref": "#/$defs/theme" },
     "stories": { "$ref": "#/$defs/stories" },
     "pages": { "$ref": "#/$defs/pages" }
   },
   "$defs": {
+    "storage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "description": "Where the kit is stored. Without it, \"github\": a GitHub Actions artifact. Older versions of the package reject this key, so bump the pinned version (DESIGN_KIT_PACKAGE in the workflow) when you add it by hand.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["github", "codepress", "s3", "r2"],
+          "description": "\"github\" (default): a GitHub Actions artifact. \"codepress\": CodePress keeps the newest kit of each branch; the workflow signs in with its GitHub OIDC token. \"s3\": your own AWS S3 bucket. \"r2\": your own Cloudflare R2 bucket."
+        },
+        "url": {
+          "type": "string",
+          "pattern": "^https?://[^\\s/]+/?$",
+          "description": "codepress: the CodePress address, which is also the upload token's audience. Default https://codepress.dev."
+        },
+        "apiUrl": {
+          "type": "string",
+          "pattern": "^https?://\\S+$",
+          "description": "codepress: the CodePress API base. Default https://api.codepress.dev/v1 for the default url, else <url>/v1."
+        },
+        "bucket": {
+          "type": "string",
+          "minLength": 1,
+          "description": "s3 and r2: the bucket's name."
+        },
+        "prefix": {
+          "type": "string",
+          "description": "s3 and r2: a folder in the bucket for the kits, such as \"design-kits\". Kits are <prefix>/<branch>/<sha>.zip with <prefix>/<branch>/latest.json."
+        },
+        "region": {
+          "type": "string",
+          "minLength": 1,
+          "description": "s3: the bucket's AWS region, such as \"us-east-1\". Default: the aws CLI's own (AWS_REGION)."
+        },
+        "endpoint": {
+          "type": "string",
+          "pattern": "^https?://\\S+$",
+          "description": "s3: the endpoint of another S3-compatible store. Not needed for AWS S3, or for R2 (use type \"r2\")."
+        },
+        "accountId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "r2: your Cloudflare account id (letters and digits). The endpoint https://<accountId>.r2.cloudflarestorage.com and region auto follow from it."
+        }
+      }
+    },
     "size": {
       "type": "object",
       "additionalProperties": false,

package/src/ci.mjs

@@ -9,113 +9,30 @@
  * - `design-kit ci-cleanup` deletes the older kits on the branch once a new
  *   one is uploaded. A failed delete is a warning, never a failure.
  *
- * Where kits are stored is behind two functions, `findNewestKit` and
- * `deleteOlderKits` (GitHub Actions artifacts, through `gh`), so another
- * store changes only those and the workflow's upload step.
+ * The newest kit comes from the configured store's `latest` (see
+ * src/storage/); cleanup is for `github` storage only, since CodePress and
+ * a bucket keep one pointer per branch.
  */
 import { execFileSync } from "node:child_process";
 import { appendFileSync } from "node:fs";
 import { posix } from "node:path";
 
 import { CONFIG_NAME, ConfigError, loadConfig } from "./config.mjs";
+import { errorText } from "./storage/common.mjs";
+import {
+  ARTIFACT,
+  deleteOlderKits,
+  findNewestKit,
+  runGh,
+} from "./storage/github.mjs";
+import { storageFor } from "./storage/index.mjs";
 
-export const ARTIFACT = "design-kit";
+export { ARTIFACT, deleteOlderKits, findNewestKit, runGh };
 /** Rebuild a kit this old even with no UI change, so it never expires. */
 export const DEFAULT_MAX_AGE_DAYS = 75;
 /** What `watch` means when a config has none: the whole repository. */
 export const DEFAULT_WATCH = ["."];
 const DAY_MS = 86_400_000;
-const PAGES = 5;
-
-// ── storage: GitHub Actions artifacts ───────────────────────────────────────
-
-/** Runs `gh` and returns its stdout. */
-export function runGh(args, { env = process.env } = {}) {
-  return execFileSync("gh", args, {
-    encoding: "utf8",
-    env,
-    stdio: ["ignore", "pipe", "pipe"],
-    maxBuffer: 32 * 1024 * 1024,
-  });
-}
-
-/** Every `design-kit` artifact of the repository, newest first. */
-function listKits({ repo, gh }) {
-  const artifacts = [];
-  for (let page = 1; page <= PAGES; page += 1) {
-    const body = JSON.parse(
-      gh([
-        "api",
-        `repos/${repo}/actions/artifacts?name=${ARTIFACT}&per_page=100&page=${page}`,
-      ]),
-    );
-    const batch = body?.artifacts ?? [];
-    artifacts.push(...batch);
-    if (batch.length < 100) break;
-  }
-  return artifacts
-    .filter((artifact) => artifact.name === ARTIFACT)
-    .sort((a, b) => (a.created_at < b.created_at ? 1 : -1));
-}
-
-/**
- * The newest unexpired kit on `branch`: `{id, sha, createdAt, runId}`, or
- * null when there is none. Throws when the store cannot be read.
- */
-export function findNewestKit({ repo, branch, gh = runGh }) {
-  const kit = listKits({ repo, gh }).find(
-    (artifact) =>
-      !artifact.expired && artifact.workflow_run?.head_branch === branch,
-  );
-  if (!kit?.workflow_run?.head_sha) return null;
-  return {
-    id: String(kit.id),
-    sha: kit.workflow_run.head_sha,
-    createdAt: kit.created_at,
-    runId: kit.workflow_run.id ? String(kit.workflow_run.id) : null,
-  };
-}
-
-/**
- * Deletes the kits on `branch` older than the one `keep` names (an artifact
- * id). Returns `{deleted: [ids], failed: [{id, error}], keptFound}`; never
- * throws for a single failed delete. When the kept kit is not in the listing
- * (not listed yet, or on another branch), nothing is deleted: "older" has
- * nothing to be measured against.
- */
-export function deleteOlderKits({ repo, branch, keep, gh = runGh }) {
-  const kits = listKits({ repo, gh }).filter(
-    (artifact) => artifact.workflow_run?.head_branch === branch,
-  );
-  const kept = kits.find((artifact) => String(artifact.id) === String(keep));
-  const deleted = [];
-  const failed = [];
-  if (!kept) return { deleted, failed, keptFound: false };
-  for (const artifact of kits) {
-    if (String(artifact.id) === String(keep)) continue;
-    // Only kits uploaded before the one just kept: a newer one, or one
-    // uploaded in the same instant, is never removed.
-    if (!(Date.parse(artifact.created_at) < Date.parse(kept.created_at)))
-      continue;
-    try {
-      gh([
-        "api",
-        "--method",
-        "DELETE",
-        `repos/${repo}/actions/artifacts/${artifact.id}`,
-      ]);
-      deleted.push(String(artifact.id));
-    } catch (error) {
-      failed.push({ id: String(artifact.id), error: errorText(error) });
-    }
-  }
-  return { deleted, failed, keptFound: Boolean(kept) };
-}
-
-function errorText(error) {
-  const stderr = error?.stderr ? String(error.stderr).trim() : "";
-  return (stderr || error?.message || String(error)).split("\n")[0];
-}
 
 // ── git: ids of the watched paths ───────────────────────────────────────────
 
@@ -282,9 +199,9 @@ export function decide({
 
 /**
  * Looks everything up and decides. `kit` given (`{sha, createdAt}`, or null
- * for "no kit") skips the store lookup; otherwise `findKit()` is called.
- * `head` is the commit being built (default HEAD). Returns
- * `{build, reason, kit}`.
+ * for "no kit", with `lookupError` when the lookup failed) skips the store
+ * lookup; otherwise `findKit()` is called. `head` is the commit being built
+ * (default HEAD). Returns `{build, reason, kit}`.
  */
 export function ciCheck({
   repoDir,
@@ -293,12 +210,12 @@ export function ciCheck({
   force = false,
   packageSpec = "",
   kit,
+  lookupError,
   findKit,
   now = Date.now(),
   maxAgeDays = DEFAULT_MAX_AGE_DAYS,
 }) {
   const inputs = { force, packageSpec, now, maxAgeDays };
-  let lookupError;
   if (kit === undefined && !force && !packageSpec) {
     try {
       kit = findKit();
@@ -343,12 +260,16 @@ function maxAgeFrom(value, env) {
   return days;
 }
 
-function repoAndBranch(options, env) {
+function repoAndBranch(options, env, storage = { type: "github" }) {
   const repo = options.repo ?? env.GITHUB_REPOSITORY;
   const branch = options.branch ?? env.GITHUB_REF_NAME;
-  if (!repo || !branch)
+  // A bucket is not keyed by repository; GitHub and CodePress are.
+  const needsRepo = storage.type === "github" || storage.type === "codepress";
+  if ((needsRepo && !repo) || !branch)
     throw new ConfigError(
-      "--repo <owner/name> and --branch <name> are needed outside GitHub Actions",
+      needsRepo
+        ? "--repo <owner/name> and --branch <name> are needed outside GitHub Actions"
+        : "--branch <name> is needed outside GitHub Actions",
     );
   return { repo, branch };
 }
@@ -371,9 +292,15 @@ function summary(text, env) {
 
 /**
  * `design-kit ci-check`: prints `build=true|false` and `reason=…` (and
- * writes them to $GITHUB_OUTPUT and the step summary when set).
+ * writes them to $GITHUB_OUTPUT and the step summary when set). The newest
+ * kit comes from the configured store's `latest`. With `github` storage
+ * (or when no lookup is needed) it runs synchronously and returns 0; the
+ * other stores answer over the network, so it returns a promise of 0.
  */
-export function ciCheckCommand(options, { env = process.env, gh, now } = {}) {
+export function ciCheckCommand(
+  options,
+  { env = process.env, gh, aws, now } = {},
+) {
   const config = loadConfig(options.config);
   const watch = config.raw.watch?.length ? config.raw.watch : DEFAULT_WATCH;
   if ((options.since === undefined) !== (options["kit-created"] === undefined))
@@ -392,20 +319,57 @@ export function ciCheckCommand(options, { env = process.env, gh, now } = {}) {
     "rev-parse",
     "--show-toplevel",
   ]).trim();
-  const result = ciCheck({
+  const storage = config.storage ?? { type: "github" };
+  const check = {
     repoDir,
     watch,
     force: Boolean(options.force),
     packageSpec: options.package ?? "",
-    kit,
-    findKit: () =>
-      findNewestKit({
-        ...repoAndBranch(options, env),
-        gh: gh ?? ((args) => runGh(args, { env })),
-      }),
     now: now ?? Date.now(),
     maxAgeDays: maxAgeFrom(options["max-age-days"], env),
-  });
+  };
+  const store = () => {
+    const { repo, branch } = repoAndBranch(options, env, storage);
+    return {
+      branch,
+      store: storageFor(storage, {
+        repo,
+        env,
+        gh: gh ?? ((args) => runGh(args, { env })),
+        aws,
+      }),
+    };
+  };
+  const finish = (result) => {
+    report(result, env);
+    return 0;
+  };
+  if (kit !== undefined || check.force || check.packageSpec)
+    return finish(ciCheck({ ...check, kit }));
+  if (storage.type === "github")
+    return finish(
+      ciCheck({
+        ...check,
+        findKit: () => {
+          const { store: github, branch } = store();
+          return github.latest({ branch });
+        },
+      }),
+    );
+  return (async () => {
+    let found = null;
+    let lookupError;
+    try {
+      const { store: other, branch } = store();
+      found = await other.latest({ branch });
+    } catch (error) {
+      lookupError = errorText(error);
+    }
+    return finish(ciCheck({ ...check, kit: found, lookupError }));
+  })();
+}
+
+function report(result, env) {
   if (result.missing?.length)
     console.log(
       `::warning title=Design kit::These watch paths do not exist at this commit, so they never trigger a rebuild: ${result.missing.join(", ")}. Fix or remove them in ${CONFIG_NAME}.`,
@@ -422,7 +386,6 @@ export function ciCheckCommand(options, { env = process.env, gh, now } = {}) {
     `Design kit: ${result.build ? "building" : "nothing to build"}, ${result.reason}.`,
     env,
   );
-  return 0;
 }
 
 /**

package/src/cli.mjs

@@ -28,7 +28,19 @@ const USAGE = `usage: design-kit <command> [options]
   init              set a kit up in this repository: the config, a daily
                     GitHub Actions build, and a skill for its agents
       [--root <dir>] [--dry-run] [--force] [--workflow-only]
-                    --workflow-only --force rewrites just the workflow
+      [--storage github|codepress|s3|r2]
+                    --workflow-only --force rewrites just the workflow;
+                    with --storage it also sets where the kit is stored
+  upload            upload a built kit to the configured storage
+                    (codepress, s3 or r2; github uploads in the workflow)
+      --dir <kit> [--config <file>] [--branch <name>] [--sha <commit>]
+  fetch             download the newest kit, once per commit (cached under
+                    $TMPDIR/design-kit-<sha>); prints path=, sha= and branch=
+      [--branch <name>] [--out <dir>] [--config <file>] [--repo <owner/name>]
+      [--token-file <path>]   codepress: the API key, if not CODEPRESS_API_KEY
+  latest            print the newest kit's sha= and created=
+      [--branch <name>] [--config <file>] [--repo <owner/name>]
+      [--token-file <path>]
   capture stories   capture every story of a Storybook 7-9 static build
       [--config <file>] [--out <dir>] [--storybook-dir <dir>]
       [--only <id,...> | --only-file <file>] [--base <previous kit>]
@@ -57,8 +69,8 @@ const USAGE = `usage: design-kit <command> [options]
 
 The config is the nearest design-kit.config.json at or above the working
 directory unless --config names one. Exit codes: 0 done, 1 a capture could
-not run (or init found the repository already set up), 2 a config or usage
-error.`;
+not run, a store refused or could not be reached (or init found the
+repository already set up), 2 a config or usage error.`;
 
 function parse(argv, spec) {
   const options = {};
@@ -190,6 +202,7 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         "dry-run": "flag",
         force: "flag",
         "workflow-only": "flag",
+        storage: "value",
       });
       const { init } = await import("./init.mjs");
       return init({
@@ -197,6 +210,7 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         dryRun: Boolean(options["dry-run"]),
         force: Boolean(options.force),
         workflowOnly: Boolean(options["workflow-only"]),
+        storage: options.storage,
       });
     }
     if (command === "ci-check") {
@@ -212,7 +226,7 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         branch: "value",
       });
       const { ciCheckCommand } = await import("./ci.mjs");
-      return ciCheckCommand(options, { env });
+      return await ciCheckCommand(options, { env });
     }
     if (command === "ci-cleanup") {
       const options = parse(argv.slice(1), {
@@ -223,6 +237,25 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
       const { ciCleanupCommand } = await import("./ci.mjs");
       return ciCleanupCommand(options, { env });
     }
+    if (command === "upload" || command === "fetch" || command === "latest") {
+      const spec = {
+        config: "value",
+        branch: "value",
+        repo: "value",
+        ...(command === "upload"
+          ? { dir: "value", sha: "value" }
+          : { "token-file": "value" }),
+        ...(command === "fetch" ? { out: "value" } : {}),
+      };
+      const options = parse(argv.slice(1), spec);
+      const storage = await import("./storage/index.mjs");
+      const run = {
+        upload: storage.uploadCommand,
+        fetch: storage.fetchCommand,
+        latest: storage.latestCommand,
+      }[command];
+      return await run(options, { env });
+    }
     if (command === "setup-guide") {
       parse(argv.slice(1), {});
       process.stdout.write(readFileSync(SETUP_GUIDE, "utf8"));

package/src/config.mjs

@@ -194,6 +194,7 @@ export function resolveConfig(raw, path) {
       errors.push(`pages.pages[${index}].name: "${page.name}" is used twice`);
     names.add(page?.name);
   });
+  if (!errors.length && raw.storage) errors.push(...storageErrors(raw.storage));
   if (errors.length) {
     throw new ConfigError(
       `${path}:\n${errors.map((error) => `  ${error}`).join("\n")}`,
@@ -208,6 +209,7 @@ export function resolveConfig(raw, path) {
     configDir,
     raw,
     out: at(raw.out),
+    storage: raw.storage ? { ...raw.storage } : { type: "github" },
     theme: raw.theme ? normalizeTheme(raw.theme) : undefined,
   };
   if (raw.stories) {
@@ -264,6 +266,44 @@ export function resolveConfig(raw, path) {
   return config;
 }
 
+/** The keys each storage type takes, and which of them it needs. */
+const STORAGE_KEYS = {
+  github: { allowed: [], required: [] },
+  codepress: { allowed: ["url", "apiUrl"], required: [] },
+  s3: {
+    allowed: ["bucket", "prefix", "region", "endpoint"],
+    required: ["bucket"],
+  },
+  r2: {
+    allowed: ["accountId", "bucket", "prefix"],
+    required: ["accountId", "bucket"],
+  },
+};
+
+/** What the schema cannot say about `storage`: the keys each type takes. */
+function storageErrors(storage) {
+  const keys = STORAGE_KEYS[storage.type];
+  if (!keys) return [];
+  const errors = [];
+  for (const key of keys.required)
+    if (!(key in storage))
+      errors.push(`storage.${key}: is required for ${storage.type} storage`);
+  for (const key of Object.keys(storage)) {
+    if (key === "type") continue;
+    if (!keys.allowed.includes(key))
+      errors.push(
+        `storage.${key}: not used by ${storage.type} storage${key === "endpoint" && storage.type === "r2" ? " (r2 derives it from accountId)" : ""}`,
+      );
+    else if (/^TODO/.test(String(storage[key])))
+      errors.push(`storage.${key}: still ${storage[key]}`);
+    else if (key === "accountId" && !/^[A-Za-z0-9]+$/.test(storage[key]))
+      errors.push(
+        "storage.accountId: must be your Cloudflare account id, letters and digits only",
+      );
+  }
+  return errors;
+}
+
 /** The theme as the manifest records it, with its defaults filled in. */
 export function normalizeTheme(theme) {
   const attribute = theme.attribute ?? "class";