create-snagset 0.1.5 → 0.1.7

package/dist/index.js

@@ -22,7 +22,8 @@ catch (e) {
 const name = target.split("/").pop() || "snagset";
 process.stdout.write(`\n  ✓ ${name}\n\n` +
     `  1. Put a Postgres URL in .env as DATABASE_URL.\n` +
-    `     A free Neon or Supabase branch works, so does a local install.\n\n` +
+    `     A free Supabase or Neon project works, so does a local install;\n` +
+    `     .env says which Supabase string goes where.\n\n` +
     `  cd ${target}\n` +
     `  pnpm install && pnpm start\n\n` +
     `  (npm, yarn and bun work the same way.)\n\n` +

package/dist/template/README.md

@@ -6,8 +6,11 @@ review for your clients' live sites.
 ## Run it
 
 You need a Postgres and its connection string. A free
-[Neon](https://neon.tech) or [Supabase](https://supabase.com) branch takes a
+[Supabase](https://supabase.com) or [Neon](https://neon.tech) project takes a
 minute and works from anywhere; a local `postgres` install is just as good.
+On Supabase, use the **session pooler** string for `npm start` and the
+**transaction pooler** string on Vercel — the comments in `.env` say which is
+which. On Neon, the pooled string.
 
 Put the URL in `.env` as `DATABASE_URL`, then:
 
@@ -64,21 +67,29 @@ pnpm run env MAIL    # just the ones matching MAIL
 # Node versions) and shadows the script. npm and yarn need no `run`.
 ```
 
-Screenshots need an S3-compatible bucket (R2, Spaces, MinIO, AWS).
-Notifications need a mailer. Both are optional: with no bucket you get
-annotation mode and the widget says screenshots are unavailable rather than
-offering one that fails; with no mailer, notifications are off and the
-dashboard says so.
+Screenshots need an S3-compatible bucket (DigitalOcean Spaces, R2, MinIO,
+AWS). Notifications need a mailer (Resend, or any SMTP). Both are optional:
+with no bucket you get annotation mode and the widget says screenshots are
+unavailable rather than offering one that fails; with no mailer, notifications
+are off and the dashboard says so. `.env` carries a worked example of each,
+and both can also be connected later from Studio › General without a restart.
+
+**Row-level security.** Supabase's `postgres` role (and Neon's owner role)
+can bypass the policies the server installs, and the boot log says so if
+yours does. The app scopes every query itself, so that is a lost second
+net rather than a hole; the self-hosting guide has the four-line SQL that
+gives you a role without the bypass.
 
 ## Deploy it
 
 **Vercel.** `vercel.json` and `api/index.js` are here already. The
 `rewrites` entry is load-bearing: without it Vercel's filesystem router serves
 only `/api/index` and 404s `/`, `/snag.js` and the cron's own path. Keep the
-file free of comment keys — Vercel's schema rejects them. Add a Postgres
-from the marketplace, set `SNAGSET_SECRET_KEY` (required on serverless — the
+file free of comment keys — Vercel's schema rejects them. Set `DATABASE_URL`
+to the **transaction pooler** string (Supabase from the marketplace sets a
+pooled one for you), set `SNAGSET_SECRET_KEY` (required on serverless — the
 filesystem is ephemeral, so a generated key would differ per instance and
-nothing would decrypt), and add a release command:
+nothing would decrypt) and `CRON_SECRET`, and add a build command:
 
 ```
 npx snagset migrate

package/dist/template/_env.example

@@ -1,8 +1,21 @@
 # ── Required ───────────────────────────────────────────────────────────
-# Any Postgres 14+ — a free Neon or Supabase branch, or a local install.
-# Use the POOLED connection string where your provider offers one.
-# QUOTE IT. A managed provider appends `?sslmode=require&channel_binding=require`,
-# and an unquoted `&` ends the line as far as `. .env` is concerned.
+# Any Postgres 14+: Supabase, Neon, RDS, or a local install. A free Supabase
+# or Neon project in a region near your clients takes a minute. Neon's
+# pooled string (the `-pooler` host) is the one to use and needs no notes.
+#
+# WHICH SUPABASE STRING. "Connect" on the project shows three:
+#   · Session pooler  (…pooler.supabase.com:5432, user postgres.<ref>)
+#       — for `npm start`: a Node process on Railway, Render, Fly, a VPS or
+#         your laptop. Works over IPv4.
+#   · Transaction pooler (…pooler.supabase.com:6543, same user)
+#       — for Vercel and other serverless hosts.
+#   · Direct (db.<ref>.supabase.co:5432) — IPv6 only unless you pay for the
+#         IPv4 add-on. A "network unreachable" at boot usually means this one
+#         was pasted on a host without IPv6.
+#
+# TLS is on for any host that is not local (SNAGSET_DATABASE_SSL=auto), so a
+# string with no `?sslmode=` in it is still encrypted. QUOTE IT regardless:
+# a string that does carry `?sslmode=require&…` ends a shell line at the `&`.
 DATABASE_URL="postgres://snagset:snagset@localhost:5432/snagset"
 
 # ── Strongly recommended ───────────────────────────────────────────────
@@ -28,9 +41,16 @@ DATABASE_URL="postgres://snagset:snagset@localhost:5432/snagset"
 # 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.
+#
+# DigitalOcean Spaces, which these lines are written for: make a Space in a
+# region, then API › Spaces Keys › Generate. The region is the one in the
+# endpoint (ams3 with ams3, fra1 with fra1 — `auto` is for R2). The ACCESS
+# KEY is the short DO00… value and the SECRET is the long one beside it; a
+# DigitalOcean API token is a different credential and cannot sign S3
+# requests. The bucket stays PRIVATE — the server serves every image itself.
 # SNAGSET_STORAGE_S3_ENDPOINT=https://ams3.digitaloceanspaces.com
 # SNAGSET_STORAGE_S3_BUCKET=my-bucket
-# SNAGSET_STORAGE_S3_REGION=auto
+# SNAGSET_STORAGE_S3_REGION=ams3
 # SNAGSET_STORAGE_S3_ACCESS_KEY_ID=
 # SNAGSET_STORAGE_S3_SECRET_ACCESS_KEY=
 
@@ -38,8 +58,14 @@ DATABASE_URL="postgres://snagset:snagset@localhost:5432/snagset"
 # 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.
+#
+# Resend: add and verify a domain at resend.com/domains FIRST (a subdomain
+# such as send.yourstudio.com keeps its reputation apart from your own
+# mail), then create an API key with sending access to it. The From address
+# must be on that domain, or every send is refused with "domain is not
+# verified" — the boot log and Studio › General both say so.
 # SNAGSET_MAIL_URL=resend://re_your_api_key
-# SNAGSET_MAIL_FROM=snagset@example.com
+# SNAGSET_MAIL_FROM="Snagset <review@send.yourstudio.com>"
 
 # ── Everything else ────────────────────────────────────────────────────
 # `npm run env` prints every variable this build accepts, with its default —

package/dist/template/_gitignore

@@ -5,3 +5,9 @@ node_modules/
 # The signing key the server generates on first boot if you did not set one.
 # Back this up; without it every session and encrypted credential is lost.
 .snagset/
+# `vercel link` and `vercel dev` write the project binding here.
+.vercel
+# OS and editor clutter, so the first `git status` shows only the scaffold.
+.DS_Store
+Thumbs.db
+*.log

package/dist/template/vercel.json

@@ -9,7 +9,7 @@
   "crons": [
     {
       "path": "/api/jobs/run",
-      "schedule": "* * * * *"
+      "schedule": "0 3 * * *"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-snagset",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "description": "Scaffold your own Snagset instance. One command, Postgres included, one variable to fill in.",