Add create-scratchwork-server: npm create scaffolding for self-hosted servers

[koomen]

What

npm create scratchwork-server my-server -- --platform cloudflare now scaffolds a standalone self-hosted Scratchwork server project. Platforms: cloudflare (Worker + R2 + D1), aws (Lambda Function URL + S3 + DynamoDB), local (single-machine Bun server).

New top-level create/ workspace publishing one package, create-scratchwork-server, with the platform chosen by --platform (or a TTY-only prompt).

Why one package instead of per-platform packages

The homepage promised npm create scratchwork-server-cloudflare (and variants). A single package is cleaner here:

• one bin, one README, one lockstep version entry instead of three near-identical packages in every build/verify/publish flow;
• the platform list can grow without minting new npm names;
• the UX cost is one extra flag, and the flag form is friendlier to the primary audience (agents) than interactive pickers anyway. Non-interactive with args alone; it prompts for the platform only when stdin/stdout are a TTY, and errors with usage otherwise.

scratchwork.dev/www/index.md's self-hosting section now documents the real commands (including bun run local / bun run deploy replacing the fictional node local.ts / node deploy.ts). The site is not republished here.

Template drift prevention (structural)

Templates are generated from the real deploy/* projects at build/pack time (create/generate-templates.ts, called from scripts/build-packages.ts while staging) and are never committed, so template code cannot drift from the deploy sources:

• cloudflare ← deploy/cloudflare-vanilla, aws ← deploy/generic-aws, local ← deploy/local-dev;
• mechanical transform: sndbx.sh → example.com placeholders, workspace:* → the exact lockstep version read from the root manifest at staging time (scripts/set-version.ts keeps it stamped — nothing hardcoded), repo-only ci/test scripts dropped, ../../shared tsconfig includes dropped;
• only the standalone README.md and gitignore per platform are hand-written (create/templates-src/) — the deploy projects' READMEs describe this repo's own deployments, so verbatim copies would be wrong;
• dotfiles ship underscore-prefixed (_env.example, _gitignore) because npm strips/repurposes some dotfiles in tarballs; the scaffolder renames them back.

ci coverage added

• create/ joins the root workspaces, so bun run ci runs its typecheck + test (22 tests: template transform guarantees, scaffolder behavior, bin arg handling) and check-versions enforces its lockstep version.
• create joins PUBLISHABLE, so scripts/check-npm-pack.ts packs and shape-checks its tarball (bin target present, templates ship, no stray sources), and adds a new stage: it runs the packed bin under plain Node (what npm create uses) to scaffold every platform template into the hermetic consumer — where the scaffolded @scratchwork/* deps resolve to the staged tarballs, no network — then typechecks each scaffolded project with the consumer-pinned tsc and asserts the deps are pinned to the exact lockstep version.
• Publish order: create-scratchwork-server publishes last via the same scripts/publish-packages.ts; RELEASING.md updated.

Also fixed in check-npm-pack.ts: the consumer assembly used to symlink every non-scoped repo node_modules entry, then copy extracted tarballs through those symlinks — for an unscoped packed package (like this one) that overwrote the actual workspace source. Packed package names are no longer symlinked.

Invariants

• Invariant 1: the new scaffolder code lives under the new top-level create/ dir and is deliberately plain Effect-free TypeScript, like scripts/ — the shipped bin must run under npm's plain Node with zero runtime dependencies. It is outside the Effect-boundary lint scope by placement, and AGENTS.md's workspace map now says so explicitly. No cli/, server/, or shared/ source changed (only the generated renderer hash, which follows the bun.lock change from adding a workspace).
• Invariant 2 (spirit): no hand-duplicated templates — generation from deploy/* at pack time makes drift structurally impossible, and the scaffold+typecheck ci stage verifies the result against exactly what ships.
• Invariants 3–6: untouched.

bun run ci passes locally end to end under the pinned Bun 1.2.15 (including the e2e LocalStack/miniflare lanes).

🤖 Generated with Claude Code