@jant/core 0.7.0 → 0.7.1

package/src/__tests__/node-dev-tasks.test.ts

@@ -0,0 +1,264 @@
+/**
+ * Local Node Dev Task Guard
+ *
+ * `db-node-bootstrap-shell` and `db-node-clean` were added in 4bc0bfe8 and
+ * never touched the Node database. The shell migrated it, then set up the
+ * local Wrangler D1 database and wrote credentials to `.dev.vars`, leaving the
+ * Node site at `/setup`. Clean deleted `packages/core/.data`, a directory the
+ * Node runtime no longer uses. Both exited 0, so nothing noticed.
+ *
+ * These tests run each task's own script through `dev/run-script.mjs` against
+ * a throwaway directory, and check the database and env file it leaves. The
+ * runner starts Vite, hence the timeouts.
+ */
+
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import Database from "better-sqlite3";
+import { afterEach, describe, expect, it } from "vitest";
+import { writeScriptEnvValues } from "../../dev/script-env.js";
+import { DEFAULT_NAVIGATION_PROFILE } from "../types/constants.js";
+
+const CORE_DIR = resolve(import.meta.dirname, "../..");
+
+/** Variables that would point a task somewhere other than the temp directory. */
+const TARGET_VARIABLES = [
+  "AUTH_SECRET",
+  "DATABASE_URL",
+  "DATA_DIR",
+  "DEMO_EMAIL",
+  "DEMO_PASSWORD",
+  "DEV_API_TOKEN",
+  "LOCAL_STORAGE_PATH",
+  "PORT",
+  "SITE_RESOLUTION_MODE",
+  "STORAGE_DRIVER",
+];
+
+function taskEnv(
+  overrides: Record<string, string>,
+): Record<string, string | undefined> {
+  const env: Record<string, string | undefined> = {
+    ...process.env,
+    // No announcement to a Discover directory from a test database.
+    DISCOVER_PING_URL: "",
+  };
+  for (const name of TARGET_VARIABLES) {
+    delete env[name];
+  }
+  return { ...env, ...overrides };
+}
+
+function runScript(
+  script: string,
+  args: string[],
+  env: Record<string, string | undefined>,
+) {
+  const result = spawnSync(
+    process.execPath,
+    ["dev/run-script.mjs", `dev/scripts/${script}`, ...args],
+    { cwd: CORE_DIR, encoding: "utf8", env, timeout: 120_000 },
+  );
+  expect(result.error).toBeUndefined();
+  return { ...result, output: `${result.stdout}\n${result.stderr}` };
+}
+
+function envFileLines(path: string): string[] {
+  return readFileSync(path, "utf8").split("\n");
+}
+
+describe("local Node dev tasks", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  function makeTempDir(prefix: string): string {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+  }
+
+  it(
+    "db-node-bootstrap-shell sets up the Node database and writes dev credentials to the env file",
+    { timeout: 300_000 },
+    () => {
+      const dir = makeTempDir("jant-bootstrap-shell-");
+      const envPath = join(dir, "test.env");
+      const ownLines = ["# Local settings", `DATA_DIR=${dir}`];
+      writeFileSync(envPath, `${ownLines.join("\n")}\n`);
+      const env = taskEnv({ JANT_ENV_FILE: envPath });
+
+      const first = runScript("bootstrap-node-dev.ts", [], env);
+      expect(first.status, first.output).toBe(0);
+      expect(first.stdout).toContain("created the site and the dev account");
+      expect(first.stdout).not.toMatch(/do(es)? not sign in/);
+
+      // The file's own lines stay as they were; the credentials follow as one
+      // block below a blank line.
+      const written = envFileLines(envPath);
+      expect(written.slice(0, 3)).toEqual([...ownLines, ""]);
+      expect(written.slice(3)).toEqual([
+        expect.stringMatching(/^AUTH_SECRET=\S{32,}$/),
+        expect.stringMatching(/^DEV_API_TOKEN=jnt_dev_[0-9a-f]{32}$/),
+        "DEMO_EMAIL=debug@jant.test",
+        "DEMO_PASSWORD=jant-dev-debug-login",
+        "",
+      ]);
+
+      const sqlite = new Database(join(dir, "jant.sqlite"), {
+        readonly: true,
+      });
+      try {
+        expect(
+          sqlite
+            .prepare(
+              `SELECT "user"."email" FROM "user" JOIN "account" ON "account"."user_id" = "user"."id" WHERE "account"."provider_id" = 'credential'`,
+            )
+            .all(),
+        ).toEqual([{ email: "debug@jant.test" }]);
+        expect(
+          sqlite
+            .prepare(
+              `SELECT "value" FROM "site_setting" WHERE "key" = 'ONBOARDING_STATUS'`,
+            )
+            .get(),
+        ).toEqual({ value: "completed" });
+        expect(
+          (
+            sqlite.prepare(`SELECT "system_key" FROM "nav_item"`).all() as {
+              system_key: string;
+            }[]
+          )
+            .map((row) => row.system_key)
+            .sort(),
+        ).toEqual([...DEFAULT_NAVIGATION_PROFILE.systemKeys].sort());
+        expect(
+          sqlite.prepare(`SELECT COUNT(*) AS count FROM "post"`).get(),
+        ).toEqual({ count: 0 });
+      } finally {
+        sqlite.close();
+      }
+
+      // A second run finds the site set up, and keeps the generated secrets.
+      const afterFirst = readFileSync(envPath, "utf8");
+      const second = runScript("bootstrap-node-dev.ts", [], env);
+      expect(second.status, second.output).toBe(0);
+      expect(second.stdout).toContain("already set up, left unchanged");
+      expect(second.stdout).not.toMatch(/do(es)? not sign in/);
+      expect(readFileSync(envPath, "utf8")).toBe(afterFirst);
+
+      // A new password is recorded, but not set on the existing account, and
+      // the task says so.
+      const third = runScript(
+        "bootstrap-node-dev.ts",
+        ["another-password"],
+        env,
+      );
+      expect(third.status, third.output).toBe(0);
+      expect(third.stdout).toContain(
+        "debug@jant.test has a different password",
+      );
+      expect(envFileLines(envPath)).toContain("DEMO_PASSWORD=another-password");
+    },
+  );
+
+  it(
+    "db-node-clean deletes the SQLite database, its WAL files, and media, and nothing else",
+    { timeout: 150_000 },
+    () => {
+      const dir = makeTempDir("jant-clean-");
+      const deleted = [
+        join(dir, "jant.sqlite"),
+        join(dir, "jant.sqlite-wal"),
+        join(dir, "jant.sqlite-shm"),
+        join(dir, "media"),
+      ];
+      const kept = join(dir, "notes.txt");
+      mkdirSync(join(dir, "media/2026"), { recursive: true });
+      writeFileSync(join(dir, "media/2026/photo.webp"), "image");
+      for (const file of deleted.slice(0, 3)) {
+        writeFileSync(file, "");
+      }
+      writeFileSync(kept, "keep");
+
+      const result = runScript(
+        "clean-node-dev.ts",
+        [],
+        taskEnv({ JANT_ENV_FILE: "", DATA_DIR: dir }),
+      );
+
+      expect(result.status, result.output).toBe(0);
+      expect(deleted.filter((path) => existsSync(path))).toEqual([]);
+      expect(existsSync(kept)).toBe(true);
+    },
+  );
+
+  it("db-node-clean refuses a Postgres database", { timeout: 150_000 }, () => {
+    const result = runScript(
+      "clean-node-dev.ts",
+      [],
+      taskEnv({
+        JANT_ENV_FILE: "",
+        DATABASE_URL: "postgres://jant:jant@127.0.0.1:9/jant_dev",
+      }),
+    );
+
+    expect(result.status).not.toBe(0);
+    expect(result.output).toContain(
+      "db-node-clean only supports Node SQLite development databases.",
+    );
+  });
+});
+
+describe("writeScriptEnvValues", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("replaces keys in place and appends new ones as one block", () => {
+    const dir = mkdtempSync(join(tmpdir(), "jant-script-env-"));
+    tempDirs.push(dir);
+    const envPath = join(dir, ".env.node");
+    writeFileSync(
+      envPath,
+      "# Database\nDATABASE_URL=file:./data/jant.sqlite\nDEMO_PASSWORD=old\n\n\n",
+    );
+
+    writeScriptEnvValues(envPath, {
+      DEMO_PASSWORD: "new",
+      AUTH_SECRET: "secret",
+      DEV_API_TOKEN: "token",
+    });
+
+    expect(readFileSync(envPath, "utf8")).toBe(
+      "# Database\nDATABASE_URL=file:./data/jant.sqlite\nDEMO_PASSWORD=new\n\nAUTH_SECRET=secret\nDEV_API_TOKEN=token\n",
+    );
+  });
+
+  it("writes a new file without a leading blank line", () => {
+    const dir = mkdtempSync(join(tmpdir(), "jant-script-env-"));
+    tempDirs.push(dir);
+    const envPath = join(dir, ".env.node");
+
+    writeScriptEnvValues(envPath, { AUTH_SECRET: "secret" });
+
+    expect(readFileSync(envPath, "utf8")).toBe("AUTH_SECRET=secret\n");
+  });
+});

package/src/__tests__/site-export-canonical-import.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Canonical Site-Export Import Guard
+ *
+ * `sites/demo-source/canonical/site-export/` is a committed `jant site export`.
+ * `mise run db-node-load-demo` loads it the portable way: migrate a local Node
+ * database, set it up, serve the app on a loopback port, and run
+ * `jant site import` against that server.
+ *
+ * Nothing ran that path, and it broke twice without a sign. From b259f4e3 the
+ * task called `site import` without the site URL the command had come to
+ * require. From 6c79f0b4 the importer sent boolean settings the settings route
+ * rejects, so importing any export stopped before it created a post. This test
+ * runs the task's own script against a throwaway SQLite database, so a change
+ * to the importer, the API it calls, the fixture, or the task fails here.
+ *
+ * `JANT_ENV_FILE` is empty for the whole suite (`vitest.config.ts`), and the
+ * script honours it, so a developer's `.env.node` is neither read nor
+ * rewritten. The script runs through `dev/run-script.mjs`, which starts Vite,
+ * hence the timeout.
+ */
+
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import Database from "better-sqlite3";
+import { afterEach, describe, expect, it } from "vitest";
+import { __test__ as importSite } from "../../bin/commands/import-site.js";
+
+const CORE_DIR = resolve(import.meta.dirname, "../..");
+const CANONICAL_DIR = resolve(
+  CORE_DIR,
+  "../../sites/demo-source/canonical/site-export",
+);
+
+function count(sqlite: Database.Database, sql: string): number {
+  return (sqlite.prepare(sql).get() as { count: number }).count;
+}
+
+describe("canonical demo site-export", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it(
+    "imports through `jant site import` into a local Node database at head",
+    { timeout: 150_000 },
+    async () => {
+      const dir = mkdtempSync(join(tmpdir(), "jant-load-demo-"));
+      tempDirs.push(dir);
+      const databasePath = join(dir, "jant.sqlite");
+
+      const env: Record<string, string | undefined> = {
+        ...process.env,
+        JANT_ENV_FILE: "",
+        DATABASE_URL: `file:${databasePath}`,
+        DATA_DIR: dir,
+        LOCAL_STORAGE_PATH: join(dir, "media"),
+        STORAGE_DRIVER: "local",
+        // No announcement to a Discover directory from a test database.
+        DISCOVER_PING_URL: "",
+        // Every request off this machine goes to a closed port, so the export
+        // has to import from its own files. The importer falls back to
+        // fetching a file from the exported site's URL; with the network up,
+        // that fallback hid icons it failed to find in the export.
+        NODE_USE_ENV_PROXY: "1",
+        HTTP_PROXY: "http://127.0.0.1:9",
+        HTTPS_PROXY: "http://127.0.0.1:9",
+        NO_PROXY: "127.0.0.1",
+      };
+      delete env.SITE_RESOLUTION_MODE;
+      for (const name of [
+        "http_proxy",
+        "https_proxy",
+        "no_proxy",
+        "all_proxy",
+        "ALL_PROXY",
+      ]) {
+        delete env[name];
+      }
+
+      const result = spawnSync(
+        process.execPath,
+        ["dev/run-script.mjs", "dev/scripts/import-node-demo-site-export.ts"],
+        { cwd: CORE_DIR, encoding: "utf8", env, timeout: 120_000 },
+      );
+      const output = `${result.stdout}\n${result.stderr}`;
+
+      expect(result.error).toBeUndefined();
+      expect(result.status, output).toBe(0);
+      expect(result.stdout).toContain("(none: JANT_ENV_FILE is empty)");
+      // The importer reports a step it gave up on as a warning and carries on,
+      // the way it once dropped the site avatar.
+      expect(output).not.toMatch(/^Warning:/m);
+
+      const { rootBundles, collectionBundles } =
+        await importSite.walkHugoContent(CANONICAL_DIR);
+      const siteConfig = await importSite.loadSiteConfig(CANONICAL_DIR);
+      const replyCount = rootBundles.reduce(
+        (sum: number, root: { children: unknown[] }) =>
+          sum + root.children.length,
+        0,
+      );
+      // An empty fixture and an import that did nothing would agree on zero.
+      expect(rootBundles.length).toBeGreaterThan(0);
+      const avatarFile = basename(siteConfig.extra.jant.site_avatar_url);
+      const postMediaFiles = readdirSync(
+        join(CANONICAL_DIR, "static/media"),
+      ).filter((name) => name !== avatarFile);
+
+      const sqlite = new Database(databasePath, { readonly: true });
+      try {
+        expect(count(sqlite, `SELECT COUNT(*) AS count FROM "user"`)).toBe(1);
+        expect(count(sqlite, `SELECT COUNT(*) AS count FROM "post"`)).toBe(
+          rootBundles.length + replyCount,
+        );
+        expect(
+          count(sqlite, `SELECT COUNT(*) AS count FROM "collection"`),
+        ).toBe(collectionBundles.length);
+        expect(
+          count(
+            sqlite,
+            `SELECT COUNT(*) AS count FROM "media" WHERE "storage_key" LIKE '%/files/%'`,
+          ),
+        ).toBe(postMediaFiles.length);
+
+        const settings = new Map(
+          (
+            sqlite
+              .prepare(`SELECT "key", "value" FROM "site_setting"`)
+              .all() as { key: string; value: string }[]
+          ).map(({ key, value }) => [key, value]),
+        );
+        expect(settings.get("SITE_NAME")).toBe(siteConfig.title);
+        expect(settings.get("SITE_AVATAR")).toMatch(/\/assets\/avatar\//);
+        expect(settings.get("SITE_FAVICON_ICO")).toBeTruthy();
+        expect(settings.get("SITE_FAVICON_APPLE_TOUCH")).toMatch(
+          /\/assets\/favicon\/apple-touch-icon\.png$/,
+        );
+      } finally {
+        sqlite.close();
+      }
+    },
+  );
+});

package/src/__tests__/snapshot-canonical-replay.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Canonical Snapshot Replay Guard
+ *
+ * `sites/demo-source/canonical/snapshot/` is a committed SQL dump. The nightly
+ * demo rebuild migrates demo.jant.me's database to whatever `main` says, then
+ * replays that dump into it — so the dump has to stay loadable against head,
+ * however long ago it was exported.
+ *
+ * Nothing checked that. A migration that renamed a column, added a NOT NULL
+ * without a default, or reordered the snapshot registries would leave the
+ * committed dump unloadable, and the first sign of it would be the reset job
+ * failing at ~03:00 UTC — which nothing reports either. This test moves that
+ * failure to the pull request that causes it.
+ *
+ * `createTestDatabase()` applies every migration in order and enables foreign
+ * keys, so the replay here is checked at least as strictly as the real target.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  DEFER_FOREIGN_KEYS_SQL,
+  SNAPSHOT_TABLES,
+  assertSnapshotMeta,
+  buildReplaceSql,
+  getSnapshotBootstrapSite,
+  getSnapshotSelectSql,
+  normalizeD1Sql,
+  rewriteSnapshotSiteIdentifiers,
+} from "../../bin/lib/site-snapshot.js";
+import { DEFAULT_TEST_SITE_ID, createTestDatabase } from "./helpers/db.js";
+
+const CANONICAL_DIR = resolve(
+  import.meta.dirname,
+  "../../../../sites/demo-source/canonical/snapshot",
+);
+
+function readCanonicalSql(): string {
+  const meta = JSON.parse(
+    readFileSync(resolve(CANONICAL_DIR, "meta.json"), "utf8"),
+  );
+  assertSnapshotMeta(meta);
+
+  const snapshotSite = getSnapshotBootstrapSite(meta);
+  if (!snapshotSite) {
+    throw new Error("Canonical snapshot has no embedded site metadata.");
+  }
+
+  const rawDbSql = readFileSync(resolve(CANONICAL_DIR, "db.sql"), "utf8");
+  return normalizeD1Sql(
+    rewriteSnapshotSiteIdentifiers(
+      rawDbSql,
+      snapshotSite.id,
+      DEFAULT_TEST_SITE_ID,
+    ),
+  );
+}
+
+describe("canonical demo snapshot", () => {
+  it("replays into a database migrated to head", () => {
+    const { sqlite } = createTestDatabase();
+    const dbSql = readCanonicalSql();
+
+    expect(() => {
+      sqlite.exec(buildReplaceSql(DEFAULT_TEST_SITE_ID));
+      sqlite.exec(dbSql);
+    }).not.toThrow();
+
+    // Guard against a vacuous pass: an empty dump would also "not throw".
+    const posts = sqlite
+      .prepare(`SELECT COUNT(*) AS count FROM "post" WHERE "site_id" = ?`)
+      .get(DEFAULT_TEST_SITE_ID) as { count: number };
+    expect(posts.count).toBeGreaterThan(0);
+  });
+
+  it("restores the language setup its posts are stamped for", () => {
+    // The demo publishes in two languages. When the snapshot carried each
+    // post's `language` but not `MULTILINGUAL_ENABLED`, every rebuild left
+    // demo.jant.me serving no per-language views at all, and the Chinese side
+    // of the demo disappeared at ~00:00 UTC each night.
+    const { sqlite } = createTestDatabase();
+
+    sqlite.exec(buildReplaceSql(DEFAULT_TEST_SITE_ID));
+    sqlite.exec(readCanonicalSql());
+
+    const languages = sqlite
+      .prepare(
+        `SELECT DISTINCT "language" FROM "post" WHERE "site_id" = ? AND "language" IS NOT NULL`,
+      )
+      .all(DEFAULT_TEST_SITE_ID) as { language: string }[];
+    if (languages.length < 2) return;
+
+    const settings = sqlite
+      .prepare(
+        `SELECT "key", "value" FROM "site_setting" WHERE "site_id" = ? AND "key" IN ('SITE_LANGUAGE', 'MULTILINGUAL_ENABLED', 'ADDITIONAL_LANGUAGES')`,
+      )
+      .all(DEFAULT_TEST_SITE_ID) as { key: string; value: string }[];
+    const value = (key: string) =>
+      settings.find((row) => row.key === key)?.value ?? "";
+
+    expect(value("MULTILINGUAL_ENABLED")).toBe("true");
+
+    const served = new Set([
+      value("SITE_LANGUAGE"),
+      ...value("ADDITIONAL_LANGUAGES").split(",").filter(Boolean),
+    ]);
+    expect(
+      languages.map((row) => row.language).filter((tag) => !served.has(tag)),
+    ).toEqual([]);
+  });
+
+  it("replays twice, the way a nightly rebuild does", () => {
+    // `--replace` runs against a site that already holds the previous rebuild's
+    // rows, so the delete order matters as much as the insert order. A first
+    // load into an empty database would never exercise it.
+    const { sqlite } = createTestDatabase();
+    const dbSql = readCanonicalSql();
+
+    sqlite.exec(buildReplaceSql(DEFAULT_TEST_SITE_ID));
+    sqlite.exec(dbSql);
+
+    expect(() => {
+      sqlite.exec(buildReplaceSql(DEFAULT_TEST_SITE_ID));
+      sqlite.exec(dbSql);
+    }).not.toThrow();
+  });
+});
+
+describe("snapshot export queries", () => {
+  it("runs every content table's export query against head", () => {
+    // The registry, the SELECT statement and the schema have to agree on
+    // column names, not just table names. A stale `ORDER BY` column would
+    // otherwise only surface the next time someone exported a snapshot.
+    const { sqlite } = createTestDatabase();
+
+    for (const table of SNAPSHOT_TABLES) {
+      expect(() =>
+        sqlite.prepare(getSnapshotSelectSql(table, DEFAULT_TEST_SITE_ID)).all(),
+      ).not.toThrow();
+    }
+  });
+
+  // Snapshots written before posts were ordered parents-first put a reply
+  // older than its root ahead of the root. The import checks foreign keys at
+  // commit on SQLite and D1, so those snapshots still load.
+  it("loads a snapshot that lists a reply before its root", () => {
+    const { sqlite } = createTestDatabase();
+    const post = (id: string, threadId: string, replyToId: string | null) =>
+      `INSERT INTO "post" ("id", "site_id", "format", "status", "visibility", "reply_to_id", "thread_id", "published_at", "last_activity_at", "created_at", "updated_at", "thread_updated_at") VALUES ('${id}', '${DEFAULT_TEST_SITE_ID}', 'note', 'published', 'public', ${replyToId ? `'${replyToId}'` : "NULL"}, '${threadId}', 1, 1, 1, 1, 1);`;
+    const dump = [
+      post(
+        "pst_01aaaaaaaaaaaaaaaaaaaaaaab",
+        "pst_01aaaaaaaaaaaaaaaaaaaaaaaa",
+        "pst_01aaaaaaaaaaaaaaaaaaaaaaaa",
+      ),
+      post(
+        "pst_01aaaaaaaaaaaaaaaaaaaaaaaa",
+        "pst_01aaaaaaaaaaaaaaaaaaaaaaaa",
+        null,
+      ),
+    ].join("\n");
+
+    expect(() =>
+      sqlite.transaction(() => {
+        sqlite.exec(buildReplaceSql(DEFAULT_TEST_SITE_ID));
+        sqlite.exec(dump);
+      })(),
+    ).toThrow(/FOREIGN KEY/);
+
+    expect(() =>
+      sqlite.transaction(() => {
+        sqlite.exec(DEFER_FOREIGN_KEYS_SQL);
+        sqlite.exec(buildReplaceSql(DEFAULT_TEST_SITE_ID));
+        sqlite.exec(dump);
+      })(),
+    ).not.toThrow();
+  });
+});

package/src/__tests__/snapshot-settings.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Snapshot Setting Registry Guard
+ *
+ * `jant site snapshot export/import` filters `site_setting` through the
+ * hand-written `SNAPSHOT_SETTING_KEYS` allowlist in `bin/lib/site-snapshot.js`.
+ * `bin/` is plain JavaScript, outside the type system, so a new setting key
+ * compiles, lints and tests clean while the snapshot silently skips it.
+ *
+ * That already happened. `MULTILINGUAL_ENABLED` and `ADDITIONAL_LANGUAGES`
+ * arrived with multilingual content and never reached the allowlist, while the
+ * whole-row `post` dump kept carrying `language` and `translation_group_id`.
+ * Restoring a multilingual site therefore produced posts stamped per language
+ * on a site that served no per-language views — and the nightly demo rebuild
+ * reset `demo.jant.me` to a single-language site every night.
+ *
+ * This test closes the gap the same way `snapshot-tables.test.ts` does for
+ * tables: every DB-backed setting has to be named in one of the two
+ * registries, so a new key forces a decision instead of defaulting to
+ * "forgotten".
+ *
+ * `envOnly` keys are the one exemption, and are asserted to be in neither
+ * list: they resolve from the environment and never reach `site_setting`, so
+ * there is no row for an export to read or for `--replace` to clear.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  SNAPSHOT_EXCLUDED_SETTING_KEYS,
+  SNAPSHOT_SETTING_KEYS,
+} from "../../bin/lib/site-snapshot.js";
+import { CONFIG_FIELDS } from "../types/config.js";
+
+type ConfigKey = keyof typeof CONFIG_FIELDS;
+
+const ALL_KEYS = Object.keys(CONFIG_FIELDS) as ConfigKey[];
+
+/** Keys that can hold a `site_setting` row — everything not env-resolved. */
+const DB_BACKED_KEYS = ALL_KEYS.filter(
+  (key) => !("envOnly" in CONFIG_FIELDS[key] && CONFIG_FIELDS[key].envOnly),
+);
+
+/** Keys resolved from the environment, which never reach `site_setting`. */
+const ENV_ONLY_KEYS = ALL_KEYS.filter((key) => !DB_BACKED_KEYS.includes(key));
+
+describe("snapshot setting registry", () => {
+  it("names every DB-backed setting in exactly one registry", () => {
+    const carried = new Set<string>(SNAPSHOT_SETTING_KEYS);
+    const excluded = new Set<string>(SNAPSHOT_EXCLUDED_SETTING_KEYS);
+
+    const unregistered = DB_BACKED_KEYS.filter(
+      (key) => !carried.has(key) && !excluded.has(key),
+    );
+    const registeredTwice = DB_BACKED_KEYS.filter(
+      (key) => carried.has(key) && excluded.has(key),
+    );
+
+    expect(
+      { unregistered, registeredTwice },
+      "Add each new DB-backed setting to SNAPSHOT_SETTING_KEYS (it belongs to " +
+        "the site's published content) or to SNAPSHOT_EXCLUDED_SETTING_KEYS " +
+        "(with the reason), in bin/lib/site-snapshot.js.",
+    ).toEqual({ unregistered: [], registeredTwice: [] });
+  });
+
+  it("leaves env-only settings out of both registries", () => {
+    const listed = ENV_ONLY_KEYS.filter(
+      (key) =>
+        SNAPSHOT_SETTING_KEYS.includes(key) ||
+        SNAPSHOT_EXCLUDED_SETTING_KEYS.includes(key),
+    );
+
+    expect(listed).toEqual([]);
+  });
+
+  it("registers no key that CONFIG_FIELDS does not define", () => {
+    const known = new Set<string>(ALL_KEYS);
+    const unknown = [
+      ...SNAPSHOT_SETTING_KEYS,
+      ...SNAPSHOT_EXCLUDED_SETTING_KEYS,
+    ].filter((key) => !known.has(key));
+
+    expect(unknown).toEqual([]);
+  });
+
+  it("carries the whole language trio, so restored posts keep their views", () => {
+    // `post.language` and `post.translation_group_id` ride along in the
+    // whole-row `post` dump. A snapshot that carried those but not the switch
+    // restored a site whose per-language views had silently disappeared.
+    expect(SNAPSHOT_SETTING_KEYS).toEqual(
+      expect.arrayContaining([
+        "SITE_LANGUAGE",
+        "MULTILINGUAL_ENABLED",
+        "ADDITIONAL_LANGUAGES",
+      ]),
+    );
+  });
+});