create-avocado-site 0.11.6 → 0.11.8

package/dist/index.js

@@ -4,19 +4,39 @@ import { spawn } from "node:child_process";
 import { mkdir, readdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { runPrompts, demoConfig } from "./prompts.js";
+import { runPrompts, demoConfig, promptForApiKey, AVOCADO_INTRO } from "./prompts.js";
 import { collectFiles, collectDemoFiles, generateFiles } from "./generator.js";
 import { printInstructions } from "./instructions.js";
 async function main() {
     const cwd = process.cwd();
     /*
      * `npm create avocado-site my-demo` — a directory argument means the demo,
-     * with no questions. Somebody who has typed a name has already answered the
-     * only one that mattered, and the fastest path to seeing the product should
-     * not be gated behind three selects.
+     * with no *configuration* questions. Somebody who has typed a name has
+     * already answered the only one that mattered, and the fastest path to
+     * seeing the product should not be gated behind three selects.
+     *
+     * One question survives that rule, and it earns its place: the API key.
+     *
+     * Not to gate anything — everything except chat works without one, and that
+     * is deliberate and worth protecting, so Enter skips it. It is here because
+     * **keys are read at startup**. A key given now is live the first time the
+     * dev server runs; a key added afterwards needs a file edit *and* a restart,
+     * 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.
      */
     const target = process.argv.slice(2).find((arg) => !arg.startsWith("-"));
-    const config = target ? await demoConfig(target) : await runPrompts(cwd);
+    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());
+    }
+    else {
+        config = await runPrompts(cwd);
+    }
     if (!config)
         return;
     if (config.mode === "demo") {
@@ -78,10 +98,9 @@ async function bootstrapDemo(cwd, dirName, config) {
         p.log.warn(`Run \`npm install\` in ${dirName} yourself — everything else is in place.`);
     }
     p.log.message([
-        `  cd ${dirName}`,
-        `  npm run dev`,
+        `  cd ${dirName} && npm run dev`,
         ``,
-        `  Opens the editor at`,
+        `  opens the editor at`,
         ``,
         `    http://localhost:${config.editorPort}/?siteId=${config.siteId}&session=dev`,
         ``,
@@ -90,10 +109,62 @@ async function bootstrapDemo(cwd, dirName, config) {
         `  default site when the URL does not name one. \`npm run dev\` opens this`,
         `  URL for you.`,
         ``,
-        `  No API key needed to look around; add ANTHROPIC_API_KEY to .env.local`,
-        `  when you want to edit by chat.`,
+        /*
+         * Two whole sentences, not one with a dangling clause.
+         *
+         * This was a single line ending "…add ANTHROPIC_API_KEY to .env.local"
+         * followed by a hard-coded "when you want to edit by chat." — fine as one
+         * sentence, nonsense as soon as the first half could say something else.
+         * The keyed variant read "Chat is enabled — OPENAI_API_KEY is in
+         * .env.local when you want to edit by chat."
+         */
+        ...(config.apiKey
+            ? [`  Chat is enabled \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.`,
+            ]),
     ].join("\n"));
-    p.outro("Done.");
+    /*
+     * Offer to run it, rather than ending on homework.
+     *
+     * The scaffold installed 29 files and every dependency, chose two free ports,
+     * generated three secrets and wrote a key — and then handed back two commands
+     * to type. Everything it needed to know it already knew; the remaining steps
+     * were manual only because nobody had automated them.
+     *
+     * Asked, not assumed. Starting two long-running servers is not something to
+     * do to somebody's terminal without permission, and anyone scaffolding into a
+     * 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,
+    });
+    if (p.isCancel(start) || !start) {
+        p.outro(`Done. Run \`cd ${dirName} && npm run dev\` when you are ready.`);
+        return;
+    }
+    p.outro("Starting \u2014 press Ctrl+C to stop.");
+    /*
+     * `stdio: "inherit"` and no `await` on a resolved promise: this is the user's
+     * session now. The dev script prints its own banner, opens the editor, and
+     * owns Ctrl+C from here.
+     */
+    const dev = spawn("npm", ["run", "dev"], {
+        cwd: dir,
+        stdio: "inherit",
+        shell: process.platform === "win32",
+    });
+    await new Promise((resolve) => {
+        dev.on("exit", () => resolve());
+        dev.on("error", () => {
+            p.log.warn(`Could not start it. Run \`cd ${dirName} && npm run dev\` yourself.`);
+            resolve();
+        });
+    });
 }
 /** Resolves false rather than throwing — the caller decides what a failure means. */
 function run(command, args, cwd) {

package/dist/prompts.d.ts

@@ -1,8 +1,46 @@
 import type { ScaffoldConfig } from "./types.js";
+/**
+ * The product, named, with its own mark.
+ *
+ * Shared so both entry paths use it. The directory-argument path had no intro
+ * at all — it went straight from an `npx` line to a demand for a secret.
+ */
+export declare const AVOCADO_INTRO = "\uD83E\uDD51  Avocado Studio";
 /** A directory name turned into something the orchestrator will accept as a site id. */
 export declare function toSiteId(name: string): string;
+/**
+ * Which provider a pasted key belongs to, by prefix.
+ *
+ * Exported so `api-key-prompt.test.ts` can check the classification without a
+ * terminal. Unknown shapes are not rejected — a key format can change, and
+ * refusing a real key because this list is out of date is worse than writing it
+ * under the most likely variable and letting the server report the truth.
+ */
+export declare function variableForKey(raw: string): string | null;
+/**
+ * Offer to take an API key now. One keypress to skip.
+ *
+ * The product deliberately works without one — the preview, click-to-select,
+ * the property panel, publishing and every metadata guarantee need no model,
+ * and "no API key needed to look around" is a real differentiator worth
+ * protecting. So this must never become a gate: Enter continues, and the copy
+ * says so before it says anything else.
+ *
+ * What it buys is the restart. Keys are read at startup, so a key set *here* is
+ * live the first time the dev server runs, while a key added afterwards needs
+ * a file edit and a restart — and nothing in the product confirms either
+ * happened. "I added the key and nothing changed" has no error message
+ * anywhere, and this is the cheapest way to stop most people reaching it.
+ */
+export declare function promptForApiKey(): Promise<{
+    variable: string;
+    value: string;
+} | undefined>;
 /** Everything a demo scaffold needs, with no questions asked. */
-export declare function demoConfig(dirName: string): Promise<ScaffoldConfig>;
+export declare function demoConfig(dirName: string, apiKey?: {
+    variable: string;
+    value: string;
+}): Promise<ScaffoldConfig>;
 /**
  * The mode question, asked first.
  *

package/dist/prompts.js

@@ -3,13 +3,115 @@ import { randomBytes } from "node:crypto";
 import { basename } from "node:path";
 import { detectNextMajor } from "./next-version.js";
 import { findFreePort } from "./ports.js";
+/**
+ * The product, named, with its own mark.
+ *
+ * Shared so both entry paths use it. The directory-argument path had no intro
+ * at all — it went straight from an `npx` line to a demand for a secret.
+ */
+export const AVOCADO_INTRO = "\u{1F951}  Avocado Studio";
 /** A directory name turned into something the orchestrator will accept as a site id. */
 export function toSiteId(name) {
     const cleaned = name.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
     return cleaned.length > 0 ? cleaned : "avocado-demo";
 }
+/**
+ * Which provider a pasted key belongs to, by prefix.
+ *
+ * Exported so `api-key-prompt.test.ts` can check the classification without a
+ * terminal. Unknown shapes are not rejected — a key format can change, and
+ * refusing a real key because this list is out of date is worse than writing it
+ * under the most likely variable and letting the server report the truth.
+ */
+export function variableForKey(raw) {
+    const key = raw.trim();
+    if (!key)
+        return null;
+    if (key.startsWith("sk-ant-"))
+        return "ANTHROPIC_API_KEY";
+    if (key.startsWith("sk-"))
+        return "OPENAI_API_KEY";
+    if (key.startsWith("AIza"))
+        return "GOOGLE_GENAI_API_KEY";
+    return "ANTHROPIC_API_KEY";
+}
+/**
+ * Offer to take an API key now. One keypress to skip.
+ *
+ * The product deliberately works without one — the preview, click-to-select,
+ * the property panel, publishing and every metadata guarantee need no model,
+ * and "no API key needed to look around" is a real differentiator worth
+ * protecting. So this must never become a gate: Enter continues, and the copy
+ * says so before it says anything else.
+ *
+ * What it buys is the restart. Keys are read at startup, so a key set *here* is
+ * live the first time the dev server runs, while a key added afterwards needs
+ * a file edit and a restart — and nothing in the product confirms either
+ * happened. "I added the key and nothing changed" has no error message
+ * anywhere, and this is the cheapest way to stop most people reaching it.
+ */
+export async function promptForApiKey() {
+    /*
+     * Say what this is before asking for a secret.
+     *
+     * On the `npm create avocado-site my-site` path this was the **first thing a
+     * stranger ever saw** — no product name, no explanation, just "Paste an API
+     * key" on an otherwise empty terminal. Asking for a credential is the one
+     * moment where an unexplained prompt is not merely unfriendly; it is the
+     * shape of something a careful person refuses.
+     *
+     * It also never said *which* key. Three providers are accepted and the
+     * 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" +
+        "Accepted:  ANTHROPIC_API_KEY   \u00b7  OPENAI_API_KEY   \u00b7  GOOGLE_GENAI_API_KEY\n" +
+        "The right variable is picked from the key itself.", "Optional \u2014 enable chat now");
+    const key = await p.password({
+        message: "Paste a key, or press Enter to skip",
+        mask: "\u2022",
+        validate: () => undefined,
+    });
+    if (p.isCancel(key))
+        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");
+        return undefined;
+    }
+    const variable = variableForKey(value);
+    if (!variable)
+        return undefined;
+    /*
+     * Say *why* this variable, and how to change it.
+     *
+     * The confirmation used to state a conclusion and nothing else. A tester who
+     * meant to paste an Anthropic key and grabbed an OpenAI one from the line
+     * above it in the same file read "Writing OPENAI_API_KEY" and had no idea
+     * whether the product had misread the key or they had copied the wrong line —
+     * and no route back either way. Naming the evidence (the prefix) settles
+     * which of the two happened in one glance.
+     */
+    const hint = value.startsWith("sk-ant-")
+        ? "sk-ant-"
+        : value.startsWith("sk-")
+            ? "sk-"
+            : value.startsWith("AIza")
+                ? "AIza"
+                : null;
+    p.note(`${variable} \u2192 .env.local\n` +
+        (hint
+            ? `Chosen because the key starts with "${hint}".\n`
+            : "The key matched no known prefix, so this is a best guess.\n") +
+        "Wrong one? Edit .env.local and restart \u2014 nothing else needs to change.\n\n" +
+        "Live on first start. No restart needed now.", "Key saved");
+    return { variable, value };
+}
 /** Everything a demo scaffold needs, with no questions asked. */
-export async function demoConfig(dirName) {
+export async function demoConfig(dirName, apiKey) {
     const sitePort = await findFreePort(3000);
     const editorPort = await findFreePort(4100);
     return {
@@ -21,6 +123,7 @@ export async function demoConfig(dirName) {
         editorPort,
         draftSecret: randomBytes(24).toString("hex"),
         publishToken: randomBytes(24).toString("hex"),
+        apiKey,
     };
 }
 /**
@@ -31,7 +134,7 @@ export async function demoConfig(dirName) {
  * seen what the product does.
  */
 export async function runPrompts(cwd) {
-    p.intro("Avocado Studio");
+    p.intro(AVOCADO_INTRO);
     const mode = await p.select({
         message: "What would you like to do?",
         options: [
@@ -101,6 +204,7 @@ async function integratePrompts(cwd) {
         p.cancel("Cancelled.");
         return null;
     }
+    const apiKey = await promptForApiKey();
     return {
         mode: "integrate",
         cms: cms,
@@ -117,5 +221,6 @@ async function integratePrompts(cwd) {
         // that already looks filled in is a step nobody performs.
         draftSecret: randomBytes(24).toString("hex"),
         publishToken: randomBytes(24).toString("hex"),
+        apiKey,
     };
 }

package/dist/templates/demo-app.js

@@ -155,7 +155,9 @@ function envLocal(config) {
 #                         installs it for you and a Gemini plan fails on the
 #                         first call without it.
 #
-# ANTHROPIC_API_KEY=
+${config.apiKey
+        ? `${config.apiKey.variable}=${config.apiKey.value}`
+        : "# ANTHROPIC_API_KEY="}
 
 # The orchestrator runs inside this app, at /api/avocado. There is no third
 # service to start and nothing to deploy separately.
@@ -270,6 +272,7 @@ function devScript(config) {
  * at /api/avocado. Two processes, one terminal, no third service.
  */
 import { spawn } from "node:child_process"
+import { readFileSync } from "node:fs"
 import { createConnection } from "node:net"
 
 const SITE_PORT = process.env.PORT ?? "${config.sitePort}"
@@ -295,8 +298,34 @@ const OPEN_URL = \`\${EDITOR_URL}/?siteId=\${SITE_ID}&session=dev\`
 
 const children = []
 
+/*
+ * Read DRAFT_MODE_SECRET out of .env.local and hand it to the children.
+ *
+ * Next loads .env.local by itself; an npm script does not, so the editor CLI
+ * would otherwise never see it. Without it the editor cannot select or edit
+ * anything once the site is built for production — the SDK requires \`secret=\`
+ * on the preview URL there, and with none it renders an ordinary public page
+ * with no block markers at all.
+ */
+function envFromLocalFile() {
+  try {
+    const text = readFileSync(new URL("../.env.local", import.meta.url), "utf8")
+    const match = text.match(/^\\s*DRAFT_MODE_SECRET\\s*=\\s*(.+)\\s*$/m)
+    const value = match?.[1]?.trim().replace(/^["']|["']$/g, "")
+    return value ? { DRAFT_MODE_SECRET: value } : {}
+  } catch {
+    return {}
+  }
+}
+
+const EXTRA_ENV = envFromLocalFile()
+
 function run(command, args) {
-  const child = spawn(command, args, { stdio: "inherit", shell: process.platform === "win32" })
+  const child = spawn(command, args, {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+    env: { ...process.env, ...EXTRA_ENV }
+  })
   children.push(child)
   child.on("exit", (code) => {
     // If either half dies the other is useless, so take both down rather than

package/dist/types.d.ts

@@ -40,6 +40,20 @@ export type ScaffoldConfig = {
      * `POST /api/editor/publish` took content from anyone who asked.
      */
     publishToken: string;
+    /**
+     * An API key pasted during setup, written straight into `.env.local`.
+     *
+     * Offered once, skippable in one keypress. The point is not to gate the
+     * product — everything except chat works without a key, and that is a real
+     * feature — it is that **a key set before the dev server first starts needs
+     * no restart**. Keys are read at startup, so one added afterwards requires
+     * editing a file *and* restarting, and "I added the key and nothing changed"
+     * is a failure mode with no error message anywhere.
+     */
+    apiKey?: {
+        variable: string;
+        value: string;
+    };
 };
 export type GeneratedFile = {
     path: string;

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.11.6";
+export declare const AVOCADO = "0.11.8";
 /**
  * Next 15.5.15 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.11.6";
+export const AVOCADO = "0.11.8";
 /**
  * Next 15.5.15 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.11.6",
+  "version": "0.11.8",
   "description": "Bootstrap a runnable Avocado Studio demo site, or wire Avocado into an existing Next.js project",
   "type": "module",
   "bin": {
@@ -34,8 +34,8 @@
     "@types/node": "^22.13.10",
     "tsx": "^4.19.0",
     "typescript": "^5.7.3",
-    "@avocadostudio-ai/site-sdk": "0.11.6",
-    "@avocadostudio-ai/shared": "0.11.6"
+    "@avocadostudio-ai/site-sdk": "0.11.8",
+    "@avocadostudio-ai/shared": "0.11.8"
   },
   "license": "Apache-2.0",
   "homepage": "https://docs.avocadostudio.dev",