@3sln/create-trove 0.0.3 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3sln/create-trove",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "description": "Scaffold a Trove deployment — Bun, Node, or Cloudflare Workers — with the bindings, environment and secrets each one needs.",
   "repository": {

package/src/cli.js

@@ -158,6 +158,7 @@ async function main() {
     let rendered;
     try {
       plan = await askPlan(prompter, { name, version, runtime: opts.runtime });
+      plan.inPlace = target === process.cwd();
       rendered = renderProject(plan);
     } catch (err) {
       // A bad --set value: name the key rather than making someone map a stack trace

package/src/index.js

@@ -35,13 +35,14 @@ export { createPrompter, presetPrompter, recordingPrompter, scripted } from './p
 /** Somewhere for headings to go that is not a caller's stdout. */
 const SILENT = { write() {}, isTTY: false };
 
-export async function createProject({ name, version, runtime, answers = {}, prompter } = {}) {
+export async function createProject({ name, version, runtime, answers = {}, prompter, inPlace = false } = {}) {
   // Silent unless the caller hands over a prompter that wants to talk. A library that
   // prints section headings to stdout cannot be used inside anything that emits
   // structured output — which is most of what would want to call this.
   const base = prompter ?? createPrompter({ assumeDefaults: true, output: SILENT });
   const preset = presetPrompter(answers, base);
   const plan = await askPlan(preset, { name, version, runtime: runtime ?? undefined });
+  plan.inPlace = inPlace;
   const { files, steps } = renderProject(plan);
   return { plan, files, steps, unused: preset.unused() };
 }

package/src/plan.js

@@ -17,8 +17,18 @@
 //   step on Workers and an untracked `.env` line elsewhere — it never lands in a file
 //   that belongs in version control. `secret: true` on an entry is what carries that.
 
+import { generateVapidKeys } from './vapid.js';
+
 export const RUNTIMES = ['bun', 'node', 'workers'];
 
+// LocalHashEmbedding's dimension (see core/src/search/embeddings.js). Not a default
+// anyone should be asked to confirm: with the built-in embedding this IS the number, and
+// a Vectorize index created at any other size accepts the deploy and then rejects every
+// vector write — so search returns nothing, forever, without a single error anywhere a
+// user would look. The wizard knows which embedding was chosen, so it derives this
+// rather than asking a question whose wrong answer is invisible.
+export const BUILTIN_EMBEDDING_DIM = '256';
+
 /** An environment/config entry. `secret` keeps it out of anything committed. */
 const entry = (key, value, { comment, secret = false, commented = false } = {}) =>
   ({ key, value, comment, secret, commented });
@@ -35,9 +45,13 @@ const placeholder = (key, comment) => entry(key, '', { comment, commented: true
  * @param {string} opts.version the @3sln/trove version to pin (this package's own —
  *   the two are released together, so they are the same number by construction)
  * @param {string} [opts.runtime] pre-answered by --runtime
+ * @param {() => Promise<{publicKey: string, privateKey: string}>} [opts.generateKeys]
+ *   how a local VAPID pair is minted. Injected so this stays the pure, transcript-driven
+ *   function it is elsewhere — a real key pair is random, and a test asserting on the
+ *   plan cannot assert on randomness.
  * @returns {Promise<object>} the plan
  */
-export async function askPlan(prompter, { name, version, runtime: preset }) {
+export async function askPlan(prompter, { name, version, runtime: preset, generateKeys = generateVapidKeys }) {
   const runtime = preset ?? await prompter.choice('Where will this run?', [
     { value: 'bun', label: 'Bun', hint: 'recommended for self-hosting' },
     { value: 'node', label: 'Node', hint: 'identical behaviour, a little slower' },
@@ -45,7 +59,11 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
   ], { key: 'runtime', default: 'bun' });
 
   const isWorkers = runtime === 'workers';
-  const plan = { name, version, runtime, sections: [], workers: null, server: null, skipped: [], warnings: [] };
+  const plan = {
+    name, version, runtime, sections: [], workers: null, server: null, skipped: [], warnings: [],
+    // Overwritten only if an HTTP embedding names its own size.
+    embeddingDim: BUILTIN_EMBEDDING_DIM,
+  };
 
   const add = (title, entries, { skipped = false } = {}) => {
     plan.sections.push({ title, entries, skipped });
@@ -135,7 +153,8 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
       entries.push(entry('TROVE_EMBEDDINGS_URL', await prompter.text('  Embeddings URL', { key: 'search.embeddingsUrl', default: 'https://api.openai.com/v1/embeddings' })));
       entries.push(entry('TROVE_EMBEDDINGS_API_KEY', await prompter.text('  API key', { key: 'search.embeddingsApiKey', default: '' }), { secret: true }));
       entries.push(entry('TROVE_EMBEDDINGS_MODEL', await prompter.text('  Model', { key: 'search.embeddingsModel', default: 'text-embedding-3-small' })));
-      entries.push(entry('TROVE_EMBEDDINGS_DIM', await prompter.text('  Dimensions', { key: 'search.embeddingsDim', default: '1536' }),
+      plan.embeddingDim = await prompter.text('  Dimensions', { key: 'search.embeddingsDim', default: '1536' });
+      entries.push(entry('TROVE_EMBEDDINGS_DIM', plan.embeddingDim,
         { comment: 'must match the model, and changing it means a reindex' }));
     }
 
@@ -229,6 +248,50 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
     ], { skipped: true });
   }
 
+  // --- notifications ---------------------------------------------------------
+  // Off by default, and harmless to decline: mentions reach the in-app inbox either
+  // way. What VAPID adds is the ping — a browser waking a service worker while the
+  // drive is closed. The push carries no text (the worker fetches the inbox over its
+  // own authenticated connection), so declining costs a banner and nothing else.
+  if (await prompter.section('Push notifications', { key: 'notify.enabled',
+    blurb: 'Web push when someone @mentions you. The in-app inbox works without it.',
+    default: false,
+  })) {
+    // A LOCAL pair, minted here, written only to the gitignored .dev.vars. VAPID keys
+    // are self-issued — no account, no network — so unlike an R2 credential there is
+    // nothing to go and fetch, and making the developer find a way to produce a P-256
+    // point before they can try the feature is friction with nothing on the other side
+    // of it.
+    //
+    // Separate from production on purpose. A key identifies an application server, and
+    // these are two different servers; keeping them apart also means the value sitting
+    // on a laptop is worth nothing if it leaks.
+    plan.devVapid = await generateKeys();
+
+    // The production PUBLIC key only. The private half is never asked for: the answer
+    // would be written to disk by a program whose whole job is writing files, and a
+    // production signing key has no business in a scaffolder's output. It goes straight
+    // from `npm run vapid` into `wrangler secret put`, and the step for that is emitted
+    // whether or not this is filled in — see the blank-secret entry below.
+    const publicKey = await prompter.text('  Production public key', { key: 'notify.publicKey', default: '',
+      hint: 'leave blank — `npm run vapid` prints a pair once the project is installed',
+    });
+    add('Push notifications', [
+      entry('TROVE_VAPID_PUBLIC_KEY', publicKey,
+        { comment: 'must be the pair of the TROVE_VAPID_PRIVATE_KEY secret' }),
+      entry('TROVE_VAPID_PRIVATE_KEY', '', { secret: true }),
+      entry('TROVE_VAPID_SUBJECT', await prompter.text('  Contact subject', { key: 'notify.subject', default: 'mailto:admin@example.com',
+        hint: 'mailto: or https URL — how a push service reaches you about your own traffic',
+      })),
+    ]);
+  } else {
+    add('Push notifications', [
+      placeholder('TROVE_VAPID_PUBLIC_KEY', 'both keys set enables web push; the inbox works either way'),
+      placeholder('TROVE_VAPID_PRIVATE_KEY', 'a credential — set it with `wrangler secret put`, not here'),
+      placeholder('TROVE_VAPID_SUBJECT', 'mailto: or https URL; defaults to mailto:admin@example.com'),
+    ], { skipped: true });
+  }
+
   // --- branding --------------------------------------------------------------
   // The manifest is generated from configuration rather than served from a file, so
   // this is the one place a self-hoster gets to put their own name on the thing their
@@ -262,7 +325,7 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
 
   // --- runtime specifics -----------------------------------------------------
   if (isWorkers) {
-    plan.workers = await askWorkers(prompter);
+    plan.workers = await askWorkers(prompter, { embeddingDim: plan.embeddingDim });
   } else {
     plan.server = { port: '8787', host: '0.0.0.0' };
     if (await prompter.section('Server', { key: 'server.enabled', blurb: 'Port and bind address.', default: false })) {
@@ -283,10 +346,12 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
  * the single most common way a first Workers deploy fails, and it fails at request time
  * rather than at deploy time.
  */
-async function askWorkers(prompter) {
+async function askWorkers(prompter, { embeddingDim }) {
   const w = {
     d1: null, pluginDb: null, vectorize: null, ai: false, tasks: true,
-    compatibilityDate: '2024-09-23',
+    // nodejs_compat v2 needs 2024-09-23 or later; that exact floor was also the hardcoded
+    // value, which made it two years stale on the day it shipped.
+    compatibilityDate: '2026-07-01',
   };
 
   if (await prompter.section('D1 (metadata)', { key: 'workers.d1.enabled',
@@ -309,7 +374,9 @@ async function askWorkers(prompter) {
   })) {
     w.vectorize = {
       index: await prompter.text('  Index name', { key: 'workers.vectorize.index', default: 'trove' }),
-      dimensions: await prompter.text('  Dimensions', { key: 'workers.vectorize.dimensions', default: '1536', hint: 'must match your embedding model' }),
+      // Derived, not asked. It has exactly one correct value — the dimension of the
+      // embedding chosen above — and getting it wrong fails silently.
+      dimensions: embeddingDim,
       metric: await prompter.choice('  Distance metric', [
         { value: 'cosine', label: 'cosine' },
         { value: 'euclidean', label: 'euclidean' },

package/src/render.js

@@ -10,6 +10,8 @@
 // everywhere else it means a gitignored `.env`. `secret: true` on an entry is the whole
 // mechanism — there is no second list to keep in sync.
 
+import { LOCAL_S3 } from './templates/localS3.js';
+import { VAPID_SCRIPT } from './templates/vapid.js';
 const RULE = '─'.repeat(58);
 
 /** The exact version, not a range: the two packages are released together, and a drive
@@ -18,10 +20,20 @@ const pin = (version) => version;
 
 const isSet = (e) => !e.commented && e.value !== '' && e.value != null;
 
+/** The value of one env key across every section, or undefined. */
+const valueOf = (sections, key) =>
+  sections.flatMap((s) => s.entries).find((e) => e.key === key && isSet(e))?.value;
+
+/** `cd` only when there is somewhere to go — scaffolding into `.` is already there. */
+const enter = (plan) => (plan.inPlace ? '' : `cd ${plan.name} && `);
+
 export function renderProject(plan) {
   const files = [];
   const steps = [];
-  const secrets = plan.sections.flatMap((s) => s.entries.filter((e) => e.secret && isSet(e)));
+  // Not `isSet`: leaving credentials blank is the common case at scaffold time — you
+  // rarely have R2 keys yet — and that is precisely when you need to be told which
+  // secrets the drivers you picked are going to want.
+  const secrets = plan.sections.flatMap((s) => s.entries.filter((e) => e.secret));
 
   if (plan.runtime === 'workers') renderWorkers(plan, files, steps, secrets);
   else renderServer(plan, files, steps);
@@ -101,7 +113,7 @@ import '@3sln/trove/server/adapters/${adapter}';
   files.push({ path: '.env', contents: envHeader(plan) + renderEnv(plan.sections) + serverVars(server) });
   files.push({ path: '.gitignore', contents: gitignore(['data/']) });
 
-  steps.push({ cmd: `cd ${name} && npm install`, why: 'pulls @3sln/trove — the web app is already built inside it' });
+  steps.push({ cmd: `${enter(plan)}npm install`, why: 'pulls @3sln/trove — the web app is already built inside it' });
   steps.push({ cmd: `npm start`, why: `serves the API and the workbench on :${server?.port ?? '8787'}` });
 }
 
@@ -119,18 +131,55 @@ const envHeader = (plan) => `# Generated by create-trove for a ${plan.runtime} d
 function renderWorkers(plan, files, steps, secrets) {
   const { name, version, workers: w } = plan;
 
+  // A local run needs somewhere for bytes to go, and there is no local R2. When the
+  // drive is configured for S3 we ship a bucket that speaks the same API, because the
+  // alternative — TROVE_STORAGE=memory — looks like it works and is a trap: memory
+  // storage lives in ONE isolate while scans and reindexes run in the TroveTasks Durable
+  // Object, which is another, so every item fails to index and search stays empty.
+  const bucket = valueOf(plan.sections, 'TROVE_S3_BUCKET');
+  const localS3 = valueOf(plan.sections, 'TROVE_STORAGE') === 's3' && bucket;
+  // Push was configured if the section ran, whether or not a production key was pasted
+  // in — the point of `npm run vapid` is that it usually was not.
+  const push = plan.sections.some((sec) => sec.title === 'Push notifications' && !sec.skipped);
+
   files.push({
     path: 'package.json',
     contents: JSON.stringify({
       name,
       private: true,
       type: 'module',
-      scripts: { dev: 'wrangler dev', deploy: 'wrangler deploy' },
+      scripts: {
+        dev: 'wrangler dev',
+        ...(localS3 ? { 'dev:s3': 'node dev/local-s3.js' } : {}),
+        ...(push ? { vapid: 'node dev/vapid.js' } : {}),
+        deploy: 'wrangler deploy',
+      },
       dependencies: { '@3sln/trove': pin(version) },
-      devDependencies: { wrangler: '^3.90.0' },
+      devDependencies: { wrangler: '^4.0.0' },
     }, null, 2) + '\n',
   });
 
+  if (localS3) {
+    // The bucket name is baked in rather than passed through the environment, so the
+    // script stays `node dev/local-s3.js` on every platform — `BUCKET=x node …` is not
+    // a thing that runs on Windows.
+    files.push({
+      path: 'dev/local-s3.js',
+      contents: LOCAL_S3.replace(
+        "const BUCKET = process.env.BUCKET || 'trove';",
+        `const BUCKET = process.env.BUCKET || ${JSON.stringify(bucket)};`,
+      ),
+    });
+  }
+
+  // Key rotation, and the way to produce the production pair in the first place. It
+  // lives in the generated project rather than in the wizard because the wizard runs
+  // through `npm create`, before this project has a node_modules — a scaffolder cannot
+  // hand you a command that needs a package it has not installed yet.
+  if (push) {
+    files.push({ path: 'dev/vapid.js', contents: VAPID_SCRIPT });
+  }
+
   files.push({
     path: 'src/worker.js',
     contents: `// The Worker entry.
@@ -146,16 +195,27 @@ export { default, TroveTasks } from '@3sln/trove/server/adapters/worker.js';
   files.push({ path: 'wrangler.toml', contents: wranglerToml(plan) });
   files.push({ path: '.gitignore', contents: gitignore(['.wrangler/']) });
 
-  const devVars = renderEnv(plan.sections, { secretsOnly: true });
-  if (devVars.trim()) {
+  // `.dev.vars.example` rather than `.dev.vars`: the real file is gitignored, so
+  // generating it produces something the next person on the project cannot see. The
+  // example is committed and says what to copy it to.
+  const devVars = devVarsExample(plan, { localS3, bucket });
+  if (devVars) files.push({ path: '.dev.vars.example', contents: devVars });
+
+  // And the real thing, gitignored, when there were answers worth keeping out of it.
+  // Without this the credentials someone just typed would be discarded — the example
+  // cannot hold them — and a local run against the real services would mean entering
+  // them a second time.
+  // A generated dev key counts: it is a value that exists nowhere else, so without
+  // this the pair minted a moment ago would be described and then thrown away.
+  const answered = secrets.some(isSet) || Boolean(plan.devVapid);
+  if (devVars && answered) {
     files.push({
       path: '.dev.vars',
-      contents: `# Credentials for \`wrangler dev\`. Gitignored, and NOT uploaded by \`wrangler deploy\` —\n`
-        + `# the deployed Worker reads these from secrets, which the README lists as commands.\n\n${devVars}`,
+      contents: devVarsExample(plan, { localS3, bucket, withSecrets: true }),
     });
   }
 
-  steps.push({ cmd: `cd ${name} && npm install`, why: 'wrangler, and @3sln/trove for the app assets' });
+  steps.push({ cmd: `${enter(plan)}npm install`, why: 'wrangler, and @3sln/trove for the app assets' });
   if (w?.d1) {
     steps.push({
       cmd: `npx wrangler d1 create ${w.d1.name}`,
@@ -171,14 +231,149 @@ export { default, TroveTasks } from '@3sln/trove/server/adapters/worker.js';
       why: 'semantic search — Vectorize is the only vector store that runs here',
     });
   }
-  const bucket = plan.sections.flatMap((s) => s.entries).find((e) => e.key === 'TROVE_S3_BUCKET' && isSet(e));
-  if (bucket) steps.push({ cmd: `npx wrangler r2 bucket create ${bucket.value}`, why: 'object bytes' });
+  if (bucket) steps.push({ cmd: `npx wrangler r2 bucket create ${bucket}`, why: 'object bytes' });
   for (const s of secrets) {
-    steps.push({ cmd: `npx wrangler secret put ${s.key}`, why: 'not in wrangler.toml — secrets never belong in a committed file' });
+    steps.push({
+      cmd: `npx wrangler secret put ${s.key}`,
+      why: isSet(s) ? 'in .dev.vars for local runs; set it here for the deployed Worker' : 'required by the drivers you chose',
+    });
   }
   steps.push({ cmd: 'npx wrangler deploy', why: '' });
 }
 
+/**
+ * The local-development overrides, as a committed example.
+ *
+ * `wrangler dev` reads `.dev.vars`, and values there beat `[vars]` in wrangler.toml.
+ * That is the only lever a local run has, and it needs one: a scaffolded Workers drive
+ * points at three things a laptop does not have. Without these overrides `npm run dev`
+ * builds, boots, serves the web app — and then answers every API route with a 500,
+ * which is a poor first five minutes and reads as a broken scaffold rather than a
+ * missing account.
+ *
+ * Each block is emitted only when the configuration actually needs it, so nobody is
+ * handed an override for a service they did not choose.
+ */
+function devVarsExample(plan, { localS3, bucket, withSecrets = false }) {
+  const { sections, workers: w } = plan;
+  const L = [];
+  const supplied = (key) => valueOf(sections, key);
+  const rule = (title) => {
+    L.push(`# ${RULE}`, `# ${title}`, `# ${RULE}`);
+  };
+
+  const auth = valueOf(sections, 'TROVE_AUTH');
+  const needsIdentityOverride = auth && auth !== 'anonymous';
+  const secrets = sections.flatMap((s) => s.entries.filter((e) => e.secret));
+  if (!needsIdentityOverride && !localS3 && !w?.vectorize && !plan.devVapid && !secrets.length) return null;
+
+  L.push(withSecrets
+    ? '# Local settings for `wrangler dev`. Gitignored, and NOT uploaded by `wrangler deploy` —'
+    : '# Copy to .dev.vars (gitignored) for `wrangler dev`. NOT uploaded by `wrangler deploy` —');
+  L.push('# the deployed Worker reads its credentials from secrets; see README.md for the commands.');
+  L.push('#');
+  L.push('# Values here OVERRIDE [vars] in wrangler.toml for local runs. That is what lets a');
+  L.push('# local drive work without a Cloudflare account: there is no local R2, no local');
+  L.push('# Vectorize, and nothing in front of `wrangler dev` to authenticate anyone.');
+  L.push('');
+
+  if (needsIdentityOverride) {
+    rule('Identity — local only');
+    L.push(`# TROVE_AUTH is "${auth}" in wrangler.toml, which verifies a token nothing issues`);
+    L.push('# locally — every request would be rejected. Locally you are one anonymous user,');
+    L.push('# and an admin, so the workbench is actually usable.');
+    L.push('TROVE_AUTH=anonymous');
+    L.push('TROVE_AUTH_REQUIRED=false');
+    L.push('TROVE_ADMINS=anonymous');
+    L.push('');
+  }
+
+  if (localS3) {
+    rule('Object storage — local only');
+    L.push('# `npm run dev:s3` serves a bucket on :9000 over the same S3 API R2 speaks, so a');
+    L.push('# local run exercises the real path: SigV4, presigned PUTs, multipart, ranges.');
+    L.push('#');
+    L.push('# Do NOT replace this with TROVE_STORAGE=memory. Memory storage lives in one');
+    L.push('# isolate, and scans and reindexes run in the TroveTasks Durable Object, which is');
+    L.push('# another — every item fails to index with "Object not found" and search quietly');
+    L.push('# returns nothing.');
+    L.push(`TROVE_S3_BUCKET=${bucket}`);
+    L.push('TROVE_S3_ENDPOINT=http://127.0.0.1:9000');
+    L.push('# Virtual-host style would need a subdomain of localhost to resolve, which is not');
+    L.push('# dependable; path style keeps it on 127.0.0.1.');
+    L.push('TROVE_S3_PATH_STYLE=true');
+    L.push('# dev/local-s3.js does not verify signatures. These only have to be non-empty so');
+    L.push('# the SigV4 signer has something to sign with.');
+    // Real credentials, when they were supplied, but only into the gitignored file. The
+    // committed example gets the throwaway pair — see below.
+    const id = (withSecrets && supplied('TROVE_S3_ACCESS_KEY_ID')) || 'local';
+    const key = (withSecrets && supplied('TROVE_S3_SECRET_ACCESS_KEY')) || 'local-secret';
+    L.push(`TROVE_S3_ACCESS_KEY_ID=${id}`);
+    L.push(`TROVE_S3_SECRET_ACCESS_KEY=${key}`);
+    L.push('');
+  }
+
+  if (plan.devVapid) {
+    rule('Push notifications — local only');
+    L.push('# A local key pair, generated when this project was scaffolded. Production uses');
+    L.push('# a different one: a VAPID key identifies an application server, and these are');
+    L.push('# two servers — so this value leaking costs nothing, and a browser that');
+    L.push('# subscribed to your laptop is not subscribed to production.');
+    L.push('#');
+    L.push('# Only in .dev.vars, never in the committed example: it is still a private key,');
+    L.push('# and one shared by every clone of the repo is one nobody can reason about.');
+    L.push('# `npm run vapid` mints another.');
+    if (withSecrets) {
+      L.push(`TROVE_VAPID_PUBLIC_KEY=${plan.devVapid.publicKey}`);
+      L.push(`TROVE_VAPID_PRIVATE_KEY=${plan.devVapid.privateKey}`);
+    } else {
+      L.push('# TROVE_VAPID_PUBLIC_KEY=    # run `npm run vapid` and paste the pair here');
+      L.push('# TROVE_VAPID_PRIVATE_KEY=');
+    }
+    L.push('');
+  }
+
+  if (w?.vectorize) {
+    rule('Semantic search — local only');
+    L.push('# Vectorize has no local emulation: every call fails with "Binding VECTORIZE needs');
+    L.push('# to be run remotely". An explicit TROVE_VECTOR beats the binding, so this swaps in');
+    L.push('# the in-process store — the same code path a drive with no Vectorize would take.');
+    L.push('# To exercise the real index instead, log in and add `remote = true` to [[vectorize]].');
+    L.push('TROVE_VECTOR=memory');
+    L.push('');
+  }
+
+  // Whatever a local block already set is NOT repeated below. Listing a key twice in one
+  // dotenv file is a trap: the commented copy reads like the place to put your real
+  // credential, and uncommenting it silently points local runs at a bucket that is not
+  // the one `npm run dev:s3` is serving.
+  const overridden = new Set([
+    ...(localS3 ? ['TROVE_S3_ACCESS_KEY_ID', 'TROVE_S3_SECRET_ACCESS_KEY'] : []),
+    // The local pair above already set this one. Repeating it, commented, reads as the
+    // place to paste the PRODUCTION key — which is a value this file should never hold
+    // and which the wizard deliberately never asks for.
+    ...(plan.devVapid ? ['TROVE_VAPID_PRIVATE_KEY'] : []),
+  ]);
+  const remaining = secrets.filter((e) => !overridden.has(e.key));
+  if (remaining.length) {
+    rule('Credentials');
+    L.push('# Only needed for a local run that talks to the real service. The deployed Worker');
+    L.push('# reads these from secrets, not from this file — leaving them blank is fine.');
+    for (const e of remaining) {
+      // A value only ever reaches the gitignored file. `.dev.vars.example` is committed,
+      // so it carries the KEY and nothing else — writing an answered credential into it
+      // would put the secret in version control, which is the one rule this whole module
+      // is built around.
+      const value = withSecrets && isSet(e) ? e.value : '';
+      const comment = e.comment ? `   # ${e.comment}` : '';
+      L.push(value ? `${e.key}=${value}${comment}` : `# ${e.key}=${comment}`);
+    }
+    L.push('');
+  }
+
+  return L.join('\n');
+}
+
 function wranglerToml(plan) {
   const { workers: w, sections } = plan;
   const q = (v) => JSON.stringify(String(v));
@@ -189,7 +384,12 @@ function wranglerToml(plan) {
   L.push('');
   L.push('name = ' + q(plan.name));
   L.push('main = "src/worker.js"');
-  L.push(`compatibility_date = ${q(w?.compatibilityDate ?? '2024-09-23')}`);
+  L.push(`compatibility_date = ${q(w?.compatibilityDate ?? '2026-07-01')}`);
+  L.push('');
+  L.push('# core/index.js re-exports FilesystemStorage, which imports node:fs, node:path and');
+  L.push('# node:stream at the top level — so they are in the bundle whether or not a Workers');
+  L.push('# deployment could ever use that backend. Without this the build does not link.');
+  L.push('compatibility_flags = ["nodejs_compat"]');
   L.push('');
 
   L.push('# The built web app, served straight from the installed package — no build step');
@@ -275,6 +475,13 @@ function wranglerToml(plan) {
     L.push('');
   }
 
+  L.push('# Maintenance. A timer registered inside a request does not outlive the request, so');
+  L.push('# on Workers there is no periodic work at all without a cron: expired uploads are');
+  L.push('# never swept, trash retention never applies, and collection scans never advance.');
+  L.push('# Each firing runs one time-boxed slice (TROVE_CRON_BUDGET_MS, default 20s).');
+  L.push('[triggers]');
+  L.push('crons = ["*/5 * * * *"]');
+  L.push('');
   L.push('[vars]');
   L.push('# Configuration only. Credentials are secrets — see README.md.');
   for (const section of sections) {
@@ -311,6 +518,44 @@ function readme(plan, steps) {
   L.push('```');
   L.push('');
 
+  if (plan.runtime === 'workers') {
+    const localS3 = plan.sections.flatMap((s) => s.entries)
+      .some((e) => e.key === 'TROVE_STORAGE' && e.value === 's3' && !e.commented);
+
+    // A generated `.dev.vars` holds the credentials that were just answered; telling
+    // someone to copy the example over it would throw them away on the first read of
+    // this file.
+    const hasDevVars = plan.sections.flatMap((s) => s.entries).some((e) => e.secret && isSet(e));
+
+    L.push('## Local development');
+    L.push('');
+    L.push('None of the account setup above is needed to run this locally.');
+    L.push('');
+    L.push('```sh');
+    if (hasDevVars) L.push('# .dev.vars is already written, with the credentials you gave — it is gitignored');
+    else L.push('cp .dev.vars.example .dev.vars   # local identity, storage and search');
+    if (localS3) L.push('npm run dev:s3                  # terminal 1 — a local S3 bucket on :9000');
+    L.push(`npm run dev                     # terminal ${localS3 ? '2' : '1'} — the Worker on :8787`);
+    L.push('```');
+    L.push('');
+    L.push('`.dev.vars` overrides `[vars]` for local runs only and is never uploaded by');
+    L.push('`wrangler deploy`. Without it the Worker builds and serves the web app, then answers');
+    L.push('every API route with a 500 — it is pointed at services a laptop does not have.');
+    L.push('');
+    L.push('What a local run does **not** cover:');
+    L.push('');
+    L.push('- **Vectorize** has no local emulation, so `.dev.vars` swaps in the in-process vector');
+    L.push('  store. Same search code, different index. Add `remote = true` to `[[vectorize]]` to');
+    L.push('  use the real one.');
+    L.push('- **Authorisation.** Locally you are one anonymous admin, so nothing exercises the');
+    L.push('  identity driver or the collection grants.');
+    if (localS3) {
+      L.push('- **`dev/local-s3.js` does not verify signatures** and keeps objects in memory. It is');
+      L.push('  a development bucket, bound to 127.0.0.1, and nothing more.');
+    }
+    L.push('');
+  }
+
   if (plan.warnings.length) {
     const kind = (w) => (typeof w === 'string' ? w : w.kind);
     const has = (k) => plan.warnings.some((w) => kind(w) === k);

package/src/templates/localS3.js

@@ -0,0 +1,259 @@
+// The local S3 bucket that goes into a scaffolded Workers project, as source.
+//
+// Vendored as a string rather than pulled from npm on purpose. The only maintained
+// options that mock S3 mock the AWS SDK CLIENT, which is no use here — Trove signs its
+// own requests with SigV4 and talks to the endpoint over fetch, so what a local run
+// needs is a SERVER. The one package that is a server (s3rver) last shipped in 2021 and
+// brings four advisories, three of them high, into a project that otherwise has none.
+//
+// It is a template, so it lives here as text. Kept in its own module to stay out of
+// render.js, which is otherwise readable end to end.
+
+/* eslint-disable */
+export const LOCAL_S3 = `// A tiny S3-compatible server, for local development only.
+//
+// WHY THIS EXISTS
+//
+// On Workers the object store is R2 reached over the S3 API, and there is no local R2.
+// \`TROVE_STORAGE=memory\` gets \`wrangler dev\` running, but it is not the same drive in
+// one important way: memory storage lives INSIDE ONE ISOLATE, and scans and reindexes
+// run in the TroveTasks Durable Object, which is a different isolate with a different
+// memory. Every indexed item comes back "Object not found" and search stays empty —
+// a failure that exists only because of the stand-in, and that would send you hunting
+// for a bug in the indexer.
+//
+// Pointing TROVE_S3_ENDPOINT at this process instead gives every isolate one shared
+// bucket over HTTP, which is what R2 is. It exercises the real code path: SigV4
+// signing, multipart uploads, ranged reads, ListObjectsV2 paging.
+//
+// WHAT IT IS NOT
+//
+// It does not verify signatures. It accepts whatever Authorization header it is sent
+// and serves the request. That is fine for a bucket of test files on loopback and
+// unacceptable anywhere else, so it binds to 127.0.0.1 and refuses to start otherwise.
+// Objects are held in memory and vanish when it stops.
+//
+//   node dev/local-s3.js          # or: npm run dev:s3
+//
+// Run it alongside \`npm run dev\`, with the settings in .dev.vars.example.
+
+import { createServer } from 'node:http';
+import { createHash } from 'node:crypto';
+
+const PORT = Number(process.env.PORT || 9000);
+const HOST = '127.0.0.1';
+const BUCKET = process.env.BUCKET || 'trove';
+
+/** key -> { body: Buffer, contentType, modifiedAt, etag } */
+const objects = new Map();
+/** uploadId -> { key, contentType, parts: Map<number, Buffer> } */
+const uploads = new Map();
+
+const md5 = (buf) => createHash('md5').update(buf).digest('hex');
+const quoted = (etag) => \`"\${etag}"\`;
+const xmlEscape = (s) => String(s)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+
+const readBody = (req) => new Promise((resolve, reject) => {
+  const chunks = [];
+  req.on('data', (c) => chunks.push(c));
+  req.on('end', () => resolve(Buffer.concat(chunks)));
+  req.on('error', reject);
+});
+
+function sendXml(res, status, xml) {
+  const body = \`<?xml version="1.0" encoding="UTF-8"?>\\n\${xml}\`;
+  res.writeHead(status, { 'content-type': 'application/xml', 'content-length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+function sendError(res, status, code, message) {
+  sendXml(res, status, \`<Error><Code>\${code}</Code><Message>\${xmlEscape(message)}</Message></Error>\`);
+}
+
+/**
+ * ListObjectsV2.
+ *
+ * Paged on a continuation token that is just the key to resume after — the contract
+ * the client relies on is that the token is opaque and stable, not how it is built.
+ */
+function listObjects(res, query) {
+  const prefix = query.get('prefix') || '';
+  const maxKeys = Math.min(Number(query.get('max-keys') || 1000), 1000);
+  const after = query.get('continuation-token');
+
+  let keys = [...objects.keys()].filter((k) => k.startsWith(prefix)).sort();
+  if (after) keys = keys.filter((k) => k > after);
+
+  const page = keys.slice(0, maxKeys);
+  const truncated = keys.length > page.length;
+
+  const contents = page.map((key) => {
+    const o = objects.get(key);
+    return \`<Contents>\`
+      + \`<Key>\${xmlEscape(key)}</Key>\`
+      + \`<LastModified>\${new Date(o.modifiedAt).toISOString()}</LastModified>\`
+      // Escaped, exactly as S3 does it: the quotes around an ETag come back as &quot;.
+      + \`<ETag>\${xmlEscape(quoted(o.etag))}</ETag>\`
+      + \`<Size>\${o.body.length}</Size>\`
+      + \`<StorageClass>STANDARD</StorageClass>\`
+      + \`</Contents>\`;
+  }).join('');
+
+  sendXml(res, 200,
+    \`<ListBucketResult>\`
+    + \`<Name>\${xmlEscape(BUCKET)}</Name>\`
+    + \`<Prefix>\${xmlEscape(prefix)}</Prefix>\`
+    + \`<KeyCount>\${page.length}</KeyCount>\`
+    + \`<MaxKeys>\${maxKeys}</MaxKeys>\`
+    + \`<IsTruncated>\${truncated}</IsTruncated>\`
+    + (truncated ? \`<NextContinuationToken>\${xmlEscape(page[page.length - 1])}</NextContinuationToken>\` : '')
+    + contents
+    + \`</ListBucketResult>\`);
+}
+
+/** GET/HEAD an object, honouring a single byte range. */
+function getObject(req, res, key, head) {
+  const o = objects.get(key);
+  if (!o) return sendError(res, 404, 'NoSuchKey', 'The specified key does not exist.');
+
+  const headers = {
+    'content-type': o.contentType || 'application/octet-stream',
+    etag: quoted(o.etag),
+    'last-modified': new Date(o.modifiedAt).toUTCString(),
+    'accept-ranges': 'bytes',
+  };
+
+  const range = /^bytes=(\\d*)-(\\d*)$/.exec(req.headers.range || '');
+  if (range) {
+    const total = o.body.length;
+    // A suffix range ("bytes=-500") counts back from the end; the other two forms
+    // count forward, with an absent end meaning "to the last byte".
+    let start = range[1] === '' ? total - Number(range[2]) : Number(range[1]);
+    let end = range[1] === '' ? total - 1 : (range[2] === '' ? total - 1 : Number(range[2]));
+    start = Math.max(0, start);
+    end = Math.min(total - 1, end);
+    if (start > end) {
+      res.writeHead(416, { 'content-range': \`bytes */\${total}\` });
+      return res.end();
+    }
+    const slice = o.body.subarray(start, end + 1);
+    res.writeHead(206, {
+      ...headers,
+      'content-range': \`bytes \${start}-\${end}/\${total}\`,
+      'content-length': slice.length,
+    });
+    return res.end(head ? undefined : slice);
+  }
+
+  res.writeHead(200, { ...headers, 'content-length': o.body.length });
+  return res.end(head ? undefined : o.body);
+}
+
+async function handle(req, res) {
+  const url = new URL(req.url, \`http://\${HOST}:\${PORT}\`);
+  const query = url.searchParams;
+
+  // Path-style addressing: /<bucket>/<key...>. Virtual-host style would need
+  // <bucket>.localhost to resolve, which it does not reliably — hence
+  // TROVE_S3_PATH_STYLE=true in .dev.vars.example.
+  const segments = url.pathname.replace(/^\\//, '').split('/');
+  const bucket = segments.shift();
+  const key = decodeURIComponent(segments.join('/'));
+
+  if (bucket !== BUCKET) {
+    return sendError(res, 404, 'NoSuchBucket', \`No bucket named "\${bucket}".\`);
+  }
+
+  // --- bucket-level ---------------------------------------------------------
+  if (!key) {
+    if (req.method === 'GET' && query.get('list-type') === '2') return listObjects(res, query);
+    if (req.method === 'HEAD') { res.writeHead(200); return res.end(); }
+    return sendError(res, 400, 'InvalidRequest', 'Only ListObjectsV2 is supported at the bucket level.');
+  }
+
+  // --- multipart ------------------------------------------------------------
+  if (req.method === 'POST' && query.has('uploads')) {
+    const uploadId = \`mp_\${md5(key + Date.now() + Math.random())}\`;
+    uploads.set(uploadId, { key, contentType: req.headers['content-type'], parts: new Map() });
+    return sendXml(res, 200,
+      \`<InitiateMultipartUploadResult>\`
+      + \`<Bucket>\${xmlEscape(BUCKET)}</Bucket><Key>\${xmlEscape(key)}</Key>\`
+      + \`<UploadId>\${uploadId}</UploadId>\`
+      + \`</InitiateMultipartUploadResult>\`);
+  }
+
+  if (req.method === 'PUT' && query.has('uploadId')) {
+    const upload = uploads.get(query.get('uploadId'));
+    if (!upload) return sendError(res, 404, 'NoSuchUpload', 'Unknown uploadId.');
+    const body = await readBody(req);
+    upload.parts.set(Number(query.get('partNumber')), body);
+    res.writeHead(200, { etag: quoted(md5(body)), 'content-length': 0 });
+    return res.end();
+  }
+
+  if (req.method === 'POST' && query.has('uploadId')) {
+    const uploadId = query.get('uploadId');
+    const upload = uploads.get(uploadId);
+    if (!upload) return sendError(res, 404, 'NoSuchUpload', 'Unknown uploadId.');
+    // The client's list is authoritative about ORDER; it sorts by part number before
+    // sending, and a part it never mentions is not part of the object.
+    const body = await readBody(req);
+    const numbers = [...body.toString().matchAll(/<PartNumber>(\\d+)<\\/PartNumber>/g)].map((m) => Number(m[1]));
+    const missing = numbers.filter((n) => !upload.parts.has(n));
+    if (missing.length) return sendError(res, 400, 'InvalidPart', \`No such part(s): \${missing.join(', ')}\`);
+    const assembled = Buffer.concat(numbers.map((n) => upload.parts.get(n)));
+    uploads.delete(uploadId);
+    // A real multipart ETag is "<md5-of-part-md5s>-<count>"; the shape matters to the
+    // scanner's change detection, so it is reproduced rather than faked as a plain md5.
+    const etag = \`\${md5(Buffer.concat(numbers.map((n) => Buffer.from(md5(upload.parts.get(n)), 'hex'))))}-\${numbers.length}\`;
+    objects.set(upload.key, {
+      body: assembled, contentType: upload.contentType, modifiedAt: Date.now(), etag,
+    });
+    return sendXml(res, 200,
+      \`<CompleteMultipartUploadResult>\`
+      + \`<Bucket>\${xmlEscape(BUCKET)}</Bucket><Key>\${xmlEscape(upload.key)}</Key>\`
+      + \`<ETag>\${xmlEscape(quoted(etag))}</ETag>\`
+      + \`</CompleteMultipartUploadResult>\`);
+  }
+
+  if (req.method === 'DELETE' && query.has('uploadId')) {
+    uploads.delete(query.get('uploadId'));
+    res.writeHead(204);
+    return res.end();
+  }
+
+  // --- single object --------------------------------------------------------
+  if (req.method === 'PUT') {
+    const body = await readBody(req);
+    const etag = md5(body);
+    objects.set(key, {
+      body, contentType: req.headers['content-type'], modifiedAt: Date.now(), etag,
+    });
+    res.writeHead(200, { etag: quoted(etag), 'content-length': 0 });
+    return res.end();
+  }
+
+  if (req.method === 'GET') return getObject(req, res, key, false);
+  if (req.method === 'HEAD') return getObject(req, res, key, true);
+
+  if (req.method === 'DELETE') {
+    objects.delete(key);
+    res.writeHead(204);
+    return res.end();
+  }
+
+  return sendError(res, 405, 'MethodNotAllowed', \`\${req.method} is not supported.\`);
+}
+
+createServer((req, res) => {
+  handle(req, res).catch((err) => {
+    console.error('[local-s3]', err);
+    if (!res.headersSent) sendError(res, 500, 'InternalError', err.message);
+    else res.end();
+  });
+}).listen(PORT, HOST, () => {
+  console.log(\`[local-s3] bucket "\${BUCKET}" on http://\${HOST}:\${PORT} — in memory, signatures NOT checked\`);
+});
+`;

package/src/templates/vapid.js

@@ -0,0 +1,48 @@
+// The key-rotation script that goes into a scaffolded project, as source.
+//
+// Vendored as text for the same reason as the local bucket: it is a template. It uses
+// @3sln/trove/core, which the generated project has and the WIZARD does not — the
+// wizard runs through `npm create`, before there is a node_modules to import from.
+// That is why the first version of the push question pointed at a function nobody
+// could call yet.
+
+/* eslint-disable */
+export const VAPID_SCRIPT = `// Mint a VAPID key pair.
+//
+//   npm run vapid
+//
+// A pair identifies THIS application server to a push service. It is self-issued — no
+// account, no registration, no network — so there is nothing to fetch and nothing to
+// pay for. The two halves go to different places and only one of them is a secret,
+// which is what the output below is really about.
+//
+// Rotating invalidates every existing subscription: a browser subscribes against a
+// specific public key, so after a rotation each client re-subscribes on its next load.
+// That is free on a drive nobody has subscribed to yet and disruptive on one people
+// use, so it is worth doing once, at the start.
+import { generateVapidKeys } from '@3sln/trove/core';
+
+const { publicKey, privateKey } = await generateVapidKeys();
+
+console.log(\`
+A new VAPID pair. The halves belong in two different places.
+
+  PUBLIC — not a secret. Browsers receive it as applicationServerKey, so it is public
+  by construction. It goes in wrangler.toml under [vars]:
+
+    TROVE_VAPID_PUBLIC_KEY = "\${publicKey}"
+
+  PRIVATE — signs the JWT that authorises each push. It should never be written to a
+  file this project tracks:
+
+    npx wrangler secret put TROVE_VAPID_PRIVATE_KEY
+
+    \${privateKey}
+
+They are a PAIR. Setting one without the other leaves the drive unable to push, and it
+fails at the push service as a rejected signature rather than as anything logged here.
+
+For local development put BOTH halves in .dev.vars, which is gitignored — a local drive
+is a different application server from the deployed one, and should not share its key.
+\`);
+`;

package/src/vapid.js

@@ -0,0 +1,49 @@
+// A VAPID key pair, made locally.
+//
+// This is a copy of `generateVapidKeys` from @3sln/trove/core, and the duplication is
+// deliberate: create-trove has no dependencies and runs through `npm create`, BEFORE
+// the project it is writing has a node_modules. Pointing someone at a function inside a
+// package they have not installed yet is not a hint, it is a dead end — which is what
+// the first version of the push question did.
+//
+// The format is fixed by RFC 8292 and the Push API, not by us, so this cannot drift in
+// any interesting way. `test/vapid.test.js` checks the pair against core's own
+// implementation anyway, because "cannot drift" is a claim and that test is a fact.
+//
+// Worth being clear about what a VAPID key IS, because it decides how it should be
+// handled: it identifies this application server to a push service. It is self-issued —
+// no account, no registration, no network — which is what makes generating one here
+// legitimate where minting an R2 access key would not be. The public half goes to
+// browsers as `applicationServerKey` and ends up baked into every subscription made
+// against it; the private half signs the JWT that authorises each push.
+
+/** base64url, no padding. */
+const b64url = (bytes) => btoa(String.fromCharCode(...bytes))
+  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+
+const unb64url = (s) => {
+  const b64 = s.replace(/-/g, '+').replace(/_/g, '/');
+  const bin = atob(b64 + '='.repeat((4 - (b64.length % 4)) % 4));
+  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+};
+
+/**
+ * @returns {Promise<{publicKey: string, privateKey: string}>} both base64url.
+ *   `publicKey` is the uncompressed EC point (0x04 || X || Y, 65 bytes) that
+ *   PushManager.subscribe() wants; `privateKey` is the raw 32-byte scalar.
+ */
+export async function generateVapidKeys() {
+  const pair = await crypto.subtle.generateKey(
+    { name: 'ECDSA', namedCurve: 'P-256' },
+    true,
+    ['sign', 'verify'],
+  );
+  const jwk = await crypto.subtle.exportKey('jwk', pair.privateKey);
+  const x = unb64url(jwk.x);
+  const y = unb64url(jwk.y);
+  const point = new Uint8Array(65);
+  point[0] = 0x04;
+  point.set(x, 1);
+  point.set(y, 33);
+  return { publicKey: b64url(point), privateKey: jwk.d };
+}