@3sln/create-trove 0.0.2

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@3sln/create-trove",
+  "version": "0.0.2",
+  "type": "module",
+  "description": "Scaffold a Trove deployment — Bun, Node, or Cloudflare Workers — with the bindings, environment and secrets each one needs.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/3sln/trove.git",
+    "directory": "packages/create-trove"
+  },
+  "license": "MIT",
+  "author": "Ray Stubbs",
+  "keywords": [
+    "trove",
+    "scaffold",
+    "create",
+    "cloudflare workers",
+    "self-hosted"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-trove": "./src/cli.js"
+  },
+  "exports": {
+    "./plan": "./src/plan.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/cli.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+//
+//   npm create @3sln/trove my-drive
+//
+// Asks where the drive will run, then writes a project that runs there.
+//
+// The version this pins @3sln/trove at is *this package's own*. The two are released
+// together from one repository and one version number, so they are the same string by
+// construction — which means a scaffolded project can never pair a server with a
+// workbench from a different release, and there is no version to look up at runtime.
+
+import { mkdir, readFile, writeFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { createPrompter } from './prompt.js';
+import { askPlan, RUNTIMES } from './plan.js';
+import { renderProject } from './render.js';
+
+const USAGE = `Usage: npm create @3sln/trove <directory> [options]
+
+Options:
+  --runtime <bun|node|workers>  skip the first question
+  --yes                         take every default, ask nothing
+  --dry-run                     print what would be written, write nothing
+  --force                       write into a directory that is not empty
+  --help                        this
+`;
+
+function parseArgs(argv) {
+  const opts = { dir: null, runtime: null, yes: false, dryRun: false, force: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--yes' || a === '-y') opts.yes = true;
+    else if (a === '--dry-run') opts.dryRun = true;
+    else if (a === '--force') opts.force = true;
+    else if (a === '--runtime') opts.runtime = argv[++i];
+    else if (a.startsWith('--runtime=')) opts.runtime = a.slice('--runtime='.length);
+    else if (!a.startsWith('-') && !opts.dir) opts.dir = a;
+  }
+  return opts;
+}
+
+/** npm package names: no leading dot/underscore, no uppercase, no spaces. */
+const toPackageName = (dirName) =>
+  dirName.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+/, '').replace(/-+$/, '') || 'trove-drive';
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (opts.runtime && !RUNTIMES.includes(opts.runtime)) {
+    process.stderr.write(`--runtime must be one of: ${RUNTIMES.join(', ')}\n`);
+    return 1;
+  }
+
+  const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+  // A pipe rather than a terminal means nobody is there to answer, so take the defaults
+  // instead of blocking forever on a read that will never return.
+  const interactive = process.stdin.isTTY && !opts.yes;
+  const prompter = createPrompter({ assumeDefaults: !interactive });
+
+  try {
+    process.stdout.write(`\ncreate-trove ${version}\n`);
+
+    const dir = opts.dir || (interactive
+      ? await prompter.text('\nProject directory', { default: 'my-drive' })
+      : 'my-drive');
+    const target = path.resolve(dir);
+    const name = toPackageName(path.basename(target));
+
+    if (existsSync(target) && !opts.force) {
+      const entries = await readdir(target);
+      if (entries.length) {
+        process.stderr.write(`\n${target} is not empty. Use --force to write into it anyway.\n`);
+        return 1;
+      }
+    }
+
+    const plan = await askPlan(prompter, { name, version, runtime: opts.runtime });
+    const { files, steps } = renderProject(plan);
+
+    process.stdout.write(`\n${opts.dryRun ? 'Would write' : 'Writing'} ${files.length} files to ${target}\n`);
+    for (const f of files) process.stdout.write(`  ${f.path}\n`);
+
+    if (!opts.dryRun) {
+      for (const f of files) {
+        const dest = path.join(target, f.path);
+        await mkdir(path.dirname(dest), { recursive: true });
+        await writeFile(dest, f.contents);
+      }
+    }
+
+    process.stdout.write('\nNext:\n');
+    for (const s of steps) process.stdout.write(`  ${s.cmd}${s.why ? `    # ${s.why}` : ''}\n`);
+    if (plan.skipped.length) {
+      process.stdout.write(`\nSkipped, and left commented in the config for you: ${plan.skipped.join(', ')}.\n`);
+    }
+    for (const w of plan.warnings) {
+      const kind = typeof w === 'string' ? w : w.kind;
+      if (kind === 'anonymous') process.stdout.write('\nNo identity configured — anyone who can reach this has full access.\n');
+      if (kind === 'incomplete-identity') process.stdout.write(`\nTROVE_AUTH=${w.driver} is set but ${w.missing.join(' and ')} left blank.\n`);
+      if (kind === 'default-open') process.stdout.write('The default collection is open to every user.\n');
+    }
+    process.stdout.write('\n');
+    return 0;
+  } finally {
+    prompter.close();
+  }
+}
+
+process.exitCode = await main();

package/src/plan.js

@@ -0,0 +1,325 @@
+// The interview.
+//
+// Answers only — nothing here touches the filesystem, and nothing here knows what a
+// wrangler.toml looks like. That split is what lets the whole wizard be tested from a
+// transcript (see test/wizard.test.js): drive it with a scripted prompter, assert on the
+// plan, and never mkdir anything.
+//
+// Two rules shape the questions:
+//
+//   Skipping is an answer, not an escape. Every section can be declined, and declining
+//   still puts the section in the generated config — commented, with the keys that
+//   belong in it and a line saying what they are for. Someone who already knows their
+//   R2 credentials should not be interviewed about them, and someone who does not should
+//   not be blocked from getting a project on disk.
+//
+//   Secrets are never values. A credential answered here becomes a `wrangler secret put`
+//   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.
+
+export const RUNTIMES = ['bun', 'node', 'workers'];
+
+/** 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 });
+
+/** A declined section still emits its keys, commented, so the file documents itself. */
+const placeholder = (key, comment) => entry(key, '', { comment, commented: true });
+
+/**
+ * Run the interview.
+ *
+ * @param {object} prompter from ./prompt.js — real or scripted
+ * @param {object} opts
+ * @param {string} opts.name project directory name
+ * @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
+ * @returns {Promise<object>} the plan
+ */
+export async function askPlan(prompter, { name, version, runtime: preset }) {
+  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' },
+    { value: 'workers', label: 'Cloudflare Workers', hint: 'no disk — D1, Vectorize and R2 do the work' },
+  ], { default: 'bun' });
+
+  const isWorkers = runtime === 'workers';
+  const plan = { name, version, runtime, sections: [], workers: null, server: null, skipped: [], warnings: [] };
+
+  const add = (title, entries, { skipped = false } = {}) => {
+    plan.sections.push({ title, entries, skipped });
+    if (skipped) plan.skipped.push(title);
+  };
+
+  // --- storage ---------------------------------------------------------------
+  // Workers has no disk, so `filesystem` is not offered there — and R2 is reached
+  // through the S3 API rather than a binding because that is what lets presigned
+  // uploads go straight to the bucket instead of through the Worker's CPU time.
+  if (await prompter.section('Object storage', {
+    blurb: isWorkers
+      ? 'Where file bytes live. On Workers this is R2 through its S3-compatible API.'
+      : 'Where file bytes live.',
+  })) {
+    const driver = await prompter.choice('  Backend', isWorkers ? [
+      { value: 's3', label: 'R2 / S3-compatible' },
+      { value: 'memory', label: 'In memory', hint: 'lost when the isolate recycles — demos only' },
+    ] : [
+      { value: 'filesystem', label: 'Filesystem or NAS mount' },
+      { value: 's3', label: 'S3-compatible', hint: 'AWS, R2, MinIO, B2' },
+      { value: 'memory', label: 'In memory', hint: 'nothing is kept — demos only' },
+    ], { default: isWorkers ? 's3' : 'filesystem' });
+
+    const entries = [entry('TROVE_STORAGE', driver)];
+    if (driver === 'filesystem') {
+      entries.push(entry('TROVE_FS_ROOT', await prompter.text('  Object root', { default: './data/objects' }),
+        { comment: 'the backend creates objects/ under this, sharded two levels deep' }));
+    }
+    if (driver === 's3') {
+      entries.push(entry('TROVE_S3_BUCKET', await prompter.text('  Bucket', { default: 'trove' })));
+      entries.push(entry('TROVE_S3_REGION', await prompter.text('  Region', { default: isWorkers ? 'auto' : 'us-east-1' }),
+        { comment: 'R2 uses "auto"' }));
+      entries.push(entry('TROVE_S3_ENDPOINT', await prompter.text('  Endpoint', {
+        default: isWorkers ? 'https://<account-id>.r2.cloudflarestorage.com' : '',
+        hint: 'leave blank for AWS S3',
+      }), { comment: 'omit for AWS' }));
+      entries.push(entry('TROVE_S3_ACCESS_KEY_ID', await prompter.text('  Access key id', { default: '' }), { secret: true }));
+      entries.push(entry('TROVE_S3_SECRET_ACCESS_KEY', await prompter.text('  Secret access key', { default: '' }), { secret: true }));
+      if (!isWorkers && await prompter.confirm('  Path-style addressing?', { default: false })) {
+        entries.push(entry('TROVE_S3_PATH_STYLE', 'true', { comment: 'MinIO and most custom endpoints' }));
+      }
+    }
+    add('Object storage', entries);
+  } else {
+    add('Object storage', [
+      placeholder('TROVE_STORAGE', `memory | ${isWorkers ? '' : 'filesystem | '}s3 — defaults to memory, which keeps nothing`),
+      ...(isWorkers ? [] : [placeholder('TROVE_FS_ROOT', 'filesystem root, e.g. ./data/objects')]),
+      placeholder('TROVE_S3_BUCKET', 'for TROVE_STORAGE=s3'),
+      placeholder('TROVE_S3_REGION', '"auto" for R2'),
+      placeholder('TROVE_S3_ENDPOINT', 'e.g. https://<account-id>.r2.cloudflarestorage.com'),
+    ], { skipped: true });
+  }
+
+  // --- metadata --------------------------------------------------------------
+  // On Workers this is D1, which is a binding rather than a variable, so the question
+  // moves to the bindings block below.
+  if (!isWorkers) {
+    if (await prompter.section('Metadata', { blurb: 'The file tree, collections, plugin installs and keyword index.' })) {
+      const driver = await prompter.choice('  Store', [
+        { value: 'sqlite', label: 'SQLite file', hint: 'one file, backed up with a VACUUM INTO snapshot' },
+        { value: 'memory', label: 'In memory', hint: 'lost on restart' },
+      ], { default: 'sqlite' });
+      const entries = [entry('TROVE_METADATA', driver)];
+      if (driver === 'sqlite') {
+        entries.push(entry('TROVE_DB_PATH', await prompter.text('  Database path', { default: './data/trove.db' })));
+      }
+      add('Metadata', entries);
+    } else {
+      add('Metadata', [
+        placeholder('TROVE_METADATA', 'memory | sqlite — defaults to memory, which is lost on restart'),
+        placeholder('TROVE_DB_PATH', 'e.g. ./data/trove.db'),
+      ], { skipped: true });
+    }
+  }
+
+  // --- search ----------------------------------------------------------------
+  if (await prompter.section('Semantic search', {
+    blurb: 'Embeddings turn text into vectors; the vector store holds them. Both have working defaults.',
+  })) {
+    const entries = [];
+    const embed = await prompter.choice('  Embeddings', [
+      { value: 'builtin', label: 'Built-in hash embedding', hint: 'offline, no API key, weaker results' },
+      { value: 'http', label: 'An HTTP embeddings API', hint: 'OpenAI-compatible' },
+    ], { default: 'builtin' });
+    if (embed === 'http') {
+      entries.push(entry('TROVE_EMBEDDINGS_URL', await prompter.text('  Embeddings URL', { default: 'https://api.openai.com/v1/embeddings' })));
+      entries.push(entry('TROVE_EMBEDDINGS_API_KEY', await prompter.text('  API key', { default: '' }), { secret: true }));
+      entries.push(entry('TROVE_EMBEDDINGS_MODEL', await prompter.text('  Model', { default: 'text-embedding-3-small' })));
+      entries.push(entry('TROVE_EMBEDDINGS_DIM', await prompter.text('  Dimensions', { default: '1536' }),
+        { comment: 'must match the model, and changing it means a reindex' }));
+    }
+
+    if (isWorkers) {
+      // sqlite-vec is a native artifact and cannot load on Workers, so there is no
+      // in-process option to fall back to — Vectorize is the only vector store here.
+      entries.push(entry('TROVE_VECTOR', 'vectorize', { comment: 'the VECTORIZE binding is picked up automatically' }));
+    } else {
+      const vector = await prompter.choice('  Vector store', [
+        { value: 'memory', label: 'In process', hint: 'sqlite-vec if available, rebuilt on restart otherwise' },
+        { value: 'qdrant', label: 'Qdrant' },
+      ], { default: 'memory' });
+      entries.push(entry('TROVE_VECTOR', vector));
+      if (vector === 'qdrant') {
+        entries.push(entry('TROVE_QDRANT_URL', await prompter.text('  Qdrant URL', { default: 'http://localhost:6333' })));
+        entries.push(entry('TROVE_QDRANT_COLLECTION', await prompter.text('  Collection', { default: 'trove' })));
+        entries.push(entry('TROVE_QDRANT_API_KEY', await prompter.text('  API key', { default: '' }), { secret: true }));
+      }
+    }
+    add('Semantic search', entries);
+  } else {
+    add('Semantic search', [
+      placeholder('TROVE_EMBEDDINGS_URL', 'unset uses the built-in offline hash embedding'),
+      placeholder('TROVE_VECTOR', isWorkers ? 'vectorize — sqlite-vec cannot run on Workers' : 'memory | qdrant | vectorize'),
+    ], { skipped: true });
+  }
+
+  // --- identity --------------------------------------------------------------
+  // The one section where declining is genuinely dangerous, so the warning is attached
+  // to the plan rather than left to the reader to infer.
+  if (await prompter.section('Identity', {
+    blurb: 'Trove ships no login — it verifies what an IdP or proxy already established.',
+  })) {
+    const driver = await prompter.choice('  Verify identity via', [
+      { value: 'cloudflare-access', label: 'Cloudflare Access / Zero Trust' },
+      { value: 'jwt', label: 'A JWT from any OIDC provider', hint: 'verified against a JWKS' },
+      { value: 'header', label: 'A header set by a verifying proxy' },
+      { value: 'anonymous', label: 'Nobody', hint: 'everyone is the same anonymous user' },
+    ], { default: isWorkers ? 'cloudflare-access' : 'anonymous' });
+
+    const entries = [entry('TROVE_AUTH', driver)];
+    if (driver === 'cloudflare-access') {
+      entries.push(entry('TROVE_CF_ACCESS_TEAM', await prompter.text('  Access team name', { default: '', hint: 'the <team> in <team>.cloudflareaccess.com' })));
+      entries.push(entry('TROVE_CF_ACCESS_AUD', await prompter.text('  Application AUD tag', { default: '' })));
+      // cloudflare-access is the one driver that requires auth unless told otherwise.
+      entries.push(entry('TROVE_AUTH_REQUIRED', 'true', { comment: 'the default for this driver; "false" falls back to anonymous' }));
+    } else if (driver === 'jwt') {
+      entries.push(entry('TROVE_JWKS_URL', await prompter.text('  JWKS URL', { default: '' })));
+      entries.push(entry('TROVE_JWT_ISSUER', await prompter.text('  Issuer', { default: '' })));
+      entries.push(entry('TROVE_JWT_AUDIENCE', await prompter.text('  Audience', { default: '' })));
+      entries.push(entry('TROVE_AUTH_REQUIRED', String(await prompter.confirm('  Reject unauthenticated requests?', { default: true }))));
+    } else if (driver === 'header') {
+      entries.push(entry('TROVE_AUTH_ID_HEADER', await prompter.text('  Identity header', { default: 'cf-access-authenticated-user-email' }),
+        { comment: 'only safe behind a proxy that sets this and strips it from client requests' }));
+      entries.push(entry('TROVE_AUTH_REQUIRED', String(await prompter.confirm('  Reject unauthenticated requests?', { default: true }))));
+    }
+    if (driver === 'anonymous') plan.warnings.push('anonymous');
+    // Naming a driver whose settings were left blank is worse than naming none: the
+    // config looks configured. `cloudflare-access` in particular refuses every request
+    // it cannot verify, so a blank team is not an open door but a closed one — and
+    // either way the reason is a value nobody filled in.
+    const REQUIRED = {
+      'cloudflare-access': ['TROVE_CF_ACCESS_TEAM', 'TROVE_CF_ACCESS_AUD'],
+      jwt: ['TROVE_JWKS_URL', 'TROVE_JWT_ISSUER', 'TROVE_JWT_AUDIENCE'],
+    };
+    const missing = (REQUIRED[driver] ?? []).filter((k) => !entries.find((e) => e.key === k)?.value);
+    if (missing.length) plan.warnings.push({ kind: 'incomplete-identity', driver, missing });
+    add('Identity', entries);
+  } else {
+    plan.warnings.push('anonymous');
+    add('Identity', [
+      placeholder('TROVE_AUTH', 'anonymous | jwt | cloudflare-access | header — defaults to anonymous'),
+      placeholder('TROVE_AUTH_REQUIRED', 'true to reject unauthenticated requests'),
+    ], { skipped: true });
+  }
+
+  // --- access control --------------------------------------------------------
+  if (await prompter.section('Access control', { blurb: 'Who is an admin, and whether the default collection is open to everyone.' })) {
+    const admins = await prompter.text('  Admin principal ids', { default: '', hint: 'comma-separated, usually email addresses' });
+    const open = await prompter.confirm('  Give everyone full access to the default collection?', { default: false });
+    add('Access control', [
+      entry('TROVE_ADMINS', admins),
+      entry('TROVE_DEFAULT_OPEN', String(open), { comment: 'false means the default collection is not world-writable' }),
+    ]);
+    if (open) plan.warnings.push('default-open');
+  } else {
+    plan.warnings.push('default-open');
+    add('Access control', [
+      placeholder('TROVE_ADMINS', 'comma-separated principal ids with admin'),
+      placeholder('TROVE_DEFAULT_OPEN', 'false — otherwise everyone gets the default collection'),
+    ], { 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
+  // users install. Off by default: it is the only optional section here, and a drive
+  // called "Trove" is a perfectly good drive.
+  if (await prompter.section('Installed app name', {
+    blurb: 'What the browser calls this when someone installs it. Defaults to Trove.',
+    default: false,
+  })) {
+    const appName = await prompter.text('  App name', { default: 'Trove' });
+    const entries = [entry('TROVE_APP_NAME', appName)];
+    const short = await prompter.text('  Short name', { default: '', hint: 'for a home-screen label; defaults to the app name' });
+    if (short) entries.push(entry('TROVE_APP_SHORT_NAME', short));
+    entries.push(entry('TROVE_APP_THEME_COLOR', await prompter.text('  Theme colour', { default: '#181a1f' })));
+    const icon = await prompter.text('  Icon URL', { default: '', hint: 'leave blank for the built-in mark' });
+    if (icon) {
+      entries.push(entry('TROVE_APP_ICON', icon));
+      entries.push(entry('TROVE_APP_ICON_SIZES', await prompter.text('  Icon size', {
+        default: icon.endsWith('.svg') ? 'any' : '512x512',
+        hint: 'a raster icon claiming "any" gets scaled badly',
+      })));
+    }
+    add('Installed app name', entries);
+  } else {
+    add('Installed app name', [
+      placeholder('TROVE_APP_NAME', 'what the installed app is called; defaults to Trove'),
+      placeholder('TROVE_APP_THEME_COLOR', 'defaults to #181a1f'),
+      placeholder('TROVE_APP_ICON', 'defaults to the built-in mark'),
+    ], { skipped: true });
+  }
+
+  // --- runtime specifics -----------------------------------------------------
+  if (isWorkers) {
+    plan.workers = await askWorkers(prompter);
+  } else {
+    plan.server = { port: '8787', host: '0.0.0.0' };
+    if (await prompter.section('Server', { blurb: 'Port and bind address.', default: false })) {
+      plan.server.port = await prompter.text('  Port', { default: '8787' });
+      plan.server.host = await prompter.text('  Host', { default: '0.0.0.0' });
+    }
+  }
+
+  return plan;
+}
+
+/**
+ * The Workers bindings.
+ *
+ * These are not environment variables — they are resources that have to exist in the
+ * account before a deploy works, which is why every one of them also produces a command
+ * in the plan's steps. A wrangler.toml naming a D1 database that was never created is
+ * 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) {
+  const w = {
+    d1: null, pluginDb: null, vectorize: null, ai: false, tasks: true,
+    compatibilityDate: '2024-09-23',
+  };
+
+  if (await prompter.section('D1 (metadata)', {
+    blurb: 'Bind DB or the drive runs entirely in memory — fine until the isolate recycles, then everything is gone.',
+  })) {
+    w.d1 = {
+      name: await prompter.text('  Database name', { default: 'trove' }),
+      id: await prompter.text('  Database id', { default: '', hint: 'from `wrangler d1 create` — leave blank to fill in after' }),
+    };
+    if (await prompter.confirm('  Bind a second D1 for server-side plugin storage?', { default: false })) {
+      w.pluginDb = {
+        name: await prompter.text('  Plugin database name', { default: 'trove-plugins' }),
+        id: await prompter.text('  Plugin database id', { default: '' }),
+      };
+    }
+  }
+
+  if (await prompter.section('Vectorize (semantic search)', {
+    blurb: 'sqlite-vec is a native artifact and cannot load here, so semantic search needs Vectorize.',
+  })) {
+    w.vectorize = {
+      index: await prompter.text('  Index name', { default: 'trove' }),
+      dimensions: await prompter.text('  Dimensions', { default: '1536', hint: 'must match your embedding model' }),
+      metric: await prompter.choice('  Distance metric', [
+        { value: 'cosine', label: 'cosine' },
+        { value: 'euclidean', label: 'euclidean' },
+        { value: 'dot-product', label: 'dot-product' },
+      ], { default: 'cosine' }),
+    };
+  }
+
+  w.ai = await prompter.confirm('\nBind Workers AI for natural-language search queries?', { default: false });
+  w.tasks = await prompter.confirm('Bind the TroveTasks Durable Object for scans and reindexes?', { default: true });
+
+  return w;
+}

package/src/prompt.js

@@ -0,0 +1,144 @@
+// A prompt kit small enough to have no dependencies.
+//
+// `npm create` runs this before anything is installed, so every dependency here is one
+// the user waits on before they have answered a single question. That budget is better
+// spent on the questions themselves, and what a wizard actually needs — a line of text,
+// a pick from a list, a yes/no — is a few dozen lines over readline.
+//
+// Everything is injectable and `scripted()` implements the same interface, so the
+// wizard can be driven by a test without a terminal. That is the reason the prompter is
+// passed around rather than reached for: a wizard that reads process.stdin directly can
+// only be tested by a human.
+
+import readline from 'node:readline/promises';
+
+const DIM = '';
+const BOLD = '';
+const RESET = '';
+
+/**
+ * A prompter backed by a real terminal.
+ *
+ * @param {object} [opts]
+ * @param {NodeJS.ReadableStream} [opts.input]
+ * @param {NodeJS.WritableStream} [opts.output]
+ * @param {boolean} [opts.assumeDefaults] answer every question with its default and
+ *   never block — what `--yes` sets, and what a non-interactive stdin forces.
+ */
+export function createPrompter({ input = process.stdin, output = process.stdout, assumeDefaults = false } = {}) {
+  const colour = output.isTTY && !process.env.NO_COLOR;
+  const paint = (code, s) => (colour ? code + s + RESET : s);
+  let rl = null;
+  const lazy = () => (rl ??= readline.createInterface({ input, output }));
+
+  const write = (s) => output.write(s + '\n');
+
+  async function line(query) {
+    if (assumeDefaults) return '';
+    return (await lazy().question(query)).trim();
+  }
+
+  return {
+    close() { rl?.close(); rl = null; },
+
+    heading(text) {
+      write('');
+      write(paint(BOLD, text));
+    },
+
+    note(text) {
+      write(paint(DIM, '  ' + text));
+    },
+
+    /**
+     * Free text. An empty answer takes the default, so Enter is always the safe key.
+     */
+    async text(label, { default: def = '', hint } = {}) {
+      if (hint) this.note(hint);
+      const shown = def ? ` ${paint(DIM, `(${def})`)}` : '';
+      const answer = await line(`${label}${shown}: `);
+      return answer || def;
+    },
+
+    /**
+     * Pick one of a list. Options are `{ value, label, hint }`.
+     */
+    async choice(label, options, { default: def } = {}) {
+      const fallback = def ?? options[0].value;
+      if (assumeDefaults) return fallback;
+      write('');
+      write(label);
+      options.forEach((o, i) => {
+        const mark = o.value === fallback ? '>' : ' ';
+        write(`  ${mark} ${i + 1}) ${o.label}${o.hint ? paint(DIM, ' — ' + o.hint) : ''}`);
+      });
+      for (;;) {
+        const raw = await line(`  choice ${paint(DIM, `(${options.findIndex((o) => o.value === fallback) + 1})`)}: `);
+        if (!raw) return fallback;
+        const byIndex = options[Number(raw) - 1];
+        if (byIndex) return byIndex.value;
+        const byValue = options.find((o) => o.value === raw.toLowerCase());
+        if (byValue) return byValue.value;
+        write(paint(DIM, '  Not one of the options.'));
+      }
+    },
+
+    async confirm(label, { default: def = true } = {}) {
+      if (assumeDefaults) return def;
+      const shown = def ? 'Y/n' : 'y/N';
+      for (;;) {
+        const raw = (await line(`${label} ${paint(DIM, `(${shown})`)}: `)).toLowerCase();
+        if (!raw) return def;
+        if (['y', 'yes'].includes(raw)) return true;
+        if (['n', 'no'].includes(raw)) return false;
+      }
+    },
+
+    /**
+     * Offer a block of related questions, or let the user take it themselves.
+     *
+     * Skipping is a first-class answer rather than a way of bailing out: the generated
+     * files still carry the section, commented, with the variables that belong in it.
+     * Someone who already knows their S3 credentials does not want to be interviewed
+     * about them, and someone who does not should not be blocked from getting a
+     * project on disk.
+     */
+    async section(title, { blurb, default: def = true } = {}) {
+      this.heading(title);
+      if (blurb) this.note(blurb);
+      return this.confirm('  Configure this now?', { default: def });
+    },
+  };
+}
+
+/**
+ * A prompter that reads from a list instead of a person.
+ *
+ * Answers are consumed in order and matched by the question's label, so a test reads as
+ * a transcript rather than as a queue of bare strings — and a wizard that grows a
+ * question in the middle fails loudly instead of silently shifting every later answer
+ * onto the wrong prompt.
+ *
+ * @param {Array<[string, any]>} script pairs of [label substring, answer]
+ */
+export function scripted(script) {
+  const remaining = [...script];
+  const take = (label, fallback) => {
+    const i = remaining.findIndex(([match]) => label.includes(match));
+    if (i === -1) {
+      if (fallback !== undefined) return fallback;
+      throw new Error(`No scripted answer for: ${label}\nRemaining: ${remaining.map(([m]) => m).join(', ')}`);
+    }
+    return remaining.splice(i, 1)[0][1];
+  };
+  return {
+    close() {},
+    heading() {},
+    note() {},
+    unanswered: () => remaining.map(([m]) => m),
+    async text(label, { default: def = '' } = {}) { return take(label, def); },
+    async choice(label, options, { default: def } = {}) { return take(label, def ?? options[0].value); },
+    async confirm(label, { default: def = true } = {}) { return take(label, def); },
+    async section(title, { default: def = true } = {}) { return take(title, def); },
+  };
+}

package/src/render.js

@@ -0,0 +1,355 @@
+// Plan → files and commands.
+//
+// Pure: it takes the answers and returns `{ files, steps }`. Nothing is written here,
+// which is what lets a test assert on a generated wrangler.toml without a temp
+// directory, and what lets `--dry-run` be the same code path as a real run.
+//
+// The one rule worth stating out loud: a secret never becomes a file that belongs in
+// version control. On Workers that means `[vars]` carries configuration and credentials
+// become `wrangler secret put` steps plus a gitignored `.dev.vars` for local runs;
+// 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.
+
+const RULE = '─'.repeat(58);
+
+/** The exact version, not a range: the two packages are released together, and a drive
+ *  whose server and workbench came from different releases is the failure this avoids. */
+const pin = (version) => version;
+
+const isSet = (e) => !e.commented && e.value !== '' && e.value != null;
+
+export function renderProject(plan) {
+  const files = [];
+  const steps = [];
+  const secrets = plan.sections.flatMap((s) => s.entries.filter((e) => e.secret && isSet(e)));
+
+  if (plan.runtime === 'workers') renderWorkers(plan, files, steps, secrets);
+  else renderServer(plan, files, steps);
+
+  files.push({ path: 'README.md', contents: readme(plan, steps) });
+  return { files, steps };
+}
+
+// --- shared -----------------------------------------------------------------
+
+/**
+ * Render sections as a dotenv file.
+ *
+ * @param {object[]} sections
+ * @param {object} [opts]
+ * @param {boolean} [opts.secretsOnly] emit only the credentials — what .dev.vars wants
+ * @param {boolean} [opts.omitSecrets] emit everything but the credentials
+ */
+function renderEnv(sections, { secretsOnly = false, omitSecrets = false } = {}) {
+  const out = [];
+  for (const section of sections) {
+    const entries = section.entries.filter((e) => (secretsOnly ? e.secret : omitSecrets ? !e.secret : true));
+    if (!entries.length) continue;
+    out.push(`# ${RULE}`);
+    out.push(`# ${section.title}${section.skipped ? '  (skipped — fill these in yourself)' : ''}`);
+    out.push(`# ${RULE}`);
+    for (const e of entries) {
+      const comment = e.comment ? `   # ${e.comment}` : '';
+      out.push(isSet(e) ? `${e.key}=${e.value}${comment}` : `# ${e.key}=${comment}`);
+    }
+    out.push('');
+  }
+  return out.join('\n');
+}
+
+const gitignore = (extra = []) => ['node_modules/', '.env', '.dev.vars', ...extra, ''].join('\n');
+
+// --- bun / node --------------------------------------------------------------
+
+function renderServer(plan, files, steps) {
+  const { runtime, version, name, server } = plan;
+  const exec = runtime === 'bun' ? 'bun' : 'node';
+  const adapter = runtime === 'bun' ? 'bun.js' : 'node.js';
+
+  // Bun reads .env on its own; Node needs telling, and --env-file is why this asks for
+  // Node 20.6 rather than the 20 the server itself needs.
+  const start = runtime === 'bun' ? 'bun server.js' : 'node --env-file=.env server.js';
+
+  files.push({
+    path: 'package.json',
+    contents: JSON.stringify({
+      name,
+      private: true,
+      type: 'module',
+      scripts: { start },
+      dependencies: { '@3sln/trove': pin(version) },
+      engines: runtime === 'bun' ? { bun: '>=1.1.0' } : { node: '>=20.6' },
+    }, null, 2) + '\n',
+  });
+
+  files.push({
+    path: 'server.js',
+    contents: `// Trove, as this project runs it.
+//
+// The adapter starts listening when it is imported — it reads its configuration from
+// the environment (see .env), so there is nothing to pass it. Importing it through the
+// package's public export rather than a path into node_modules means this line keeps
+// working whatever the installer does with the tree.
+//
+// To add your own openers or views, this is the file that grows: build a workbench with
+// \`createWorkbench({ openers, views })\` from '@3sln/trove/web/workbench.js', bundle it,
+// and point TROVE_WEB_DIST at the result.
+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: `npm start`, why: `serves the API and the workbench on :${server?.port ?? '8787'}` });
+}
+
+const serverVars = (server) => server
+  ? [`# ${RULE}`, '# Server', `# ${RULE}`, `PORT=${server.port}`, `HOST=${server.host}`, ''].join('\n')
+  : '';
+
+const envHeader = (plan) => `# Generated by create-trove for a ${plan.runtime} deployment.
+# Every value here is read at startup. Nothing in this file is committed — see .gitignore.
+
+`;
+
+// --- workers ------------------------------------------------------------------
+
+function renderWorkers(plan, files, steps, secrets) {
+  const { name, version, workers: w } = plan;
+
+  files.push({
+    path: 'package.json',
+    contents: JSON.stringify({
+      name,
+      private: true,
+      type: 'module',
+      scripts: { dev: 'wrangler dev', deploy: 'wrangler deploy' },
+      dependencies: { '@3sln/trove': pin(version) },
+      devDependencies: { wrangler: '^3.90.0' },
+    }, null, 2) + '\n',
+  });
+
+  files.push({
+    path: 'src/worker.js',
+    contents: `// The Worker entry.
+//
+// Both exports matter: the default export is the fetch handler, and TroveTasks is the
+// Durable Object class that owns scans and reindexes. Wrangler looks the DO class up by
+// name in this module, so re-exporting it here is what makes the binding resolve —
+// declaring it in wrangler.toml without this is a deploy-time error.
+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()) {
+    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}`,
+    });
+  }
+
+  steps.push({ cmd: `cd ${name} && npm install`, why: 'wrangler, and @3sln/trove for the app assets' });
+  if (w?.d1) {
+    steps.push({
+      cmd: `npx wrangler d1 create ${w.d1.name}`,
+      why: w.d1.id ? 'already have the id in wrangler.toml — skip if it exists' : 'then paste database_id into wrangler.toml',
+    });
+  }
+  if (w?.pluginDb) {
+    steps.push({ cmd: `npx wrangler d1 create ${w.pluginDb.name}`, why: 'server-side plugin storage' });
+  }
+  if (w?.vectorize) {
+    steps.push({
+      cmd: `npx wrangler vectorize create ${w.vectorize.index} --dimensions=${w.vectorize.dimensions} --metric=${w.vectorize.metric}`,
+      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' });
+  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 deploy', why: '' });
+}
+
+function wranglerToml(plan) {
+  const { workers: w, sections } = plan;
+  const q = (v) => JSON.stringify(String(v));
+  const L = [];
+
+  L.push('# Generated by create-trove. Every binding below has a matching command in README.md —');
+  L.push('# a wrangler.toml naming a D1 database nobody created deploys fine and fails at request time.');
+  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('');
+
+  L.push('# The built web app, served straight from the installed package — no build step');
+  L.push('# here, because @3sln/trove ships its dist/ inside the tarball.');
+  L.push('[assets]');
+  L.push('directory = "node_modules/@3sln/trove/packages/web/dist"');
+  L.push('binding = "ASSETS"');
+  L.push('');
+
+  if (w?.d1) {
+    L.push('# Metadata, KV, plugin installs and keyword search. Without this the drive runs');
+    L.push('# entirely in memory and loses everything when the isolate recycles.');
+    L.push('[[d1_databases]]');
+    L.push('binding = "DB"');
+    L.push(`database_name = ${q(w.d1.name)}`);
+    L.push(`database_id = ${q(w.d1.id || '<run: wrangler d1 create ' + w.d1.name + '>')}`);
+    L.push('');
+  } else {
+    L.push('# [[d1_databases]]          # REQUIRED for anything to persist');
+    L.push('# binding = "DB"');
+    L.push('# database_name = "trove"');
+    L.push('# database_id = "<wrangler d1 create trove>"');
+    L.push('');
+  }
+
+  if (w?.pluginDb) {
+    L.push('# Server-side plugin storage. One database holds every plugin scope: D1 cannot');
+    L.push('# create databases on demand, so per-scope databases are not expressible here.');
+    L.push('[[d1_databases]]');
+    L.push('binding = "PLUGIN_DB"');
+    L.push(`database_name = ${q(w.pluginDb.name)}`);
+    L.push(`database_id = ${q(w.pluginDb.id || '<run: wrangler d1 create ' + w.pluginDb.name + '>')}`);
+    L.push('');
+  } else {
+    L.push('# [[d1_databases]]          # optional: server-side plugin storage');
+    L.push('# binding = "PLUGIN_DB"     # without it that one feature reports a clear error');
+    L.push('');
+  }
+
+  if (w?.vectorize) {
+    L.push('[[vectorize]]');
+    L.push('binding = "VECTORIZE"');
+    L.push(`index_name = ${q(w.vectorize.index)}`);
+    L.push('');
+  } else {
+    L.push('# [[vectorize]]             # semantic search; sqlite-vec cannot load on Workers');
+    L.push('# binding = "VECTORIZE"');
+    L.push('# index_name = "trove"');
+    L.push('');
+  }
+
+  if (w?.ai) {
+    L.push('# Turns natural language into semantic text + tag filters; falls back to the');
+    L.push('# #tag grammar on error.');
+    L.push('[ai]');
+    L.push('binding = "AI"');
+    L.push('');
+  } else {
+    L.push('# [ai]                      # optional: LLM query understanding');
+    L.push('# binding = "AI"');
+    L.push('');
+  }
+
+  if (w?.tasks) {
+    L.push('# Scans and reindexes live in one Durable Object, so a client polling /api/tasks');
+    L.push('# reaches the isolate that actually holds the task and Cancel reaches its');
+    L.push('# AbortController. Without it the work still runs, in the request isolate.');
+    L.push('[[durable_objects.bindings]]');
+    L.push('name = "TASKS"');
+    L.push('class_name = "TroveTasks"');
+    L.push('');
+    L.push('[[migrations]]');
+    L.push('tag = "v1"');
+    L.push('new_sqlite_classes = ["TroveTasks"]');
+    L.push('');
+  } else {
+    L.push('# [[durable_objects.bindings]]   # optional: owns scans and reindexes');
+    L.push('# name = "TASKS"');
+    L.push('# class_name = "TroveTasks"');
+    L.push('# [[migrations]]');
+    L.push('# tag = "v1"');
+    L.push('# new_sqlite_classes = ["TroveTasks"]');
+    L.push('');
+  }
+
+  L.push('[vars]');
+  L.push('# Configuration only. Credentials are secrets — see README.md.');
+  for (const section of sections) {
+    const shown = section.entries.filter((e) => !e.secret);
+    if (!shown.length) continue;
+    L.push(`# ${section.title}${section.skipped ? '  (skipped)' : ''}`);
+    for (const e of shown) {
+      const c = e.comment ? `  # ${e.comment}` : '';
+      L.push(isSet(e) ? `${e.key} = ${q(e.value)}${c}` : `# ${e.key} = ""${c}`);
+    }
+  }
+  L.push('');
+  return L.join('\n');
+}
+
+// --- the generated README -----------------------------------------------------
+
+function readme(plan, steps) {
+  const L = [];
+  const runtimeName = { bun: 'Bun', node: 'Node', workers: 'Cloudflare Workers' }[plan.runtime];
+
+  L.push(`# ${plan.name}`);
+  L.push('');
+  L.push(`A [Trove](https://github.com/3sln/trove) drive on **${runtimeName}**, scaffolded with \`create-trove\`.`);
+  L.push('');
+  L.push(`The web app is not built here — \`@3sln/trove@${plan.version}\` ships it already built, so the`);
+  L.push('server and the workbench it serves are the same release by construction.');
+  L.push('');
+
+  L.push('## Getting it running');
+  L.push('');
+  L.push('```sh');
+  for (const s of steps) L.push(s.why ? `${s.cmd}${' '.repeat(Math.max(1, 44 - s.cmd.length))}# ${s.why}` : s.cmd);
+  L.push('```');
+  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);
+    const found = (k) => plan.warnings.find((w) => kind(w) === k);
+
+    L.push('## Before you expose this');
+    L.push('');
+    if (has('anonymous')) {
+      L.push('- **No identity is configured.** Everyone who can reach the port is the same');
+      L.push('  anonymous user. Set `TROVE_AUTH` and `TROVE_AUTH_REQUIRED=true`, and put it behind');
+      L.push('  an authenticating proxy over TLS.');
+    }
+    if (has('incomplete-identity')) {
+      const w = found('incomplete-identity');
+      L.push(`- **\`TROVE_AUTH=${w.driver}\` is set but incomplete** — ${w.missing.join(', ')} ${w.missing.length > 1 ? 'are' : 'is'} blank.`);
+      L.push('  The config reads as configured while the driver has nothing to verify against.');
+    }
+    if (has('default-open')) {
+      L.push('- **The default collection is open.** Every authenticated user gets full');
+      L.push('  read/write/delete on it. Set `TROVE_DEFAULT_OPEN=false`.');
+    }
+    L.push('');
+  }
+
+  if (plan.skipped.length) {
+    L.push('## Skipped');
+    L.push('');
+    L.push('Left for you to fill in. The keys are already in place, commented, in');
+    L.push(plan.runtime === 'workers' ? '`wrangler.toml`:' : '`.env`:');
+    L.push('');
+    for (const s of plan.skipped) L.push(`- ${s}`);
+    L.push('');
+  }
+
+  L.push('## Configuration');
+  L.push('');
+  L.push(plan.runtime === 'workers'
+    ? 'Non-secret settings live in `[vars]` in `wrangler.toml`; credentials are secrets, set with\n`wrangler secret put`, and mirrored into a gitignored `.dev.vars` for `wrangler dev`.'
+    : 'Everything is in `.env`, which is gitignored. The full set of variables, with defaults,\nis documented in the Trove README.');
+  L.push('');
+  return L.join('\n');
+}