create-zerotal 1.6.3 → 1.7.2

package/CHANGELOG.md

@@ -8,6 +8,27 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+### Added
+
+- **A non-interactive mode, so the scaffolder can be scripted.** Every prompt now has a flag —
+  `--template`, `--db`, `--name` — plus `--yes` to take the defaults for anything unset,
+  `--no-install`, `--help` and `--version`. `bun create zerotal my-app` is unchanged.
+
+### Fixed
+
+- **With no TTY the scaffolder hung instead of failing.** It read `process.argv[2]` as the project
+  name and asked for everything else through `readline`, which waits for a line that never arrives
+  in CI, in a pipeline, or under an agent. So it did not error and did not exit — it held the job
+  open until something timed it out. The workaround in this repo was to bypass the CLI entirely and
+  call `scaffold()` directly, which is the shape of an admission.
+
+  It now detects the absent terminal and refuses, naming the flag that would have answered the
+  question, with a non-zero exit code. Unknown flags are refused too rather than dropped: silently
+  ignoring `--tempalte=api` means asking again for something the caller thought they had given,
+  which in CI is the hang all over again. A failed `bun install` also exits non-zero when there is
+  no terminal — a half-built project reported as a success is worse than one that stops.
+
+
 ## [1.6.3] — 2026-08-15
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zerotal",
-  "version": "1.6.3",
+  "version": "1.7.2",
   "description": "Create a new Zerotal application",
   "license": "MIT",
   "maturity": "stable",

package/src/args.ts

@@ -0,0 +1,192 @@
+import type { Database, Template } from './scaffold.ts';
+
+export const TEMPLATES: readonly Template[] = ['api', 'admin', 'flow', 'react', 'vue', 'minimal'];
+export const DATABASES: readonly Database[] = ['sqlite', 'postgres', 'mysql'];
+
+/** Defaults, matching the first option of each prompt. */
+export const DEFAULT_TEMPLATE: Template = 'api';
+export const DEFAULT_DATABASE: Database = 'sqlite';
+
+export interface ParsedArgs {
+  name?: string;
+  template?: string;
+  db?: string;
+  /** Take defaults for anything not supplied, instead of asking. */
+  yes: boolean;
+  install: boolean;
+  help: boolean;
+  version: boolean;
+  /** Flags that are not ours — reported rather than ignored. */
+  unknown: string[];
+}
+
+/**
+ * Parse the command line.
+ *
+ * Supports `--flag value` and `--flag=value`, plus `-t`/`-y`/`-h` shorthands, so
+ * neither habit is wrong. The first non-flag argument is the project name, which
+ * keeps `bun create zerotal my-app` working exactly as before.
+ *
+ * Unknown flags are collected rather than dropped. Silently ignoring
+ * `--tempalte=api` and then interactively asking for the template is the worst
+ * of both worlds: in CI it hangs, and a human is asked a question they thought
+ * they had answered.
+ */
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+  const out: ParsedArgs = { yes: false, install: true, help: false, version: false, unknown: [] };
+  const takesValue = new Set(['name', 'template', 'db', 't']);
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+
+    if (!arg.startsWith('-')) {
+      out.name ??= arg;
+      continue;
+    }
+
+    const [rawKey, inlineValue] = arg.replace(/^--?/, '').split(/=(.*)/s, 2) as [string, string?];
+    const key = rawKey === 't' ? 'template' : rawKey === 'y' ? 'yes' : rawKey === 'h' ? 'help' : rawKey;
+
+    // `--no-install` — the standard spelling for negating a boolean flag.
+    if (key === 'no-install') {
+      out.install = false;
+      continue;
+    }
+    if (key === 'yes') {
+      out.yes = true;
+      continue;
+    }
+    if (key === 'help') {
+      out.help = true;
+      continue;
+    }
+    if (key === 'version' || key === 'v') {
+      out.version = true;
+      continue;
+    }
+
+    if (takesValue.has(key === 'template' ? 'template' : key)) {
+      // `--template api` as well as `--template=api`; a following flag is not a
+      // value, so `--template --yes` is a missing value rather than the string
+      // "--yes".
+      const next = argv[i + 1];
+      const value = inlineValue ?? (next && !next.startsWith('-') ? (i++, next) : undefined);
+      // Assigned only when present: `exactOptionalPropertyTypes` treats an
+      // explicit `undefined` as different from an absent key, and "absent" is
+      // exactly what a flag with no value means.
+      if (value !== undefined) {
+        if (key === 'name') out.name = value;
+        else if (key === 'template') out.template = value;
+        else if (key === 'db') out.db = value;
+      }
+      continue;
+    }
+
+    out.unknown.push(arg);
+  }
+
+  return out;
+}
+
+export interface Resolution {
+  ok: boolean;
+  /** Populated when `ok` — everything the scaffolder needs. */
+  name?: string | undefined;
+  template?: Template | undefined;
+  db?: Database | undefined;
+  install?: boolean | undefined;
+  /** Questions still to ask. Empty in non-interactive mode. */
+  askFor?: Array<'name' | 'template' | 'db'>;
+  /** Populated when `!ok` — a message a human or a CI log can act on. */
+  error?: string;
+}
+
+/**
+ * Turn parsed flags into either a plan or a refusal.
+ *
+ * The rule that matters: **never wait on stdin that is not there.** Without a
+ * TTY the prompts' `readline` never receives a line, so the old scaffolder did
+ * not fail in CI — it hung, forever, holding the job open until the runner timed
+ * it out. A missing answer is now an error with the flag that would have
+ * supplied it.
+ *
+ * `--yes` takes the defaults for whatever is unspecified, which is what makes
+ * the tool scriptable in one word.
+ */
+export function resolveOptions(args: ParsedArgs, interactive: boolean): Resolution {
+  if (args.unknown.length) {
+    return { ok: false, error: `Unknown option${args.unknown.length > 1 ? 's' : ''}: ${args.unknown.join(', ')}` };
+  }
+
+  if (args.template !== undefined && !TEMPLATES.includes(args.template as Template)) {
+    return { ok: false, error: `Unknown template "${args.template}". Choose one of: ${TEMPLATES.join(', ')}` };
+  }
+  if (args.db !== undefined && !DATABASES.includes(args.db as Database)) {
+    return { ok: false, error: `Unknown database "${args.db}". Choose one of: ${DATABASES.join(', ')}` };
+  }
+
+  const template = (args.template as Template | undefined);
+  const db = (args.db as Database | undefined);
+
+  if (interactive && !args.yes) {
+    const askFor: Array<'name' | 'template' | 'db'> = [];
+    if (!args.name) askFor.push('name');
+    if (!template) askFor.push('template');
+    // Only the API template offers a database choice; the rest have no DB config.
+    if (!db && (template === undefined || template === 'api')) askFor.push('db');
+    return { ok: true, name: args.name, template, db, install: args.install, askFor };
+  }
+
+  // Non-interactive from here: everything must already be known, or defaulted.
+  if (!args.name) {
+    return {
+      ok: false,
+      error:
+        'A project name is required when there is no terminal to ask on.\n' +
+        '  bunx create-zerotal my-app --template=api --yes',
+    };
+  }
+  if (!template && !args.yes) {
+    return {
+      ok: false,
+      error:
+        'No template given, and no terminal to ask on.\n' +
+        `  Pass --template=<${TEMPLATES.join('|')}>, or --yes to take the default (${DEFAULT_TEMPLATE}).`,
+    };
+  }
+
+  const chosen = template ?? DEFAULT_TEMPLATE;
+  return {
+    ok: true,
+    name: args.name,
+    template: chosen,
+    db: chosen === 'api' ? (db ?? DEFAULT_DATABASE) : DEFAULT_DATABASE,
+    install: args.install,
+    askFor: [],
+  };
+}
+
+/** The `--help` text. */
+export function helpText(): string {
+  return [
+    'create-zerotal — scaffold a Zerotal application',
+    '',
+    'Usage',
+    '  bun create zerotal <name> [options]',
+    '  bunx create-zerotal <name> [options]',
+    '',
+    'Options',
+    `  -t, --template <name>  ${TEMPLATES.join(' | ')}`,
+    `      --db <name>        ${DATABASES.join(' | ')} (api template only)`,
+    '  -y, --yes              Take defaults for anything not given; never prompt',
+    '      --no-install       Skip bun install',
+    '  -h, --help             Show this message',
+    '  -v, --version          Print the scaffolder version',
+    '',
+    'Non-interactive',
+    '  With no TTY (CI, an agent, a pipe) the scaffolder never prompts. Supply the',
+    '  answers as flags, or pass --yes to take the defaults.',
+    '',
+    '  bunx create-zerotal my-app --template=api --db=postgres --yes',
+  ].join('\n');
+}

package/src/index.ts

@@ -10,6 +10,7 @@
 import { resolve } from 'node:path';
 import { printBanner, ask, choose, log, info, warn, step, dim, c } from './prompts.ts';
 import { scaffold, install, type Template, type Database } from './scaffold.ts';
+import { parseArgs, resolveOptions, helpText, TEMPLATES, DATABASES } from './args.ts';
 import { newerScaffolderVersion } from './staleness.ts';
 
 /** This scaffolder's own version, read from the manifest that ships beside it. */
@@ -18,6 +19,28 @@ const ZT_SELF_VERSION: string = (
 ).version;
 
 async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    process.stdout.write(helpText() + '\n');
+    return;
+  }
+  if (args.version) {
+    process.stdout.write(ZT_SELF_VERSION + '\n');
+    return;
+  }
+
+  // Whether there is anybody to answer a question. Without this the prompts'
+  // readline waits on a line that never comes, so a scaffolder run in CI or by
+  // an agent did not fail — it hung until something killed it.
+  const interactive = Boolean(process.stdin.isTTY);
+  const plan = resolveOptions(args, interactive);
+  if (!plan.ok) {
+    process.stderr.write(`\x1b[31mError: ${plan.error}\x1b[0m\n\n${helpText()}\n`);
+    process.exit(1);
+  }
+  const asking = new Set(plan.askFor ?? []);
+
   // Started before the banner and awaited after the prompts, so the check costs
   // no perceived time at all — the answer arrives while a human is reading.
   const newerScaffolder = newerScaffolderVersion(ZT_SELF_VERSION);
@@ -25,9 +48,9 @@ async function main(): Promise<void> {
   printBanner();
 
   // ── Project name ────────────────────────────────────────────────────────────
-  const nameArg = process.argv[2]?.trim() ?? '';
-  const name    = nameArg
-    || await ask('Project name', 'my-zerotal-app');
+  const name = asking.has('name')
+    ? await ask('Project name', 'my-zerotal-app')
+    : plan.name!;
 
   const target = resolve(process.cwd(), name);
 
@@ -40,7 +63,9 @@ async function main(): Promise<void> {
 
   // ── Template ────────────────────────────────────────────────────────────────
   log('');
-  const template = await choose<Template>('Template', [
+  const template: Template = !asking.has('template')
+    ? plan.template!
+    : await choose<Template>('Template', [
     {
       value:       'api',
       label:       'API',
@@ -75,8 +100,8 @@ async function main(): Promise<void> {
 
   // ── Database ─────────────────────────────────────────────────────────────────
   // Only the API template ships a database config; minimal/flow have no DB.
-  let db: Database = 'sqlite';
-  if (template === 'api') {
+  let db: Database = plan.db ?? 'sqlite';
+  if (template === 'api' && asking.has('db')) {
     log('');
     db = await choose<Database>('Database', [
       {
@@ -118,13 +143,19 @@ async function main(): Promise<void> {
   info(`Project files created`);
 
   // ── Install ─────────────────────────────────────────────────────────────────
-  log('');
-  step('Installing dependencies…');
-  const ok = await install(target);
-  if (ok) {
-    info(`Dependencies installed`);
-  } else {
-    warn(`bun install failed — run it manually inside the project`);
+  if (plan.install !== false) {
+    log('');
+    step('Installing dependencies…');
+    const ok = await install(target);
+    if (ok) {
+      info(`Dependencies installed`);
+    } else {
+      warn(`bun install failed — run it manually inside the project`);
+      // A failed install is a broken project, and a script that carried on
+      // regardless would report success for one. A human has the message above
+      // and the directory in front of them; CI needs the exit code.
+      if (!interactive) process.exit(1);
+    }
   }
 
   // ── Done ─────────────────────────────────────────────────────────────────────

package/src/scaffold.ts

@@ -13,7 +13,7 @@ export type Template = 'minimal' | 'api' | 'admin' | 'flow' | 'react' | 'vue';
 // "^1.1.0" found for specifier "zerotal"` — the first thing anyone trying the
 // framework saw. `scaffold.test.ts` now asserts the two agree, so CI fails rather
 // than the user's install.
-export const ZT_VERSION = "^1.6.3";
+export const ZT_VERSION = "^1.7.2";
 
 export interface ScaffoldOptions {
   name:     string;