@3sln/create-trove 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3sln/create-trove",
-  "version": "0.0.2",
+  "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": {
@@ -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,29 @@ 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 });
+      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
+      // 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 +186,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,130 @@
+// 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, 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() };
+}
+
+/**
+ * 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()];
+}