create-meith 0.17.2 → 0.19.0

package/dist/bin.mjs

@@ -8,6 +8,59 @@ import { promisify } from "node:util";
 
 // src/scaffold.ts
 var DEFAULT_REPOSITORY_URL = "https://github.com/meith-dev/meith";
+var DEFAULT_TEMPLATE_REPOSITORY_URL = "https://github.com/meith-dev/vercel-template";
+var NEXT_VERSION = "16.3.1";
+var AT_ROOT_FLAG = "--at-root";
+var MATERIALIZED_AT_ROOT = [
+  "app",
+  "src",
+  "public",
+  "next.config.mjs",
+  "postcss.config.mjs",
+  "components.json",
+  "instrumentation.ts",
+  "proxy.ts",
+  "tsconfig.json",
+  "next-env.d.ts"
+];
+var VERCEL_BUILD_COMMAND = `community migrate && forum-web build ${AT_ROOT_FLAG}`;
+var TICK_PATH = "/api/system/tick";
+var TICK_SCHEDULE = "* * * * *";
+var MATERIALIZED_PUBLIC = [
+  "placeholder-logo.png",
+  "placeholder-logo.svg",
+  "placeholder-user.jpg",
+  "placeholder.jpg",
+  "placeholder.svg",
+  "sw.js"
+];
+var AT_ROOT_IGNORE_PATHS = MATERIALIZED_AT_ROOT.flatMap(
+  (entry) => entry === "public" ? MATERIALIZED_PUBLIC.map((file) => `/public/${file}`) : [`/${entry}`]
+).join("\n");
+var AT_ROOT_IGNORES = `# What \`forum-web ${AT_ROOT_FLAG}\` writes into this directory: @meith/web's own
+# Next app, materialized here rather than into .meith/app so that the build
+# artefact lands at ./.next, where Vercel's Next.js builder reads it. Every
+# path here belongs to the framework and is rewritten on every build.
+#
+# public/ is listed file by file rather than as a directory, because that one
+# is shared: forum-web decides what it owns per file, so this board's own
+# public/ads.txt, public/.well-known/... or domain-verification file sits
+# beside the framework's and is tracked normally.
+#
+# app/ and src/ are ignored WHOLESALE, and that has a consequence worth
+# knowing before you go looking for it: a file you add under either is left
+# alone by the build and still never committed, so it works locally and is
+# simply absent from the deploy, which builds from what git has. Extend the
+# board with a plugin or a theme instead \u2014 the forum loads those from
+# community.config.ts, and they are yours to commit. forum-web prints a
+# warning naming any file of yours it finds there.
+#
+# For the rest, a build refuses rather than overwriting a file it did not
+# write, and names it. The two exceptions are tsconfig.json and
+# next-env.d.ts: forum-web generates those from scratch every run rather than
+# copying them, so it cannot tell one of yours from a stale one of its own
+# and replaces them without asking.
+${AT_ROOT_IGNORE_PATHS}`;
 var NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,213}$/;
 function validateName(name) {
   if (name === "") return "A project name is required.";
@@ -20,8 +73,305 @@ function validateName(name) {
   }
   return null;
 }
+var ENV_REQUIRED_HEADING = `# \u2500\u2500\u2500 Required \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`;
+var ENV_OPTIONAL_HEADING = `# \u2500\u2500\u2500 Optional \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`;
+var ENV_DATABASE_URL_PROSE = `# Your Postgres connection string.
+#
+# If it is a managed database that offers a TRANSACTION-MODE POOLER string, use
+# that rather than the direct one \u2014 Neon, Supabase and their kind hand out both,
+# and on the direct string a board works in testing and starts refusing
+# connections under the first real traffic, with an error that names the
+# database rather than the cause. Your own Postgres, with a fixed number of
+# processes in front of it, does not need one.`;
+var ENV_DIRECT_DATABASE_URL_PROSE = `# The other half of that pair: the DIRECT (non-pooler) string, used only by
+# \`community migrate\` and \`community backup\`. Migrations hold a session-level
+# advisory lock so that two deploys landing together queue instead of both
+# applying the same migration, and a transaction-mode pooler cannot hold that
+# lock: it takes the connection back the moment the lock statement ends, which
+# leaves the lock on a backend another client gets. Set both and each gets the
+# connection it needs; set only DATABASE_URL and migrations use it too, which is
+# right for a Postgres you run yourself.`;
+var ENV_AUTH_SECRET_PROSE = `# Session and token signing. No default, deliberately: a shipped default is a
+# board every reader of the source can sign a session for.
+#
+#   node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"`;
+var ENV_TICK_SECRET_PROSE = `# The shared secret the tick caller presents to GET /api/system/tick. Generate
+# it the same way. Without it the tick is unauthenticated, and the tick is how
+# bans expire and digests send.`;
+var ENV_DATA_SOURCE_PROSE = `# fixture = deterministic in-memory sample data, no database needed. This is
+# what \`npm run build\` uses, and what a checkout with no database falls back to.`;
+var ENV_APP_URL_PROSE = `# Absolute, no trailing slash. Used in mail, feeds and canonical URLs \u2014 every
+# place a relative URL cannot work because there is no request to be relative to.
+#
+# Optional: leave it blank and the installer asks, prefilled from the address you
+# load /install at, and stores the answer on the board where the settings screen
+# can change it without a redeploy. Set it here and it wins outright.`;
+var ENV_SMTP_MAIL_BLOCK = `# Mail. Leave these alone and the installer asks for mail on first run, storing
+# it on the board \u2014 a settings screen with a test button, no redeploy. Set
+# MAIL_DRIVER here instead and the environment wins outright, which is what you
+# want if the credential must not live in the database.
+#
+# The default sends NOTHING: each message goes to the server log, so password
+# reset fails silently until mail is configured one way or the other.
+# MAIL_DRIVER=smtp
+# MAIL_SMTP_HOST=smtp.example.com
+# MAIL_SMTP_PORT=465
+# MAIL_SMTP_SECURITY=tls        # tls (465) | starttls (587) | none
+# MAIL_SMTP_USERNAME=
+# MAIL_SMTP_PASSWORD=
+# MAIL_FROM=noreply@yourdomain.com`;
+function selfHostEnvExample(name) {
+  return `# ${name} \u2014 environment.
+#
+# Copy to .env.local for development. On the server this is \`.env\` beside the
+# compose file; nothing here belongs in git.
+
+${ENV_REQUIRED_HEADING}
+
+${ENV_DATABASE_URL_PROSE}
+DATABASE_URL=
+
+${ENV_DIRECT_DATABASE_URL_PROSE}
+# DIRECT_DATABASE_URL=
+
+${ENV_AUTH_SECRET_PROSE}
+AUTH_SECRET=
+
+${ENV_TICK_SECRET_PROSE}
+TICK_SECRET=
+
+${ENV_OPTIONAL_HEADING}
+
+${ENV_DATA_SOURCE_PROSE}
+DATA_SOURCE=postgres
+
+${ENV_APP_URL_PROSE}
+APP_URL=
+
+${ENV_SMTP_MAIL_BLOCK}
+
+`;
+}
+function vercelEnvExample(name) {
+  return `# ${name} \u2014 environment, on Vercel.
+#
+# Nothing on Vercel reads this file. The platform holds each of these as a
+# project environment variable, and the Deploy Button in README.md asks for the
+# ones it cannot provision itself. This is the reference for what they mean \u2014
+# and the file to copy to .env.local to run the same board on your own machine.
+
+# \u2500\u2500\u2500 Drivers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+# An instance is created for a request, may be frozen between requests, and is
+# destroyed without warning; it has a writable /tmp nothing else can read and no
+# background process of its own. Every driver below therefore keeps its state
+# somewhere outside the instance, and these five values are not a default to
+# tune \u2014 they are the one combination the board supports on functions.
+#
+# DATA_SOURCE=fixture is a read-only sample board with no write side.
+# QUEUE_DRIVER=memory loses every queued job when the instance goes away, which
+# is after almost every request, and the board already refuses it in production.
+# CACHE_DRIVER=next and memory cache inside the process, so each instance serves
+# its own stale copy for up to a minute. FILESTORE_DRIVER=local writes to a disk
+# no other instance can read and that is discarded with the instance \u2014 on Vercel
+# the board refuses it outright rather than losing uploads quietly.
+#
+# The deploy form asks for none of them. On Vercel the board works each one out
+# from what the linked stores publish: a DATABASE_URL means postgres for the
+# data source and the queue, a Redis connection string means CACHE_DRIVER=redis,
+# a Blob store's read-write token means FILESTORE_DRIVER=blob, and a
+# RESEND_API_KEY with a MAIL_FROM beside it means mail over the provider's HTTPS
+# API. Setting one here overrides the derivation, which is what this file is for
+# when you copy it to .env.local.
+#
+# Every one of those derivations is scoped to Vercel, and each fires only from a
+# value that is unambiguously the thing itself \u2014 a redis:// or rediss:// URL, a
+# read-write token. A board you run anywhere else is untouched by all of it and
+# still takes these values from this file, exactly as it did before.
+#
+# A derivation that cannot resolve is a configuration error, not an invitation
+# to pick something safe-looking. On Vercel, with the cache or the object store
+# missing, the board refuses to boot and names every variable it looked at. It
+# will not quietly cache inside the instance, and it will not quietly write
+# uploads to a disk that is about to disappear.
+DATA_SOURCE=postgres
+QUEUE_DRIVER=postgres
+CACHE_DRIVER=redis
+FILESTORE_DRIVER=blob
+MAIL_DRIVER=http
+
+${ENV_REQUIRED_HEADING}
+
+${ENV_DATABASE_URL_PROSE}
+DATABASE_URL=
+
+${ENV_DIRECT_DATABASE_URL_PROSE}
+#
+# On Vercel this is not optional, and it is no longer yours to copy. DATABASE_URL
+# here is the pooler string, the build runs \`community migrate\` against it, and
+# /install takes the second of those two session locks on first run. Left blank,
+# the board reads Neon's own direct string \u2014 \`DATABASE_URL_UNPOOLED\` first, then
+# \`POSTGRES_URL_NON_POOLING\` \u2014 and refuses to boot if neither is there, naming
+# both. Never \`POSTGRES_URL\`: that one is pooled.
+DIRECT_DATABASE_URL=
+
+# The shared cache \u2014 a Redis or Valkey endpoint, \`rediss://\` for TLS. Redis
+# holds cache entries and nothing else: losing it costs the board a warm cache,
+# not data, and signs nobody out. Left blank on Vercel, the board reads the
+# Upstash store's own \`KV_URL\`, which is the one variable it publishes that
+# speaks the Redis protocol \u2014 \`KV_REST_API_URL\` is an HTTPS endpoint and is
+# never used for this. A name we do not know goes here by hand.
+REDIS_URL=
+
+${ENV_AUTH_SECRET_PROSE}
+AUTH_SECRET=
+
+${ENV_TICK_SECRET_PROSE}
+#
+# Vercel Cron sends \`Authorization: Bearer <CRON_SECRET>\` and cannot be told to
+# send any other name, so CRON_SECRET is the one to set here. The board accepts
+# either name, and both when both are set. Whichever you use, 32 characters is
+# the floor \u2014 stricter than the 16 Vercel's own cron documentation suggests, so
+# a secret generated by following those instructions is rejected here.
+CRON_SECRET=
+# TICK_SECRET=
+
+# Uploads, in the Vercel Blob store the Deploy Button provisions. A store
+# attached to the project publishes BLOB_STORE_ID and nothing else \u2014 no token \u2014
+# because the SDK authenticates with the deployment's own OIDC identity: the
+# board hands it the store id and lets it fetch the credential. There is nothing
+# to type and nothing to mistype, and FILESTORE_DRIVER=blob derives from this
+# variable being present.
+#
+# BLOB_READ_WRITE_TOKEN is the other way in, and you make it yourself on the
+# store. Set it when something has to reach the store from OUTSIDE a Vercel
+# deployment \u2014 \`community backup\` run on your own machine is the case that
+# matters \u2014 because there is no OIDC identity there to borrow. Set both and the
+# board prefers the store id, unless the token names a different store, in which
+# case the token wins: naming another store is a deliberate act.
+#
+# Every object is written with private access: an object URL is not a public
+# link, and member content is served by the board, which is where permissions
+# are checked. An upload is held whole in the instance's memory on the way in
+# and on the way out, so the function's memory limit, not the store, is what
+# caps a file.
+BLOB_STORE_ID=
+BLOB_READ_WRITE_TOKEN=
+
+# Uploads in an S3-compatible bucket instead \u2014 AWS, R2, MinIO, Spaces. This is
+# the portable option, and the one every other deployment of this board uses:
+# a bucket is a thing you hold, and it is not the only way to get the objects
+# out of it. Set FILESTORE_DRIVER=s3 above and the first four below; boot fails
+# naming any that are missing. S3_ENDPOINT is for anything that is not AWS and
+# switches the client to path-style addressing; set S3_REGION=auto for R2.
+# S3_PUBLIC_BASE_URL is the host objects are *served* from when that is not the
+# API endpoint.
+# S3_BUCKET=
+# S3_REGION=
+# S3_ACCESS_KEY_ID=
+# S3_SECRET_ACCESS_KEY=
+# S3_ENDPOINT=
+# S3_PUBLIC_BASE_URL=
+
+# Mail over the provider's own HTTPS API, on 443 \u2014 the one outbound path a
+# function can rely on. SMTP on port 25 is blocked by serverless egress and the
+# board refuses it on Vercel; 587 with STARTTLS may work, but an API does not
+# depend on the platform's egress rules staying as they are.
+#
+# MAIL_FROM is yours to decide, and it belongs to the step that adds Resend
+# rather than to the deploy: it must be an address at a domain the provider has
+# verified for you, no default is right, and until a provider is added the board
+# cannot send from any address at all. Set it alongside the integration.
+MAIL_FROM=
+
+# Add the Resend integration to the project from Vercel's marketplace and it
+# publishes its key under this name, which the board reads: with RESEND_API_KEY
+# set, and MAIL_FROM beside it, the board sends over Resend's HTTPS API and
+# needs neither of the two variables below. The mail driver itself is a plain
+# JSON-over-HTTPS sender and is not Resend-specific \u2014 this is one injected name
+# bridged to the generic pair, not a provider baked into the board.
+RESEND_API_KEY=
+
+# Any other provider with the same shape \u2014 a bearer token and an endpoint that
+# accepts {from, to, subject, text, html, reply_to}. Set BOTH, plus
+# MAIL_DRIVER=http above; they do not turn the driver on by themselves, and only
+# RESEND_API_KEY implies it.
+#
+# Setting just one of them stands the Resend bridge down completely, on purpose:
+# the board will not hand a key issued for Resend to an endpoint you chose, nor
+# aim your token at Resend. Boot fails naming the half you left out. Delete
+# RESEND_API_KEY once you have moved off Resend.
+# MAIL_HTTP_ENDPOINT=
+# MAIL_HTTP_TOKEN=
+
+${ENV_OPTIONAL_HEADING}
+
+${ENV_APP_URL_PROSE}
+APP_URL=
+
+`;
+}
+function envExample(name, target) {
+  return target === "vercel" ? vercelEnvExample(name) : selfHostEnvExample(name);
+}
+var SELF_HOST_DEPLOY_KIT = [
+  ".dockerignore",
+  ".github/workflows/build.yml",
+  "Dockerfile",
+  "docker-compose.yml",
+  "docker-entrypoint.sh",
+  "docker-healthcheck.sh"
+];
+var VERCEL_DERIVED_DRIVERS = [
+  "DATA_SOURCE=postgres",
+  "QUEUE_DRIVER=postgres",
+  "CACHE_DRIVER=redis",
+  "FILESTORE_DRIVER=blob",
+  "MAIL_DRIVER=http"
+];
+var VERCEL_PROMPTED_ENV = ["AUTH_SECRET", "CRON_SECRET"];
+var VERCEL_MARKETPLACE_STORES = [
+  { type: "integration", integrationSlug: "neon", productSlug: "neon", protocol: "storage" },
+  {
+    type: "integration",
+    integrationSlug: "upstash",
+    productSlug: "upstash-kv",
+    protocol: "storage"
+  },
+  { type: "blob" }
+];
+function deployButtonUrl(templateRepositoryUrl) {
+  const params = new URLSearchParams([
+    ["repository-url", templateRepositoryUrl],
+    ["project-name", "meith-board"],
+    ["repository-name", "meith-board"],
+    ["env", VERCEL_PROMPTED_ENV.join(",")],
+    [
+      "envDescription",
+      "Two secrets, generated rather than chosen \u2014 32 characters or more each. Everything else the board reads from the database, cache and blob store this form links."
+    ],
+    ["envLink", `${templateRepositoryUrl}/blob/main/.env.example`],
+    ["stores", JSON.stringify(VERCEL_MARKETPLACE_STORES)],
+    ["skippable-integrations", "1"]
+  ]);
+  return `https://vercel.com/new/clone?${params.toString()}`;
+}
+function vercelJson() {
+  return `${JSON.stringify(
+    {
+      framework: "nextjs",
+      buildCommand: VERCEL_BUILD_COMMAND,
+      crons: [{ path: TICK_PATH, schedule: TICK_SCHEDULE }]
+    },
+    null,
+    2
+  )}
+`;
+}
 function scaffold(options) {
   const { name, version, repositoryUrl } = options;
+  const target = options.target ?? "self-host";
+  const atRootFlag = target === "vercel" ? ` ${AT_ROOT_FLAG}` : "";
   const files = /* @__PURE__ */ new Map();
   files.set(
     "package.json",
@@ -32,15 +382,16 @@ function scaffold(options) {
         private: true,
         type: "module",
         scripts: {
-          dev: "forum-web dev",
-          build: "forum-web build",
-          start: "forum-web start",
+          dev: `forum-web dev${atRootFlag}`,
+          build: `forum-web build${atRootFlag}`,
+          start: `forum-web start${atRootFlag}`,
           community: "community"
         },
         dependencies: {
           "@meith/web": version,
           "@meith/cli": version,
-          "@meith/theme-default": version
+          "@meith/theme-default": version,
+          next: NEXT_VERSION
         },
         engines: { node: ">=22" }
       },
@@ -54,7 +405,7 @@ function scaffold(options) {
     `# Every @meith/* dependency here is an exact version, not a range \u2014 see
 # README.md, "Upgrading", for why a range breaks the build. This makes that
 # the default for any \`npm install\` run in this project from here on,
-# including a plugin installed by hand later, not only the three packages
+# including a plugin installed by hand later, not only the four packages
 # the scaffold pinned itself.
 save-exact=true
 `
@@ -134,67 +485,7 @@ export function installedPluginDefinitions() {
 }
 `
   );
-  files.set(
-    ".env.example",
-    `# ${name} \u2014 environment.
-#
-# Copy to .env.local for development. On the server this is \`.env\` beside the
-# compose file; nothing here belongs in git.
-
-# \u2500\u2500\u2500 Required \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-
-# Your Postgres connection string.
-#
-# If it is a managed database that offers a TRANSACTION-MODE POOLER string, use
-# that rather than the direct one \u2014 Neon, Supabase and their kind hand out both,
-# and on the direct string a board works in testing and starts refusing
-# connections under the first real traffic, with an error that names the
-# database rather than the cause. Your own Postgres, with a fixed number of
-# processes in front of it, does not need one.
-DATABASE_URL=
-
-# Session and token signing. No default, deliberately: a shipped default is a
-# board every reader of the source can sign a session for.
-#
-#   node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
-AUTH_SECRET=
-
-# The shared secret the tick caller presents to GET /api/system/tick. Generate
-# it the same way. Without it the tick is unauthenticated, and the tick is how
-# bans expire and digests send.
-TICK_SECRET=
-
-# \u2500\u2500\u2500 Optional \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-
-# fixture = deterministic in-memory sample data, no database needed. This is
-# what \`npm run build\` uses, and what a checkout with no database falls back to.
-DATA_SOURCE=postgres
-
-# Absolute, no trailing slash. Used in mail, feeds and canonical URLs \u2014 every
-# place a relative URL cannot work because there is no request to be relative to.
-#
-# Optional: leave it blank and the installer asks, prefilled from the address you
-# load /install at, and stores the answer on the board where the settings screen
-# can change it without a redeploy. Set it here and it wins outright.
-APP_URL=
-
-# Mail. Leave these alone and the installer asks for mail on first run, storing
-# it on the board \u2014 a settings screen with a test button, no redeploy. Set
-# MAIL_DRIVER here instead and the environment wins outright, which is what you
-# want if the credential must not live in the database.
-#
-# The default sends NOTHING: each message goes to the server log, so password
-# reset fails silently until mail is configured one way or the other.
-# MAIL_DRIVER=smtp
-# MAIL_SMTP_HOST=smtp.example.com
-# MAIL_SMTP_PORT=465
-# MAIL_SMTP_SECURITY=tls        # tls (465) | starttls (587) | none
-# MAIL_SMTP_USERNAME=
-# MAIL_SMTP_PASSWORD=
-# MAIL_FROM=noreply@yourdomain.com
-
-`
-  );
+  files.set(".env.example", envExample(name, target));
   files.set(
     ".gitignore",
     `node_modules
@@ -629,11 +920,20 @@ echo "<password>" | npm run community -- user:create --username <name> --email <
 
 \`\`\`sh
 npm install --save-exact @meith/web@latest @meith/cli@latest @meith/theme-default@latest
-git commit -am "Upgrade @meith/web, @meith/cli and @meith/theme-default"
+npm install --save-exact next@$(node -p "require('./node_modules/@meith/web/package.json').dependencies.next")
+git commit -am "Upgrade Meith and the Next.js version it builds with"
 git push
 \`\`\`
 
-That one \`package.json\` change is the whole pin: \`Dockerfile\`'s own
+The second command is not optional. This board pins \`next\` itself, and
+nothing bumps it for you: upgrading only the \`@meith/*\` packages leaves the
+board's own pin on the old Next while \`@meith/web\` depends on the new one,
+which npm resolves by installing both \u2014 the build then runs on one version
+while everything reading \`package.json\` sees the other. Reading the version
+out of the freshly installed \`@meith/web\` is what keeps the two the same
+without anybody having to know the number.
+
+That \`package.json\` change is the whole pin: \`Dockerfile\`'s own
 \`FROM\` line takes the version as a build argument, and
 \`.github/workflows/build.yml\` reads it straight out of \`package.json\`'s
 own \`@meith/web\` dependency when it rebuilds \u2014 nothing in \`Dockerfile\`
@@ -654,8 +954,279 @@ there is no down migration to undo a destructive one, and a button that pretende
 otherwise would be worse than its absence.
 `
   );
+  if (target === "vercel") {
+    return vercelTree(files, {
+      name,
+      repositoryUrl,
+      templateRepositoryUrl: options.templateRepositoryUrl ?? DEFAULT_TEMPLATE_REPOSITORY_URL
+    });
+  }
   return files;
 }
+function vercelTree(base, options) {
+  const files = new Map(base);
+  for (const path of SELF_HOST_DEPLOY_KIT) files.delete(path);
+  files.set(
+    ".gitignore",
+    `node_modules
+.next
+.meith
+.vercel
+.env
+.env.local
+.env*.local
+*.log
+.DS_Store
+
+${AT_ROOT_IGNORES}
+`
+  );
+  files.set("vercel.json", vercelJson());
+  files.set("README.md", vercelReadme(options));
+  return files;
+}
+function vercelReadme({ name, repositoryUrl, templateRepositoryUrl }) {
+  return `# ${name}
+
+A forum, built on [Meith](${repositoryUrl}), running as Vercel functions.
+
+[![Deploy with Vercel](https://vercel.com/button)](${deployButtonUrl(templateRepositoryUrl)})
+
+## What the button provisions
+
+- **A copy of this repository** under your own GitHub account. Vercel builds
+  from it, and every later push to \`main\` redeploys.
+- **A Neon Postgres database**, attached to the project. Neon publishes the
+  pooled connection string as \`DATABASE_URL\` and the direct one as
+  \`DATABASE_URL_UNPOOLED\`.
+- **An Upstash Redis store**, attached the same way, for the shared cache. It
+  publishes \`KV_URL\`, which the board reads as \`REDIS_URL\` \u2014 \`KV_REST_API_URL\`
+  beside it is an HTTPS endpoint and is not used for this.
+- **A Vercel Blob store** for uploads, which publishes \`BLOB_STORE_ID\` into the
+  project by itself. That is the whole credential: the board hands the id to
+  Vercel's SDK, which authenticates with the deployment's own OIDC identity, so
+  there is no token to copy. This is what used to be four hand-typed \`S3_*\`
+  secrets.
+- **A Vercel project** carrying \`vercel.json\` \u2014 the build command
+  \`${VERCEL_BUILD_COMMAND}\`,
+  which applies the schema before it builds, materializes the board's app at
+  the project root so the artefact lands where Vercel reads it, and the cron
+  entry that drives the tick.
+
+**Mail is the one thing the button does not set up**, and it takes one click
+after the deploy \u2014 see *Mail, in one click* below. That is also where the
+address the board sends from goes: it has to be at a domain your provider has
+verified, which cannot be true of any domain before a provider exists. The
+board boots and runs without mail, and delivers nothing, silently, until it is
+done.
+
+## What to type into the deploy form
+
+**Two secrets**, generated rather than chosen. Thirty-two characters is a floor
+the board enforces at boot, not a suggestion:
+
+\`\`\`sh
+openssl rand -hex 32   # AUTH_SECRET
+openssl rand -hex 32   # CRON_SECRET
+\`\`\`
+
+\`CRON_SECRET\` is the name Vercel Cron sends, as \`Authorization: Bearer\`, and it
+cannot be told to send another \u2014 the caller is the platform, so this one has to
+be an environment variable both ends can read, and cannot be something the
+board makes up for itself. Note that this floor is stricter than the 16
+characters Vercel's own cron documentation suggests \u2014 a value generated by
+following those instructions is refused here, and the fix is a longer secret.
+
+\`AUTH_SECRET\` seals members' two-factor secrets and signs the unsubscribe links
+in outgoing mail. It stays in the environment deliberately: a copy of the
+database is then not enough to forge either.
+
+**That is the whole form.** Everything else the board works out from the stores
+this button just linked to the project:
+
+\`\`\`ini
+${VERCEL_DERIVED_DRIVERS.join("\n")}
+\`\`\`
+
+\`DIRECT_DATABASE_URL\` comes from Neon's own \`DATABASE_URL_UNPOOLED\`, or
+\`POSTGRES_URL_NON_POOLING\` if that one is absent \u2014 migrations and the first-run
+installer each hold a session-level advisory lock, which the pooled
+\`DATABASE_URL\` cannot hold. \`REDIS_URL\` comes from Upstash's \`KV_URL\`, the one
+variable it publishes that speaks the Redis protocol.
+
+Every one of those derivations is scoped to this platform, fires only where you
+have not set the variable yourself, and **refuses to boot rather than guess**.
+If a store is missing, or publishes a name this board does not know, the deploy
+stops with a message naming every variable it looked at \u2014 it will not fall back
+to caching inside each instance, or to uploads on a disk that is discarded with
+the instance. When the name is one we do not know, set \`REDIS_URL\` or
+\`DIRECT_DATABASE_URL\` in the project's environment settings and the derivation
+stands aside.
+
+If you would rather keep uploads somewhere you hold yourself \u2014 see *Leaving
+Vercel* below for why that matters \u2014 set \`FILESTORE_DRIVER=s3\` and add
+\`S3_BUCKET\`, \`S3_REGION\`, \`S3_ACCESS_KEY_ID\` and \`S3_SECRET_ACCESS_KEY\` in the
+project's environment settings, with \`S3_ENDPOINT\` for a bucket that is not AWS
+(\`S3_REGION=auto\` for R2). The same board runs either way.
+
+## Mail, in one click
+
+A board that cannot send mail cannot reset a password, so do this before you
+invite anybody.
+
+1. Open your project on Vercel, go to **Storage \u2192 Marketplace** (or
+   **Integrations**), and add **Resend**. It creates a Resend account linked to
+   the project and connects your sending domain.
+2. Verify that domain in the Resend dashboard if you have not already. Resend
+   refuses to send from an address at a domain it has not verified.
+3. Add \`MAIL_FROM\` to the project's environment settings \u2014 an address at that
+   verified domain, and the only mail value you ever type. The deploy form does
+   not ask for it, because a sender address is not something you can know
+   before there is a provider to verify it.
+4. Redeploy, or let the next push redeploy.
+
+That is all. The integration publishes its key into the project as
+\`RESEND_API_KEY\`, and the board reads that name: with it set, and \`MAIL_FROM\`
+beside it, mail sends over Resend's HTTPS API with nothing further to
+configure.
+
+The board is not tied to Resend. Its mail driver is a plain JSON-over-HTTPS
+sender that posts \`{from, to, subject, text, html, reply_to}\` with a bearer
+token \u2014 Resend's \`POST /emails\` happens to be exactly that shape, which is why
+it needs no adapter. Any provider with the same shape works: set
+\`MAIL_HTTP_ENDPOINT\`, \`MAIL_HTTP_TOKEN\` and \`MAIL_DRIVER=http\` in the
+project's environment settings, and set the first two **together** \u2014 either
+one on its own stands the Resend bridge down, so a key issued for Resend is
+never presented to an endpoint you chose. Only \`RESEND_API_KEY\` turns the
+driver on by itself. Delete it once you have moved off Resend.
+
+Check it worked: sign in as the administrator and use the test button on
+**/admin \u2192 Settings \u2192 Mail**.
+
+## First run: \`/install\`
+
+The build applies migrations, but an empty schema is not yet a board. Open
+\`https://<your-deployment>/install\` once the first deploy is green. It asks for
+the board's name and address and for the first administrator's username, email
+and password, creates the board and that account, and then **seals itself**:
+\`/install\` answers 404 from then on. Run it against the database you intend to
+keep \u2014 the screens are the ones
+[docs/quickstart.md](${repositoryUrl}/blob/main/docs/quickstart.md#4-run-the-installer)
+walks through.
+
+## The tick
+
+\`vercel.json\` asks Vercel to call \`${TICK_PATH}\` on \`${TICK_SCHEDULE}\`. That
+route is how bans expire, digests send, mail leaves the outbox and the queue
+drains; nothing here runs it on its own, because there is no worker process on
+a function platform. Two things about it are worth knowing **before** you
+deploy rather than after:
+
+- **A per-minute schedule needs a paid plan.** Hobby allows a couple of cron
+  jobs and runs each of them roughly once a day, at an hour Vercel chooses;
+  only paid plans accept an arbitrary cron expression. A board ticking daily
+  still loses nothing \u2014 tasks are written so a missed run delays work rather
+  than dropping it \u2014 but "as it happens" notifications become a daily digest in
+  all but name. To keep a minute-by-minute tick on Hobby, drive
+  \`${TICK_PATH}\` from something else that can call a URL on a schedule \u2014 a
+  GitHub Actions workflow, a systemd timer, an uptime pinger \u2014 presenting
+  \`TICK_SECRET\` instead.
+- **\`maxDuration = 300\` is validated when the project builds, not when the
+  function runs.** A plan that does not allow 300 seconds therefore **fails the
+  deployment** rather than clamping the request. With Fluid Compute \u2014 the
+  default for new projects \u2014 Hobby allows 300 and this builds as written. With
+  Fluid Compute switched off, Hobby caps a function at 60 seconds and the build
+  fails. Turn Fluid Compute back on.
+
+A tick that reaches the tasks and runs them answers \`200\` even when one of them
+threw, with \`ok: false\` and the failure named in \`ran\`. That is deliberate:
+schedulers retry non-2xx answers, and a task that fails every time would turn
+each retry into another attempt against whatever it is failing against.
+
+## Upgrading
+
+\`\`\`sh
+npm install --save-exact @meith/web@latest @meith/cli@latest @meith/theme-default@latest
+npm install --save-exact next@$(node -p "require('./node_modules/@meith/web/package.json').dependencies.next")
+git commit -am "Upgrade Meith and the Next.js version it builds with"
+git push
+\`\`\`
+
+Vercel rebuilds on the push, and the build command applies the new migrations
+before it builds. \`--save-exact\` matters and \`.npmrc\` already sets it for
+everything else installed here.
+
+The second command is not optional. This board pins \`next\` itself \u2014 Vercel
+reads that pin to pick its Next.js builder \u2014 and nothing bumps it for you.
+Upgrading only the \`@meith/*\` packages leaves two versions of Next
+installed, the board built with one and the platform configured for the
+other. Reading the version out of the freshly installed \`@meith/web\` keeps
+them the same without anybody having to know the number.
+
+Migrations are forward-only. Recovery is by restore, so take a backup first \u2014
+there is no down migration to undo a destructive one.
+
+## Leaving Vercel
+
+A board must stay movable, and the Blob store is the one part of this shape that
+is not portable: Neon and Upstash hand out ordinary Postgres and Redis strings
+that any host accepts, but a Vercel Blob store is reachable only through Vercel's
+own API and there is no bucket to sync out of it. **The uploads are the thing you
+have to carry out deliberately, and \`community backup\` is how.**
+
+Under \`FILESTORE_DRIVER=blob\`, \`community backup\` includes the uploads **by
+default** \u2014 it walks the Blob store, pulls every object, and puts them in the
+bundle beside the database dump. This is the opposite of the \`s3\` default, which
+skips them, because a bucket has its own backup story you can drive yourself and
+a Blob store does not:
+
+\`\`\`sh
+DATABASE_URL=\u2026            # Neon's pooled string
+DIRECT_DATABASE_URL=\u2026     # Neon's DATABASE_URL_UNPOOLED
+FILESTORE_DRIVER=blob
+BLOB_READ_WRITE_TOKEN=\u2026   # create one on the store; see below
+npm run community -- backup
+\`\`\`
+
+Run that from a checkout of this repository, with those four values in the
+environment \u2014 the CLI talks to Neon and to the Blob store over the network, so
+it does not have to run on Vercel.
+
+That last one is the one value this route asks you to make by hand, and only
+here. On the deployment the board reaches the store with \`BLOB_STORE_ID\` and
+the deployment's OIDC identity, which a command on your own machine does not
+have. Open the store under **Storage**, create a read-write token, and use it
+for the backup; the board itself never needs it. The bundle it writes holds the dump *and*
+every object. Check the last line it prints: if it says *no uploads*, the
+uploads are not in the bundle and restoring it gives a board whose posts have
+broken images.
+
+Restoring puts them wherever the *restoring* board's \`FILESTORE_DRIVER\` points,
+so the same bundle moves the board either onward or away:
+
+\`\`\`sh
+# onto a self-hosted board with a bucket
+FILESTORE_DRIVER=s3 S3_BUCKET=\u2026 RESTORE_DATABASE_URL=\u2026 npm run community -- restore bundle.tar.gz
+
+# onto a board that keeps uploads on its own disk
+RESTORE_DATABASE_URL=\u2026 npm run community -- restore bundle.tar.gz --uploads-dir ./uploads
+\`\`\`
+
+Take one before you need it. A Blob store deleted with the Vercel project takes
+the attachments with it, and there is no second copy anywhere unless you made
+one.
+
+## Somewhere other than Vercel
+
+Everything above is one deployment shape.
+[docs/self-hosting.md](${repositoryUrl}/blob/main/docs/self-hosting.md) is the
+same board as containers you run yourself, and \`npx create-meith <name>\`
+scaffolds that shape instead \u2014 a Dockerfile, a compose file and a workflow that
+builds the image. [docs/scaling.md](${repositoryUrl}/blob/main/docs/scaling.md)
+explains why the drivers above are what they are, and why an S3-compatible
+bucket is the portable choice for uploads everywhere but here.
+`;
+}
 function nextSteps(name) {
   return [`cd ${name}`, "npm install", "cp .env.example .env.local", "npm run dev"];
 }
@@ -758,7 +1329,7 @@ async function run(argv, version) {
 }
 
 // src/bin.ts
-var result = await run(process.argv.slice(2), "0.17.2");
+var result = await run(process.argv.slice(2), "0.19.0");
 for (const line of result.lines) {
   if (result.code === 0) console.log(line);
   else console.error(line);