create-avocado-site 0.17.0 → 0.18.0

package/README.md

@@ -55,6 +55,30 @@ For an existing site of any size this is the smaller half of the job. The
 larger half — your components, your content model, your CMS — is at
 [docs.avocadostudio.dev/sites](https://docs.avocadostudio.dev/sites).
 
+## Unattended runs
+
+The demo path takes a directory name and needs no terminal, so it can be
+scripted, run in CI, or baked into an image:
+
+```bash
+npm create avocado-site@latest my-demo -- --yes --no-install
+```
+
+| Option | |
+|---|---|
+| `-y`, `--yes` | Never ask. Implied whenever stdin is not a terminal. |
+| `--no-install` | Write the files and stop, for callers that install their own way. |
+| `--api-key KEY` | Write `KEY` to `.env.local`; the variable is chosen from its prefix. Also read from `AVOCADO_SETUP_API_KEY`. |
+| `-h`, `--help` | Print the usage. |
+
+A key is written only when you name it. A provider variable that happens to be
+exported in your shell is left alone — it is usually your own credential, and a
+scaffold is about to become a git repository.
+
+Unattended runs never start the dev server; they print the command instead. A
+run with no terminal and no directory name exits 1 and says why, because the
+guided path has questions that nothing can answer for you.
+
 ## Requirements
 
 - Node.js 22+

package/dist/args.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What the command was asked to do, decided before anything can block.
+ *
+ * This file exists because the scaffolder could not be run by anything that is
+ * not a person at a keyboard. The demo path asks for an API key and then, at
+ * the end, whether to start the dev server — both unconditional, both
+ * `@clack/prompts`. With stdin closed the first one cancels and the process
+ * exits 1 having created nothing; under a pty with a newline piped in it
+ * ignores the keystroke and waits forever. So no CI job, no Dockerfile, no
+ * agent and no gate could run `npm create avocado-site`, which is the one
+ * command every new user runs first. `scaffold-serve-check.mjs` generates from
+ * the scaffolder's *templates* rather than by running it, so nothing in the
+ * repo noticed.
+ *
+ * Parsing is separated from `main()` for the reason the prompts had to be: a
+ * pure function over `argv` and `env` can be tested without a terminal.
+ */
+export type ParsedArgs = {
+    /** The directory to create. Its absence is what selects the guided path. */
+    target?: string;
+    /** No question may block: `--yes`, or stdin is not a terminal. */
+    nonInteractive: boolean;
+    /** `--no-install` writes the files and stops, for gates and images. */
+    install: boolean;
+    /** Only ever from an explicit flag or `AVOCADO_SETUP_API_KEY` — see below. */
+    apiKey?: {
+        variable: string;
+        value: string;
+    };
+    help: boolean;
+    unknown: string[];
+};
+export declare const USAGE = "Usage\n  npm create avocado-site [directory] [options]\n\n  With a directory name, bootstraps the demo into it. With none, asks what to\n  build \u2014 which needs a terminal.\n\nOptions\n  -y, --yes          Never ask. Implied when stdin is not a terminal.\n      --no-install   Write the files, skip `npm install`.\n      --api-key KEY  Write KEY to .env.local. The variable is chosen from the\n                     key's prefix. Also read from AVOCADO_SETUP_API_KEY.\n  -h, --help         Show this.\n\nNon-interactive runs never start the dev server; the command to start it is\nprinted instead.";
+export declare function parseArgs(argv: string[], env?: Record<string, string | undefined>, isTty?: boolean): ParsedArgs;
+/**
+ * Why a run with no terminal and no directory name cannot continue.
+ *
+ * The guided path is four questions; there is no answer to guess at. What this
+ * must not do is what it used to: exit 1 with an empty directory listing and
+ * nothing on stderr, which reads as a crash rather than as a choice.
+ */
+export declare const NEEDS_A_NAME = "create-avocado-site: no terminal, and no directory name.\n\nThe guided setup asks what to build, which needs a terminal. To run unattended,\nname the directory to create:\n\n  npm create avocado-site my-site -- --yes\n\nUsage\n  npm create avocado-site [directory] [options]\n\n  With a directory name, bootstraps the demo into it. With none, asks what to\n  build \u2014 which needs a terminal.\n\nOptions\n  -y, --yes          Never ask. Implied when stdin is not a terminal.\n      --no-install   Write the files, skip `npm install`.\n      --api-key KEY  Write KEY to .env.local. The variable is chosen from the\n                     key's prefix. Also read from AVOCADO_SETUP_API_KEY.\n  -h, --help         Show this.\n\nNon-interactive runs never start the dev server; the command to start it is\nprinted instead.";

package/dist/args.js

@@ -0,0 +1,97 @@
+import { variableForKey } from "./prompts.js";
+export const USAGE = `Usage
+  npm create avocado-site [directory] [options]
+
+  With a directory name, bootstraps the demo into it. With none, asks what to
+  build — which needs a terminal.
+
+Options
+  -y, --yes          Never ask. Implied when stdin is not a terminal.
+      --no-install   Write the files, skip \`npm install\`.
+      --api-key KEY  Write KEY to .env.local. The variable is chosen from the
+                     key's prefix. Also read from AVOCADO_SETUP_API_KEY.
+  -h, --help         Show this.
+
+Non-interactive runs never start the dev server; the command to start it is
+printed instead.`;
+/**
+ * The key is taken only when it is named, never inherited from the shell.
+ *
+ * `--api-key` and `AVOCADO_SETUP_API_KEY` both say "put this in the project I
+ * am creating". A bare `ANTHROPIC_API_KEY` in the environment says nothing of
+ * the sort — it is usually the developer's own key, exported in a shell
+ * profile, and harvesting it would write a live credential into a new
+ * `.env.local` in a directory that is about to become a git repository. The
+ * interactive path has always required the key to be typed at it; the
+ * unattended path requires it to be named. Neither reads what happens to be
+ * lying around.
+ */
+const API_KEY_ENV_VAR = "AVOCADO_SETUP_API_KEY";
+export function parseArgs(argv, env = process.env, isTty = Boolean(process.stdin.isTTY)) {
+    let target;
+    let yes = false;
+    let install = true;
+    let help = false;
+    let rawKey;
+    const unknown = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        /*
+         * `--api-key sk-ant-…` takes the next token, which is why the old
+         * one-liner could not survive a flag that takes a value: it picked the
+         * target with `find(arg => !arg.startsWith("-"))`, so the key itself would
+         * have become the directory name — and the scaffold would have been
+         * created in a directory named after a secret.
+         */
+        if (arg === "--api-key") {
+            rawKey = argv[++i];
+            continue;
+        }
+        if (arg.startsWith("--api-key=")) {
+            rawKey = arg.slice("--api-key=".length);
+            continue;
+        }
+        if (arg === "-y" || arg === "--yes") {
+            yes = true;
+            continue;
+        }
+        if (arg === "--no-install") {
+            install = false;
+            continue;
+        }
+        if (arg === "-h" || arg === "--help") {
+            help = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            unknown.push(arg);
+            continue;
+        }
+        target ??= arg;
+    }
+    const value = (rawKey ?? env[API_KEY_ENV_VAR] ?? "").trim();
+    const variable = value ? variableForKey(value) : null;
+    return {
+        target,
+        nonInteractive: yes || !isTty,
+        install,
+        apiKey: variable && value ? { variable, value } : undefined,
+        help,
+        unknown,
+    };
+}
+/**
+ * Why a run with no terminal and no directory name cannot continue.
+ *
+ * The guided path is four questions; there is no answer to guess at. What this
+ * must not do is what it used to: exit 1 with an empty directory listing and
+ * nothing on stderr, which reads as a crash rather than as a choice.
+ */
+export const NEEDS_A_NAME = `create-avocado-site: no terminal, and no directory name.
+
+The guided setup asks what to build, which needs a terminal. To run unattended,
+name the directory to create:
+
+  npm create avocado-site my-site -- --yes
+
+${USAGE}`;

package/dist/index.js

@@ -7,8 +7,33 @@ import { resolve } from "node:path";
 import { runPrompts, demoConfig, promptForApiKey, AVOCADO_INTRO } from "./prompts.js";
 import { collectFiles, collectDemoFiles, generateFiles } from "./generator.js";
 import { printInstructions } from "./instructions.js";
+import { parseArgs, USAGE, NEEDS_A_NAME } from "./args.js";
 async function main() {
     const cwd = process.cwd();
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        console.log(USAGE);
+        return;
+    }
+    if (args.unknown.length > 0) {
+        console.error(`create-avocado-site: unknown option ${args.unknown.join(", ")}\n\n${USAGE}`);
+        process.exitCode = 1;
+        return;
+    }
+    /*
+     * Say so, rather than cancelling into an empty directory listing.
+     *
+     * Without a terminal the guided path's first prompt returns a cancel
+     * symbol, `main` returns, and the process exits 1 with nothing written and
+     * nothing printed. Every unattended caller that ever tried this — a CI job,
+     * an image build, an agent — saw a bare exit code and no way to tell a crash
+     * from a refusal.
+     */
+    if (args.nonInteractive && !args.target) {
+        console.error(NEEDS_A_NAME);
+        process.exitCode = 1;
+        return;
+    }
     /*
      * `npm create avocado-site my-demo` — a directory argument means the demo,
      * with no *configuration* questions. Somebody who has typed a name has
@@ -24,15 +49,21 @@ async function main() {
      * and nothing in the product confirms either happened. "I added the key and
      * nothing changed" has no error message anywhere in the system, and this
      * prompt is the cheapest way to stop most people arriving there.
+     *
+     * Unattended, that reasoning inverts: there is nobody to ask, and a question
+     * nobody can answer is not a prompt, it is a hang. `--api-key` says the same
+     * thing in advance, and skipping stays free — a scaffold with no key is a
+     * complete, working project.
      */
-    const target = process.argv.slice(2).find((arg) => !arg.startsWith("-"));
+    const target = args.target;
     let config;
     if (target) {
         // `runPrompts` opens with this; the fast path had no intro at all, so a
         // stranger's first interaction with the product was an unexplained request
         // for a credential on an otherwise blank terminal.
         p.intro(AVOCADO_INTRO);
-        config = await demoConfig(target, await promptForApiKey());
+        const apiKey = args.apiKey ?? (args.nonInteractive ? undefined : await promptForApiKey());
+        config = await demoConfig(target, apiKey);
     }
     else {
         config = await runPrompts(cwd);
@@ -40,7 +71,7 @@ async function main() {
     if (!config)
         return;
     if (config.mode === "demo") {
-        await bootstrapDemo(cwd, target ?? config.siteId, config);
+        await bootstrapDemo(cwd, target ?? config.siteId, config, args);
         return;
     }
     await scaffoldInto(cwd, collectFiles(config), config);
@@ -69,7 +100,7 @@ async function scaffoldInto(dir, files, config) {
  * ended, and every printed step is a place for somebody evaluating the product
  * to put it down.
  */
-async function bootstrapDemo(cwd, dirName, config) {
+async function bootstrapDemo(cwd, dirName, config, options) {
     const dir = resolve(cwd, dirName);
     if (existsSync(dir) && (await readdir(dir)).length > 0) {
         p.log.error(`${dirName} already exists and is not empty.`);
@@ -81,21 +112,32 @@ async function bootstrapDemo(cwd, dirName, config) {
     const files = collectDemoFiles(config);
     await generateFiles(dir, files);
     p.log.success(`Created ${dirName} — ${files.length} files`);
-    const spinner = p.spinner();
-    spinner.start("Installing dependencies");
-    const installed = await run("npm", ["install", "--no-audit", "--no-fund"], dir);
-    if (installed) {
-        spinner.stop("Installed dependencies");
+    /*
+     * `--no-install` is for the callers that install differently or not at all —
+     * a gate that overlays tarballs packed from a working tree, an image build
+     * with its own cache, a test that only cares that the files are correct.
+     * Without it, proving the command runs costs a full `npm install`.
+     */
+    if (options.install) {
+        const spinner = p.spinner();
+        spinner.start("Installing dependencies");
+        const installed = await run("npm", ["install", "--no-audit", "--no-fund"], dir);
+        if (installed) {
+            spinner.stop("Installed dependencies");
+        }
+        else {
+            /*
+             * Not fatal, and worth being explicit about rather than exiting. A failed
+             * install is usually a registry or proxy problem on the user's side, and
+             * the project on disk is complete and correct — `npm install` in it will
+             * work once that is fixed. Deleting it would throw away the good half.
+             */
+            spinner.stop("Could not install dependencies");
+            p.log.warn(`Run \`npm install\` in ${dirName} yourself — everything else is in place.`);
+        }
     }
     else {
-        /*
-         * Not fatal, and worth being explicit about rather than exiting. A failed
-         * install is usually a registry or proxy problem on the user's side, and
-         * the project on disk is complete and correct — `npm install` in it will
-         * work once that is fixed. Deleting it would throw away the good half.
-         */
-        spinner.stop("Could not install dependencies");
-        p.log.warn(`Run \`npm install\` in ${dirName} yourself — everything else is in place.`);
+        p.log.warn(`Skipped \`npm install\` — run it in ${dirName} before starting.`);
     }
     p.log.message([
         `  cd ${dirName} && npm run dev`,
@@ -159,10 +201,19 @@ async function bootstrapDemo(cwd, dirName, config) {
      * script or a container wants the files and nothing else. The default is yes
      * because the overwhelmingly common case is a person who wants to see it.
      */
-    const start = await p.confirm({
-        message: `Start it now?  (runs \`npm run dev\` in ${dirName})`,
-        initialValue: true,
-    });
+    /*
+     * The second thing that could not be answered without a keyboard, and the
+     * more dangerous of the two: a `confirm` whose default is *yes* would, if it
+     * ever stopped blocking, spawn two long-running dev servers inside a CI job
+     * or an image build. Unattended, the answer is always no — the caller asked
+     * for a project, not for a process it has no way to stop.
+     */
+    const start = options.nonInteractive
+        ? false
+        : await p.confirm({
+            message: `Start it now?  (runs \`npm run dev\` in ${dirName})`,
+            initialValue: true,
+        });
     if (p.isCancel(start) || !start) {
         p.outro(`Done. Run \`cd ${dirName} && npm run dev\` when you are ready.`);
         return;

package/dist/versions.d.ts

@@ -17,7 +17,7 @@
  * `@avocadostudio-ai/orchestrator-core`, already pinned there; naming it again
  * here is how a project ends up with two.
  */
-export declare const AVOCADO = "0.17.0";
+export declare const AVOCADO = "0.18.0";
 /**
  * Next 15.5.25 rather than 16, because that is the version every example app
  * and the demo site in this repository build and test against. The SDK

package/dist/versions.js

@@ -17,7 +17,7 @@
  * `@avocadostudio-ai/orchestrator-core`, already pinned there; naming it again
  * here is how a project ends up with two.
  */
-export const AVOCADO = "0.17.0";
+export const AVOCADO = "0.18.0";
 /**
  * Next 15.5.25 rather than 16, because that is the version every example app
  * and the demo site in this repository build and test against. The SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-avocado-site",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Bootstrap a runnable Avocado Studio demo site, or wire Avocado into an existing Next.js project",
   "type": "module",
   "bin": {
@@ -29,14 +29,14 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.9.1",
-    "@avocadostudio-ai/skills": "^0.17.0"
+    "@avocadostudio-ai/skills": "^0.18.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
     "tsx": "^4.19.0",
     "typescript": "^5.7.3",
-    "@avocadostudio-ai/shared": "0.17.0",
-    "@avocadostudio-ai/site-sdk": "0.17.0"
+    "@avocadostudio-ai/site-sdk": "0.18.0",
+    "@avocadostudio-ai/shared": "0.18.0"
   },
   "license": "Apache-2.0",
   "homepage": "https://docs.avocadostudio.dev",