@mccaskie-labs/workbench-supabase 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @mccaskie-labs/workbench-supabase
+
+## 0.1.0
+
+- First version (step 4.11): `supabaseConfig`, `createBrowserClient`, `createServerClient`, `createUserClient`, `createServiceClient` (logs its reason once per isolate), `WorkbenchSupabaseError`, and the CLI's `check:migrations`, `check:prod-schema` and `prod-schema-sql` (`docs/spec.md` §3).

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @mccaskie-labs/workbench-supabase
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Supabase for apps built on Workbench, a private platform. Each app has its own Supabase projects (`<id>-staging`, `<id>-production`), and Workbench Control writes their URL and keys onto the app's Workers, so the app holds no other Supabase credential. Published publicly so Workbench projects can install it with no token; it is not supported for other uses.
+
+```sh
+npm install @mccaskie-labs/workbench-supabase @mccaskie-labs/workbench-config zod
+```
+
+```ts
+import { createUserClient, createServiceClient, supabaseConfig } from '@mccaskie-labs/workbench-supabase'
+import { workerSecret } from '@mccaskie-labs/workbench-config'
+
+const cfg = supabaseConfig(env) // SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY; throws naming any that are missing
+const db = createUserClient({ ...cfg, accessToken }) // RLS applies as the caller
+const admin = createServiceClient({ url: cfg.url, secretKey: workerSecret(env, 'SUPABASE_SECRET_KEY'), reason: 'nightly clean-up' })
+```
+
+| Export | What it does |
+| --- | --- |
+| `supabaseConfig(env)` | `{ url, publishableKey }` from `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY`. One `WorkbenchConfigError` names every bad variable; no value is ever printed. Only `sb_publishable_` keys: legacy JWT keys are refused |
+| `createBrowserClient(cfg)` | In the browser: the signed-in user's session, kept in cookies (`@supabase/ssr`) |
+| `createServerClient({ ...cfg, cookies })` | On the server, as the signed-in user from the request's cookies. `cookies` is `{ getAll, setAll }` |
+| `createUserClient({ ...cfg, accessToken })` | As the caller, with the token they sent (audit F7). No session is stored or refreshed |
+| `createServiceClient({ url, secretKey, reason })` | The `sb_secret_` key: **bypasses RLS**. `reason` (one line) is logged once per isolate: `[workbench-supabase] service client (bypasses RLS): <reason>`. Refused in a browser and for a publishable key |
+| `WorkbenchSupabaseError` | A client built wrongly: `code` is `invalid_config` or `forbidden`. Never holds a key, URL or token |
+
+Every client takes an optional `fetch`, for tests against a fake Supabase.
+
+## Worker secrets
+
+Control writes them with `cf_worker_secret_put`, from the Worker's own database (`<id>-staging` Worker: `<id>-staging`; `<id>` Worker: `<id>-production`). Nobody types a value.
+
+| Secret | Source | Gate |
+| --- | --- | --- |
+| `SUPABASE_URL` | `supabase_url` | Free |
+| `SUPABASE_PUBLISHABLE_KEY` | `supabase_publishable` | Free |
+| `SUPABASE_SECRET_KEY` | `supabase_secret` | Two-step (Robert approves) |
+
+## Checks
+
+Add both to the project's `Checks`:
+
+```sh
+npx workbench-supabase check:migrations      # every supabase/migrations/<14 digits>_<name>.sql has supabase/rollback/<same>_down.sql
+npx workbench-supabase check:prod-schema     # code in src/ names nothing production's database lacks
+```
+
+`check:prod-schema` compares what the migrations create (public tables, views, functions and added columns) with `supabase/production-schema.json`, production's schema snapshot, and fails when a string literal in code bound for production (`src/` by default, or each `--code <path>`; tests are skipped) names something missing there. Refresh the snapshot after each production apply: run the SQL from `npx workbench-supabase prod-schema-sql` with `sb_query env=production` and save its `snapshot` value. Before production has a database, the snapshot is `{ "format": 1, "tables": {}, "functions": [] }`.
+
+A use that is kept off production by a switch is allowed by an entry in `supabase/prod-schema-allow.json`: `[{ "file": "src/x.ts", "names": ["notes"], "why": "only when WORKBENCH_ENV is staging" }]`. An entry that matches nothing fails too, so the list stays true.
+
+It is a tripwire, not a proof: it sees names in string literals only (`.from('x')`, `.rpc('x')`, `.select('a, x')`), not names built at run time.
+
+Runs on Node 24 and the Cloudflare Workers runtime (the CLI on Node only). `zod` 4 is a peer dependency, through `workbench-config`.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// workbench-supabase: the database checks a project runs in Checks.
+//
+//   workbench-supabase check:migrations [dir]
+//   workbench-supabase check:prod-schema [dir] [--code <path>]...
+//   workbench-supabase prod-schema-sql
+//
+// `dir` is the project root (default: the current folder). Offline; reads files only.
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { migrationProblems } from "./migrations.js";
+import { findUses, missingOnProduction, parseAllow, parseProductionSchema, PRODUCTION_SCHEMA_SQL, unusedAllows } from "./prod-schema.js";
+const MIGRATIONS = "supabase/migrations";
+const ROLLBACK = "supabase/rollback";
+const SNAPSHOT = "supabase/production-schema.json";
+const ALLOW = "supabase/prod-schema-allow.json";
+const CODE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+const SKIP_FILE = /(\.(test|spec)\.[cm]?[jt]sx?|\.d\.[cm]?ts)$/;
+const SKIP_DIR = new Set(["node_modules", "dist", ".wrangler", ".git", "test", "tests", "__tests__"]);
+const list = (dir) => (existsSync(dir) ? readdirSync(dir) : []);
+const posix = (p) => p.split(sep).join("/");
+function walk(root, path, out) {
+    if (!existsSync(path))
+        return;
+    if (statSync(path).isFile()) {
+        if (CODE_EXT.test(path) && !SKIP_FILE.test(path))
+            out.push(posix(relative(root, path)));
+        return;
+    }
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+        if (entry.isDirectory() && (SKIP_DIR.has(entry.name) || entry.name.startsWith(".")))
+            continue;
+        walk(root, join(path, entry.name), out);
+    }
+}
+function checkMigrations(dir) {
+    const ups = list(join(dir, MIGRATIONS));
+    const problems = migrationProblems(ups, list(join(dir, ROLLBACK)));
+    if (problems.length) {
+        for (const p of problems)
+            console.error(`${p.file}: ${p.problem}`);
+        console.error(`check:migrations failed: ${problems.length} problem(s).`);
+        return 1;
+    }
+    const count = ups.filter((f) => f.endsWith(".sql")).length;
+    console.log(`check:migrations passed: ${count} migration(s), each with a down file.`);
+    return 0;
+}
+function readJson(path, what) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`${what} isn't valid JSON: ${e.message}`);
+    }
+}
+function checkProdSchema(dir, code) {
+    const snapshotPath = join(dir, SNAPSHOT);
+    if (!existsSync(snapshotPath)) {
+        console.error(`check:prod-schema: no ${SNAPSHOT}. Save production's schema there: run \`workbench-supabase prod-schema-sql\` on production ` +
+            "(sb_query env=production) and save its snapshot value. Before production has a database, use " +
+            '{ "format": 1, "tables": {}, "functions": [] }.');
+        return 2;
+    }
+    let prod;
+    let allow;
+    try {
+        prod = parseProductionSchema(readJson(snapshotPath, SNAPSHOT));
+    }
+    catch (e) {
+        console.error(`check:prod-schema: ${SNAPSHOT}: ${e.message}`);
+        return 2;
+    }
+    try {
+        allow = existsSync(join(dir, ALLOW)) ? parseAllow(readJson(join(dir, ALLOW), ALLOW)) : [];
+    }
+    catch (e) {
+        console.error(`check:prod-schema: ${ALLOW}: ${e.message}`);
+        return 2;
+    }
+    const migrations = list(join(dir, MIGRATIONS))
+        .filter((f) => f.endsWith(".sql"))
+        .sort()
+        .map((f) => ({ stem: f.replace(/\.sql$/, ""), sql: readFileSync(join(dir, MIGRATIONS, f), "utf8") }));
+    const missing = missingOnProduction(migrations, prod);
+    const files = [];
+    for (const c of code.length ? code : ["src"])
+        walk(dir, join(dir, c), files);
+    const sources = [...new Set(files)].sort().map((path) => ({ path, text: readFileSync(join(dir, path), "utf8") }));
+    const uses = findUses(sources, missing, allow);
+    const bad = uses.filter((u) => !u.allowed);
+    const unused = unusedAllows(allow, uses);
+    console.log(`check:prod-schema: ${missing.size} name(s) in migrations that production lacks; scanned ${sources.length} file(s): ` +
+        `${uses.length} use(s), ${uses.length - bad.length} allowed.`);
+    if (bad.length) {
+        console.error("\nCode bound for production names something production's database doesn't have:");
+        for (const u of bad) {
+            const m = missing.get(u.name);
+            console.error(`  ${u.file}:${u.line} ${m.kind} ${m.label} (${m.migration})`);
+        }
+        console.error(`\nApply the migration on production first (then refresh ${SNAPSHOT}), or keep the use behind a switch that is off on ` +
+            `production and add an entry to ${ALLOW}: { "file", "names", "why" }.`);
+    }
+    if (unused.length) {
+        console.error(`\nEntries in ${ALLOW} that match nothing (remove them):`);
+        for (const u of unused)
+            console.error(`  ${u.file}: ${u.name}`);
+    }
+    if (bad.length || unused.length)
+        return 1;
+    console.log("OK. Limits: direct uses in string literals only; names built at run time aren't seen.");
+    return 0;
+}
+function main(argv) {
+    const [command, ...rest] = argv;
+    const code = [];
+    const positional = [];
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === "--code" && rest[i + 1])
+            code.push(rest[++i]);
+        else
+            positional.push(rest[i]);
+    }
+    const dir = positional[0] ?? ".";
+    if (command === "check:migrations")
+        return checkMigrations(dir);
+    if (command === "check:prod-schema")
+        return checkProdSchema(dir, code);
+    if (command === "prod-schema-sql") {
+        console.log(PRODUCTION_SCHEMA_SQL);
+        return 0;
+    }
+    console.error("Usage: workbench-supabase check:migrations [dir] | check:prod-schema [dir] [--code <path>]... | prod-schema-sql");
+    return 2;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/clients.d.ts

@@ -0,0 +1,39 @@
+import { type CookieMethodsServer } from "@supabase/ssr";
+import { type SupabaseClient } from "@supabase/supabase-js";
+/** Reads and writes the request's cookies: `getAll` from the request, `setAll` onto the response. */
+export type CookieAdapter = CookieMethodsServer;
+type Fetch = typeof fetch;
+interface PublicConfig {
+    url: string;
+    publishableKey: string;
+    /** For tests: a fake Supabase. Defaults to the global fetch. */
+    fetch?: Fetch;
+}
+/** In the browser: the signed-in user's session, kept in cookies so the server sees it too. */
+export declare function createBrowserClient<DB = any>(cfg: PublicConfig): SupabaseClient<DB>;
+/** On the server, acting as the signed-in user whose session is in the request's cookies. */
+export declare function createServerClient<DB = any>(cfg: PublicConfig & {
+    cookies: CookieAdapter;
+}): SupabaseClient<DB>;
+/**
+ * Acts as the caller, with the access token they sent (audit F7): RLS applies
+ * as that user. No session is stored or refreshed, and `auth` methods are
+ * unavailable on this client.
+ */
+export declare function createUserClient<DB = any>(cfg: PublicConfig & {
+    accessToken: string;
+}): SupabaseClient<DB>;
+/** Forgets which reasons were logged, so a test can see the line again. */
+export declare function resetServiceLog(): void;
+/**
+ * The secret key: bypasses RLS. `reason` says why this code needs that, and is
+ * logged once per isolate (per reason), so every use is visible in the
+ * Worker's logs. Refused in a browser, and refused for a publishable key.
+ */
+export declare function createServiceClient<DB = any>(cfg: {
+    url: string;
+    secretKey: string;
+    reason: string;
+    fetch?: Fetch;
+}): SupabaseClient<DB>;
+export {};

package/dist/clients.js

@@ -0,0 +1,85 @@
+// The four Supabase clients (docs/spec.md §3). Lifted from Imprint's
+// apps/admin/lib/supabase-server.ts, supabase-browser.ts and
+// packages/site-kit/src/lib/supabase.ts.
+//
+//   createBrowserClient  in the browser, the signed-in user's session in cookies
+//   createServerClient   on the server, acting as the signed-in user (@supabase/ssr)
+//   createUserClient     the caller's own access token, no session handling (audit F7)
+//   createServiceClient  the secret key: bypasses RLS, so it needs a reason, which
+//                        is logged once per isolate
+import { createBrowserClient as ssrBrowser, createServerClient as ssrServer } from "@supabase/ssr";
+import { createClient } from "@supabase/supabase-js";
+import { PUBLISHABLE_PREFIX, SECRET_PREFIX, urlProblem } from "./config.js";
+import { WorkbenchSupabaseError } from "./errors.js";
+function checkUrl(url) {
+    if (typeof url !== "string" || urlProblem(url)) {
+        throw new WorkbenchSupabaseError("invalid_config", "The Supabase URL is missing or invalid: expected https://<project ref>.supabase.co, or the local stack.");
+    }
+    return url.replace(/\/+$/, "");
+}
+function checkPublishable(key) {
+    if (typeof key !== "string" || !key.startsWith(PUBLISHABLE_PREFIX)) {
+        throw new WorkbenchSupabaseError("invalid_config", key?.startsWith?.(SECRET_PREFIX)
+            ? "A secret key was passed where the publishable key belongs. Use createServiceClient for the secret key."
+            : `Expected a ${PUBLISHABLE_PREFIX} key.`);
+    }
+    return key;
+}
+const global = (f) => (f ? { global: { fetch: f } } : {});
+/** In the browser: the signed-in user's session, kept in cookies so the server sees it too. */
+export function createBrowserClient(cfg) {
+    return ssrBrowser(checkUrl(cfg.url), checkPublishable(cfg.publishableKey), { ...global(cfg.fetch) });
+}
+/** On the server, acting as the signed-in user whose session is in the request's cookies. */
+export function createServerClient(cfg) {
+    if (!cfg.cookies || typeof cfg.cookies.getAll !== "function") {
+        throw new WorkbenchSupabaseError("invalid_config", "createServerClient needs a cookie adapter with getAll (and setAll to write refreshed sessions).");
+    }
+    return ssrServer(checkUrl(cfg.url), checkPublishable(cfg.publishableKey), { cookies: cfg.cookies, ...global(cfg.fetch) });
+}
+/**
+ * Acts as the caller, with the access token they sent (audit F7): RLS applies
+ * as that user. No session is stored or refreshed, and `auth` methods are
+ * unavailable on this client.
+ */
+export function createUserClient(cfg) {
+    if (typeof cfg.accessToken !== "string" || cfg.accessToken === "") {
+        throw new WorkbenchSupabaseError("invalid_config", "createUserClient needs the caller's access token.");
+    }
+    const token = cfg.accessToken;
+    return createClient(checkUrl(cfg.url), checkPublishable(cfg.publishableKey), {
+        accessToken: async () => token,
+        ...global(cfg.fetch),
+    });
+}
+const logged = new Set();
+/** Forgets which reasons were logged, so a test can see the line again. */
+export function resetServiceLog() {
+    logged.clear();
+}
+/**
+ * The secret key: bypasses RLS. `reason` says why this code needs that, and is
+ * logged once per isolate (per reason), so every use is visible in the
+ * Worker's logs. Refused in a browser, and refused for a publishable key.
+ */
+export function createServiceClient(cfg) {
+    if ("document" in globalThis) {
+        throw new WorkbenchSupabaseError("forbidden", "createServiceClient runs on the server only: the secret key must never reach a browser.");
+    }
+    if (typeof cfg.secretKey !== "string" || !cfg.secretKey.startsWith(SECRET_PREFIX)) {
+        throw new WorkbenchSupabaseError("invalid_config", `createServiceClient needs a ${SECRET_PREFIX} key (SUPABASE_SECRET_KEY).`);
+    }
+    const reason = typeof cfg.reason === "string" ? cfg.reason.trim() : "";
+    if (reason.length < 3 || reason.length > 200 || /[\r\n]/.test(reason)) {
+        throw new WorkbenchSupabaseError("invalid_config", "createServiceClient needs a reason: one line, 3 to 200 characters, saying why RLS is bypassed.");
+    }
+    const url = checkUrl(cfg.url);
+    if (!logged.has(reason)) {
+        logged.add(reason);
+        console.info(`[workbench-supabase] service client (bypasses RLS): ${reason}`);
+    }
+    return createClient(url, cfg.secretKey, {
+        auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
+        ...global(cfg.fetch),
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+/** Where an app finds its own Supabase project (docs/spec.md §3). Both values are public. */
+export interface SupabaseConfig {
+    url: string;
+    publishableKey: string;
+}
+export declare const URL_VARIABLE = "SUPABASE_URL";
+export declare const PUBLISHABLE_VARIABLE = "SUPABASE_PUBLISHABLE_KEY";
+/** The secret key's Worker secret, written by Control (cf_worker_secret_put source=supabase_secret). Never in this config. */
+export declare const SECRET_VARIABLE = "SUPABASE_SECRET_KEY";
+export declare const PUBLISHABLE_PREFIX = "sb_publishable_";
+export declare const SECRET_PREFIX = "sb_secret_";
+/** A problem with the URL, in words that never include it. Null when it's fine. */
+export declare function urlProblem(url: string): string | null;
+/**
+ * Reads SUPABASE_URL and SUPABASE_PUBLISHABLE_KEY. Throws one
+ * WorkbenchConfigError naming every missing or invalid variable; never prints
+ * a value and never falls back to a default (audit F18). Legacy JWT keys
+ * (anon, service_role) are refused: Control only ever writes sb_publishable_
+ * and sb_secret_ keys.
+ */
+export declare function supabaseConfig(env: Record<string, unknown>): SupabaseConfig;

package/dist/config.js

@@ -0,0 +1,48 @@
+import { WorkbenchConfigError } from "@mccaskie-labs/workbench-config";
+export const URL_VARIABLE = "SUPABASE_URL";
+export const PUBLISHABLE_VARIABLE = "SUPABASE_PUBLISHABLE_KEY";
+/** The secret key's Worker secret, written by Control (cf_worker_secret_put source=supabase_secret). Never in this config. */
+export const SECRET_VARIABLE = "SUPABASE_SECRET_KEY";
+export const PUBLISHABLE_PREFIX = "sb_publishable_";
+export const SECRET_PREFIX = "sb_secret_";
+const HOSTED = /^https:\/\/[a-z0-9]{20}\.supabase\.co$/;
+const LOCAL = /^http:\/\/(127\.0\.0\.1|localhost):\d{2,5}$/;
+/** A problem with the URL, in words that never include it. Null when it's fine. */
+export function urlProblem(url) {
+    const trimmed = url.replace(/\/+$/, "");
+    if (HOSTED.test(trimmed) || LOCAL.test(trimmed))
+        return null;
+    return "expected https://<project ref>.supabase.co, or http://127.0.0.1:<port> for the local stack";
+}
+/**
+ * Reads SUPABASE_URL and SUPABASE_PUBLISHABLE_KEY. Throws one
+ * WorkbenchConfigError naming every missing or invalid variable; never prints
+ * a value and never falls back to a default (audit F18). Legacy JWT keys
+ * (anon, service_role) are refused: Control only ever writes sb_publishable_
+ * and sb_secret_ keys.
+ */
+export function supabaseConfig(env) {
+    const problems = [];
+    const url = env[URL_VARIABLE];
+    const key = env[PUBLISHABLE_VARIABLE];
+    if (typeof url !== "string" || url === "")
+        problems.push({ variable: URL_VARIABLE, problem: "missing" });
+    else {
+        const why = urlProblem(url);
+        if (why)
+            problems.push({ variable: URL_VARIABLE, problem: "invalid", detail: why });
+    }
+    if (typeof key !== "string" || key === "")
+        problems.push({ variable: PUBLISHABLE_VARIABLE, problem: "missing" });
+    else if (key.startsWith(SECRET_PREFIX)) {
+        problems.push({ variable: PUBLISHABLE_VARIABLE, problem: "invalid", detail: `holds a secret key; it must be a ${PUBLISHABLE_PREFIX} key` });
+    }
+    else if (!key.startsWith(PUBLISHABLE_PREFIX)) {
+        problems.push({ variable: PUBLISHABLE_VARIABLE, problem: "invalid", detail: `expected a ${PUBLISHABLE_PREFIX} key (legacy anon keys aren't used)` });
+    }
+    if (problems.length) {
+        const code = problems.every((p) => p.problem === "missing") ? "missing_variable" : "invalid_variable";
+        throw new WorkbenchConfigError(code, problems);
+    }
+    return { url: url.replace(/\/+$/, ""), publishableKey: key };
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export type SupabaseErrorCode = "invalid_config" | "forbidden";
+/** A client built wrongly. The message never holds a key, URL or token. */
+export declare class WorkbenchSupabaseError extends Error {
+    readonly code: SupabaseErrorCode;
+    constructor(code: SupabaseErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+/** A client built wrongly. The message never holds a key, URL or token. */
+export class WorkbenchSupabaseError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WorkbenchSupabaseError";
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { supabaseConfig, URL_VARIABLE, PUBLISHABLE_VARIABLE, SECRET_VARIABLE, PUBLISHABLE_PREFIX, SECRET_PREFIX, type SupabaseConfig, } from "./config.ts";
+export { createBrowserClient, createServerClient, createUserClient, createServiceClient, resetServiceLog, type CookieAdapter } from "./clients.ts";
+export { WorkbenchSupabaseError, type SupabaseErrorCode } from "./errors.ts";
+export { migrationProblems, type MigrationProblem } from "./migrations.ts";
+export { PRODUCTION_SCHEMA_SQL, createdBy, missingOnProduction, findUses, unusedAllows, parseProductionSchema, parseAllow, type ProductionSchema, type AllowEntry, type MissingName, type Use, } from "./prod-schema.ts";
+export { stringPieces, type StringPiece } from "./strings.ts";
+export type { SupabaseClient } from "@supabase/supabase-js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { supabaseConfig, URL_VARIABLE, PUBLISHABLE_VARIABLE, SECRET_VARIABLE, PUBLISHABLE_PREFIX, SECRET_PREFIX, } from "./config.js";
+export { createBrowserClient, createServerClient, createUserClient, createServiceClient, resetServiceLog } from "./clients.js";
+export { WorkbenchSupabaseError } from "./errors.js";
+export { migrationProblems } from "./migrations.js";
+export { PRODUCTION_SCHEMA_SQL, createdBy, missingOnProduction, findUses, unusedAllows, parseProductionSchema, parseAllow, } from "./prod-schema.js";
+export { stringPieces } from "./strings.js";

package/dist/migrations.d.ts

@@ -0,0 +1,11 @@
+export declare const MIGRATION_NAME: RegExp;
+export declare const DOWN_NAME: RegExp;
+export interface MigrationProblem {
+    file: string;
+    problem: string;
+}
+/**
+ * `migrations` and `rollback` are the file names in supabase/migrations and
+ * supabase/rollback. Dotfiles (.gitkeep) are ignored.
+ */
+export declare function migrationProblems(migrations: string[], rollback: string[]): MigrationProblem[];

package/dist/migrations.js

@@ -0,0 +1,42 @@
+// check:migrations (docs/spec.md §3): every supabase/migrations/<14 digits>_<name>.sql
+// has supabase/rollback/<same>_down.sql, and names are valid. Control's
+// sb_migration_apply refuses a file with no down file, so this catches it in CI.
+export const MIGRATION_NAME = /^(\d{14})_([a-z0-9][a-z0-9_]*)\.sql$/;
+export const DOWN_NAME = /^(\d{14})_([a-z0-9][a-z0-9_]*)_down\.sql$/;
+/**
+ * `migrations` and `rollback` are the file names in supabase/migrations and
+ * supabase/rollback. Dotfiles (.gitkeep) are ignored.
+ */
+export function migrationProblems(migrations, rollback) {
+    const problems = [];
+    const ups = new Map();
+    const versions = new Map();
+    for (const f of migrations.filter((x) => !x.startsWith(".")).sort()) {
+        const m = MIGRATION_NAME.exec(f);
+        if (!m) {
+            problems.push({ file: `supabase/migrations/${f}`, problem: "the name isn't <14 digits>_<lower case name>.sql" });
+            continue;
+        }
+        const seen = versions.get(m[1]);
+        if (seen)
+            problems.push({ file: `supabase/migrations/${f}`, problem: `version ${m[1]} is also used by ${seen}` });
+        versions.set(m[1], f);
+        ups.set(f.replace(/\.sql$/, ""), f);
+    }
+    const downs = new Set();
+    for (const f of rollback.filter((x) => !x.startsWith(".")).sort()) {
+        if (!DOWN_NAME.test(f)) {
+            problems.push({ file: `supabase/rollback/${f}`, problem: "the name isn't <14 digits>_<name>_down.sql" });
+            continue;
+        }
+        const stem = f.replace(/_down\.sql$/, "");
+        downs.add(stem);
+        if (!ups.has(stem))
+            problems.push({ file: `supabase/rollback/${f}`, problem: `no migration ${stem}.sql for this down file` });
+    }
+    for (const [stem, f] of ups) {
+        if (!downs.has(stem))
+            problems.push({ file: `supabase/migrations/${f}`, problem: `no down file: add supabase/rollback/${stem}_down.sql` });
+    }
+    return problems;
+}

package/dist/prod-schema.d.ts

@@ -0,0 +1,58 @@
+export interface ProductionSchema {
+    format: 1;
+    /** Tables and views in `public`, each with its columns. */
+    tables: Record<string, string[]>;
+    /** Functions in `public`. */
+    functions: string[];
+}
+/** One allowed use: `file` may name `names` because `why` (the switch that keeps it off production). */
+export interface AllowEntry {
+    file: string;
+    names: string[];
+    why: string;
+}
+export interface CreatedNames {
+    tables: string[];
+    functions: string[];
+    columns: Array<[table: string, column: string]>;
+}
+export interface MissingName {
+    kind: "table" | "function" | "column";
+    /** The name as code would write it. */
+    name: string;
+    /** `table.column` for a column. */
+    label: string;
+    migration: string;
+}
+export interface Use {
+    file: string;
+    line: number;
+    name: string;
+    allowed: boolean;
+}
+/**
+ * The query whose one row is the snapshot, read through pg_catalog so it works
+ * as a restricted read-only role. Run it on production (sb_query env=production)
+ * and save the `snapshot` value as supabase/production-schema.json.
+ */
+export declare const PRODUCTION_SCHEMA_SQL = "select json_build_object(\n  'format', 1,\n  'tables', coalesce((\n    select json_object_agg(relname, cols order by relname) from (\n      select c.relname, json_agg(a.attname::text order by a.attnum) as cols\n      from pg_catalog.pg_class c\n      join pg_catalog.pg_namespace n on n.oid = c.relnamespace\n      join pg_catalog.pg_attribute a on a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped\n      where n.nspname = 'public' and c.relkind in ('r', 'p', 'v', 'm', 'f')\n      group by c.relname\n    ) t\n  ), '{}'::json),\n  'functions', coalesce((\n    select json_agg(distinct p.proname::text order by p.proname::text)\n    from pg_catalog.pg_proc p\n    join pg_catalog.pg_namespace n on n.oid = p.pronamespace\n    where n.nspname = 'public'\n  ), '[]'::json)\n) as snapshot";
+/** Checks the snapshot's shape. Throws with a plain reason. */
+export declare function parseProductionSchema(json: unknown): ProductionSchema;
+export declare function parseAllow(json: unknown): AllowEntry[];
+/** What a migration creates in `public`: tables and views, functions, and columns added to existing tables. */
+export declare function createdBy(sql: string): CreatedNames;
+/** Every name the repo's migrations create that production's snapshot lacks. */
+export declare function missingOnProduction(migrations: Array<{
+    stem: string;
+    sql: string;
+}>, prod: ProductionSchema): Map<string, MissingName>;
+/** Every use of a missing name inside a string literal, with whether the allow list covers it. */
+export declare function findUses(files: Array<{
+    path: string;
+    text: string;
+}>, missing: Map<string, MissingName>, allow: AllowEntry[]): Use[];
+/** Allow entries that match no use: stale, so they fail too and the list stays true. */
+export declare function unusedAllows(allow: AllowEntry[], uses: Use[]): Array<{
+    file: string;
+    name: string;
+}>;

package/dist/prod-schema.js

@@ -0,0 +1,168 @@
+// check:prod-schema (docs/spec.md §3): fails when code bound for production
+// names a table, view, column or function that production's database doesn't
+// have. Imprint's scripts/check-prod-schema.mjs, made generic: instead of a
+// list of migrations applied on production, production's schema is a snapshot,
+// supabase/production-schema.json, refreshed after each production apply
+// (from sb_schema_fingerprint once it is built; until then from
+// PRODUCTION_SCHEMA_SQL through sb_query, read-only).
+//
+// It is a tripwire, not a proof. It sees direct uses only: names inside string
+// literals, as whole words. Names built at run time aren't seen, and a column
+// with a common word for a name matches any string holding that word (allow it,
+// or rename it).
+import { stringPieces } from "./strings.js";
+/**
+ * The query whose one row is the snapshot, read through pg_catalog so it works
+ * as a restricted read-only role. Run it on production (sb_query env=production)
+ * and save the `snapshot` value as supabase/production-schema.json.
+ */
+export const PRODUCTION_SCHEMA_SQL = `select json_build_object(
+  'format', 1,
+  'tables', coalesce((
+    select json_object_agg(relname, cols order by relname) from (
+      select c.relname, json_agg(a.attname::text order by a.attnum) as cols
+      from pg_catalog.pg_class c
+      join pg_catalog.pg_namespace n on n.oid = c.relnamespace
+      join pg_catalog.pg_attribute a on a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped
+      where n.nspname = 'public' and c.relkind in ('r', 'p', 'v', 'm', 'f')
+      group by c.relname
+    ) t
+  ), '{}'::json),
+  'functions', coalesce((
+    select json_agg(distinct p.proname::text order by p.proname::text)
+    from pg_catalog.pg_proc p
+    join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'public'
+  ), '[]'::json)
+) as snapshot`;
+/** Checks the snapshot's shape. Throws with a plain reason. */
+export function parseProductionSchema(json) {
+    const s = json;
+    if (!s || typeof s !== "object" || s.format !== 1)
+        throw new Error("format must be 1");
+    if (!s.tables || typeof s.tables !== "object" || Array.isArray(s.tables))
+        throw new Error("tables must be an object of table name to column names");
+    for (const [t, cols] of Object.entries(s.tables)) {
+        if (!Array.isArray(cols) || !cols.every((c) => typeof c === "string"))
+            throw new Error(`tables.${t} must be a list of column names`);
+    }
+    if (!Array.isArray(s.functions) || !s.functions.every((f) => typeof f === "string"))
+        throw new Error("functions must be a list of names");
+    return s;
+}
+export function parseAllow(json) {
+    if (!Array.isArray(json))
+        throw new Error("the allow list must be an array of { file, names, why }");
+    return json.map((e, i) => {
+        const x = e;
+        if (typeof x?.file !== "string" || !Array.isArray(x.names) || !x.names.every((n) => typeof n === "string") || typeof x.why !== "string" || x.why.trim() === "") {
+            throw new Error(`entry ${i} needs file, names and why (the switch that keeps the use off production)`);
+        }
+        return { file: x.file, names: x.names, why: x.why };
+    });
+}
+const stripSql = (sql) => sql.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--[^\n]*/g, " ");
+const NAME = String.raw `(?:"?(\w+)"?\s*\.\s*)?"?(\w+)"?`;
+const isPublic = (schema) => !schema || schema.toLowerCase() === "public";
+/** What a migration creates in `public`: tables and views, functions, and columns added to existing tables. */
+export function createdBy(sql) {
+    const s = stripSql(sql);
+    const out = { tables: [], functions: [], columns: [] };
+    for (const m of s.matchAll(new RegExp(String.raw `\bcreate\s+(?:(?:unlogged|temp|temporary)\s+)?table\s+(?:if\s+not\s+exists\s+)?${NAME}`, "gi"))) {
+        if (isPublic(m[1]))
+            out.tables.push(m[2].toLowerCase());
+    }
+    for (const m of s.matchAll(new RegExp(String.raw `\bcreate\s+(?:or\s+replace\s+)?(?:materialized\s+)?view\s+(?:if\s+not\s+exists\s+)?${NAME}`, "gi"))) {
+        if (isPublic(m[1]))
+            out.tables.push(m[2].toLowerCase());
+    }
+    for (const m of s.matchAll(new RegExp(String.raw `\bcreate\s+(?:or\s+replace\s+)?function\s+${NAME}`, "gi"))) {
+        if (isPublic(m[1]))
+            out.functions.push(m[2].toLowerCase());
+    }
+    for (const m of s.matchAll(new RegExp(String.raw `\balter\s+table\s+(?:if\s+exists\s+)?(?:only\s+)?${NAME}([^;]*);`, "gi"))) {
+        if (!isPublic(m[1]))
+            continue;
+        for (const c of m[3].matchAll(/\badd\s+(?:column\s+)?(?:if\s+not\s+exists\s+)?"?(\w+)"?/gi)) {
+            const col = c[1].toLowerCase();
+            if (["constraint", "primary", "unique", "foreign", "check", "exclude"].includes(col))
+                continue;
+            out.columns.push([m[2].toLowerCase(), col]);
+        }
+    }
+    return out;
+}
+/** Every name the repo's migrations create that production's snapshot lacks. */
+export function missingOnProduction(migrations, prod) {
+    const tables = new Map(Object.entries(prod.tables).map(([t, cols]) => [t.toLowerCase(), new Set(cols.map((c) => c.toLowerCase()))]));
+    const functions = new Set(prod.functions.map((f) => f.toLowerCase()));
+    const out = new Map();
+    const add = (n) => {
+        if (!out.has(n.name))
+            out.set(n.name, n);
+    };
+    for (const { stem, sql } of migrations) {
+        const c = createdBy(sql);
+        for (const t of c.tables)
+            if (!tables.has(t))
+                add({ kind: "table", name: t, label: t, migration: stem });
+        for (const f of c.functions)
+            if (!functions.has(f))
+                add({ kind: "function", name: f, label: f, migration: stem });
+        for (const [t, col] of c.columns) {
+            // A column of a table production lacks is covered by the table itself.
+            const cols = tables.get(t);
+            if (cols && !cols.has(col))
+                add({ kind: "column", name: col, label: `${t}.${col}`, migration: stem });
+        }
+    }
+    return out;
+}
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Every use of a missing name inside a string literal, with whether the allow list covers it. */
+export function findUses(files, missing, allow) {
+    if (missing.size === 0)
+        return [];
+    const re = new RegExp(String.raw `(?<![A-Za-z0-9_])(${[...missing.keys()].sort((a, b) => b.length - a.length).map(escape).join("|")})(?![A-Za-z0-9_])`, "g");
+    const uses = [];
+    for (const { path, text } of files) {
+        re.lastIndex = 0;
+        const found = re.test(text);
+        // matchAll copies lastIndex, so reset it before reading the pieces.
+        re.lastIndex = 0;
+        if (!found)
+            continue;
+        const lineStarts = [0];
+        for (let i = 0; i < text.length; i++)
+            if (text[i] === "\n")
+                lineStarts.push(i + 1);
+        const lineOf = (pos) => {
+            let lo = 0;
+            let hi = lineStarts.length - 1;
+            while (lo < hi) {
+                const mid = (lo + hi + 1) >> 1;
+                if (lineStarts[mid] <= pos)
+                    lo = mid;
+                else
+                    hi = mid - 1;
+            }
+            return lo + 1;
+        };
+        for (const piece of stringPieces(text)) {
+            for (const m of piece.text.matchAll(re)) {
+                const name = m[1];
+                uses.push({ file: path, line: lineOf(piece.start + m.index), name, allowed: allow.some((a) => a.file === path && a.names.includes(name)) });
+            }
+        }
+    }
+    return uses;
+}
+/** Allow entries that match no use: stale, so they fail too and the list stays true. */
+export function unusedAllows(allow, uses) {
+    const out = [];
+    for (const a of allow)
+        for (const n of a.names)
+            if (!uses.some((u) => u.allowed && u.file === a.file && u.name === n))
+                out.push({ file: a.file, name: n });
+    return out;
+}

package/dist/strings.d.ts

@@ -0,0 +1,7 @@
+export interface StringPiece {
+    /** Offset of the text's first character in the source. */
+    start: number;
+    text: string;
+}
+/** Every string literal and template text in `src`, in order. */
+export declare function stringPieces(src: string): StringPiece[];

package/dist/strings.js

@@ -0,0 +1,135 @@
+// A small JavaScript and TypeScript lexer that finds string literals and
+// template text, and skips comments and regular expressions. supabase-js names
+// tables, columns and functions in strings (.from('x'), .rpc('x'),
+// .select('a, x')), so these are where check:prod-schema looks. Imprint used
+// the TypeScript compiler API; TypeScript 7 has none, so this is hand-written.
+// It is a tripwire, not a parser: a regular expression after a keyword other
+// than those below (or in JSX text) may be read as division.
+const REGEX_AFTER_WORD = new Set([
+    "return", "typeof", "instanceof", "in", "of", "new", "delete", "void", "throw", "case", "do", "else", "yield", "await",
+]);
+/** Every string literal and template text in `src`, in order. */
+export function stringPieces(src) {
+    const out = [];
+    // For each open template, the brace depth inside its current ${ }.
+    const templates = [];
+    let i = 0;
+    // Whether a `/` here starts a regular expression (true) or is division.
+    let regexOk = true;
+    const readTemplate = (from) => {
+        // From just after ` or }, up to and including the closing ` or ${.
+        let j = from;
+        while (j < src.length) {
+            const c = src[j];
+            if (c === "\\") {
+                j += 2;
+                continue;
+            }
+            if (c === "`") {
+                out.push({ start: from, text: src.slice(from, j) });
+                return j + 1;
+            }
+            if (c === "$" && src[j + 1] === "{") {
+                out.push({ start: from, text: src.slice(from, j) });
+                templates.push(0);
+                return j + 2;
+            }
+            j++;
+        }
+        out.push({ start: from, text: src.slice(from) });
+        return src.length;
+    };
+    while (i < src.length) {
+        const c = src[i];
+        const next = src[i + 1];
+        if (c === "/" && next === "/") {
+            const end = src.indexOf("\n", i);
+            i = end < 0 ? src.length : end;
+            continue;
+        }
+        if (c === "/" && next === "*") {
+            const end = src.indexOf("*/", i + 2);
+            i = end < 0 ? src.length : end + 2;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            let j = i + 1;
+            while (j < src.length && src[j] !== c && src[j] !== "\n")
+                j += src[j] === "\\" ? 2 : 1;
+            out.push({ start: i + 1, text: src.slice(i + 1, j) });
+            i = j + 1;
+            regexOk = false;
+            continue;
+        }
+        if (c === "`") {
+            i = readTemplate(i + 1);
+            regexOk = false;
+            continue;
+        }
+        if (c === "{" && templates.length) {
+            templates[templates.length - 1]++;
+            i++;
+            regexOk = true;
+            continue;
+        }
+        if (c === "}" && templates.length) {
+            if (templates[templates.length - 1] === 0) {
+                templates.pop();
+                i = readTemplate(i + 1);
+                regexOk = false;
+                continue;
+            }
+            templates[templates.length - 1]--;
+            i++;
+            regexOk = false;
+            continue;
+        }
+        if (c === "/" && regexOk) {
+            let j = i + 1;
+            let inClass = false;
+            while (j < src.length && src[j] !== "\n") {
+                const d = src[j];
+                if (d === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (d === "[")
+                    inClass = true;
+                else if (d === "]")
+                    inClass = false;
+                else if (d === "/" && !inClass)
+                    break;
+                j++;
+            }
+            i = j + 1;
+            while (i < src.length && /[a-z]/i.test(src[i]))
+                i++;
+            regexOk = false;
+            continue;
+        }
+        if (/[A-Za-z_$]/.test(c)) {
+            let j = i + 1;
+            while (j < src.length && /[\w$]/.test(src[j]))
+                j++;
+            regexOk = REGEX_AFTER_WORD.has(src.slice(i, j));
+            i = j;
+            continue;
+        }
+        if (/[0-9]/.test(c)) {
+            let j = i + 1;
+            while (j < src.length && /[\w.]/.test(src[j]))
+                j++;
+            i = j;
+            regexOk = false;
+            continue;
+        }
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        // Punctuation: a regex may follow anything but a closing bracket.
+        regexOk = !(c === ")" || c === "]" || c === "}");
+        i++;
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@mccaskie-labs/workbench-supabase",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Supabase clients for Workbench apps (browser, server, the caller's own token, and a service client that logs its reason), plus check:migrations and check:prod-schema.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mccaskie-labs/workbench.git",
+    "directory": "packages/supabase"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "workbench-supabase": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.check.json && tsc -p test/tsconfig.json",
+    "test": "vitest run",
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs"
+  },
+  "dependencies": {
+    "@mccaskie-labs/workbench-config": "^0.1.3",
+    "@supabase/ssr": "^0.12.7",
+    "@supabase/supabase-js": "^2.119.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "vitest": "^5.1.0",
+    "zod": "4.6.7"
+  },
+  "peerDependencies": {
+    "zod": "^4.1.0"
+  }
+}