create-avocado-site 0.9.0

package/dist/index.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import * as p from "@clack/prompts";
+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 { 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.
+     */
+    const target = process.argv.slice(2).find((arg) => !arg.startsWith("-"));
+    const config = target ? await demoConfig(target) : await runPrompts(cwd);
+    if (!config)
+        return;
+    if (config.mode === "demo") {
+        await bootstrapDemo(cwd, target ?? config.siteId, config);
+        return;
+    }
+    await scaffoldInto(cwd, collectFiles(config), config);
+}
+/** The integrate path: write wiring into an app that already exists, then say what is left. */
+async function scaffoldInto(dir, files, config) {
+    const fileList = files.map((f) => `  ${f.path}`).join("\n");
+    const confirm = await p.confirm({ message: `Generate ${files.length} files?\n${fileList}` });
+    if (p.isCancel(confirm) || !confirm) {
+        p.cancel("Cancelled.");
+        return;
+    }
+    const { written, skipped } = await generateFiles(dir, files);
+    if (skipped.length > 0) {
+        p.log.warn(`Skipped (already exist):\n${skipped.map((f) => `  ${f}`).join("\n")}`);
+    }
+    p.log.success(`Generated ${written.length} files`);
+    p.log.message(printInstructions(config));
+    p.outro("Done!");
+}
+/**
+ * The demo path: a directory, a project in it, and its dependencies installed.
+ *
+ * Installing is the part that makes this a bootstrap rather than a scaffold.
+ * Printing `npm install` as step three of five is how the previous version
+ * ended, and every printed step is a place for somebody evaluating the product
+ * to put it down.
+ */
+async function bootstrapDemo(cwd, dirName, config) {
+    const dir = resolve(cwd, dirName);
+    if (existsSync(dir) && (await readdir(dir)).length > 0) {
+        p.log.error(`${dirName} already exists and is not empty.`);
+        p.outro("Pick a name that is not taken.");
+        process.exitCode = 1;
+        return;
+    }
+    await mkdir(dir, { recursive: true });
+    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");
+    }
+    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.message([
+        `  cd ${dirName}`,
+        `  npm run dev`,
+        ``,
+        `  Opens the editor at`,
+        ``,
+        `    http://localhost:${config.editorPort}/?siteId=${config.siteId}&session=dev`,
+        ``,
+        `  with the site on http://localhost:${config.sitePort}. The ?siteId= is`,
+        `  load-bearing: the editor bundle is prebuilt and falls back to its own`,
+        `  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.`,
+    ].join("\n"));
+    p.outro("Done.");
+}
+/** Resolves false rather than throwing — the caller decides what a failure means. */
+function run(command, args, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { cwd, stdio: "ignore", shell: process.platform === "win32" });
+        child.on("error", () => resolve(false));
+        child.on("exit", (code) => resolve(code === 0));
+    });
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/instructions.d.ts

@@ -0,0 +1,19 @@
+import type { ScaffoldConfig } from "./types.js";
+/**
+ * What is left to do after the integrate path writes its files.
+ *
+ * Shorter than it was, because most of it was wrong. Step 1 used to print a
+ * `transpilePackages` array and six `images.remotePatterns` entries to copy by
+ * hand; `withAvocado` has supplied both — plus `serverExternalPackages`, the
+ * matching server externals, and `skipTrailingSlashRedirect` — for several
+ * releases. Hand-copying four settings that a wrapper sets correctly is four
+ * chances to get one wrong, and the failures are all quiet: an unlisted image
+ * host is a render error, a missing server external is a native module that
+ * will not load, a missing `skipTrailingSlashRedirect` is a 308 on a CORS
+ * preflight that the browser declines to follow.
+ *
+ * The old step 5 read "Start the orchestrator and editor (see
+ * docs/integration/README.md)". That is the entire product, delegated to a
+ * path that does not exist.
+ */
+export declare function printInstructions(config: ScaffoldConfig): string;

package/dist/instructions.js

@@ -0,0 +1,82 @@
+import { CMS_CONFIGS } from "./cms-config.js";
+import { AVOCADO } from "./versions.js";
+/**
+ * What is left to do after the integrate path writes its files.
+ *
+ * Shorter than it was, because most of it was wrong. Step 1 used to print a
+ * `transpilePackages` array and six `images.remotePatterns` entries to copy by
+ * hand; `withAvocado` has supplied both — plus `serverExternalPackages`, the
+ * matching server externals, and `skipTrailingSlashRedirect` — for several
+ * releases. Hand-copying four settings that a wrapper sets correctly is four
+ * chances to get one wrong, and the failures are all quiet: an unlisted image
+ * host is a render error, a missing server external is a native module that
+ * will not load, a missing `skipTrailingSlashRedirect` is a 308 on a CORS
+ * preflight that the browser declines to follow.
+ *
+ * The old step 5 read "Start the orchestrator and editor (see
+ * docs/integration/README.md)". That is the entire product, delegated to a
+ * path that does not exist.
+ */
+export function printInstructions(config) {
+    const c = CMS_CONFIGS[config.cms];
+    const imageLine = c.imageHostname
+        ? `\n   images: {\n     remotePatterns: [{ protocol: "https", hostname: "${c.imageHostname}" }],\n   },`
+        : "";
+    const compiler = c.compilerConfig ? `\n${c.compilerConfig.trimEnd()}` : "";
+    return `
+Next steps:
+
+1. Install:
+
+   npm install @avocadostudio-ai/site-sdk@^${AVOCADO} @avocadostudio-ai/blocks@^${AVOCADO} \\
+     @avocadostudio-ai/shared@^${AVOCADO} @avocadostudio-ai/preview-adapter@^${AVOCADO} \\
+     @avocadostudio-ai/orchestrator-core@^${AVOCADO}${c.npmDeps}
+
+2. next.config.ts — wrap the exported config:
+
+   import { withAvocado } from "@avocadostudio-ai/site-sdk/next-config"
+
+   export default withAvocado({${compiler}${imageLine}
+   })
+
+   Do not hand-write transpilePackages or serverExternalPackages. withAvocado
+   sets those, the server externals and skipTrailingSlashRedirect together, and
+   setting one of them alone fails quietly on the native dependencies.
+
+3. app/globals.css — add as the first line:
+
+   @import "@avocadostudio-ai/blocks/styles.css";
+
+   Without it every block renders correct, complete, unstyled HTML.
+
+4. Mount the orchestrator inside this app, at app/api/avocado/[[...path]]/route.ts:
+
+   import { createOrchestrator } from "@avocadostudio-ai/site-sdk/server"
+
+   export const runtime = "nodejs"
+   export const dynamic = "force-dynamic"
+
+   const handler = createOrchestrator({ siteId: "${config.siteId}" })
+   export const GET = handler
+   export const POST = handler
+   export const OPTIONS = handler
+
+   createOrchestrator returns one callable — assign it three times rather than
+   destructuring, which yields undefined with no type error.
+
+5. Copy .env.local.example to .env.local. Set DRAFT_MODE_SECRET to any long
+   random string: without it draft mode silently does not work, and the editor
+   renders the published page while ignoring every edit.
+
+6. Add .data/ to .gitignore — the orchestrator writes SQLite state there on the
+   first request.
+
+7. Run your dev server, then the editor beside it:
+
+   npx @avocadostudio-ai/cli@^${AVOCADO} start \\
+     --orchestrator http://localhost:3000/api/avocado \\
+     --preview      http://localhost:3000
+
+Full reference: https://docs.avocadostudio.dev/integration/nextjs-integration
+`;
+}

package/dist/next-version.d.ts

@@ -0,0 +1,15 @@
+import { createRequire } from "node:module";
+/**
+ * Best-effort detection of the Next.js major version in the target project.
+ *
+ * Next.js 16 renamed the `middleware` file convention to `proxy`, so the
+ * scaffolder needs to know which one to write. Returns `undefined` when the
+ * version can't be determined — callers should fall back to the older
+ * convention, which still works (deprecated) on 16.
+ *
+ * `makeRequire` is a seam: module resolution walks up from `cwd` to the
+ * filesystem root, so under a test runner (or an `npx` cache) it can find a
+ * *different* project's Next and answer confidently with the wrong number.
+ * Tests pass a resolver that fails, to exercise the manifest path.
+ */
+export declare function detectNextMajor(cwd: string, makeRequire?: typeof createRequire): number | undefined;

package/dist/next-version.js

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+/**
+ * Best-effort detection of the Next.js major version in the target project.
+ *
+ * Next.js 16 renamed the `middleware` file convention to `proxy`, so the
+ * scaffolder needs to know which one to write. Returns `undefined` when the
+ * version can't be determined — callers should fall back to the older
+ * convention, which still works (deprecated) on 16.
+ *
+ * `makeRequire` is a seam: module resolution walks up from `cwd` to the
+ * filesystem root, so under a test runner (or an `npx` cache) it can find a
+ * *different* project's Next and answer confidently with the wrong number.
+ * Tests pass a resolver that fails, to exercise the manifest path.
+ */
+export function detectNextMajor(cwd, makeRequire = createRequire) {
+    // Prefer the installed copy — that's the version the app actually runs.
+    try {
+        const require = makeRequire(join(cwd, "__scaffold__.js"));
+        const pkg = require("next/package.json");
+        const major = parseMajor(pkg.version);
+        if (major)
+            return major;
+    }
+    catch {
+        // next not installed yet — fall through to the manifest range
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf-8"));
+        return parseMajor(pkg.dependencies?.next ?? pkg.devDependencies?.next);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Pull the major out of a version or a range (`^16.3.1`, `>=15.0.0`, `15.5.23`, `16`). */
+function parseMajor(version) {
+    if (!version)
+        return undefined;
+    const match = /^(\d+)/.exec(version.replace(/^[^\d]*/, ""));
+    return match ? Number(match[1]) : undefined;
+}

package/dist/ports.d.ts

@@ -0,0 +1,11 @@
+/**
+ * First free port at or above `start`.
+ *
+ * A demo that fails on "port 3000 is already in use" fails at the only moment
+ * the user has no context for fixing it, and on a developer's machine 3000 is
+ * occupied more often than not. Next would pick another port by itself, but
+ * the editor is told where the orchestrator lives at startup and the
+ * orchestrator is inside the site — so the port has to be decided once, here,
+ * and both halves told the same answer.
+ */
+export declare function findFreePort(start: number, attempts?: number): Promise<number>;

package/dist/ports.js

@@ -0,0 +1,61 @@
+import { createConnection, createServer } from "node:net";
+/**
+ * First free port at or above `start`.
+ *
+ * A demo that fails on "port 3000 is already in use" fails at the only moment
+ * the user has no context for fixing it, and on a developer's machine 3000 is
+ * occupied more often than not. Next would pick another port by itself, but
+ * the editor is told where the orchestrator lives at startup and the
+ * orchestrator is inside the site — so the port has to be decided once, here,
+ * and both halves told the same answer.
+ */
+export async function findFreePort(start, attempts = 20) {
+    for (let port = start; port < start + attempts; port++) {
+        if (await isFree(port))
+            return port;
+    }
+    return start;
+}
+/**
+ * Free means both "nothing answers" and "we can bind".
+ *
+ * Neither test is sufficient alone, and each one alone shipped a bug:
+ *
+ *  - Binding `127.0.0.1` reported 3000 free while `next dev` was listening on
+ *    `*:3000`, so the scaffold wrote 3000 into five files and the demo died on
+ *    EADDRINUSE.
+ *  - Binding the wildcard reported 4100 free while the editor was listening on
+ *    `[::1]:4100`. Node sets SO_REUSEADDR, so a wildcard bind succeeds beside a
+ *    loopback-specific one — and the result is two servers answering
+ *    `localhost:4100`, chosen by whichever family the client resolves.
+ *
+ * So: connect to both loopback addresses, and if nothing accepts, confirm we
+ * can actually take the port.
+ */
+async function isFree(port) {
+    const answered = await Promise.all([accepts(port, "127.0.0.1"), accepts(port, "::1")]);
+    if (answered.some(Boolean))
+        return false;
+    return bindable(port);
+}
+/** Whether something accepts a connection on this address. */
+function accepts(port, host) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ port, host });
+        const done = (answer) => {
+            socket.destroy();
+            resolve(answer);
+        };
+        socket.setTimeout(250, () => done(false));
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+    });
+}
+function bindable(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.once("listening", () => server.close(() => resolve(true)));
+        server.listen(port);
+    });
+}

package/dist/prompts.d.ts

@@ -0,0 +1,13 @@
+import type { ScaffoldConfig } from "./types.js";
+/** A directory name turned into something the orchestrator will accept as a site id. */
+export declare function toSiteId(name: string): string;
+/** Everything a demo scaffold needs, with no questions asked. */
+export declare function demoConfig(dirName: string): Promise<ScaffoldConfig>;
+/**
+ * The mode question, asked first.
+ *
+ * It used to be "Which CMS?", which is a reasonable question to ask somebody
+ * mid-integration and the wrong first thing to ask somebody who has not yet
+ * seen what the product does.
+ */
+export declare function runPrompts(cwd: string): Promise<ScaffoldConfig | null>;

package/dist/prompts.js

@@ -0,0 +1,119 @@
+import * as p from "@clack/prompts";
+import { randomBytes } from "node:crypto";
+import { basename } from "node:path";
+import { detectNextMajor } from "./next-version.js";
+import { findFreePort } from "./ports.js";
+/** 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";
+}
+/** Everything a demo scaffold needs, with no questions asked. */
+export async function demoConfig(dirName) {
+    const sitePort = await findFreePort(3000);
+    const editorPort = await findFreePort(4100);
+    return {
+        mode: "demo",
+        cms: "none",
+        siteId: toSiteId(dirName),
+        blocksMode: "default",
+        sitePort,
+        editorPort,
+        draftSecret: randomBytes(24).toString("hex"),
+    };
+}
+/**
+ * The mode question, asked first.
+ *
+ * It used to be "Which CMS?", which is a reasonable question to ask somebody
+ * mid-integration and the wrong first thing to ask somebody who has not yet
+ * seen what the product does.
+ */
+export async function runPrompts(cwd) {
+    p.intro("Avocado Studio");
+    const mode = await p.select({
+        message: "What would you like to do?",
+        options: [
+            {
+                value: "demo",
+                label: "See the demo site",
+                hint: "creates a new project — nine pages, editable by chat",
+            },
+            {
+                value: "integrate",
+                label: "Wire Avocado into this project",
+                hint: "an existing Next.js app, in this directory",
+            },
+        ],
+    });
+    if (p.isCancel(mode)) {
+        p.cancel("Cancelled.");
+        return null;
+    }
+    if (mode === "demo") {
+        const dir = await p.text({
+            message: "Directory name",
+            placeholder: "avocado-demo",
+            defaultValue: "avocado-demo",
+            validate: (v) => (v.includes("/") || v.includes("\\") ? "A single directory name, not a path" : undefined),
+        });
+        if (p.isCancel(dir)) {
+            p.cancel("Cancelled.");
+            return null;
+        }
+        return demoConfig(dir);
+    }
+    return integratePrompts(cwd);
+}
+async function integratePrompts(cwd) {
+    const cms = await p.select({
+        message: "Which CMS?",
+        options: [
+            { value: "sanity", label: "Sanity" },
+            { value: "contentful", label: "Contentful" },
+            { value: "strapi", label: "Strapi" },
+            { value: "none", label: "None (static JSON)" },
+        ],
+    });
+    if (p.isCancel(cms)) {
+        p.cancel("Cancelled.");
+        return null;
+    }
+    const siteId = await p.text({
+        message: "Site ID (used for orchestrator sessions)",
+        placeholder: basename(cwd),
+        defaultValue: basename(cwd),
+        validate: (v) => /^[a-zA-Z0-9_-]+$/.test(v) ? undefined : "Only letters, numbers, hyphens, and underscores",
+    });
+    if (p.isCancel(siteId)) {
+        p.cancel("Cancelled.");
+        return null;
+    }
+    const blocksMode = await p.select({
+        message: "Block types?",
+        options: [
+            { value: "default", label: "Default blocks", hint: "Hero, CTA, FeatureGrid, etc." },
+            { value: "custom", label: "Custom blocks", hint: "Generates stub manifest for you to fill in" },
+        ],
+    });
+    if (p.isCancel(blocksMode)) {
+        p.cancel("Cancelled.");
+        return null;
+    }
+    return {
+        mode: "integrate",
+        cms: cms,
+        siteId: siteId,
+        blocksMode: blocksMode,
+        nextMajor: detectNextMajor(cwd),
+        // The host app owns its own ports; these are only the defaults the emitted
+        // `.env.local.example` and the printed instructions assume.
+        sitePort: 3000,
+        editorPort: 4100,
+        // Generated here for the same reason the demo path generates one: the
+        // example env used to ship `DRAFT_MODE_SECRET=dev-secret` next to a step
+        // telling the reader to replace it with a long random string, and a value
+        // that already looks filled in is a step nobody performs.
+        draftSecret: randomBytes(24).toString("hex"),
+    };
+}

package/dist/templates/assets.d.ts

@@ -0,0 +1,2 @@
+import type { GeneratedFile } from "../types.js";
+export declare function demoAssets(): GeneratedFile[];

package/dist/templates/assets.js

@@ -0,0 +1,41 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, posix, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+/*
+ * The files the demo content points at.
+ *
+ * Twelve of them: a logo, used in the header of every page, and eleven images
+ * across five of the nine pages. `apps/site` keeps them in its own `public/`,
+ * so nothing in the monorepo ever noticed they were not part of the content —
+ * and a scaffolded project has no `public/` at all, so every page rendered a
+ * broken logo and five of them rendered broken images. A demo that ships
+ * broken images is the placeholder problem again, wearing better copy.
+ *
+ * `scripts/sync-demo-seed.mjs` fills this directory from the same source as the
+ * content itself and fails if an asset the content names is missing, so the two
+ * cannot come apart.
+ *
+ * Resolved relative to the package root, which is two levels up from both
+ * `src/templates` and `dist/templates` — the same answer whether this runs from
+ * source under tsx or from the published build.
+ */
+const ASSETS = fileURLToPath(new URL("../../assets", import.meta.url));
+export function demoAssets() {
+    return walk(ASSETS).map((absolute) => ({
+        // Published under `public/`, because that is where Next serves the root-
+        // relative paths the content uses (`/logos/avocado-hub.svg`).
+        path: posix.join("public", absolute.slice(ASSETS.length + 1).split(sep).join("/")),
+        source: absolute,
+    }));
+}
+function walk(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            out.push(...walk(full));
+        else
+            out.push(full);
+    }
+    return out.sort();
+}

package/dist/templates/common.d.ts

@@ -0,0 +1,45 @@
+import type { ScaffoldConfig } from "../types.js";
+export declare function editorApiRoute(config: ScaffoldConfig): string;
+export declare function revalidateRoute(config: ScaffoldConfig): string | null;
+export declare function manifestFile(config: ScaffoldConfig): string;
+/**
+ * Which of `createSitePage`'s three modes a scaffolded route file uses.
+ *
+ * `auto` is one route that decides published-vs-editor per request, and needs
+ * neither a middleware nor a proxy nor a second route file. That costs static
+ * rendering — reading `searchParams` opts every visitor into a dynamic render —
+ * which is the right trade for a demo and the wrong one for a production site.
+ * `static` + `preview` is the pair a real site wants, and is what the
+ * integrate path still scaffolds.
+ */
+export type PageMode = "auto" | "static" | "preview";
+export declare function pageFile(config: ScaffoldConfig, mode?: PageMode): string;
+/**
+ * `createSitePage` calls `notFound()` for an unknown slug, which renders this
+ * file with a real 404 status. Without it Next falls back to its own bare
+ * default page — correct status, but none of the site's chrome.
+ */
+export declare function notFoundFile(): string;
+/** Next.js 15 and earlier: the rewrite lives in `middleware.ts`. */
+export declare function middlewareFile(): string;
+/**
+ * Next.js 16+: `middleware` was renamed to the `proxy` convention, and `config`
+ * must be a static object literal — Next 16 reads it by static analysis and
+ * rejects a factory return value or an imported constant.
+ */
+export declare function proxyFile(): string;
+/**
+ * The integrate path's `.env.local.example`.
+ *
+ * It used to contradict the instructions printed beside it. Step 4 mounts the
+ * orchestrator inside the app at `/api/avocado` — there is no separate service
+ * — while this file set `ORCHESTRATOR_URL=http://localhost:4200`, pointing at
+ * the standalone server the integrator was never told to run. The env var
+ * wins, so every draft read went to a port with nothing on it and the editor
+ * showed published content with the edits silently dropped.
+ *
+ * `DRAFT_MODE_SECRET` was likewise pre-filled with `dev-secret` next to a step
+ * saying to set it to a long random string; it is generated now, as on the
+ * demo path.
+ */
+export declare function envExample(config: ScaffoldConfig): string;