@3sln/create-trove 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3sln/create-trove",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "description": "Scaffold a Trove deployment — Bun, Node, or Cloudflare Workers — with the bindings, environment and secrets each one needs.",
   "repository": {
@@ -24,7 +24,10 @@
     "create-trove": "./src/cli.js"
   },
   "exports": {
+    ".": "./src/index.js",
     "./plan": "./src/plan.js",
+    "./render": "./src/render.js",
+    "./prompt": "./src/prompt.js",
     "./package.json": "./package.json"
   },
   "files": [

package/src/cli.js

@@ -8,35 +8,63 @@
 // 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.
+//
+// It is also usable by something that cannot read a prompt. `--set key=value` supplies
+// answers up front, `--json` puts a machine-readable result on stdout with every human
+// word on stderr, and `--describe` lists the keys rather than making a caller read this
+// file to find them. Keys are a flat namespace (`storage.bucket`) rather than the text
+// of a question, because the wording of a question is not an interface and rewording a
+// hint should not break a caller.
 
 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 { createPrompter, presetPrompter } from './prompt.js';
 import { askPlan, RUNTIMES } from './plan.js';
 import { renderProject } from './render.js';
+import { describeQuestions } from './index.js';
 
 const USAGE = `Usage: npm create @3sln/trove <directory> [options]
 
 Options:
   --runtime <bun|node|workers>  skip the first question
+  --set <key=value>             answer one question; repeatable (see --describe)
+  --config <file.json>          answer many, as a flat { "key": value } object
   --yes                         take every default, ask nothing
-  --dry-run                     print what would be written, write nothing
+  --json                        machine-readable result on stdout, prose on stderr
+  --describe                    list every question key and exit
+  --dry-run                     report what would be written, write nothing
   --force                       write into a directory that is not empty
   --help                        this
+
+Answers given by --set and --config are taken as-is; anything left over is asked
+interactively, or defaulted when there is no terminal. A key that is never asked for
+is an error, since it is either a typo or a setting the other answers ruled out.
 `;
 
 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];
+  const opts = {
+    dir: null, runtime: null, yes: false, dryRun: false, force: false,
+    help: false, json: false, describe: false, config: null, set: {},
+  };
+  const value = (a, i, flag) => (a.startsWith(`${flag}=`) ? a.slice(flag.length + 1) : argv[++i.v]);
+  for (const i = { v: 0 }; i.v < argv.length; i.v++) {
+    const a = argv[i.v];
     if (a === '--help' || a === '-h') opts.help = true;
     else if (a === '--yes' || a === '-y') opts.yes = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--describe') opts.describe = 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;
+    else if (a.startsWith('--runtime')) opts.runtime = value(a, i, '--runtime');
+    else if (a.startsWith('--config')) opts.config = value(a, i, '--config');
+    else if (a.startsWith('--set')) {
+      const raw = value(a, i, '--set');
+      const eq = String(raw ?? '').indexOf('=');
+      if (eq < 1) throw new Error(`--set wants key=value, got "${raw}"`);
+      opts.set[raw.slice(0, eq)] = raw.slice(eq + 1);
+    } else if (a.startsWith('-')) throw new Error(`Unknown option "${a}"`);
+    else if (!opts.dir) opts.dir = a;
   }
   return opts;
 }
@@ -46,28 +74,74 @@ const toPackageName = (dirName) =>
   dirName.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+/, '').replace(/-+$/, '') || 'trove-drive';
 
 async function main() {
-  const opts = parseArgs(process.argv.slice(2));
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`${err.message}\n\n${USAGE}`);
+    return 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;
+    return 2;
   }
 
   const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
 
+  // Prose goes to stderr under --json, so stdout is one parseable document and nothing
+  // else. Without that split a caller has to strip the banner before it can parse, which
+  // is the sort of thing that works until someone adds a line to the banner.
+  const say = opts.json ? (s) => process.stderr.write(s) : (s) => process.stdout.write(s);
+  const emit = (obj) => process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
+
+  if (opts.describe) {
+    const questions = await describeQuestions({ version });
+    if (opts.json) emit({ version, questions });
+    else {
+      process.stdout.write(`\nEvery question, by key. Use --set key=value.\n\n`);
+      for (const q of questions) {
+        const opt = q.options ? `  (${q.options.map((o) => o.value).join(' | ')})` : '';
+        process.stdout.write(`  ${q.key.padEnd(30)} ${q.kind}${opt}\n`);
+        process.stdout.write(`  ${''.padEnd(30)} ${q.label} — default ${JSON.stringify(q.default)}\n`);
+        if (q.runtimes.length < RUNTIMES.length) {
+          process.stdout.write(`  ${''.padEnd(30)} only for: ${q.runtimes.join(', ')}\n`);
+        }
+        process.stdout.write('\n');
+      }
+    }
+    return 0;
+  }
+
+  let answers = { ...opts.set };
+  if (opts.config) {
+    try {
+      const parsed = JSON.parse(await readFile(path.resolve(opts.config), 'utf8'));
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('expected a flat JSON object of key/value pairs');
+      }
+      // --set wins, so a config file can be a base that one flag overrides.
+      answers = { ...parsed, ...opts.set };
+    } catch (err) {
+      process.stderr.write(`Could not read ${opts.config}: ${err.message}\n`);
+      return 2;
+    }
+  }
+
   // 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 });
+  const interactive = process.stdin.isTTY && !opts.yes && !opts.json;
+  const base = createPrompter({ assumeDefaults: !interactive, output: opts.json ? process.stderr : process.stdout });
+  const prompter = presetPrompter(answers, base);
 
   try {
-    process.stdout.write(`\ncreate-trove ${version}\n`);
+    say(`\ncreate-trove ${version}\n`);
 
     const dir = opts.dir || (interactive
-      ? await prompter.text('\nProject directory', { default: 'my-drive' })
+      ? await base.text('\nProject directory', { default: 'my-drive' })
       : 'my-drive');
     const target = path.resolve(dir);
     const name = toPackageName(path.basename(target));
@@ -80,11 +154,28 @@ async function main() {
       }
     }
 
-    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`);
+    let plan;
+    let rendered;
+    try {
+      plan = await askPlan(prompter, { name, version, runtime: opts.runtime });
+      rendered = renderProject(plan);
+    } catch (err) {
+      // A bad --set value: name the key rather than making someone map a stack trace
+      // back to a flag they typed.
+      process.stderr.write(`\n${err.message}\n`);
+      return 2;
+    }
+    const { files, steps } = rendered;
+
+    // Either it was a typo or the other answers ruled the question out. Both are worth
+    // refusing over: an agent that thinks it set a bucket should not get a drive with
+    // no bucket and a zero exit code.
+    const unused = prompter.unused();
+    if (unused.length) {
+      process.stderr.write(`\nThese answers were never asked for: ${unused.join(', ')}\n`);
+      process.stderr.write('Either the key is wrong (see --describe) or another answer ruled the question out.\n');
+      return 2;
+    }
 
     if (!opts.dryRun) {
       for (const f of files) {
@@ -94,21 +185,37 @@ async function main() {
       }
     }
 
-    process.stdout.write('\nNext:\n');
-    for (const s of steps) process.stdout.write(`  ${s.cmd}${s.why ? `    # ${s.why}` : ''}\n`);
+    if (opts.json) {
+      emit({
+        version,
+        directory: target,
+        written: !opts.dryRun,
+        runtime: plan.runtime,
+        files: files.map((f) => f.path),
+        steps: steps.map((s) => ({ command: s.cmd, why: s.why || undefined })),
+        skipped: plan.skipped,
+        warnings: plan.warnings.map((w) => (typeof w === 'string' ? { kind: w } : w)),
+      });
+      return 0;
+    }
+
+    say(`\n${opts.dryRun ? 'Would write' : 'Writing'} ${files.length} files to ${target}\n`);
+    for (const f of files) say(`  ${f.path}\n`);
+    say('\nNext:\n');
+    for (const s of steps) say(`  ${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`);
+      say(`\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');
+      if (kind === 'anonymous') say('\nNo identity configured — anyone who can reach this has full access.\n');
+      if (kind === 'incomplete-identity') say(`\nTROVE_AUTH=${w.driver} is set but ${w.missing.join(' and ')} left blank.\n`);
+      if (kind === 'default-open') say('The default collection is open to every user.\n');
     }
-    process.stdout.write('\n');
+    say('\n');
     return 0;
   } finally {
-    prompter.close();
+    base.close();
   }
 }
 

package/src/index.js

@@ -0,0 +1,129 @@
+// The programmatic surface.
+//
+// The CLI is one caller of this, not the only way in. `exports` previously named
+// `./plan` alone, which was not usable: `askPlan` needs a prompter, and neither the
+// prompter nor the renderer was exported. So the package advertised a library entry
+// that could not build anything.
+//
+// Everything here is non-interactive by construction — no terminal is touched unless a
+// caller passes a prompter that wants one. That is the shape an agent needs: supply the
+// answers it knows, take defaults for the rest, and get files back as data rather than
+// as a directory it then has to go and read.
+
+import { presetPrompter, recordingPrompter, createPrompter } from './prompt.js';
+import { askPlan, RUNTIMES } from './plan.js';
+import { renderProject } from './render.js';
+
+export { askPlan, renderProject, RUNTIMES };
+export { createPrompter, presetPrompter, recordingPrompter, scripted } from './prompt.js';
+
+/**
+ * Plan and render a project without asking anybody anything.
+ *
+ * @param {object} opts
+ * @param {string} opts.name project (and package) name
+ * @param {string} opts.version the @3sln/trove version to pin
+ * @param {string} [opts.runtime] bun | node | workers; also settable as answers.runtime
+ * @param {Record<string, string|boolean|number>} [opts.answers] keyed answers — see
+ *   `describeQuestions()` for what the keys are
+ * @param {object} [opts.prompter] asked about anything `answers` does not cover;
+ *   defaults to one that takes every default and never blocks
+ * @returns {Promise<{plan: object, files: Array, steps: Array, unused: string[]}>}
+ *   `unused` is the answers that were never asked for — a typo, or a setting the other
+ *   answers made unreachable. Both are worth surfacing rather than swallowing.
+ */
+/** 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 } = {}) {
+  // 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 });
+  const { files, steps } = renderProject(plan);
+  return { plan, files, steps, unused: preset.unused() };
+}
+
+/**
+ * Every question the wizard can ask, by key.
+ *
+ * Generated by running the interview rather than kept by hand, because the interview
+ * branches on its own answers and a hand-written schema would drift from it the first
+ * time a question moved. Running it once per runtime with a recorder covers the three
+ * shapes that actually differ; a question only reachable under a non-default answer
+ * (Qdrant's URL, say) is reported against the answer that reveals it via `revealedBy`.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.version] only affects the plan, not the questions
+ */
+export async function describeQuestions({ version = '0.0.0' } = {}) {
+  const byKey = new Map();
+
+  const run = async (runtime, answers) => {
+    const rec = recordingPrompter();
+    try {
+      // `runtime: undefined` lets the runtime question itself be asked and recorded;
+      // passing it skips the question, which is how it went undocumented at first.
+      await askPlan(presetPrompter(answers, rec), { name: 'example', version, runtime });
+    } catch {
+      // The combination does not exist — `storage.driver=filesystem` under Workers,
+      // which has no disk and so does not offer it. Not every pairing of answers is a
+      // reachable state, and probing for that is the point.
+      return false;
+    }
+    let discovered = false;
+    for (const q of rec.questions()) {
+      const seen = byKey.get(q.key);
+      if (!seen) {
+        byKey.set(q.key, { ...q, runtimes: [runtime ?? 'bun'] });
+        discovered = true;
+      } else {
+        if (runtime && !seen.runtimes.includes(runtime)) seen.runtimes.push(runtime);
+        // A choice can offer different options per runtime, so the description is the
+        // union — otherwise `--describe` would reject a value the wizard accepts.
+        for (const o of q.options ?? []) {
+          if (!seen.options.some((x) => x.value === o.value)) seen.options.push(o);
+        }
+      }
+    }
+    return discovered;
+  };
+
+  // The interview branches on its own answers, so one pass describes only the path the
+  // defaults take. Walking it to a fixed point — turn every section on, then try each
+  // alternative of every choice, then give every empty text field a value — reaches the
+  // questions that only exist under some other answer: Qdrant's URL, the JWT fields,
+  // the icon size that appears once an icon is named. It is bounded by the question set
+  // rather than by a guess, and it cannot drift from the code the way a hand-kept
+  // schema would.
+  await run(undefined, {});
+  for (const runtime of RUNTIMES) await run(runtime, {});
+
+  for (let round = 0; round < 4; round++) {
+    const on = Object.fromEntries([...byKey.keys()].filter((k) => k.endsWith('.enabled')).map((k) => [k, true]));
+    let discovered = false;
+
+    for (const runtime of RUNTIMES) {
+      if (await run(runtime, on)) discovered = true;
+
+      for (const q of [...byKey.values()]) {
+        // Each alternative of a choice, one at a time, so a reveal is attributable.
+        if (q.kind === 'choice') {
+          for (const opt of q.options) {
+            if (await run(runtime, { ...on, [q.key]: opt.value })) discovered = true;
+          }
+        }
+        // A field left blank by default usually gates something (an icon URL gates its
+        // size). Anything non-empty will do; the value is never used.
+        if (q.kind === 'text' && q.default === '') {
+          if (await run(runtime, { ...on, [q.key]: 'x' })) discovered = true;
+        }
+      }
+    }
+    if (!discovered) break;
+  }
+
+  return [...byKey.values()];
+}

package/src/plan.js

@@ -42,7 +42,7 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
     { 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' });
+  ], { key: 'runtime', default: 'bun' });
 
   const isWorkers = runtime === 'workers';
   const plan = { name, version, runtime, sections: [], workers: null, server: null, skipped: [], warnings: [] };
@@ -56,7 +56,7 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
   // 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', {
+  if (await prompter.section('Object storage', { key: 'storage.enabled',
     blurb: isWorkers
       ? 'Where file bytes live. On Workers this is R2 through its S3-compatible API.'
       : 'Where file bytes live.',
@@ -68,24 +68,24 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
       { 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' });
+    ], { key: 'storage.driver', 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' }),
+      entries.push(entry('TROVE_FS_ROOT', await prompter.text('  Object root', { key: 'storage.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' }),
+      entries.push(entry('TROVE_S3_BUCKET', await prompter.text('  Bucket', { key: 'storage.bucket', default: 'trove' })));
+      entries.push(entry('TROVE_S3_REGION', await prompter.text('  Region', { key: 'storage.region', default: isWorkers ? 'auto' : 'us-east-1' }),
         { comment: 'R2 uses "auto"' }));
-      entries.push(entry('TROVE_S3_ENDPOINT', await prompter.text('  Endpoint', {
+      entries.push(entry('TROVE_S3_ENDPOINT', await prompter.text('  Endpoint', { key: 'storage.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_ACCESS_KEY_ID', await prompter.text('  Access key id', { key: 'storage.accessKeyId', default: '' }), { secret: true }));
+      entries.push(entry('TROVE_S3_SECRET_ACCESS_KEY', await prompter.text('  Secret access key', { key: 'storage.secretAccessKey', default: '' }), { secret: true }));
+      if (!isWorkers && await prompter.confirm('  Path-style addressing?', { key: 'storage.pathStyle', default: false })) {
         entries.push(entry('TROVE_S3_PATH_STYLE', 'true', { comment: 'MinIO and most custom endpoints' }));
       }
     }
@@ -104,14 +104,14 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
   // 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.' })) {
+    if (await prompter.section('Metadata', { key: 'metadata.enabled', 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' });
+      ], { key: 'metadata.driver', 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' })));
+        entries.push(entry('TROVE_DB_PATH', await prompter.text('  Database path', { key: 'metadata.path', default: './data/trove.db' })));
       }
       add('Metadata', entries);
     } else {
@@ -123,19 +123,19 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
   }
 
   // --- search ----------------------------------------------------------------
-  if (await prompter.section('Semantic search', {
+  if (await prompter.section('Semantic search', { key: 'search.enabled',
     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' });
+    ], { key: 'search.embeddings', 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' }),
+      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' }),
         { comment: 'must match the model, and changing it means a reindex' }));
     }
 
@@ -147,12 +147,12 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
       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' });
+      ], { key: 'search.vector', 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 }));
+        entries.push(entry('TROVE_QDRANT_URL', await prompter.text('  Qdrant URL', { key: 'search.qdrantUrl', default: 'http://localhost:6333' })));
+        entries.push(entry('TROVE_QDRANT_COLLECTION', await prompter.text('  Collection', { key: 'search.qdrantCollection', default: 'trove' })));
+        entries.push(entry('TROVE_QDRANT_API_KEY', await prompter.text('  API key', { key: 'search.qdrantApiKey', default: '' }), { secret: true }));
       }
     }
     add('Semantic search', entries);
@@ -166,7 +166,7 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
   // --- 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', {
+  if (await prompter.section('Identity', { key: 'identity.enabled',
     blurb: 'Trove ships no login — it verifies what an IdP or proxy already established.',
   })) {
     const driver = await prompter.choice('  Verify identity via', [
@@ -174,23 +174,23 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
       { 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' });
+    ], { key: 'identity.driver', 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: '' })));
+      entries.push(entry('TROVE_CF_ACCESS_TEAM', await prompter.text('  Access team name', { key: 'identity.team', default: '', hint: 'the <team> in <team>.cloudflareaccess.com' })));
+      entries.push(entry('TROVE_CF_ACCESS_AUD', await prompter.text('  Application AUD tag', { key: 'identity.aud', 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 }))));
+      entries.push(entry('TROVE_JWKS_URL', await prompter.text('  JWKS URL', { key: 'identity.jwksUrl', default: '' })));
+      entries.push(entry('TROVE_JWT_ISSUER', await prompter.text('  Issuer', { key: 'identity.issuer', default: '' })));
+      entries.push(entry('TROVE_JWT_AUDIENCE', await prompter.text('  Audience', { key: 'identity.audience', default: '' })));
+      entries.push(entry('TROVE_AUTH_REQUIRED', String(await prompter.confirm('  Reject unauthenticated requests?', { key: 'identity.required', default: true }))));
     } else if (driver === 'header') {
-      entries.push(entry('TROVE_AUTH_ID_HEADER', await prompter.text('  Identity header', { default: 'cf-access-authenticated-user-email' }),
+      entries.push(entry('TROVE_AUTH_ID_HEADER', await prompter.text('  Identity header', { key: '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 }))));
+      entries.push(entry('TROVE_AUTH_REQUIRED', String(await prompter.confirm('  Reject unauthenticated requests?', { key: 'identity.required', default: true }))));
     }
     if (driver === 'anonymous') plan.warnings.push('anonymous');
     // Naming a driver whose settings were left blank is worse than naming none: the
@@ -213,9 +213,9 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
   }
 
   // --- 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 });
+  if (await prompter.section('Access control', { key: 'access.enabled', blurb: 'Who is an admin, and whether the default collection is open to everyone.' })) {
+    const admins = await prompter.text('  Admin principal ids', { key: 'access.admins', default: '', hint: 'comma-separated, usually email addresses' });
+    const open = await prompter.confirm('  Give everyone full access to the default collection?', { key: 'access.defaultOpen', 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' }),
@@ -234,19 +234,19 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
   // 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', {
+  if (await prompter.section('Installed app name', { key: 'app.enabled',
     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 appName = await prompter.text('  App name', { key: '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' });
+    const short = await prompter.text('  Short name', { key: 'app.shortName', 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' });
+    entries.push(entry('TROVE_APP_THEME_COLOR', await prompter.text('  Theme colour', { key: 'app.themeColor', default: '#181a1f' })));
+    const icon = await prompter.text('  Icon URL', { key: 'app.icon', 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', {
+      entries.push(entry('TROVE_APP_ICON_SIZES', await prompter.text('  Icon size', { key: 'app.iconSizes',
         default: icon.endsWith('.svg') ? 'any' : '512x512',
         hint: 'a raster icon claiming "any" gets scaled badly',
       })));
@@ -265,9 +265,9 @@ export async function askPlan(prompter, { name, version, runtime: preset }) {
     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' });
+    if (await prompter.section('Server', { key: 'server.enabled', blurb: 'Port and bind address.', default: false })) {
+      plan.server.port = await prompter.text('  Port', { key: 'server.port', default: '8787' });
+      plan.server.host = await prompter.text('  Host', { key: 'server.host', default: '0.0.0.0' });
     }
   }
 
@@ -289,37 +289,37 @@ async function askWorkers(prompter) {
     compatibilityDate: '2024-09-23',
   };
 
-  if (await prompter.section('D1 (metadata)', {
+  if (await prompter.section('D1 (metadata)', { key: 'workers.d1.enabled',
     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' }),
+      name: await prompter.text('  Database name', { key: 'workers.d1.name', default: 'trove' }),
+      id: await prompter.text('  Database id', { key: 'workers.d1.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 })) {
+    if (await prompter.confirm('  Bind a second D1 for server-side plugin storage?', { key: 'workers.pluginDb.enabled', default: false })) {
       w.pluginDb = {
-        name: await prompter.text('  Plugin database name', { default: 'trove-plugins' }),
-        id: await prompter.text('  Plugin database id', { default: '' }),
+        name: await prompter.text('  Plugin database name', { key: 'workers.pluginDb.name', default: 'trove-plugins' }),
+        id: await prompter.text('  Plugin database id', { key: 'workers.pluginDb.id', default: '' }),
       };
     }
   }
 
-  if (await prompter.section('Vectorize (semantic search)', {
+  if (await prompter.section('Vectorize (semantic search)', { key: 'workers.vectorize.enabled',
     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' }),
+      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' }),
       metric: await prompter.choice('  Distance metric', [
         { value: 'cosine', label: 'cosine' },
         { value: 'euclidean', label: 'euclidean' },
         { value: 'dot-product', label: 'dot-product' },
-      ], { default: 'cosine' }),
+      ], { key: 'workers.vectorize.metric', 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 });
+  w.ai = await prompter.confirm('\nBind Workers AI for natural-language search queries?', { key: 'workers.ai', default: false });
+  w.tasks = await prompter.confirm('Bind the TroveTasks Durable Object for scans and reindexes?', { key: 'workers.tasks', default: true });
 
   return w;
 }

package/src/prompt.js

@@ -111,6 +111,105 @@ export function createPrompter({ input = process.stdin, output = process.stdout,
   };
 }
 
+// --- non-interactive drivers -------------------------------------------------
+//
+// Everything below is the same interface, which is the point: the wizard does not know
+// whether a person, a test transcript, a `--set` flag or nobody at all is answering it.
+//
+// These two are what make the tool usable by something that is not a human. An agent
+// cannot read a blurb and type a bucket name, so it supplies answers up front by key —
+// `storage.bucket`, not "  Bucket". Keys are stable; the wording of a question is not,
+// and pinning an interface to prose means rewording a hint breaks callers.
+
+const TRUE = new Set(['true', 'yes', 'y', '1', 'on']);
+const FALSE = new Set(['false', 'no', 'n', '0', 'off']);
+
+function toBool(raw, key) {
+  const v = String(raw).trim().toLowerCase();
+  if (TRUE.has(v)) return true;
+  if (FALSE.has(v)) return false;
+  throw new Error(`${key}: expected a boolean, got "${raw}"`);
+}
+
+/**
+ * Answer from a map of keys, and ask `inner` about anything not supplied.
+ *
+ * Unused keys are an error rather than a shrug — see `unused()`. A key that was never
+ * consumed is either a typo or a setting that the other answers made unreachable
+ * (`storage.bucket` when the backend is `filesystem`), and both are things the caller
+ * wants told to them rather than silently dropped.
+ *
+ * @param {Record<string, string|number|boolean>} answers
+ * @param {object} inner the prompter to fall back to
+ */
+export function presetPrompter(answers, inner) {
+  const supplied = new Map(Object.entries(answers ?? {}).map(([k, v]) => [k, v]));
+  const used = new Set();
+
+  const take = (key) => {
+    if (key === undefined || !supplied.has(key)) return undefined;
+    used.add(key);
+    return supplied.get(key);
+  };
+
+  return {
+    close: () => inner.close(),
+    heading: (t) => inner.heading(t),
+    note: (t) => inner.note(t),
+    /** Keys that were given but never asked for. */
+    unused: () => [...supplied.keys()].filter((k) => !used.has(k)),
+
+    async text(label, opts = {}) {
+      const v = take(opts.key);
+      return v === undefined ? inner.text(label, opts) : String(v);
+    },
+    async choice(label, options, opts = {}) {
+      const v = take(opts.key);
+      if (v === undefined) return inner.choice(label, options, opts);
+      const wanted = String(v);
+      if (!options.some((o) => o.value === wanted)) {
+        throw new Error(`${opts.key}: "${wanted}" is not one of ${options.map((o) => o.value).join(', ')}`);
+      }
+      return wanted;
+    },
+    async confirm(label, opts = {}) {
+      const v = take(opts.key);
+      return v === undefined ? inner.confirm(label, opts) : toBool(v, opts.key);
+    },
+    async section(title, opts = {}) {
+      const v = take(opts.key);
+      return v === undefined ? inner.section(title, opts) : toBool(v, opts.key);
+    },
+  };
+}
+
+/**
+ * Ask nothing, answer with defaults, and write down every question it was asked.
+ *
+ * This is how `--describe` works. The interview branches on its own answers, so there is
+ * no static schema to print — but running it with a recorder produces the questions that
+ * are actually reachable, which is the honest version of the same thing and cannot drift
+ * from the code the way a hand-kept list would.
+ */
+export function recordingPrompter() {
+  const seen = [];
+  const record = (kind, label, opts, value, options) => {
+    if (opts.key) seen.push({ key: opts.key, kind, label: label.trim(), default: value, ...(options ? { options } : {}) });
+    return value;
+  };
+  return {
+    close() {}, heading() {}, note() {},
+    questions: () => seen,
+    async text(label, opts = {}) { return record('text', label, opts, opts.default ?? ''); },
+    async choice(label, options, opts = {}) {
+      return record('choice', label, opts, opts.default ?? options[0].value,
+        options.map((o) => ({ value: o.value, label: o.label })));
+    },
+    async confirm(label, opts = {}) { return record('boolean', label, opts, opts.default ?? true); },
+    async section(title, opts = {}) { return record('boolean', title, opts, opts.default ?? true); },
+  };
+}
+
 /**
  * A prompter that reads from a list instead of a person.
  *