supabase-worker-previews 0.0.0 → 0.1.1

package/dist/usage.js

@@ -0,0 +1,297 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DOCS_URL, TOKENS_URL } from "./http.js";
+import { parseArgs } from "./run.js";
+import { didYouMean } from "./suggest.js";
+import { makeStyle } from "./style.js";
+const TOKENS = ["SUPABASE_ACCESS_TOKEN", "CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"];
+const WITH_GITHUB = [...TOKENS, "GITHUB_TOKEN"];
+const DRY_RUN = { name: "dry-run", help: "Print the plan; change nothing" };
+const OVERRIDES = [
+    { name: "dotenv", value: "<path>", help: "Load tokens from this file (default: .env.swp when present)" },
+    { name: "worker", value: "<name>", help: 'Worker name (default: "name" in the wrangler config)' },
+    { name: "project-ref", value: "<ref>", help: "Production project ref (default: swp.config.json)" },
+    { name: "trunk", value: "<branch>", help: "Branch the shared database tracks (default: swp.config.json)" },
+];
+const BRANCH = [
+    { name: "branch", value: "<b>", help: "Git branch (default: the current one, or the CI branch)" },
+    { name: "pr", value: "<n>", help: 'Pull request number; needed when previewName is "pr"' },
+];
+const HELP = [
+    { name: "help", help: "Show help" },
+    { name: "version", help: "Print the version" },
+];
+export const COMMANDS = [
+    {
+        name: "init",
+        group: "Set up",
+        args: "[--project-ref <ref>] [--trunk <branch>] [--action]",
+        summary: "Scaffold swp.config.json, the grants migration and the PR workflow",
+        details: "Writes swp.config.json, a first migration that grants the API roles default privileges, and\n" +
+            ".github/workflows/supabase-previews.yml. Never overwrites a file; run it again safely.",
+        flags: [
+            { name: "project-ref", value: "<ref>", help: "Production project ref (default: from `supabase link`)" },
+            {
+                name: "trunk",
+                value: "<branch>",
+                help: "Branch the shared database tracks (default: origin/HEAD, else main)",
+            },
+            {
+                name: "action",
+                help: "Write a workflow that uses the published GitHub Action instead of npx supabase-worker-previews",
+            },
+            { ...DRY_RUN, help: "Print what it would write; write nothing" },
+        ],
+        env: [],
+        dryRunEnv: [],
+        examples: ["swp init --project-ref abcdefghijklmnopqrst", "swp init --action"],
+    },
+    {
+        name: "doctor",
+        group: "Set up",
+        args: "",
+        summary: "Check the setup: local files, and the Supabase project when a token is set",
+        details: "Checks wrangler, the previews block, bindings, static HTML, the grants migration and auth\n" +
+            "redirects. With SUPABASE_ACCESS_TOKEN it also checks branching, the shared Preview database\n" +
+            "and the GitHub integration. Exits 1 when any check fails.",
+        flags: OVERRIDES,
+        env: [],
+        dryRunEnv: [],
+        examples: ["swp doctor"],
+    },
+    {
+        name: "shared",
+        group: "Set up",
+        args: "",
+        summary: "Create or repair the shared Preview database; prints its previews.vars",
+        details: "Makes a persistent Supabase branch that tracks the trunk, waits for its migrations, sets its\n" +
+            "auth redirects, stores its secret key in the Preview base config, and prints the values to\n" +
+            "paste under previews.vars in the wrangler config.",
+        flags: [DRY_RUN, ...OVERRIDES],
+        env: TOKENS,
+        dryRunEnv: ["SUPABASE_ACCESS_TOKEN"],
+        examples: ["swp shared --dry-run", "swp shared"],
+    },
+    {
+        name: "up",
+        group: "Per branch",
+        args: "[--branch <b>] [--pr <n>]",
+        summary: "Give a branch's Preview its own database",
+        details: "Finds or creates the Supabase branch for the git branch, waits for its migrations, and points\n" +
+            "the branch's Preview at it with one SUPABASE_OVERRIDE secret.",
+        flags: [...BRANCH, DRY_RUN, ...OVERRIDES],
+        env: TOKENS,
+        dryRunEnv: [],
+        examples: ["swp up --branch feat/notes --dry-run"],
+    },
+    {
+        name: "check",
+        group: "Per branch",
+        args: "[--branch <b>] [--pr <n>] [--isolated]",
+        summary: "Fail unless a branch's Preview serves the right database",
+        details: "Reads which database the deployed Preview serves and retries for up to 15 minutes while it\n" +
+            "deploys. Fails at once if it serves production.",
+        flags: [
+            ...BRANCH,
+            { name: "isolated", help: "Expect the branch's own database, not the shared one" },
+            DRY_RUN,
+            ...OVERRIDES,
+        ],
+        env: TOKENS,
+        dryRunEnv: [],
+        examples: ["swp check --branch feat/notes --isolated"],
+    },
+    {
+        name: "down",
+        group: "Per branch",
+        args: "[--branch <b>] [--pr <n>]",
+        summary: "Delete a branch's Preview and its own database",
+        details: "Never deletes the production project, the shared database or a persistent branch.",
+        flags: [...BRANCH, DRY_RUN, ...OVERRIDES],
+        env: TOKENS,
+        dryRunEnv: TOKENS,
+        examples: ["swp down --branch feat/notes --dry-run"],
+    },
+    {
+        name: "pr",
+        group: "In CI",
+        args: "[--no-comment] [--no-deployments]",
+        summary: "Run up, check and down for a pull_request workflow, and report on the PR",
+        details: "Reads the pull_request event from GITHUB_EVENT_PATH. On close it runs down; otherwise it gives\n" +
+            "the Preview its own database when the PR changes supabase/ (or has the isolated-db label),\n" +
+            "then checks it. Keeps one status comment and a GitHub deployment on the PR.",
+        flags: [
+            { name: "no-comment", help: "Skip the PR status comment" },
+            { name: "no-deployments", help: "Skip the GitHub deployment" },
+            DRY_RUN,
+            ...OVERRIDES,
+        ],
+        env: WITH_GITHUB,
+        dryRunEnv: WITH_GITHUB,
+        examples: ["swp pr"],
+    },
+    {
+        name: "prune",
+        group: "In CI",
+        args: "[--repo <owner/name>] [--yes]",
+        summary: "List leftovers of deleted branches and closed PRs; --yes deletes them",
+        details: "Lists Supabase branches and Previews whose git branch is gone or whose PR is closed.",
+        flags: [
+            {
+                name: "repo",
+                value: "<owner/name>",
+                help: "GitHub repo (default: GITHUB_REPOSITORY, else the origin remote)",
+            },
+            { name: "yes", help: "Delete what it lists" },
+            DRY_RUN,
+            ...OVERRIDES,
+        ],
+        env: WITH_GITHUB,
+        dryRunEnv: WITH_GITHUB,
+        examples: ["swp prune", "swp prune --yes"],
+    },
+];
+const ALL_FLAGS = [...COMMANDS.flatMap((c) => c.flags), ...HELP];
+export const BOOLEAN_FLAGS = new Set(ALL_FLAGS.filter((f) => !f.value).map((f) => f.name));
+export function command(name) {
+    return COMMANDS.find((c) => c.name === name);
+}
+export function version() {
+    const path = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    return JSON.parse(readFileSync(path, "utf8")).version;
+}
+function flagTable(flags, s) {
+    const label = (f) => (f.name === "help" ? "-h, " : f.name === "version" ? "-v, " : "") +
+        `--${f.name}${f.value ? ` ${f.value}` : ""}`;
+    const width = Math.max(...flags.map((f) => label(f).length));
+    return flags.map((f) => `  ${s.cyan(label(f).padEnd(width))}  ${f.help}`);
+}
+export function mainHelp(s = makeStyle(false)) {
+    const width = Math.max(...COMMANDS.map((c) => c.name.length));
+    const groups = [...new Set(COMMANDS.map((c) => c.group))].flatMap((group) => [
+        "",
+        s.bold(group),
+        ...COMMANDS.filter((c) => c.group === group).map((c) => `  ${s.cyan(c.name.padEnd(width))}  ${c.summary}`),
+    ]);
+    return [
+        `${s.bold("swp")} ${version()}: branch previews for Cloudflare Workers on Supabase branching`,
+        "",
+        `${s.bold("Usage:")} swp <command> [flags]`,
+        ...groups,
+        "",
+        s.bold("Common flags"),
+        ...flagTable([DRY_RUN, ...OVERRIDES, ...HELP], s),
+        "",
+        s.bold("Environment"),
+        `  ${TOKENS.join(", ")}, and GITHUB_TOKEN for pr and prune.`,
+        `  Where to get them: ${TOKENS_URL}`,
+        "",
+        s.bold("Examples"),
+        "  npx supabase-worker-previews init --project-ref abcdefghijklmnopqrst",
+        "  npx supabase-worker-previews doctor",
+        "  npx supabase-worker-previews shared --dry-run",
+        "",
+        `Run ${s.cyan("swp <command> --help")} for one command. Docs: ${DOCS_URL}`,
+    ].join("\n");
+}
+export function commandHelp(c, s = makeStyle(false)) {
+    return [
+        `${s.bold(`swp ${c.name}`)}: ${c.summary.charAt(0).toLowerCase()}${c.summary.slice(1)}`,
+        "",
+        `${s.bold("Usage:")} swp ${c.name}${c.args ? ` ${c.args}` : ""}`,
+        "",
+        c.details,
+        "",
+        s.bold("Flags"),
+        ...flagTable([...c.flags, HELP[0]], s),
+        ...(c.env.length ? ["", `${s.bold("Needs:")} ${c.env.join(", ")} (${TOKENS_URL})`] : []),
+        "",
+        s.bold("Examples"),
+        ...c.examples.map((e) => `  ${e}`),
+        "",
+        `Docs: ${DOCS_URL}`,
+    ].join("\n");
+}
+/** What the arguments ask for, or a usage error that says how to fix them. */
+export function resolveInvocation(argv, s = makeStyle(false)) {
+    const { positional, flags } = parseArgs(argv, BOOLEAN_FLAGS);
+    if (flags.version)
+        return { kind: "version" };
+    const [name, ...rest] = positional;
+    if (name === "help") {
+        if (!rest[0])
+            return { kind: "help", text: mainHelp(s), code: 0 };
+        const c = command(rest[0]);
+        return c ? { kind: "help", text: commandHelp(c, s), code: 0 } : unknownCommand(rest[0]);
+    }
+    if (!name)
+        return { kind: "help", text: mainHelp(s), code: flags.help ? 0 : 2 };
+    const c = command(name);
+    if (!c)
+        return unknownCommand(name);
+    if (flags.help)
+        return { kind: "help", text: commandHelp(c, s), code: 0 };
+    if (rest.length) {
+        const hint = BRANCH.every((f) => c.flags.includes(f))
+            ? ` To name a branch, use --branch ${rest[0]}.`
+            : "";
+        return usageError(`${c.name} takes no arguments, but got "${rest.join(" ")}".${hint}`, c.name);
+    }
+    const known = [...c.flags, ...HELP].map((f) => f.name);
+    for (const [key, value] of Object.entries(flags)) {
+        const flag = c.flags.find((f) => f.name === key);
+        if (!flag) {
+            const elsewhere = ALL_FLAGS.some((f) => f.name === key);
+            const guess = key === "env-file" ? "dotenv" : didYouMean(key, known);
+            return usageError(elsewhere
+                ? `${c.name} does not take --${key}.`
+                : `Unknown flag --${key}.${guess ? ` Did you mean --${guess}?` : ""}`, c.name);
+        }
+        if (flag.value && (value === true || value === ""))
+            return usageError(`--${key} needs a value: --${key} ${flag.value}`, c.name);
+        if (!flag.value && value !== true)
+            return usageError(`--${key} takes no value.`, c.name);
+    }
+    return { kind: "run", command: c.name, flags };
+}
+function unknownCommand(name) {
+    const guess = didYouMean(name, COMMANDS.map((c) => c.name));
+    return {
+        kind: "error",
+        message: `Unknown command "${name}".${guess ? ` Did you mean "swp ${guess}"?` : ""}\nRun swp --help to see every command.`,
+    };
+}
+function usageError(message, name) {
+    return { kind: "error", message: `${message}\nRun swp ${name} --help for its usage.` };
+}
+const ENV_SOURCES = {
+    SUPABASE_ACCESS_TOKEN: "https://supabase.com/dashboard/account/tokens (organization-scoped)",
+    CLOUDFLARE_API_TOKEN: "https://dash.cloudflare.com/profile/api-tokens (Workers Scripts: Edit)",
+    CLOUDFLARE_ACCOUNT_ID: "Cloudflare dashboard, Workers and Pages, Account details",
+    GITHUB_TOKEN: "`gh auth token` locally; ${{ github.token }} in Actions",
+};
+/** Names every variable the command needs and lacks, with where to get each; undefined when none is missing. */
+export function missingEnvMessage(name, dryRun, env = process.env) {
+    const c = command(name);
+    const missing = (dryRun ? c.dryRunEnv : c.env).filter((v) => !env[v]);
+    if (!missing.length)
+        return undefined;
+    const width = Math.max(...missing.map((v) => v.length));
+    return [
+        `${name}${dryRun ? " --dry-run" : ""} needs ${missing.length === 1 ? "this variable" : "these variables"}, not set:`,
+        ...missing.map((v) => `  ${v.padEnd(width)}  ${ENV_SOURCES[v]}`),
+        `Put ${missing.length === 1 ? "it" : "them"} in .env.swp (git-ignore it) or the environment. Scopes: ${TOKENS_URL}`,
+    ].join("\n");
+}
+/** One line for the user: the message, and for a network failure the host and the system error. */
+export function formatError(err, debug = !!process.env.SWP_DEBUG) {
+    if (!(err instanceof Error))
+        return String(err);
+    if (debug && err.stack)
+        return err.stack;
+    const cause = err.cause;
+    if (err.message === "fetch failed" && cause)
+        return `network error${cause.hostname ? ` reaching ${cause.hostname}` : ""}: ${cause.code ?? cause.message ?? "unknown"}. Check the connection and try again.`;
+    return err.message;
+}

package/package.json

@@ -1,17 +1,92 @@
 {
   "name": "supabase-worker-previews",
-  "version": "0.0.0",
-  "description": "Placeholder. Install 0.1.0 or later.",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
+  "version": "0.1.1",
+  "description": "Branch previews for Cloudflare Workers on Supabase branching: every git branch gets a Worker Preview, and every PR that changes the schema gets its own Supabase database.",
   "license": "MIT",
-  "type": "commonjs",
+  "author": "Matt Ruby",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mattruby/supabase-worker-previews.git"
+  },
+  "homepage": "https://github.com/mattruby/supabase-worker-previews#readme",
+  "bugs": {
+    "url": "https://github.com/mattruby/supabase-worker-previews/issues"
+  },
+  "type": "module",
+  "keywords": [
+    "cloudflare",
+    "cloudflare-workers",
+    "workers",
+    "wrangler",
+    "supabase",
+    "supabase-branching",
+    "branching",
+    "preview",
+    "preview-deployments",
+    "branch-preview",
+    "database",
+    "postgres",
+    "ci",
+    "github-actions",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "swp": "dist/cli.js",
+    "supabase-worker-previews": "dist/cli.js"
+  },
+  "main": "./dist/runtime.js",
+  "types": "./dist/runtime.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:package": "node scripts/check-package.mjs",
+    "changeset": "changeset",
+    "version-packages": "changeset version && node scripts/sync-plugin-version.mjs && npm install --package-lock-only --ignore-scripts --no-audit --no-fund",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "wrangler": ">=4.135.0"
+  },
+  "peerDependenciesMeta": {
+    "wrangler": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@cloudflare/workers-types": "^5.20261001.1",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.20.4",
+    "eslint": "^10.11.0",
+    "prettier": "^3.9.9",
+    "typescript": "^5.9.0",
+    "typescript-eslint": "^8.71.0",
+    "vitest": "^4.0.0"
+  },
+  "dependencies": {
+    "smol-toml": "^1.9.0"
   }
 }

package/templates/default-privileges.sql

@@ -0,0 +1,9 @@
+-- Supabase branches (and newer projects) start without the API roles in the
+-- default privileges; only migrations can grant them back.
+-- This must run before any table exists. Later migrations revoke what they must.
+alter default privileges for role postgres in schema public
+  grant all on tables to anon, authenticated, service_role;
+alter default privileges for role postgres in schema public
+  grant all on sequences to anon, authenticated, service_role;
+alter default privileges for role postgres in schema public
+  grant execute on functions to anon, authenticated, service_role;

package/templates/supabase-previews-action.yml

@@ -0,0 +1,29 @@
+name: Preview database
+
+# The same job as supabase-previews.yml, through the published action. It runs
+# the project's installed swp when there is one, else downloads the package.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled, closed]
+
+concurrency:
+  group: supabase-previews-${{ github.head_ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pull-requests: write
+  deployments: write
+
+jobs:
+  preview-db:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+      - uses: mattruby/supabase-worker-previews@v0
+        with:
+          supabase-access-token: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
+          cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          cloudflare-account-id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

package/templates/supabase-previews.yml

@@ -0,0 +1,38 @@
+name: Preview database
+
+# Workers Builds makes a Worker Preview of every branch; the Supabase GitHub
+# integration makes a database for every PR that changes supabase/. This
+# points each PR's Preview at the right database, proves it never serves
+# production, and cleans up when the PR closes. It reports on the PR with one
+# status comment and a GitHub deployment (the "View deployment" button).
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled, closed]
+
+concurrency:
+  group: supabase-previews-${{ github.head_ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pull-requests: write
+  deployments: write
+
+jobs:
+  preview-db:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci --no-audit --no-fund
+      - run: npx supabase-worker-previews pr
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}