@mccaskie-labs/workbench-supabase 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @mccaskie-labs/workbench-supabase
 
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @mccaskie-labs/workbench-forms@0.2.0
+
+## 0.4.0
+
+- `check:limits`: compares the app's limits register (`workbench-forms`) with snapshots of the real columns on staging (required, and taken after every migration in the repo) and production (when there is one). `limits-sql` prints the read-only query for `sb_query`; `limits-save --env staging|production` saves its result, stamped with the repo's migrations, as `supabase/<env>-columns.json`.
+
 ## 0.3.0
 
 - `createSessions({ url, publishableKey, secret })`: app sign-in by typed emailed code with the session held by the server (authentication standard §4, §6, §10). `sendCode`, `verifyCode`, `read`, `signOut`, and a pending-sign-in cookie that grants nothing. The session is one AES-GCM sealed `__Host-session` cookie (Secure, HttpOnly, SameSite=Lax) with four dials: idle on a private device (14 days), on a shared one (30 minutes), an absolute cap (30 days, never moved by a refresh) and a freshness window (15 minutes). The access token is refreshed by the server and never reaches page script. Sign-out clears the cookie first, with every attribute, then ends this session only at Supabase.

package/README.md

@@ -80,4 +80,19 @@ A use that is kept off production by a switch is allowed by an entry in `supabas
 
 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.
 
+### check:limits
+
+```sh
+npx workbench-supabase check:limits            # src/limits.ts (or --register <path>) against the database's real column sizes
+```
+
+The register is the app's `LIMITS` from `@mccaskie-labs/workbench-forms/limits`. It is compared with `supabase/staging-columns.json` and, when there is one, `supabase/production-columns.json`. Refresh a snapshot right after migrations apply on that database:
+
+```sh
+npx workbench-supabase limits-sql               # the read-only query: run it with sb_query env=staging
+npx workbench-supabase limits-save --env staging --from result.json   # or pipe the result in
+```
+
+`limits-save` stamps the snapshot with the repo's migrations; `check:limits` fails when the staging snapshot is older than any migration in the repo, so it can't silently go stale. Text limits need `varchar(max)` or `text` with `check (char_length(col) <= max)`, money `numeric(p, scale)`, whole numbers an integer type holding the range (and equal `check` bounds when there are any), dates `date`.
+
 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.js

@@ -4,10 +4,14 @@
 //   workbench-supabase check:migrations [dir]
 //   workbench-supabase check:prod-schema [dir] [--code <path>]...
 //   workbench-supabase prod-schema-sql
+//   workbench-supabase check:limits [dir] [--register <path>]
+//   workbench-supabase limits-sql
+//   workbench-supabase limits-save [dir] --env staging|production [--from <file>]   (else reads stdin)
 //
 // `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 { LIMITS_SQL } from "./limits-sql.js";
 import { migrationProblems } from "./migrations.js";
 import { findUses, missingOnProduction, parseAllow, parseProductionSchema, PRODUCTION_SCHEMA_SQL, unusedAllows } from "./prod-schema.js";
 const MIGRATIONS = "supabase/migrations";
@@ -111,13 +115,22 @@ function checkProdSchema(dir, code) {
     console.log("OK. Limits: direct uses in string literals only; names built at run time aren't seen.");
     return 0;
 }
-function main(argv) {
+async function main(argv) {
     const [command, ...rest] = argv;
     const code = [];
     const positional = [];
+    let registerPath = "src/limits.ts";
+    let env = "";
+    let from = "";
     for (let i = 0; i < rest.length; i++) {
         if (rest[i] === "--code" && rest[i + 1])
             code.push(rest[++i]);
+        else if (rest[i] === "--register" && rest[i + 1])
+            registerPath = rest[++i];
+        else if (rest[i] === "--env" && rest[i + 1])
+            env = rest[++i];
+        else if (rest[i] === "--from" && rest[i + 1])
+            from = rest[++i];
         else
             positional.push(rest[i]);
     }
@@ -130,7 +143,21 @@ function main(argv) {
         console.log(PRODUCTION_SCHEMA_SQL);
         return 0;
     }
-    console.error("Usage: workbench-supabase check:migrations [dir] | check:prod-schema [dir] [--code <path>]... | prod-schema-sql");
+    if (command === "check:limits") {
+        // Loaded only here, so the other checks don't need workbench-forms.
+        const { checkLimits } = await import("./limits-check.js");
+        return checkLimits(dir, registerPath);
+    }
+    if (command === "limits-save") {
+        const { limitsSave } = await import("./limits-check.js");
+        return limitsSave(dir, env, readFileSync(from || 0, "utf8"));
+    }
+    if (command === "limits-sql") {
+        console.log(LIMITS_SQL);
+        return 0;
+    }
+    console.error("Usage: workbench-supabase check:migrations [dir] | check:prod-schema [dir] [--code <path>]... | prod-schema-sql | " +
+        "check:limits [dir] [--register <path>] | limits-sql | limits-save [dir] --env staging|production [--from <file>]");
     return 2;
 }
-process.exitCode = main(process.argv.slice(2));
+process.exitCode = await main(process.argv.slice(2));

package/dist/limits-check.d.ts

@@ -0,0 +1,8 @@
+/**
+ * limits-save: writes supabase/<env>-columns.json from LIMITS_SQL's result,
+ * stamped with the environment and the repo's migrations. Run it right after
+ * the migrations apply on that environment, so the stamp is true.
+ */
+export declare function limitsSave(dir: string, env: string, input: string): number;
+/** Runs check:limits and returns the exit code; messages go to the console. */
+export declare function checkLimits(dir: string, registerPath: string): Promise<number>;

package/dist/limits-check.js

@@ -0,0 +1,138 @@
+// check:limits (docs/spec.md §3; form-validation standard §4.1): the app's
+// limits register (workbench-forms) against the column snapshots in
+// supabase/staging-columns.json (required, and taken after every migration in
+// the repo) and supabase/production-columns.json (when there is one).
+// Offline: the snapshots come from LIMITS_SQL, run with sb_query, and are
+// saved by limits-save, which stamps them with the repo's migrations.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { defineLimits, limitsProblems, parseColumnSnapshot } from "@mccaskie-labs/workbench-forms/limits";
+const MIGRATIONS = "supabase/migrations";
+const COLUMNS = (env) => `supabase/${env}-columns.json`;
+const list = (dir) => (existsSync(dir) ? readdirSync(dir) : []);
+function readJson(path, what) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`${what} isn't valid JSON: ${e.message}`);
+    }
+}
+/** The repo's migration versions, oldest first. */
+function migrationVersions(dir) {
+    return list(join(dir, MIGRATIONS))
+        .map((f) => /^(\d{14})_.+\.sql$/.exec(f)?.[1])
+        .filter((v) => v !== undefined)
+        .sort();
+}
+/** The snapshot inside whatever sb_query returned: the object itself, { snapshot }, { rows: [...] } or a list of rows. */
+function findSnapshot(value, depth = 0) {
+    if (!value || typeof value !== "object" || depth > 4)
+        return null;
+    if (Array.isArray(value))
+        return value.length ? findSnapshot(value[0], depth + 1) : null;
+    const v = value;
+    if (v.format === 1 && v.columns && typeof v.columns === "object")
+        return v;
+    for (const key of ["snapshot", "rows", "result", "data"])
+        if (key in v)
+            return findSnapshot(v[key], depth + 1);
+    return null;
+}
+/**
+ * limits-save: writes supabase/<env>-columns.json from LIMITS_SQL's result,
+ * stamped with the environment and the repo's migrations. Run it right after
+ * the migrations apply on that environment, so the stamp is true.
+ */
+export function limitsSave(dir, env, input) {
+    if (env !== "staging" && env !== "production") {
+        console.error("limits-save: --env is staging or production");
+        return 2;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch (e) {
+        console.error(`limits-save: the input isn't JSON: ${e.message}`);
+        return 2;
+    }
+    const found = findSnapshot(parsed);
+    if (!found) {
+        console.error("limits-save: no snapshot in the input. Pass the result of `workbench-supabase limits-sql` run with sb_query.");
+        return 2;
+    }
+    const snapshot = { format: 1, env, migrations: migrationVersions(dir), columns: found.columns };
+    try {
+        parseColumnSnapshot(snapshot);
+    }
+    catch (e) {
+        console.error(`limits-save: ${e.message}`);
+        return 2;
+    }
+    writeFileSync(join(dir, COLUMNS(env)), `${JSON.stringify(snapshot, null, 2)}\n`);
+    console.log(`limits-save: wrote ${COLUMNS(env)} (${Object.keys(snapshot.columns).length} columns, ${snapshot.migrations.length} migrations).`);
+    return 0;
+}
+/** Runs check:limits and returns the exit code; messages go to the console. */
+export async function checkLimits(dir, registerPath) {
+    const path = resolve(dir, registerPath);
+    if (!existsSync(path)) {
+        console.error(`check:limits: no register at ${registerPath}. Export LIMITS = defineLimits({...}) from it (workbench-forms/limits), or pass --register <path>.`);
+        return 2;
+    }
+    let register;
+    try {
+        const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+        register = defineLimits((mod.LIMITS ?? mod.default));
+    }
+    catch (e) {
+        console.error(`check:limits: ${registerPath}: ${e.message}`);
+        return 2;
+    }
+    const migrations = migrationVersions(dir);
+    const problems = [];
+    let read = 0;
+    for (const env of ["staging", "production"]) {
+        const file = join(dir, COLUMNS(env));
+        if (!existsSync(file)) {
+            if (env === "staging") {
+                console.error(`check:limits: no ${COLUMNS("staging")}. After the migrations apply on staging, run \`workbench-supabase limits-sql\` with ` +
+                    "sb_query env=staging and pipe the result to `workbench-supabase limits-save --env staging`.");
+                return 2;
+            }
+            continue;
+        }
+        try {
+            const snapshot = parseColumnSnapshot(readJson(file, COLUMNS(env)));
+            if (snapshot.env !== env)
+                throw new Error(`it says it is from ${String(snapshot.env)}`);
+            problems.push(...limitsProblems(register, snapshot, env === "production" ? [] : migrations));
+            read++;
+        }
+        catch (e) {
+            console.error(`check:limits: ${COLUMNS(env)}: ${e.message}`);
+            return 2;
+        }
+    }
+    const entries = Object.values(register);
+    const stored = entries.filter((l) => l.column !== null).length;
+    const proposed = entries.filter((l) => l.status === "proposed").length;
+    if (problems.length) {
+        for (const p of problems)
+            console.error(`  ${p}`);
+        console.error(`check:limits failed: ${problems.length} problem(s). Change the register or the column (a migration) so they agree.`);
+        return 1;
+    }
+    console.log(`check:limits passed: ${stored} stored limit(s) match ${read} database snapshot(s); ${proposed} still proposed.`);
+    return 0;
+}

package/dist/limits-sql.d.ts

@@ -0,0 +1 @@
+export declare const LIMITS_SQL = "select json_build_object(\n  'format', 1,\n  'columns', coalesce((\n    select json_object_agg(c.relname || '.' || a.attname, json_build_object(\n      'type', format_type(a.atttypid, null),\n      'length', case when a.atttypid in (1042, 1043) and a.atttypmod > 4 then a.atttypmod - 4 end,\n      'precision', case when a.atttypid = 1700 and a.atttypmod > 4 then ((a.atttypmod - 4) >> 16) & 65535 end,\n      'scale', case when a.atttypid = 1700 and a.atttypmod > 4 then (a.atttypmod - 4) & 65535 end,\n      'checks', coalesce((\n        select json_agg(pg_get_constraintdef(k.oid) order by k.conname)\n        from pg_catalog.pg_constraint k\n        where k.conrelid = c.oid and k.contype = 'c' and a.attnum = any(k.conkey)\n      ), '[]'::json)\n    ) order by c.relname, a.attnum)\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')\n  ), '{}'::json)\n) as snapshot";

package/dist/limits-sql.js

@@ -0,0 +1,28 @@
+// check:limits (docs/spec.md §3; form-validation standard §4.1): the query
+// whose one row is a snapshot of every column's size in `public`. Read-only
+// and through pg_catalog only, so it works as sb_query's restricted role
+// (which can't read supabase_migrations). Claude runs it with sb_query right
+// after migrations apply (env=staging, and env=production once production has
+// a database) and saves the result with `workbench-supabase limits-save`,
+// which stamps it with the repo's migrations; check:limits compares it with
+// the app's limits register in Checks, which have no database access.
+export const LIMITS_SQL = `select json_build_object(
+  'format', 1,
+  'columns', coalesce((
+    select json_object_agg(c.relname || '.' || a.attname, json_build_object(
+      'type', format_type(a.atttypid, null),
+      'length', case when a.atttypid in (1042, 1043) and a.atttypmod > 4 then a.atttypmod - 4 end,
+      'precision', case when a.atttypid = 1700 and a.atttypmod > 4 then ((a.atttypmod - 4) >> 16) & 65535 end,
+      'scale', case when a.atttypid = 1700 and a.atttypmod > 4 then (a.atttypmod - 4) & 65535 end,
+      'checks', coalesce((
+        select json_agg(pg_get_constraintdef(k.oid) order by k.conname)
+        from pg_catalog.pg_constraint k
+        where k.conrelid = c.oid and k.contype = 'c' and a.attnum = any(k.conkey)
+      ), '[]'::json)
+    ) order by c.relname, a.attnum)
+    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')
+  ), '{}'::json)
+) as snapshot`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mccaskie-labs/workbench-supabase",
-  "version": "0.3.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.",
+  "version": "0.4.1",
+  "description": "Supabase clients for Workbench apps (browser, server, the caller's own token, and a service client that logs its reason), plus check:migrations, check:prod-schema and check:limits.",
   "license": "UNLICENSED",
   "type": "module",
   "repository": {
@@ -39,6 +39,7 @@
   },
   "dependencies": {
     "@mccaskie-labs/workbench-config": "^0.1.3",
+    "@mccaskie-labs/workbench-forms": "^0.2.0",
     "@supabase/ssr": "^0.12.7",
     "@supabase/supabase-js": "^2.119.0"
   },