create-avocado-site 0.11.7 → 0.11.9

package/dist/index.js

@@ -4,7 +4,7 @@ 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, promptForApiKey } 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() {
@@ -26,9 +26,17 @@ async function main() {
      * 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 promptForApiKey())
-        : 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") {
@@ -90,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`,
         ``,
@@ -102,12 +109,81 @@ async function bootstrapDemo(cwd, dirName, config) {
         `  default site when the URL does not name one. \`npm run dev\` opens this`,
         `  URL for you.`,
         ``,
-        config.apiKey
-            ? `  Chat is enabled \u2014 ${config.apiKey.variable} is in .env.local`
-            : `  No API key needed to look around; add ANTHROPIC_API_KEY to .env.local and restart`,
-        `  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."
+         */
+        /*
+         * Said at the start and again here, because the banner is what stays on
+         * screen while the servers boot and is the last thing read before the
+         * browser opens. A preview that only announces itself once, eight lines
+         * earlier, has not really announced itself.
+         */
+        `  Avocado Studio is a research preview \u2014 expect rough edges,`,
+        `  and please tell us about them.`,
+        ``,
+        /*
+         * The demo's job is to make somebody want this on their own site, and
+         * until now nothing in the terminal said where that starts. `/sites` is
+         * the decision page — three paths with the recommended one first — rather
+         * than the Next.js wiring guide, which is the right page only once the
+         * decision is made.
+         */
+        `  Want this on your own site?`,
+        `  https://docs.avocadostudio.dev/sites`,
+        ``,
+        ...(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,4 +1,11 @@
 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 \u2014 research preview";
 /** A directory name turned into something the orchestrator will accept as a site id. */
 export declare function toSiteId(name: string): string;
 /**

package/dist/prompts.js

@@ -3,6 +3,13 @@ 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 \u2014 research preview";
 /** 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, "");
@@ -44,8 +51,27 @@ export function variableForKey(raw) {
  * 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" +
+        "  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");
     const key = await p.password({
-        message: "Paste an API key to enable chat, or press Enter to skip",
+        message: "Paste a key, or press Enter to skip",
         mask: "\u2022",
         validate: () => undefined,
     });
@@ -55,13 +81,35 @@ export async function promptForApiKey() {
     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.", "No key \u2014 that is fine");
+            "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;
-    p.note(`Writing ${variable} to .env.local. No restart needed.`, "Key saved");
+    /*
+     * 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. */
@@ -88,7 +136,7 @@ export async function demoConfig(dirName, apiKey) {
  * 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: [

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.7";
+export declare const AVOCADO = "0.11.9";
 /**
  * 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.7";
+export const AVOCADO = "0.11.9";
 /**
  * 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.7",
+  "version": "0.11.9",
   "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.7",
-    "@avocadostudio-ai/shared": "0.11.7"
+    "@avocadostudio-ai/shared": "0.11.9",
+    "@avocadostudio-ai/site-sdk": "0.11.9"
   },
   "license": "Apache-2.0",
   "homepage": "https://docs.avocadostudio.dev",