create-snagset 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eurico Sá Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# `create-snagset`
+
+Scaffold a self-hosted **[Snagset](https://github.com/snagset/snagset)** instance
+— click-to-comment review for your clients' live sites.
+
+```bash
+npx create-snagset my-review
+cd my-review
+docker compose up
+```
+
+Postgres is included. Open `http://localhost:8080` and follow the claim URL in
+the logs. Already have a database? Put its URL in `.env`, then `npm install &&
+npm start`.
+
+## What you get
+
+A directory with everything an instance needs and nothing it does not:
+
+| | |
+|---|---|
+| `compose.yml` | The server and a Postgres, for `docker compose up` |
+| `.env` | Configuration. **`DATABASE_URL` is the only required variable** — a signing key is generated into it for you |
+| `package.json` | `@snagset/server` as a dependency, with `start`, `migrate` and `env` scripts |
+| `vercel.json` + `api/index.js` | Deploy to Vercel instead, if you would rather not run anything |
+| `README.md` | The operating manual, written for the instance you just made |
+
+## Then what
+
+Sign in, add a site, and paste the tag it gives you into the site you want
+reviewed:
+
+```html
+<script src="http://localhost:8080/snag.js" data-snag-site="prj_…" defer></script>
+```
+
+Your client opens a review link, clicks the thing that's wrong, and types.
+**No account, no extension, no login** — the link is the whole identity. You
+get the pin, the screenshot, the console and the route.
+
+Prefer an import? `npm i snagset` gives you the same tag from
+`snagset.init({ host, site })`, or the framework subpaths — `snagset/react`,
+`snagset/vue`, `snagset/next`, `snagset/vite` (which covers Nuxt and
+SvelteKit too), `snagset/astro`.
+
+## What it costs to run
+
+A Node process and a Postgres. Screenshots want an S3-compatible bucket (R2,
+Spaces, MinIO, AWS) and notifications want a mailer — **both optional**, and
+the product is honest without them: no bucket means annotation mode and the
+widget says screenshots are unavailable rather than offering one that fails.
+
+## Back up the signing key
+
+If you did not set `SNAGSET_SECRET_KEY`, one was generated into your `.env`.
+**Treat it as a password.** Without it every reviewer session is dead and any
+stored credential is unreadable ciphertext.
+
+---
+
+**Early release.** The install path is tested end to end, but this is a `0.0.x`
+line: expect the odd rough edge, and pin the version if you need stability.
+Issues and notes are welcome at
+[snagset/snagset](https://github.com/snagset/snagset).
+
+AGPL-3.0-only. The widget you put on a client's site is
+[`snagset`](https://www.npmjs.com/package/snagset), and it is MIT.

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { scaffold } from "./scaffold.js";
+/**
+ * The bin. Argument handling and exit codes only — everything that touches the
+ * filesystem is in `scaffold.ts`, which has no side effects at import time and
+ * is therefore testable.
+ */
+const target = process.argv[2];
+if (!target || target.startsWith("-")) {
+    process.stderr.write("usage: npx create-snagset <directory>\n\n" +
+        "  npx create-snagset my-review\n" +
+        "  cd my-review && docker compose up\n");
+    process.exit(2);
+}
+try {
+    scaffold(target);
+}
+catch (e) {
+    process.stderr.write(`✗ ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(2);
+}
+const name = target.split("/").pop() || "snagset";
+process.stdout.write(`\n  ✓ ${name}\n\n` +
+    `  cd ${target}\n` +
+    `  docker compose up\n\n` +
+    `  Then open http://localhost:8080 and follow the claim URL in the logs.\n` +
+    `  No Docker? Put a Postgres URL in .env, then \`npm install && npm start\`.\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

@@ -0,0 +1,106 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+/**
+ * `npx create-snagset` — D63's self-host, the `create-next-app` model.
+ *
+ * ── WHY A SCAFFOLDER AND NOT `git clone` ──
+ *
+ * FasterFixes ships `git clone` + `pnpm install` + a build, and it is the
+ * weakest part of their docs: it makes the operator your build engineer. They
+ * own the Node version, the lockfile and the build step, and every upgrade is
+ * a pull, a reinstall and a rebuild against a tree that has moved underneath
+ * them. Sixteen environment variables and four mandatory external services
+ * before the first run.
+ *
+ * What this writes instead is a small repository the operator OWNS — their
+ * `.env`, their compose file, their deploy config — that depends on
+ * `@snagset/server` like any other package. Upgrading is `npm update`. There
+ * is no build. Our source is not in their tree unless they want it, and when
+ * they do, it is AGPL and the repository is public.
+ *
+ * ── WHY NOT `npm install @snagset/server` INTO A DIRECTORY THEY INVENTED ──
+ *
+ * Because the interesting files are not the dependency. A working self-host is
+ * a compose file with Postgres in it, a `.env` with the one required variable
+ * already spelled, a Vercel config, a serverless entry point, and a README
+ * that says which of those matter. `npm install` gives you a `node_modules`
+ * and a blank page; measured on a cold room, the install is 5 seconds and the
+ * remaining friction is entirely "what do I write, and where".
+ */
+const HERE = dirname(fileURLToPath(import.meta.url));
+/**
+ * `dist/template` beside the compiled entry (see scripts/copy-template.mjs),
+ * falling back to `../template` so the package runs from source in this repo.
+ *
+ * The fallback is the honest version of "it works on my machine": without it
+ * every local run and every test would read a directory that only exists after
+ * a build, and the first person to try `node src/index.ts` would get an empty
+ * scaffold with no error.
+ */
+const TEMPLATE = existsSync(join(HERE, "template"))
+    ? join(HERE, "template")
+    : join(HERE, "..", "template");
+/**
+ * `_package.json` on disk, `package.json` when written.
+ *
+ * npm STRIPS a `.gitignore` from a published tarball and rewrites a nested
+ * `package.json`, which is why these two ship under other names. The `_`
+ * prefix is the convention `create-next-app` and `create-vite` both use, for
+ * exactly this reason, and a template that ships without its `.gitignore`
+ * produces a scaffold whose first `git add .` commits `node_modules` and a
+ * `.env` holding a database password.
+ */
+export const RENAME = {
+    "_package.json": "package.json",
+    _gitignore: ".gitignore",
+    "_env.example": ".env.example",
+    "api_index.js": "api/index.js",
+};
+/**
+ * Scaffold into `dir`. Pure enough to test: it takes and returns paths, throws
+ * a sentence rather than calling `process.exit`, and writes nothing outside
+ * the directory it was given.
+ *
+ * Split from the bin for one specific reason — the first version guarded
+ * `main()` with `if (/create-snagset/.test(process.argv[1]))` so a test could
+ * import it, and the test file's own path contains `create-snagset`, so
+ * importing it would have scaffolded into the test runner's working directory.
+ * A module with side effects at import time cannot be tested; the fix is not a
+ * cleverer guard.
+ */
+export function scaffold(target, cwd = process.cwd()) {
+    const dir = resolve(cwd, target);
+    // A non-empty directory is refused rather than merged into. Merging is how a
+    // scaffolder overwrites somebody's `.env`, and there is no undo for that.
+    if (existsSync(dir) && readdirSync(dir).length > 0) {
+        throw new Error(`${target} already exists and is not empty.`);
+    }
+    mkdirSync(join(dir, "api"), { recursive: true });
+    const name = target.split("/").pop() || "snagset";
+    // Pinned to THIS scaffolder's version, so `create-snagset@1.4.2` produces a
+    // repo on `@snagset/server@1.4.2`. A caret here would let a fresh scaffold
+    // resolve to a server this template has never been run against.
+    const version = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version;
+    for (const entry of readdirSync(TEMPLATE)) {
+        const out = RENAME[entry] ?? entry;
+        const body = readFileSync(join(TEMPLATE, entry), "utf8")
+            .replaceAll("__NAME__", name)
+            .replaceAll("__VERSION__", version);
+        writeFileSync(join(dir, out), body);
+    }
+    /**
+     * `.env` is written, not just `.env.example`, and with a REAL signing key.
+     *
+     * The alternative — ship an example and tell them to copy it — adds a step
+     * between the scaffold and the first run, which is the step where an install
+     * stalls. And generating the key here rather than letting the server do it
+     * on first boot matters for the deploy case: 08 §4.2's generate-to-disk is
+     * bin-only, so an operator who scaffolds locally and deploys to a platform
+     * 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")}`);
+    writeFileSync(join(dir, ".env"), env);
+    return dir;
+}

package/dist/template/README.md

@@ -0,0 +1,82 @@
+# __NAME__
+
+A self-hosted [Snagset](https://github.com/snagset/snagset) instance. Click-to-comment
+review for your clients' live sites.
+
+## Run it
+
+```bash
+docker compose up
+```
+
+Postgres is included. Open http://localhost:8080 and follow the claim URL
+printed in the logs.
+
+**Already have a database?** Put its URL in `.env`, then:
+
+```bash
+npm install
+npm start
+```
+
+## Add a site
+
+Sign in, open **Sites**, and add one. You get a script tag:
+
+```html
+<script src="http://localhost:8080/snag.js" data-snag-site="prj_…" defer></script>
+```
+
+Paste it into the site you want reviewed, before `</body>`. Or install the npm
+package — `npm i snagset` — and `snagset.init({ host, site })`, or one of the
+framework subpaths: `snagset/react`, `snagset/vue`, `snagset/next`,
+`snagset/vite` (which also covers Nuxt and SvelteKit), `snagset/astro`. They
+all write the same tag.
+
+**The site's address has to be on the allow-list.** That is the field beside
+the name when you add it. A tag on an address that is not listed loads and is
+ignored, which is the hardest failure here to spot from the outside.
+
+## Configure
+
+`.env`. Only `DATABASE_URL` is required.
+
+```bash
+npm run env          # every variable this build accepts, with its default
+npm run env MAIL     # just the ones matching MAIL
+```
+
+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.
+
+## Deploy it
+
+**Vercel.** `vercel.json` and `api/index.js` are here already. Add a Postgres
+from the marketplace, 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:
+
+```
+npx snagset migrate
+```
+
+**Anything that runs Node.** `npm start`. It serves the API, the dashboard and
+the widget on one port.
+
+## Upgrading
+
+```bash
+npm update @snagset/server
+```
+
+Migrations run on boot. There is no build step to redo.
+
+## Back up your signing key
+
+If you did not set `SNAGSET_SECRET_KEY`, the server generated one at
+`.snagset/secret.key` on first boot. **Treat it as a password.** Without it,
+every reviewer session is dead and any stored credential is unreadable
+ciphertext.

package/dist/template/_env.example

@@ -0,0 +1,27 @@
+# ── Required ───────────────────────────────────────────────────────────
+# Any Postgres 14+. `docker compose up` provides one at this URL.
+DATABASE_URL=postgres://snagset:snagset@localhost:5432/snagset
+
+# ── Strongly recommended ───────────────────────────────────────────────
+# 32 random bytes, base64url. Generated to .snagset/secret.key on first boot
+# if unset — which is fine on one machine and wrong everywhere else, because
+# each instance would invent a different one.
+#
+#   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.
+# SNAGSET_BASE_URL=http://localhost:8080
+
+# ── Claim it without a browser (optional) ──────────────────────────────
+# Set these and the first `npm start` creates the owner and the first site.
+# All of it is ignored once an owner exists, so it is safe to leave here.
+# SNAGSET_BOOTSTRAP_OWNER_EMAIL=you@example.com
+# SNAGSET_BOOTSTRAP_OWNER_PASSWORD_FILE=./owner-password
+# SNAGSET_BOOTSTRAP_PROJECT_NAME=First site
+# SNAGSET_BOOTSTRAP_PROJECT_ORIGINS=https://staging.example.com,http://localhost:3000
+
+# ── 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.

package/dist/template/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+# Your database URL and your signing key live here. Never commit it.
+.env
+.env.local
+# 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/

package/dist/template/_package.json

@@ -0,0 +1,16 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "snagset serve",
+    "migrate": "snagset migrate",
+    "bootstrap": "snagset bootstrap",
+    "env": "snagset env",
+    "sites": "snagset projects"
+  },
+  "dependencies": {
+    "@snagset/server": "__VERSION__"
+  },
+  "engines": { "node": ">=22" }
+}

package/dist/template/api_index.js

@@ -0,0 +1,8 @@
+// The serverless entry — one line, because `@snagset/server` exports the
+// Web-standard `fetch(Request) => Response` handler every platform accepts.
+//
+// Vercel, Netlify Functions, Cloudflare Workers and Deno Deploy all take this
+// shape. Migrations run as a DEPLOY step, not on cold start (see README) —
+// migrating on a request's critical path would put every instance behind one
+// applying DDL, on somebody's first page load.
+export { default } from "@snagset/server/serverless";

package/dist/template/compose.yml

@@ -0,0 +1,40 @@
+# One command: `docker compose up`.
+#
+# Postgres is included so there is nothing to provision before the first run.
+# Point DATABASE_URL at a managed database instead — Neon, Supabase, RDS — and
+# delete the `db` service; nothing else changes.
+services:
+  db:
+    image: postgres:18-alpine
+    environment:
+      POSTGRES_USER: snagset
+      POSTGRES_PASSWORD: snagset
+      POSTGRES_DB: snagset
+    ports: ["5432:5432"]
+    volumes: ["snagset-db:/var/lib/postgresql/data"]
+    healthcheck:
+      # The server migrates on boot, so it must not start against a database
+      # that is still initialising — the advisory lock would be taken against
+      # a socket that is not accepting connections yet.
+      test: ["CMD-SHELL", "pg_isready -U snagset"]
+      interval: 2s
+      timeout: 3s
+      retries: 20
+
+  snagset:
+    image: node:22-alpine
+    working_dir: /app
+    volumes: ["./:/app"]
+    command: sh -c "npm install --omit=dev && npm start"
+    env_file: [.env]
+    environment:
+      # Inside the compose network the database is `db`, not `localhost` —
+      # overridden here so the same .env works for `npm start` on the host.
+      DATABASE_URL: postgres://snagset:snagset@db:5432/snagset
+      SNAGSET_BIND_ADDRESS: 0.0.0.0
+    ports: ["8080:8080"]
+    depends_on:
+      db: { condition: service_healthy }
+
+volumes:
+  snagset-db:

package/dist/template/vercel.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "crons": [
+    { "path": "/api/jobs/run", "schedule": "* * * * *" }
+  ]
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "create-snagset",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "description": "Scaffold a self-hosted Snagset instance — a repository you own, with Docker Compose, a Vercel config, and one variable to fill in.",
+  "license": "AGPL-3.0-only",
+  "bin": {
+    "create-snagset": "./dist/index.js"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-template.mjs",
+    "prepack": "tsc -p tsconfig.build.json && node scripts/copy-template.mjs && node ../../tools/publish-manifest.mjs strip",
+    "postpack": "node ../../tools/publish-manifest.mjs restore"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snagset/snagset.git",
+    "directory": "packages/create-snagset"
+  },
+  "homepage": "https://github.com/snagset/snagset",
+  "bugs": {
+    "url": "https://github.com/snagset/snagset/issues"
+  }
+}