create-snagset 0.0.4 → 0.1.1

package/README.md

@@ -20,8 +20,10 @@ bun  create snagset my-review          # then: bun install  && bun start
 </details>
 
 Bring a Postgres URL — a free Neon or Supabase branch, or a local install — and
-put it in `.env` as `DATABASE_URL`. Open `http://localhost:8080` and follow the
-claim URL in the logs.
+put it in `.env` as `DATABASE_URL`. Open `http://localhost:8080` and create the
+first owner — an instance nobody has claimed shows a setup screen rather than a
+sign-in form, and **the first person to fill it in becomes the owner**, so do
+that before you share the address.
 
 **No Docker, on purpose.** No Dockerfile, no compose file, nothing to build:
 Snagset is a Node process and a Postgres URL.

package/dist/index.js

@@ -26,6 +26,9 @@ process.stdout.write(`\n  ✓ ${name}\n\n` +
     `  cd ${target}\n` +
     `  pnpm install && pnpm start\n\n` +
     `  (npm, yarn and bun work the same way.)\n\n` +
-    `  Then open http://localhost:8080 and follow the claim URL in the logs.\n\n` +
+    `  Then open http://localhost:8080 and create the first owner.\n` +
+    `  An instance nobody has claimed shows a setup screen rather than a\n` +
+    `  sign-in form, and the FIRST person to fill it in becomes the owner —\n` +
+    `  so do that before you share the address.\n\n` +
     `  A signing key was generated into .env. Back it up — without it every\n` +
     `  session and stored credential is unrecoverable.\n\n`);

package/dist/scaffold.js

@@ -101,6 +101,12 @@ export function scaffold(target, cwd = process.cwd()) {
      * would otherwise discover on the far side that they had no key to set.
      */
     const env = readFileSync(join(dir, ".env.example"), "utf8").replace("# SNAGSET_SECRET_KEY=", `SNAGSET_SECRET_KEY=${randomBytes(32).toString("base64url")}`);
+    // Nothing to quote here yet — the placeholder URL has no `&`. The QUOTED
+    // form is in the example itself, because a real connection string usually
+    // does: `?sslmode=require&channel_binding=require` ends a shell command at
+    // the `&` and runs the rest in the background, so `. .env` breaks on exactly
+    // the URL a Neon or Supabase branch hands you. Reported from a deploy trial,
+    // 2026-09-01.
     writeFileSync(join(dir, ".env"), env);
     return dir;
 }

package/dist/template/README.md

@@ -26,7 +26,9 @@ bun install && bun start
 ```
 </details>
 
-Open http://localhost:8080 and follow the claim URL printed in the logs.
+Open http://localhost:8080 and create the first owner. An instance nobody has
+claimed shows a setup screen rather than a sign-in form, and **the first person
+to fill it in becomes the owner** — so do that before you share the address.
 
 **No Docker anywhere in this project, deliberately.** One less thing to
 install, and one less thing between you and a database you can also reach from
@@ -55,8 +57,11 @@ ignored, which is the hardest failure here to spot from the outside.
 `.env`. Only `DATABASE_URL` is required.
 
 ```bash
-pnpm env             # every variable this build accepts, with its default
-pnpm env MAIL        # just the ones matching MAIL
+pnpm run env         # every variable this build accepts, with its default
+pnpm run env MAIL    # just the ones matching MAIL
+
+# `run` is not optional here: `pnpm env` is pnpm's OWN command (it manages
+# Node versions) and shadows the script. npm and yarn need no `run`.
 ```
 
 Screenshots need an S3-compatible bucket (R2, Spaces, MinIO, AWS).
@@ -82,10 +87,17 @@ the widget on one port.
 ## Upgrading
 
 ```bash
-pnpm update @snagset/server
+pnpm update @snagset/server --latest
 ```
 
-Migrations run on boot. There is no build step to redo.
+Then `pnpm start` again, or redeploy. Migrations run on boot; there is no
+build step to redo.
+
+`--latest` matters: this project pins `@snagset/server` to an exact version on
+purpose (a fresh clone installs the version you last ran), and a plain
+`pnpm update` respects the pin — it does nothing. Back up the database before
+a version that carries migrations; the release notes name any that cannot
+roll back.
 
 ## Back up your signing key
 

package/dist/template/_env.example

@@ -1,7 +1,9 @@
 # ── Required ───────────────────────────────────────────────────────────
 # Any Postgres 14+ — a free Neon or Supabase branch, or a local install.
 # Use the POOLED connection string where your provider offers one.
-DATABASE_URL=postgres://snagset:snagset@localhost:5432/snagset
+# QUOTE IT. A managed provider appends `?sslmode=require&channel_binding=require`,
+# and an unquoted `&` ends the line as far as `. .env` is concerned.
+DATABASE_URL="postgres://snagset:snagset@localhost:5432/snagset"
 
 # ── Strongly recommended ───────────────────────────────────────────────
 # 32 random bytes, base64url. Generated to .snagset/secret.key on first boot
@@ -11,7 +13,7 @@ DATABASE_URL=postgres://snagset:snagset@localhost:5432/snagset
 #   node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
 # SNAGSET_SECRET_KEY=
 
-# The public origin. Review links and the claim URL are built from it.
+# The public origin. Review links are built from it.
 # SNAGSET_BASE_URL=http://localhost:8080
 
 # ── Claim it without a browser (optional) ──────────────────────────────
@@ -22,7 +24,24 @@ DATABASE_URL=postgres://snagset:snagset@localhost:5432/snagset
 # SNAGSET_BOOTSTRAP_PROJECT_NAME=First site
 # SNAGSET_BOOTSTRAP_PROJECT_ORIGINS=https://staging.example.com,http://localhost:3000
 
+# ── Screenshots (optional) ─────────────────────────────────────────────
+# Any S3-compatible bucket — DigitalOcean Spaces, Cloudflare R2, MinIO, S3.
+# Without one the widget runs in annotation mode and SAYS so, rather than
+# failing quietly at the moment somebody files their first snag.
+# SNAGSET_STORAGE_S3_ENDPOINT=https://ams3.digitaloceanspaces.com
+# SNAGSET_STORAGE_S3_BUCKET=my-bucket
+# SNAGSET_STORAGE_S3_REGION=auto
+# SNAGSET_STORAGE_S3_ACCESS_KEY_ID=
+# SNAGSET_STORAGE_S3_SECRET_ACCESS_KEY=
+
+# ── Email notifications (optional) ─────────────────────────────────────
+# The URL SCHEME picks the transport: resend://, smtp://, smtps://.
+# Unset means no mail, which is a supported way to run — nothing queues up
+# waiting for a transport that never arrives.
+# SNAGSET_MAIL_URL=resend://re_your_api_key
+# SNAGSET_MAIL_FROM=snagset@example.com
+
 # ── Everything else ────────────────────────────────────────────────────
-# `npm run env` prints every variable this build accepts, with its default.
-# Screenshots need an S3-compatible bucket; notifications need a mailer.
-# Both are optional and the product is honest about running without them.
+# `npm run env` prints every variable this build accepts, with its default —
+# 70-odd of them, which is why only the ones most people want are written out
+# above.

package/dist/template/vercel.json

@@ -1,5 +1,9 @@
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
+
+  "//": "EVERY PATH REACHES THE ONE HANDLER. Without this, Vercel's filesystem router serves only /api/index and 404s /, /snag.js and even the cron's own /api/jobs/run — before the handler runs, with x-vercel-error: NOT_FOUND. Found on a real deploy 2026-09-01, not by any test we own: a serverless entry that is never reached looks identical to one that works until somebody opens the site.",
+  "rewrites": [{ "source": "/(.*)", "destination": "/api/index" }],
+
   "crons": [
     { "path": "/api/jobs/run", "schedule": "* * * * *" }
   ]

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "create-snagset",
-  "version": "0.0.4",
+  "version": "0.1.1",
   "private": false,
   "type": "module",
   "description": "Scaffold your own Snagset instance. One command, Postgres included, one variable to fill in.",
   "license": "AGPL-3.0-only",
   "bin": {
-    "create-snagset": "./dist/index.js"
+    "create-snagset": "dist/index.js"
   },
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit",