@devdogsuga/devtools 0.1.0

package/dist/deploy/write-env.js

@@ -0,0 +1,393 @@
+/**
+ * `devtools deploy write-env [--source <manifest>]`
+ *
+ * Materialises `.env.staging` / `.env.production` inside a deploy job.
+ *
+ * Everything downstream of this command reads its configuration through
+ * `with-env`, which reads a file on disk: `cf:build:*`, `cf:deploy:*`,
+ * `deploy:*`, `deploy secrets-file`. CI has no such file, so one step has to
+ * write it. This is that step, and it is the ONLY place in
+ * the pipeline that touches the `secrets` and `vars` contexts. After it runs, a
+ * deploy job looks exactly like a devops laptop, and every later step can be
+ * the same command a person would run by hand.
+ *
+ * ## ⚠️ This command cannot be run through `with-env`
+ *
+ * `pnpm devtools` is `with-env tsx src/cli.ts`, and `with-env` refuses to
+ * start when the file for `DEPLOY_ENV` is absent. That file is the one this
+ * command is about to create, so routing it the ordinary way is a bootstrap
+ * cycle: it would die on `MissingEnvFileError` for its own output. Use the
+ * package's `cli:no-env` script instead,
+ *
+ *     pnpm --filter @devdogsuga/devtools run cli:no-env deploy write-env
+ *
+ * the same entry point with the `with-env` wrapper removed, and how
+ * `deploy.yaml` invokes it. (`pnpm devtools env example --check` already routes
+ * through `cli:no-env` for the mirror-image reason: it must run in a job that
+ * deliberately has no env file.) Nothing here reads the ambient environment
+ * apart from `DEPLOY_ENV` and the two context variables the workflow sets on
+ * the step, so there is nothing for `with-env` to have supplied.
+ *
+ * ## Where the values come from
+ *
+ *   secret     `${{ secrets.* }}` for the environment, written by a human
+ *              running `pnpm devtools env push`. CI never reads Bitwarden.
+ *   variable   `${{ vars.* }}`, the per-environment values that are NOT
+ *              secrets (`PROJECT_REF`, `BASE_URL`, `PUBLISHABLE_KEY`, …).
+ *   derived    an `example` metadata entry that is a `$VAR` formula rather than
+ *              a placeholder: `API_URL` is `https://$PROJECT_REF.supabase.co`
+ *              and always has been. Security plan §A.4: "derived at deploy
+ *              time from PROJECT_REF, never stored".
+ *   committed  a `scope: "default"` value, identical in every environment and
+ *              carried in the registry (`GITHUB_ORG`, the avatars bucket).
+ *
+ * ⚠️ A literal `example` on a `scope: "environment"` key is NOT a fallback.
+ * `BASE_URL`'s example is `http://localhost:3000` and `GH_APP_ID`'s is
+ * `000000`: both are the shape of a working development file, and taking
+ * either as a deploy default would ship a production Worker pointed at
+ * localhost with nothing anywhere saying so. Only a `$`-formula (a derivation)
+ * and a `scope: "default"` constant qualify, which is why the two cases are
+ * separated above rather than collapsed into "use the example".
+ *
+ * ## The completeness check is the point
+ *
+ * Security plan §A.6: the deploy build needs the ENTIRE server schema, because
+ * `@t3-oss/env` validates the whole thing on import and the platform
+ * prerenders pages that resolve their gate at build time. So the interesting
+ * failure is a missing value, not a wrong one. GitHub hands a missing secret to
+ * a workflow as an EMPTY STRING rather than an error (§A.7's closing warning).
+ *
+ * Rather than trust that, this refuses to write a file that would fail the
+ * build, and names every key it could not resolve along with where that key
+ * was supposed to come from. "Required" is derived, not listed: a schema that
+ * rejects `undefined` is required, one with `.optional()` or `.default()` is
+ * not. That is the same registry the apps validate against, so the two cannot
+ * drift.
+ *
+ * ## Refusals
+ *
+ * `neverStoreKeys()` appearing in either context is a hard failure. It is
+ * mostly unreachable, since `env push` will not upload one, but this is the
+ * last place to catch a `BWS_ACCESS_TOKEN` added to the repository by hand,
+ * and the cost of missing it is every secret the project holds (see the long
+ * comment on the declaration in `packages/devtools/env.ts`).
+ *
+ * Writing uses `{ flag: "wx" }`, the same atomic refusal `env init` uses.
+ * On a runner the file never exists; on a laptop it is the devops copy of the
+ * production credentials, and a stray run of this command must not be able to
+ * overwrite it. `development` is refused outright for the same reason: `.env`
+ * is that file.
+ *
+ * ## `--source <manifest>`
+ *
+ * Composes only what one manifest declares, and demands ALL of its secrets
+ * rather than only its schema-required keys. That is for a step that exists to
+ * mutate one thing. `supabase config push` reads `supabase/env.ts` and nothing
+ * else, the job runs in a GitHub environment holding a deliberately narrow
+ * slice of the credentials, and the interesting failure is an OAuth provider
+ * reconfigured without its secret. Every one of those keys is `.optional()` in
+ * the schema (an app boots fine without them; only `config.toml` reads them),
+ * so schema-required alone would let the push through with a provider
+ * half-configured.
+ */
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { assertRegistryLoaded } from "../env/discovery.js";
+import { getEnvSync } from "../repo/peers.js";
+import { findRepoRoot } from "../repo/root.js";
+import { DeployError, summary } from "./report.js";
+/**
+ * `${{ toJSON(secrets) }}` and `${{ toJSON(vars) }}` arrive as JSON objects.
+ *
+ * Non-string members are dropped rather than coerced: the contexts only ever
+ * hold strings, and a `String(value)` here would turn a future shape change
+ * into a value like `[object Object]` written to a Worker.
+ */
+function readContext(name, env) {
+    const raw = env[name];
+    if (raw === undefined || raw.trim() === "")
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new DeployError(`${name} is not valid JSON.`, [String(cause)]);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new DeployError(`${name} is not a JSON object.`);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        // An empty value is treated as absent throughout this toolchain: it reads
+        // as "configured" to every consumer that checks for presence, which is
+        // worse than nothing being there. Same rule as `selectForPush`.
+        if (typeof value === "string" && value !== "")
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * The value the registry itself supplies, or `null` when it supplies none.
+ *
+ * The derivation half is `derivationOf()` in `@devdogsuga/env` rather than a
+ * test written here, because `env init --target` has to make the identical
+ * call: the file a person fills in by hand and the file this command composes
+ * on a runner are the same file, and a second opinion about which `example`
+ * values are real would make them differ. See that module for what each of its
+ * gates is closing, chiefly `DB_URL`, whose example is a genuine
+ * `$PROJECT_REF` derivation with `<password>` and `<host>` punched into it.
+ */
+function fromRegistry(meta) {
+    const derivation = getEnvSync().derivationOf(meta);
+    if (derivation !== null)
+        return { value: derivation, from: "derived" };
+    const example = meta.example;
+    if (example === undefined || example === "")
+        return null;
+    return meta.scope === "default" && meta.secrecy === "public"
+        ? { value: example, from: "committed" }
+        : null;
+}
+/**
+ * The one expansion failure with a second meaning. For a REQUIRED key it is a
+ * fault like any other `DeployError`; for an optional one it is the registry
+ * saying "leave it unset until the deploy exists" (STUDY_GROUP_FINDER_URL and
+ * its `_CALLBACK`, declared ahead of any web deployment), so the caller skips
+ * the key instead. A distinct class rather than a message match, because the
+ * write loop's catch must never swallow a cycle or a quoting refusal.
+ */
+class MissingSourceError extends DeployError {
+}
+/**
+ * Expands `$NAME` / `${NAME}` against the values resolved so far.
+ *
+ * dotenvx would do this at load time and the composed file could carry the
+ * formula, but only for an unquoted or double-quoted value, and quoting is what
+ * this file cannot compromise on (see `quote` below). So the derivations are
+ * resolved here and every line ships fully literal: one mechanism, verifiable
+ * by reading the file, with no dependence on which of dotenvx's three quoting
+ * modes a value landed in.
+ */
+function expand(key, value, resolved, seen = []) {
+    return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}|\$([A-Z][A-Z0-9_]*)/g, (_, a, b) => {
+        const name = (a ?? b);
+        if (seen.includes(name)) {
+            throw new DeployError(`${key} derives from ${name}, which derives back from it.`, [`chain: ${[...seen, name].join(" -> ")}`]);
+        }
+        const target = resolved.get(name);
+        if (!target) {
+            throw new MissingSourceError(`${key} is derived from ${name}, which has no value.`, [`${name} is the value to fix; ${key} follows from it.`]);
+        }
+        return expand(name, target.value, resolved, [...seen, name]);
+    });
+}
+/**
+ * Single quotes, because dotenvx treats a single-quoted value as fully
+ * literal: no `$` expansion, no backslash escapes, and multi-line values (the
+ * GitHub App private key) survive verbatim. Verified against dotenvx 2.19 on
+ * 2026-08-15, including embedded double quotes, `#`, and a bare `'`.
+ *
+ * The one shape it cannot express is a value whose first or last character is
+ * a quote, since the parser takes everything to the outermost one. That is
+ * refused rather than mangled: a credential silently truncated by one
+ * character fails at the far end of the pipeline, against a service that will
+ * only say "unauthorized".
+ */
+function quote(key, value) {
+    if (value.startsWith("'") || value.endsWith("'")) {
+        throw new DeployError(`${key} begins or ends with a single quote, which cannot be quoted.`, ["Re-issue the credential, or wrap it (base64) at both ends."]);
+    }
+    return `'${value}'`;
+}
+/**
+ * Composes the file and writes it.
+ *
+ * Every refusal is a `DeployError`, and every one of them ALSO lands in the job
+ * summary, via the wrapper below. That is deliberate here and not for the other
+ * commands in the group: the failure mode this exists to catch is a missing
+ * credential, and the person who has to add it is reading the run page rather
+ * than a step's log.
+ */
+export async function runDeployWriteEnv(options = {}) {
+    const env = options.env ?? process.env;
+    try {
+        return compose(options, env);
+    }
+    catch (err) {
+        if (err instanceof DeployError) {
+            summary(["### Deploy environment could not be composed", "", err.message, ""], env);
+            if (err.detail.length > 0) {
+                summary(["```", ...err.detail, "```", ""], env);
+            }
+        }
+        throw err;
+    }
+}
+function compose(options, env) {
+    assertRegistryLoaded();
+    const root = options.root ?? findRepoRoot();
+    const source = options.source ?? null;
+    const environment = getEnvSync().resolveEnvironment(env.DEPLOY_ENV);
+    if (environment === "development") {
+        throw new DeployError("DEPLOY_ENV must name a deployed environment (staging | production).", [
+            "development means the root .env, which is a real file with real",
+            "credentials in it. This command never writes that one.",
+        ]);
+    }
+    const ghSecrets = readContext("DEPLOY_GITHUB_SECRETS", env);
+    const ghVars = readContext("DEPLOY_GITHUB_VARS", env);
+    const smuggled = getEnvSync().neverStoreKeys().filter((k) => k in ghSecrets || k in ghVars);
+    if (smuggled.length > 0) {
+        throw new DeployError(`${smuggled.join(", ")} must never be a GitHub secret or variable.`, [
+            "Delete it from the repository and the environment, then rotate it.",
+            "See the declaration in packages/devtools/env.ts for why.",
+        ]);
+    }
+    const resolved = new Map();
+    const missing = [];
+    /** Which keys the write loop may NOT silently drop. See MissingSourceError. */
+    const requiredKeys = new Set();
+    for (const [key, entries] of getEnvSync().variables()) {
+        const meta = entries[0].meta;
+        // One contributor's own value, meaningless anywhere else and required by
+        // nothing. An app that could not boot without one could not boot in CI.
+        if (meta.scope === "developer")
+            continue;
+        // `:tooling` suffixes count as the same manifest. The split says "declared
+        // here but not read by the running thing", a distinction about the Worker,
+        // not about which step needs the value.
+        const owned = source === null ||
+            entries.some((e) => e.source === source || e.source.startsWith(`${source}:`));
+        if (!owned)
+            continue;
+        const asSecret = ghSecrets[key];
+        const asVariable = ghVars[key];
+        // GitHub allows a secret and a variable of the same name in one environment
+        // and never says which one it means. Refused: which of the two a deploy used
+        // would depend on this file's precedence rules, and nothing at the far end
+        // could report which value it got.
+        if (asSecret !== undefined && asVariable !== undefined) {
+            throw new DeployError(`${key} is set BOTH as a secret and as a variable.`, [
+                "Delete whichever is wrong. A secret is the right home for anything",
+                'the registry marks `secrecy: "secret"`; everything else is a variable.',
+            ]);
+        }
+        const value = asSecret !== undefined
+            ? { value: asSecret, from: "secret" }
+            : asVariable !== undefined
+                ? { value: asVariable, from: "variable" }
+                : fromRegistry(meta);
+        // `undefined` is rejected by at least one manifest's schema, so omitting the
+        // key breaks that app's boot. Derived rather than listed: the schemas are
+        // the same ones the build validates against, so this cannot drift from them.
+        // Under `--source`, every secret that manifest declares is required too; see
+        // the header for why optional-in-schema is not good enough there.
+        const required = entries.some((e) => !e.schema.safeParse(undefined).success) ||
+            (source !== null && meta.secrecy === "secret");
+        if (required)
+            requiredKeys.add(key);
+        if (!value) {
+            if (required)
+                missing.push(key);
+            continue;
+        }
+        resolved.set(key, value);
+    }
+    if (missing.length > 0) {
+        throw new DeployError(`${missing.length} required variable(s) have no value.`, [
+            ...missing.map((key) => {
+                const meta = getEnvSync().variables().get(key)[0].meta;
+                return meta.secrecy === "secret"
+                    ? `${key}  — a secret: \`pnpm devtools env push\` sends it`
+                    : `${key}  — not a secret: it belongs in the environment's VARIABLES`;
+            }),
+            "",
+            '`env push` syncs both stores: `secrecy: "secret"` keys to the',
+            "environment's secrets, the public per-environment ones (PROJECT_REF,",
+            "BASE_URL, PUBLISHABLE_KEY, …) to its variables. A key missing here was",
+            "either never in the pusher's .env or never pushed — run",
+            "`pnpm devtools env audit --target <target>` to see which.",
+        ]);
+    }
+    // ── write ──────────────────────────────────────────────────────────────────
+    const file = getEnvSync().fileFor(environment);
+    const lines = [
+        `# ${file} — composed by \`devtools deploy write-env\` for a deploy job.`,
+        "#",
+        "# NOT a file anybody should have on a laptop. It is written into a runner's",
+        "# checkout from the GitHub environment's secrets and variables, read once by",
+        "# with-env, and discarded with the runner. Every value is single-quoted and",
+        "# literal: the $VAR derivations were already expanded when this was written.",
+        "",
+    ];
+    const provenance = new Map();
+    for (const [key, entry] of resolved) {
+        let value;
+        if (entry.from === "derived") {
+            try {
+                value = expand(key, entry.value, resolved);
+            }
+            catch (error) {
+                // An optional derivation whose source has no value is a key the
+                // registry declared ahead of its deployment, not a fault: omit it,
+                // exactly as a hand-filled .env leaves it commented out. A required
+                // key keeps the loud failure, naming the source to fix.
+                if (error instanceof MissingSourceError && !requiredKeys.has(key)) {
+                    continue;
+                }
+                throw error;
+            }
+        }
+        else {
+            value = entry.value;
+        }
+        lines.push(`${key}=${quote(key, value)}`);
+        provenance.set(key, entry.from);
+    }
+    try {
+        writeFileSync(join(root, file), `${lines.join("\n")}\n`, {
+            flag: "wx",
+            mode: 0o600,
+        });
+    }
+    catch (cause) {
+        // `wx` is the refusal, so EEXIST is the expected shape of "you ran this on
+        // a machine that already has the file" rather than an unexplained crash.
+        // On a runner it cannot happen; on a laptop the file it declined to touch
+        // holds the live credentials for that environment.
+        if (cause.code === "EEXIST") {
+            throw new DeployError(`${file} already exists, and this never overwrites one.`, [
+                "It composes a throwaway file for a runner from the GitHub",
+                "environment's secrets and variables. An existing copy is somebody's",
+                "real one — `pnpm devtools env pull --target <target>` updates that",
+                "in place instead.",
+            ]);
+        }
+        throw cause;
+    }
+    return { file, provenance };
+}
+/**
+ * The line the job log gets: names and provenance only.
+ *
+ * Never a value, and never a fingerprint either. A fingerprint helps when
+ * comparing two stores by hand, and there is nothing here to compare against.
+ */
+export function renderWriteEnvReport(result) {
+    const counts = {
+        secret: 0,
+        variable: 0,
+        derived: 0,
+        committed: 0,
+    };
+    for (const from of result.provenance.values())
+        counts[from] += 1;
+    return [
+        `devtools deploy write-env: wrote ${result.file} — ` +
+            `${result.provenance.size} variables (${counts.secret} secret, ` +
+            `${counts.variable} variable, ${counts.derived} derived, ` +
+            `${counts.committed} committed)`,
+        ...[...result.provenance].map(([key, from]) => `  ${from.padEnd(9)} ${key}`),
+    ];
+}

package/dist/docs/index-pages.d.ts

@@ -0,0 +1,36 @@
+/** One row of the artifact `@devdogsuga/docs` builds. */
+export interface DocsPage {
+    path: string;
+    title: string;
+    description: string | null;
+    plainText: string;
+}
+/**
+ * The seam, kept as narrow as `planner/db.ts`'s.
+ *
+ * Parameterised rather than that module's `run(text)`: page content is the one
+ * thing here that is not a constant, and it is markdown, with apostrophes,
+ * dollar-quoting, whatever a contributor writes. Nothing is interpolated.
+ */
+export interface DocsDb {
+    run(query: string, params: readonly unknown[]): Promise<unknown[]>;
+    end(): Promise<void>;
+}
+export type Connect = (url: string) => DocsDb;
+export declare function connectDocsDb(url: string): DocsDb;
+export declare function isLocalDatabase(url: string): boolean;
+/**
+ * Upsert every page by path, then delete the rows whose path is gone.
+ *
+ * One transaction, and the delete is the reason `--target remote` is explicit:
+ * run against a deployed database from a working copy, this replaces the live
+ * index with whatever happens to be checked out.
+ */
+export declare function indexPages(db: DocsDb, pages: readonly DocsPage[]): Promise<number>;
+export interface DocsIndexOptions {
+    /** "remote" allows a non-local database (replaces the old --force flag). */
+    target?: "local" | "remote";
+    connect?: Connect;
+    load?: () => Promise<readonly DocsPage[]>;
+}
+export declare function runDocsIndex(options?: DocsIndexOptions): Promise<void>;

package/dist/docs/index-pages.js

@@ -0,0 +1,184 @@
+/**
+ * `devtools docs index` writes the documentation search index.
+ *
+ * ## Why it lives here
+ *
+ * It was `apps/platform/scripts/index-docs.ts`, and it was the last script in
+ * the repository run from more than one place: `pnpm devtools docs index` by a
+ * contributor, and `devtools-ci` by BOTH deploy scripts, ahead of every
+ * staging and production release. A step the deploy depends on is not an
+ * app's private tooling, and the rest of that class (`deploy write-env`,
+ * `secrets-file`, `orphans`, `preflight`, `require-token`) moved into this
+ * package already, for the reasons `cli.ts` gives.
+ *
+ * The three that stayed behind in `apps/platform/scripts/` each have exactly
+ * one caller and are about the platform's own generated sources:
+ * `post-pull.ts` patches what `drizzle-kit pull` emits, `generate-campus-map.ts`
+ * is hand-run codegen, and `db seed roles` seeds rows through the
+ * platform's own Drizzle schema. Reuse is the line, not subject matter.
+ *
+ * ## Why raw SQL rather than Drizzle
+ *
+ * The predecessor imported `~/server/db` and `~/server/db/schema`, a package
+ * reaching into an app. That is the wrong direction, and it would have dragged
+ * the platform's whole generated schema into a CLI that installs on a fresh
+ * clone. Four columns of one table do not need an ORM, and this package
+ * already talks to Postgres exactly this way (see `planner/db.ts`).
+ *
+ * `search` is a generated column, so this writes title/description/plainText
+ * and Postgres recomputes the vector.
+ */
+import { confirm, log, spinner } from "@clack/prompts";
+import postgres from "postgres";
+import { bail, errorMessage, explain, unwrap } from "../ui.js";
+import { loadDocs } from "../repo/source.js";
+export function connectDocsDb(url) {
+    // `max: 1` is load-bearing, not tuning: the write below is BEGIN, two
+    // statements and COMMIT, and they have to land on the same session.
+    const sql = postgres(url, { max: 1, prepare: false, connect_timeout: 15 });
+    return {
+        async run(query, params) {
+            return (await sql.unsafe(query, params));
+        },
+        async end() {
+            await sql.end({ timeout: 5 });
+        },
+    };
+}
+// ── Which database ───────────────────────────────────────────────────────────
+const LOCAL_DB_HOSTS = [
+    "localhost",
+    "127.0.0.1",
+    "[::1]",
+    "host.docker.internal",
+];
+export function isLocalDatabase(url) {
+    try {
+        return LOCAL_DB_HOSTS.includes(new URL(url).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+// ── The write ────────────────────────────────────────────────────────────────
+/**
+ * Upsert every page by path, then delete the rows whose path is gone.
+ *
+ * One transaction, and the delete is the reason `--target remote` is explicit:
+ * run against a deployed database from a working copy, this replaces the live
+ * index with whatever happens to be checked out.
+ */
+export async function indexPages(db, pages) {
+    const values = pages
+        .map((_, i) => `($${i * 4 + 1}, $${i * 4 + 2}, $${i * 4 + 3}, $${i * 4 + 4})`)
+        .join(", ");
+    const params = pages.flatMap((page) => [
+        page.path,
+        page.title,
+        page.description,
+        page.plainText,
+    ]);
+    await db.run("begin", []);
+    try {
+        await db.run(`insert into platform."docsPages" (path, title, description, "plainText")
+       values ${values}
+       on conflict (path) do update set
+         title = excluded.title,
+         description = excluded.description,
+         "plainText" = excluded."plainText",
+         "updatedAt" = now()`, params);
+        await db.run(`delete from platform."docsPages" where path <> all($1::text[])`, [pages.map((page) => page.path)]);
+        await db.run("commit", []);
+    }
+    catch (err) {
+        await db.run("rollback", []);
+        throw err;
+    }
+    return pages.length;
+}
+// ── The command ──────────────────────────────────────────────────────────────
+/**
+ * Loads the built artifact.
+ *
+ * Imported dynamically so that `@devdogsuga/docs` is only needed by the one
+ * command that reads it. Every other command in this CLI must not pay for a
+ * docs build to start, `setup` most of all: it runs on a clone where nothing
+ * is built yet.
+ */
+async function loadPages() {
+    const { pages } = (await loadDocs());
+    return pages;
+}
+export async function runDocsIndex(options = {}) {
+    const connect = options.connect ?? connectDocsDb;
+    const load = options.load ?? loadPages;
+    const url = process.env.DB_URL;
+    if (!url) {
+        explain("DB_URL is not set.", "", [
+            "Run through `pnpm devtools`, which loads your .env.",
+            "`pnpm devtools db start` starts Supabase on this machine and writes one.",
+        ]);
+        process.exitCode = 1;
+        return;
+    }
+    let pages;
+    try {
+        pages = await load();
+    }
+    catch (err) {
+        explain("The docs artifact could not be read.", errorMessage(err), [
+            "pnpm --filter @devdogsuga/docs build",
+        ]);
+        process.exitCode = 1;
+        return;
+    }
+    if (pages.length === 0) {
+        explain("The docs artifact is empty.", "", [
+            "pnpm --filter @devdogsuga/docs build",
+        ]);
+        process.exitCode = 1;
+        return;
+    }
+    // Non-local is opt-in because of the delete. `--target remote` is how the
+    // deploy scripts say yes; a person gets asked, which the predecessor could
+    // not do from a `process.argv` check in a bare script.
+    if (!isLocalDatabase(url)) {
+        if (options.target !== "remote") {
+            if (!process.stdin.isTTY) {
+                explain("That is not a local database, and --target remote was not given.", "", [
+                    "It deletes the rows for pages that no longer exist, so this would",
+                    "replace the live search index with your working copy.",
+                ]);
+                process.exitCode = 1;
+                return;
+            }
+            const go = unwrap(await confirm({
+                message: "DB_URL is NOT local. Replace that database's search index with " +
+                    "this working copy?",
+                initialValue: false,
+            }));
+            if (!go)
+                bail("Left the index alone.");
+        }
+        else {
+            log.warn("Indexing a non-local database, as --target remote asked.");
+        }
+    }
+    const s = spinner();
+    s.start(`Indexing ${pages.length} page(s)`);
+    const db = connect(url);
+    try {
+        const count = await indexPages(db, pages);
+        s.stop(`Indexed ${count} page(s)`);
+    }
+    catch (err) {
+        s.stop("The index was not written");
+        explain("Writing the docs index failed.", errorMessage(err), [
+            "`pnpm devtools db migrate` applies any migration the table is missing.",
+        ]);
+        process.exitCode = 1;
+    }
+    finally {
+        await db.end();
+    }
+}

package/dist/doctor.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Does my app's moderation integration actually work?
+ *
+ * Two checks, and the second is the one that matters.
+ *
+ * `conformance()` asks the database what it derived from your schema: is the
+ * table addressable, can an author be attributed, does quarantine have a column
+ * to write to, can a client still write that column. All of it is answerable
+ * from the catalog, and `platform.conformance_check()` does the answering.
+ *
+ * `quarantineRoundTrip()` answers the question the catalog cannot: *does
+ * quarantine do anything?* Quarantine is the only moderation outcome whose
+ * effect lives in the app's own policies rather than the platform's, so it is
+ * the only one that can be wired up wrong while everything appears to work.
+ * The platform records the decision, sets the column, and has no way to notice
+ * nobody reads it. The only proof is to file, resolve, and then look.
+ *
+ * It runs against `platform.profile`, where quarantine means FREEZE rather than
+ * hide: the display name is reset to the member's name of record and they lose
+ * the ability to change it back. A profile cannot be hidden: rosters, teams
+ * and standings all render the name, and the row is own-row-only over PostgREST
+ * anyway, so there is nobody to hide it from. See
+ * 20260808000000_platform_profile_moderation.sql.
+ *
+ * Both run as seeded personas over PostgREST rather than as `postgres` over
+ * SQL, because RLS is the thing under test and a superuser bypasses it.
+ */
+import { type Instance } from "./instance.js";
+import type { CheckResult } from "./ui.js";
+interface ConformanceType {
+    contentType: string;
+    /** Schema-qualified, e.g. `platform.profile`. */
+    tableName: string;
+    checks: CheckResult[];
+}
+/** Runs `platform.conformance_check()` as the seeded moderator. */
+export declare function conformance(instance: Instance, appSlug: string): Promise<ConformanceType[]>;
+/** The apps that have anything to check, for the picker. */
+export declare function listApps(instance: Instance): Promise<string[]>;
+export interface RoundTripStep {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+/**
+ * Files a report against a profile, resolves it with quarantine, and checks
+ * that the freeze and the name reset both landed.
+ *
+ * The subject is a THROWAWAY member created for the run, not one of the seeded
+ * personas, and that is not squeamishness about touching fixtures.
+ * `file_report` corroborates an existing open report rather than filing a
+ * second one against the same content, and the seeds ship exactly such a report
+ * against the author persona's profile. Reusing it would make this function's
+ * first step silently become "add a corroboration", and every assertion after
+ * it would be reading the seed's decision instead of its own.
+ *
+ * Everything it creates, it deletes, including on the failure paths, which is
+ * why the teardown is in a `finally`. A contributor running this twice should
+ * get the same answer the second time.
+ */
+export declare function quarantineRoundTrip(instance: Instance): Promise<RoundTripStep[]>;
+export {};