@clubedge/create-clubedge-app 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.30.0
+
+- **`--infra neon`** gives a project a hosted Neon database with nothing to install and no account (#84):
+  - The CLI creates a free database through Neon's claimable Postgres. It writes the pooled `DATABASE_URL` and the direct `DATABASE_URL_DIRECT` into `apps/web/.env.local`, and the next steps include `pnpm db:migrate`.
+  - Neon keeps an unclaimed database for 72 hours. `--no-neon` creates nothing, and a project is still created when Neon can't be reached.
+  - `pnpm clubedge add infra neon` switches an existing project and creates a database when `DATABASE_URL` still held the old infrastructure's example value.
+- **`pnpm clubedge neon`** shows the database's status and hours left (#84):
+  - `neon claim` opens Neon's page that moves it into your free Neon account. Claiming resets the password, and the CLI says where to copy the new connection strings from.
+  - `neon create` makes a new database, for example after one expired.
+- **`doctor`** checks the database URLs (#84): pooled for the app, direct without `-pooler`, both for the same database. It also warns when a free database has less than a day left.
+- **`deploy`** sends `DATABASE_URL_DIRECT` with a `DATABASE_URL` from the env file, and derives it from a pooled Neon URL when the file has none. It never sends one next to the platform's own database, repoints one left from an earlier database, and warns before deploying a database that is still unclaimed (#84).
+- **`deploy --preview`** deploys the current Git branch next to production on Vercel (a preview deployment) or Railway (an environment copied from production) (#84):
+  - With `NEON_API_KEY` and `NEON_PROJECT_ID`, the preview gets its own Neon branch, `preview/<git branch>`, with this branch's migrations applied.
+  - On Vercel, the branch's URLs are set as Preview variables of the Git branch, which needs the Vercel project connected to its Git repository.
+- **`try --infra neon`** creates the database on your machine and migrates it on the VM. An uploaded Neon project sends its two URLs (#84).
+- Default to Starter `v0.19.0` (#85). It adds `infra neon`, the optional `DATABASE_URL_DIRECT` that migrations and the jobs worker use, and a preview environment with its own Neon branch for each pull request.
+
 ## 0.29.0
 
 - `pnpm clubedge deploy` deploys to Netlify and Render (experimental) (#82), so it now covers Railway, Fly.io, Vercel, Netlify, and Render:

package/README.md

@@ -80,7 +80,7 @@ Authentication, file storage, caching, email, payments, background jobs, observa
 | `--jobs` | `pg-boss`, `none` | `none` |
 | `--observability` | `otel` (OpenTelemetry, to any OTLP collector), `sentry`, `none` | `none` |
 | `--deploy`  | `docker` (any container host), `fly`, `railway`, `render`, `vercel`, `netlify` | `docker` |
-| `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `none` | `docker` |
+| `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `neon` (a free hosted Neon database), `none` | `docker` |
 
 ```sh
 # Only the monorepo, UI, database, and tooling
@@ -129,7 +129,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.18.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.19.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -148,7 +148,7 @@ pnpm clubedge add email resend payments stripe              # several modules as
 pnpm clubedge remove storage payments
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.18.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.19.0 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
@@ -163,6 +163,29 @@ Several modules in one command are applied as one change, and their requirements
 
 The project must be a Git repository without uncommitted changes, so you can review the result with `git diff` and undo it. Pass `--force` to skip this check. Add `--no-install` to skip `pnpm install`. Afterward, run `pnpm db:migrate` and `pnpm check:services` if the change added tables or services.
 
+## A hosted database with Neon
+
+`--infra neon` gives the project a [Neon](https://neon.com) PostgreSQL database with nothing to install and no account:
+
+```sh
+pnpm dlx @clubedge/create-clubedge-app my-app --infra neon
+cd my-app
+pnpm db:migrate
+pnpm dev
+```
+
+The CLI creates a free database through Neon's [claimable Postgres](https://neon.com/docs/reference/claimable-postgres) and writes two URLs into `apps/web/.env.local`: `DATABASE_URL`, the pooled connection the app uses, and `DATABASE_URL_DIRECT`, the direct one that migrations and the background jobs worker use, since a transaction pooler can break them. Neon keeps an unclaimed database for 72 hours, with up to 100 MB:
+
+```sh
+pnpm clubedge neon           # where it stands and how long it has left
+pnpm clubedge neon claim     # opens Neon's page that moves it into your (free) Neon account
+pnpm clubedge neon create    # a new database, for example after one expired
+```
+
+Claiming keeps the data but resets the password: copy the pooled and direct connection strings from the Neon console into the two variables afterward. To use a Neon project you already have, paste its URLs instead, or pass `--no-neon` to create nothing. `pnpm clubedge add infra neon` switches an existing project and creates a database when `DATABASE_URL` held the old infrastructure's example value. The CLI keeps what it needs to claim each database in `neon.json` in its config directory (`~/.config/clubedge`, or `%APPDATA%\clubedge` on Windows); treat it as a secret.
+
+`doctor` checks the two URLs (pooled for the app, direct without `-pooler`, both from the same database) and warns when a free database has less than a day left. `deploy` sends `DATABASE_URL_DIRECT` with a `DATABASE_URL` from the env file, derives it from a pooled Neon URL when the file has none, and warns before deploying a database that is still unclaimed.
+
 ## Check a project
 
 Two read-only commands help you keep a project healthy:
@@ -185,9 +208,9 @@ pnpm dlx @clubedge/create-clubedge-app try --framework tanstack-start --auth non
 
 The VM needs no Railway account and lasts 60 minutes; to keep it, open the claim link the CLI prints within 24 hours after, which moves the VM, its files, and its URL into a Railway account. Keep that link private. Until the VM is claimed, the preview opens only from the IP address that created it (not from another device on mobile data, or through a VPN); claiming makes the URL shareable. Railway allows 3 free VMs per network per day.
 
-The VM has no Docker, so the project uses `--infra local` (PGlite) and Better Auth unless you choose `--auth none`, with email off; other module flags apply as usual.
+The VM has no Docker, so the project uses `--infra local` (PGlite) and Better Auth unless you choose `--auth none`, with email off; other module flags apply as usual. With `--infra neon`, the CLI creates a free Neon database first, the VM migrates it, and `neon claim` (run outside a project) keeps it after the VM is gone.
 
-Inside a project, `pnpm clubedge try` uploads that project instead, to share work in progress without deploying it. It sends what Git would commit (tracked files, plus untracked ones that are not ignored) and never `.env` files other than examples, `node_modules`, or build output; on the VM, the env file is made from `.env.example` as `create` does. The project must use `infra local` or `none`, and not Supabase Auth; `pnpm clubedge add infra local` switches a Docker project. Add `--dry-run` to list the files without uploading anything.
+Inside a project, `pnpm clubedge try` uploads that project instead, to share work in progress without deploying it. It sends what Git would commit (tracked files, plus untracked ones that are not ignored) and never `.env` files other than examples, `node_modules`, or build output; on the VM, the env file is made from `.env.example` as `create` does. The project must use `infra local`, `neon`, or `none`, and not Supabase Auth; with `neon`, the VM gets `DATABASE_URL` and `DATABASE_URL_DIRECT` from your env file; `pnpm clubedge add infra local` switches a Docker project. Add `--dry-run` to list the files without uploading anything.
 
 When the app is ready, the CLI opens the preview in your browser (`--no-open` turns that off) and asks whether to share it: claiming the VM, a free Railway sign-up, is what makes the URL work for anyone. `--claim` opens the claim page without asking. `try --status` shows the last VM's preview, time left, and claim link; it connects only while the VM is running, so it never creates a new one. To open the app from another network yourself, forward it: `ssh -i <key> -N -L 3000:127.0.0.1:3000 railway.new`, then http://localhost:3000 (the CLI prints the exact command). The CLI asks before creating anything (`--yes` agrees), keeps its own SSH key in your config directory (`~/.config/clubedge`, or `%APPDATA%\clubedge` on Windows) apart from `~/.ssh`, and connects only to Railway's known host key. Railway's [terms](https://railway.com/legal/terms) apply, and Railway can change or pause its free VM.
 
@@ -219,32 +242,44 @@ In a project with `--deploy netlify`, `pnpm clubedge deploy` uses [Netlify's CLI
 
 In a project with `--deploy render`, `pnpm clubedge deploy` uses Render's API. Render builds the Dockerfile from your Git repository, so push the project to GitHub, GitLab, or Bitbucket first, with Render's access to it granted in the dashboard; `deploy` warns about commits that aren't pushed. It signs in with an API key: `RENDER_API_KEY`, or else it opens the dashboard's API keys page and asks you to paste one. It creates or reuses a web service named after the package, on the Docker runtime and a starter instance (pre-deploy commands need a paid type), which runs `node /app/migrate.mjs` before each release, checks `/api/health`, and deploys again on each push, as `render.yaml` describes. `DATABASE_URL` comes from the env file (Render Postgres, Neon, Supabase, ...). It sets the production variables: the env file's values, the service's `*.onrender.com` URL, and a generated `BETTER_AUTH_SECRET` that later runs keep. Then it starts a deploy and waits until it is live. When Render names the app something other than `https://<service>.onrender.com`, `deploy` sets that URL and deploys again, since the build compiles it in. Running it again reuses the service. Render bills the instance on your plan.
 
+### Preview deployments
+
+In a project that deploys to Vercel or Railway, `pnpm clubedge deploy --preview` deploys the current Git branch next to production, after a first `deploy`:
+
+```sh
+NEON_API_KEY=... NEON_PROJECT_ID=... pnpm clubedge deploy --preview
+```
+
+With `NEON_API_KEY` and `NEON_PROJECT_ID` (in the shell, or in the env file), the preview gets its own [Neon branch](https://neon.com/docs/introduction/branching), `preview/<git branch>`: a copy of the production database made in seconds that shares its storage until it changes. `deploy` creates it, or reuses it on later runs, applies this branch's migrations to it, and points the preview's `DATABASE_URL` and `DATABASE_URL_DIRECT` at it. On Vercel, the preview is a preview deployment with the project's Preview variables, and the branch's URLs are set as Preview variables of your Git branch, which needs the Vercel project connected to its Git repository; without the Neon settings, it uses the Preview `DATABASE_URL`. On Railway, it is an environment named `preview-<git branch>`, copied from production with its own domain; without the Neon settings, it gets its own empty copy of Railway's Postgres, and when production's database comes from elsewhere, `deploy --preview` refuses, since the copy would use production's data. Production is not changed.
+
+Projects created with `--infra neon` also have `.github/workflows/preview.yml`, which does this for every pull request in CI: a Neon branch per pull request with its migrations, the schema diff as a comment, a Vercel or Railway preview, and cleanup when the pull request closes. The Starter's SETUP.md lists the secrets it needs.
+
 ## Version relationship
 
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.29.0
+create-clubedge-app v0.30.0
         |
         v
-Clubedge Starter v0.18.0
-commit bcd084d7d2d2aac0600ccb35491f48c251fb3a74
+Clubedge Starter v0.19.0
+commit 1fa6afcefb99f26332f08cd08ac63f6b229cafda
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.29.0` | `clubedge-starter@v0.18.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.30.0` | `clubedge-starter@v0.19.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.18.0` tag is expected to resolve to commit
-`bcd084d7d2d2aac0600ccb35491f48c251fb3a74`. The CLI verifies this before
+The `v0.19.0` tag is expected to resolve to commit
+`1fa6afcefb99f26332f08cd08ac63f6b229cafda`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.18.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.19.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -299,7 +334,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.18.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.19.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -338,6 +373,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.27.0 | v0.18.0 | Starter v0.18.0: Vercel and Netlify builds stop when a production variable is missing (`pnpm check:env`) |
 | 0.28.0 | v0.18.0 | `deploy` to Vercel (experimental) |
 | 0.29.0 | v0.18.0 | `deploy` to Netlify and Render (experimental) |
+| 0.30.0 | v0.19.0 | `--infra neon` with a free Neon database, the `neon` command, `deploy --preview` with a Neon branch per preview |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/dist/cli/args.js

@@ -16,6 +16,8 @@ const OPTIONS = {
     open: { type: "boolean", default: true },
     claim: { type: "boolean", default: false },
     status: { type: "boolean", default: false },
+    neon: { type: "boolean", default: true },
+    preview: { type: "boolean", default: false },
     "env-file": { type: "string" },
     help: { type: "boolean", short: "h", default: false },
     version: { type: "boolean", short: "v", default: false },
@@ -90,8 +92,8 @@ export function parseCliArgs(argv) {
     if (!creates && command.name !== "upgrade" && values.ref !== undefined) {
         throw new UsageError("--ref only applies when creating or upgrading a project.");
     }
-    if (command.name !== "deploy" && values["env-file"] !== undefined) {
-        throw new UsageError("--env-file only applies to deploy.");
+    if (command.name !== "deploy" && (values["env-file"] !== undefined || values.preview)) {
+        throw new UsageError("--env-file and --preview only apply to deploy.");
     }
     if (command.name !== "try" && (values.claim || values.status)) {
         throw new UsageError("--claim and --status only apply to try.");
@@ -124,6 +126,8 @@ export function parseCliArgs(argv) {
         open: values.open,
         claim: values.claim,
         status: values.status,
+        neon: values.neon,
+        preview: values.preview,
         envFile: values["env-file"],
         help: values.help,
         version: values.version,
@@ -163,9 +167,16 @@ function parseCommand(positionals) {
     }
     if (name === "deploy") {
         if (module !== undefined)
-            throw new UsageError("Usage: deploy [--env-file <path>], run inside a project.");
+            throw new UsageError("Usage: deploy [--preview] [--env-file <path>], run inside a project.");
         return { name };
     }
+    if (name === "neon") {
+        const action = module ?? "status";
+        if (rest.length > 1 || (action !== "status" && action !== "claim" && action !== "create")) {
+            throw new UsageError("Usage: neon [status|claim|create], run inside a project with --infra neon.");
+        }
+        return { name, action };
+    }
     if (name === "try") {
         if (module !== undefined) {
             throw new UsageError("Usage: try [--framework <id>] [module flags] (a new project), or try inside a project to upload it.");

package/dist/cli/ui.js

@@ -93,9 +93,10 @@ Usage:
   pnpm dlx @clubedge/create-clubedge-app doctor                  (inside a project)
   pnpm dlx @clubedge/create-clubedge-app try [options]           (experimental)
   pnpm dlx @clubedge/create-clubedge-app deploy [options]        (inside a project)
+  pnpm dlx @clubedge/create-clubedge-app neon [claim|create]     (--infra neon)
 
   Inside a project with the clubedge script, use pnpm clubedge add, remove,
-  upgrade, status, doctor, try, or deploy. Without a module or option, add and remove ask
+  upgrade, status, doctor, try, deploy, or neon. Without a module or option, add and remove ask
   for them.
 
   add and remove change modules of an existing project, several at once as one
@@ -108,11 +109,16 @@ Usage:
   newer Starter is available. doctor checks Node.js, pnpm, the dependencies, the
   lockfile, and the env file, then runs pnpm check:services; it changes nothing.
 
+  --infra neon creates a free Neon database (no account; 72 hours unless claimed) and
+  writes its pooled and direct URLs into the env file. neon shows how long it has left,
+  neon claim opens the page that keeps it in a Neon account, and neon create makes a
+  new one.
+
   try creates a new project on a free, temporary Railway VM (no account, 60 minutes)
   and prints its preview URL and the link to claim the VM. The VM has no Docker, so
-  it uses --infra local (PGlite) and Better Auth, with email off. Inside a project,
-  try uploads that project instead (what Git would commit, never .env files or
-  node_modules); it needs infra local or none. It asks first, keeps its own SSH key
+  it uses --infra local (PGlite) or --infra neon, and Better Auth, with email off.
+  Inside a project, try uploads that project instead (what Git would commit, never .env
+  files or node_modules); it needs infra local, neon, or none. It asks first, keeps its own SSH key
   apart from ~/.ssh, and opens the preview when ready. Experimental: Railway can
   change or pause its free VM.
 
@@ -127,6 +133,9 @@ ${selectionHelp(manifest)}
   --no-open               try, deploy (Vercel, Netlify, Render): do not open the URL in the browser
   --claim                 try: open the page that claims the VM, to share the preview
   --status                try: the last VM's preview, time left, and claim link
+  --no-neon               --infra neon: don't create a Neon database (set DATABASE_URL yourself)
+  --preview               deploy (Vercel, Railway): a preview of the current Git branch, with its
+                          own Neon branch when NEON_API_KEY and NEON_PROJECT_ID are set
   --env-file <path>       deploy: production values (default: .env.production when there is one)
   -y, --yes               Accept defaults and never prompt (default directory: my-app)
   --no-install            Skip dependency installation
@@ -147,6 +156,9 @@ Examples:
   pnpm dlx @clubedge/create-clubedge-app@latest upgrade
   pnpm clubedge status
   pnpm clubedge doctor --no-services
+  pnpm dlx @clubedge/create-clubedge-app my-app --infra neon
+  pnpm clubedge neon claim
+  pnpm clubedge deploy --preview
   pnpm dlx @clubedge/create-clubedge-app try --framework tanstack-start
 
 Learn more:

package/dist/core/deploy.js

@@ -1,5 +1,6 @@
 // What `deploy` sets up on Railway for a project, as pure functions: the service name, the
 // production variables, and reading the Railway CLI's output. src/deploy.ts runs the CLI.
+import { isNeonPooledUrl, neonDirectUrl } from "./neon.js";
 /** The port the production image listens on (the Starter's Dockerfile sets PORT=3000). */
 export const appPort = 3000;
 /** Railway's names for the databases `railway add --database` creates, used in references. */
@@ -83,7 +84,7 @@ export function planVariables(input) {
     const set = { ...provided, APP_URL: url, NEXT_PUBLIC_APP_URL: url };
     if (modules.auth === "better-auth" && !existing.BETTER_AUTH_SECRET)
         set.BETTER_AUTH_SECRET = secret();
-    const databaseKeys = Object.values(databaseVariables);
+    const databaseKeys = [...Object.values(databaseVariables), "DATABASE_URL_DIRECT"];
     for (const [key, value] of Object.entries(envFile)) {
         if (value === "" || databaseKeys.includes(key))
             continue;
@@ -93,9 +94,49 @@ export function planVariables(input) {
         set[key] = value;
     }
     Object.assign(set, external);
-    const unset = keys.filter((key) => set[key] === undefined && !existing[key]);
+    const direct = directDatabaseUrl(external.DATABASE_URL, envFile.DATABASE_URL_DIRECT);
+    if (direct)
+        set.DATABASE_URL_DIRECT = direct;
+    // A direct URL left from an earlier database would send migrations there: point it at the
+    // database the app now uses, or blank it (blank counts as unset).
+    else if (existing.DATABASE_URL_DIRECT)
+        set.DATABASE_URL_DIRECT = set.DATABASE_URL ?? "";
+    // Optional: without it, migrations and the jobs worker use DATABASE_URL.
+    const unset = keys.filter((key) => set[key] === undefined && !existing[key] && key !== "DATABASE_URL_DIRECT");
     return { set, unset };
 }
+/**
+ * DATABASE_URL_DIRECT for a database hosted elsewhere: the env file's, or for a pooled Neon URL the
+ * same URL without -pooler. Never next to the platform's own database (no external URL), where it
+ * would send migrations to another database.
+ */
+export function directDatabaseUrl(external, direct) {
+    if (!external)
+        return null;
+    if (direct?.trim() && !isLocalUrl(direct))
+        return direct.trim();
+    return isNeonPooledUrl(external) ? neonDirectUrl(external) : null;
+}
+/** `railway environment list --json`: an array of environments, or an object holding them. */
+export function railwayEnvironmentNames(output) {
+    let value;
+    try {
+        value = JSON.parse(output);
+    }
+    catch {
+        throw new Error("Railway listed its environments in a form deploy doesn't read. Check `railway environment list --json`.");
+    }
+    const list = Array.isArray(value) ? value : (value?.environments ?? []);
+    const items = Array.isArray(list) ? list : (list?.edges ?? []);
+    return (Array.isArray(items) ? items : [])
+        .map((item) => item?.node ?? item)
+        .map((item) => item?.name)
+        .filter((name) => typeof name === "string");
+}
+/** The body of `POST /v10/projects/:id/env?upsert=true`: encrypted Preview variables of one Git branch. */
+export function vercelPreviewEnvBody(values, gitBranch) {
+    return Object.entries(values).map(([key, value]) => ({ key, value, type: "encrypted", target: ["preview"], gitBranch }));
+}
 /** The public domain in `railway domain` output (JSON or text). */
 export function parseRailwayDomain(output) {
     const domain = /([a-z0-9-]+(?:\.[a-z0-9-]+)*\.up\.railway\.app)/i.exec(output)?.[1];

package/dist/core/health.js

@@ -1,6 +1,7 @@
 // Pure checks behind `status` and `doctor`: they take what the commands read from the project,
 // the system, and npm, and return what to show, so each can be tested without a real project.
 import { envKeys } from "./env.js";
+import { isNeonPooledUrl, isNeonUrl, neonEndpoint } from "./neon.js";
 /** Compares dotted versions such as "v0.13.1" and "0.12.0"; null when either is not one. */
 export function compareVersions(a, b) {
     const parse = (value) => {
@@ -159,3 +160,53 @@ export function checkLockfile(error) {
         detail: `could not check: ${error.split("\n").find((line) => line.trim()) ?? error}`,
     };
 }
+/** The database a connection URL names (its path). */
+function databaseName(url) {
+    try {
+        return decodeURIComponent(new URL(url.trim()).pathname.slice(1));
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * The database URLs in the local env file: Neon's pooled URL for the app and its direct URL for
+ * migrations and the jobs worker, and how long a free Neon database the CLI created has left.
+ * Null when there is nothing to say (no Neon, no direct URL, and infra isn't neon).
+ */
+export function checkDatabaseUrls(input) {
+    const { env, infra, claimable, cli, envPath } = input;
+    const name = "Database URLs";
+    const url = env.DATABASE_URL ?? "";
+    const direct = env.DATABASE_URL_DIRECT ?? "";
+    if (!url) {
+        return infra === "neon"
+            ? { name, status: "fail", detail: `DATABASE_URL in ${envPath} is empty`, fix: `Run \`${cli} neon create\` for a free Neon database, or paste your Neon project's pooled URL.` }
+            : null;
+    }
+    if (direct && isNeonPooledUrl(direct)) {
+        return { name, status: "fail", detail: "DATABASE_URL_DIRECT points at Neon's pooler", fix: "Use the same URL without -pooler in the host: migrations and the jobs worker need a direct session." };
+    }
+    if (claimable?.kind === "expired") {
+        return { name, status: "fail", detail: "the free Neon database in DATABASE_URL expired, and Neon deleted it", fix: `Run \`${cli} neon create\`, then \`pnpm db:migrate\`.` };
+    }
+    if (!isNeonUrl(url)) {
+        return direct ? { name, status: "ok", detail: "DATABASE_URL for the app, DATABASE_URL_DIRECT for migrations and the jobs worker" } : null;
+    }
+    if (!isNeonPooledUrl(url)) {
+        return { name, status: "warn", detail: "DATABASE_URL is Neon's direct host, which has fewer connections", fix: "Put the pooled URL (the host with -pooler) in DATABASE_URL, and this one in DATABASE_URL_DIRECT." };
+    }
+    if (!direct) {
+        return { name, status: "warn", detail: "DATABASE_URL is Neon's pooler, and DATABASE_URL_DIRECT is not set", fix: "Set DATABASE_URL_DIRECT to the same URL without -pooler in the host, for migrations and the jobs worker." };
+    }
+    if (neonEndpoint(direct) !== neonEndpoint(url) || databaseName(direct) !== databaseName(url)) {
+        return { name, status: "warn", detail: "DATABASE_URL and DATABASE_URL_DIRECT point at different Neon databases", fix: "Copy both from the same branch in the Neon console: pooled and direct." };
+    }
+    if (claimable?.kind === "unclaimed") {
+        const detail = `a free Neon database, unclaimed: ${claimable.hoursLeft} hours left`;
+        return claimable.hoursLeft < 24
+            ? { name, status: "warn", detail, fix: `Keep it with \`${cli} neon claim\`, or Neon deletes it with its data.` }
+            : { name, status: "ok", detail: `${detail} (\`${cli} neon claim\` keeps it)` };
+    }
+    return { name, status: "ok", detail: "Neon, pooled for the app and direct for migrations and the jobs worker" };
+}