create-avocado-site 0.16.0 → 0.17.1

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/assets/logos/avocado-hub.svg

@@ -1,7 +1,10 @@
 <svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
   <title id="title">The Avocado Hub logo</title>
-  <desc id="desc">Stylized avocado mark — dark green shell, light green flesh, brown pit.</desc>
-  <path d="M64 8C88 8 112 40 112 72C112 104 88 120 64 120C40 120 16 104 16 72C16 40 40 8 64 8Z" fill="#1F7A3A"/>
-  <path d="M64 18C82 18 100 44 100 72C100 100 82 110 64 110C46 110 28 100 28 72C28 44 46 18 64 18Z" fill="#7ED957"/>
-  <circle cx="64" cy="72" r="20" fill="#8B5E3C"/>
+  <desc id="desc">Stylized avocado mark — brand green shell, warm cream flesh, muted brown stone.</desc>
+  <!-- One green, and it is the brand's. The mark previously used #1F7A3A over
+       #7ED957: two greens, neither of them the #0f766e on every button, and the
+       lime saturated well past anything else on the page. -->
+  <path d="M64 8C88 8 112 40 112 72C112 104 88 120 64 120C40 120 16 104 16 72C16 40 40 8 64 8Z" fill="#0f766e"/>
+  <path d="M64 18C82 18 100 44 100 72C100 100 82 110 64 110C46 110 28 100 28 72C28 44 46 18 64 18Z" fill="#e9e4d4"/>
+  <circle cx="64" cy="72" r="20" fill="#8a6a4f"/>
 </svg>

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`,
@@ -138,11 +180,12 @@ async function bootstrapDemo(cwd, dirName, config) {
         `  https://docs.avocadostudio.dev/sites`,
         ``,
         ...(config.apiKey
-            ? [`  Chat is enabled \u2014 ${config.apiKey.variable} is in .env.local.`]
+            ? [`  AI editing is on \u2014 ${config.apiKey.variable} is in .env.local.`]
             : [
-                `  No API key needed to look around. Add ANTHROPIC_API_KEY,`,
-                `  OPENAI_API_KEY or GOOGLE_GENAI_API_KEY to .env.local and restart`,
-                `  when you want to edit by chat.`,
+                `  Visual editing works now: click a block, edit its fields, publish.`,
+                `  For AI editing \u2014 describing a change and having it planned for you \u2014`,
+                `  add ANTHROPIC_API_KEY, OPENAI_API_KEY or GOOGLE_GENAI_API_KEY to`,
+                `  .env.local and restart.`,
             ]),
     ].join("\n"));
     /*
@@ -158,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/prompts.js

@@ -64,12 +64,30 @@ export async function promptForApiKey() {
      * variable is chosen from the prefix, so a reader had no way to know whether
      * their key was one of the right ones.
      */
-    p.note("Chat needs a model. Everything else works without one \u2014 the preview,\n" +
-        "click-to-select, the property panel and publishing.\n\n" +
+    /*
+     * Name the product's own headline feature as the headline feature.
+     *
+     * This heading read "Optional \u2014 enable chat now", which is two mistakes in
+     * five words. "Chat" names the input box rather than what it does, and
+     * "optional" is the first word a newcomer reads about the one capability
+     * the whole product exists for \u2014 describing a change in a sentence and
+     * having it planned, applied and previewed for you. Skipping has to stay
+     * available and free of friction; it does not have to be the frame.
+     *
+     * So the heading says what this is, the first paragraph says what it does
+     * with an example, and *then* it says you can skip \u2014 in that order,
+     * because a reader who skips should know what they are skipping.
+     */
+    p.note("Describe a change and Avocado plans it, applies it and shows you the\n" +
+        "result in the live preview \u2014 \"make the hero headline shorter\",\n" +
+        "\"add a testimonials section\", \"translate this page to German\".\n" +
+        "That is the product, and it needs a model.\n\n" +
+        "You can skip and add one later. Visual editing works without a key:\n" +
+        "the preview, click-to-select, the property panel and publishing.\n\n" +
         "  ANTHROPIC_API_KEY      \u2190 recommended, the best-tested planner\n" +
         "  OPENAI_API_KEY         also does image generation\n" +
         "  GOOGLE_GENAI_API_KEY   also does image generation\n\n" +
-        "The right variable is picked from the key itself.", "Optional \u2014 enable chat now");
+        "The right variable is picked from the key itself.", "AI editing \u2014 the main event");
     const key = await p.password({
         message: "Paste a key, or press Enter to skip",
         mask: "\u2022",
@@ -79,9 +97,11 @@ export async function promptForApiKey() {
         return undefined;
     const value = typeof key === "string" ? key.trim() : "";
     if (!value) {
-        p.note("Chat will use the built-in demo planner, which handles simple, literal edits.\n" +
-            "Everything else works: the preview, click-to-select, the property panel and publishing.\n" +
-            "You can add a key to .env.local later and restart the dev server.", "No key \u2014 that is fine");
+        p.note("Visual editing works in full: the preview, click-to-select, the property\n" +
+            "panel and publishing. AI editing falls back to a built-in demo planner,\n" +
+            "which handles simple, literal edits and cannot write copy or reason\n" +
+            "about a page.\n\n" +
+            "Add a key to .env.local and restart the dev server to turn on the real thing.", "No key \u2014 that is fine");
         return undefined;
     }
     const variable = variableForKey(value);