create-avocado-site 0.9.0

package/dist/templates/demo-app.js

@@ -0,0 +1,465 @@
+import { AVOCADO, NEXT, REACT, TYPESCRIPT, TYPES_NODE, TYPES_REACT, TYPES_REACT_DOM } from "../versions.js";
+import { DEMO_SITE_CONFIG_JSON } from "./demo-content.js";
+/**
+ * The name the scaffolded site renders in its own header. Read from the seed
+ * rather than restated, so it cannot drift from what the preview shows — the
+ * editor used to title-case the directory name instead, which put two
+ * different names for one site on the same screen.
+ */
+const DEMO_SITE_NAME = JSON.parse(DEMO_SITE_CONFIG_JSON).name ?? "Demo site";
+/*
+ * The files that turn a scaffold into something you can run.
+ *
+ * Until now the scaffolder wrote eight files into a Next.js app you were
+ * assumed to already have, then printed five manual steps — edit next.config,
+ * edit globals.css, npm install this list, copy an env file, "start the
+ * orchestrator and editor (see docs/integration/README.md)", a path that does
+ * not exist. Every one of those steps is a place to stop, and the last one is
+ * the whole product.
+ *
+ * So this module supplies the missing half: a package.json, a Next config, a
+ * layout, an orchestrator mounted in-process, and one `npm run dev` that
+ * brings up both halves. Nothing here is a step for a person to perform.
+ */
+/**
+ * `withAvocado` is the entire Next config.
+ *
+ * It fills in `transpilePackages` from what is actually linked, merges
+ * Avocado's image hosts into `images.remotePatterns` (the demo's photography
+ * is on `images.unsplash.com`, and an undeclared host is a hard render error,
+ * not a broken image), sets `serverExternalPackages` together with the
+ * matching server externals so the native dependencies resolve, and sets
+ * `skipTrailingSlashRedirect` so a CORS preflight on `/api/*` is not answered
+ * with a 308 the browser will not follow.
+ *
+ * Those four used to be copied by hand into every integration, which is four
+ * chances to get it wrong and no signal when you did.
+ */
+function nextConfig() {
+    return `import type { NextConfig } from "next"
+import { withAvocado } from "@avocadostudio-ai/site-sdk/next-config"
+
+const nextConfig: NextConfig = {}
+
+export default withAvocado(nextConfig)
+`;
+}
+function packageJson(config) {
+    return `${JSON.stringify({
+        name: config.siteId,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        // better-sqlite3 ships prebuilt binaries for Node 22; on an older Node
+        // npm falls through to compiling it from source, which needs a toolchain
+        // the reader did not sign up for.
+        engines: { node: ">=22" },
+        scripts: {
+            dev: "node scripts/dev.mjs",
+            "dev:site": `next dev -p ${config.sitePort}`,
+            "dev:editor": `avocadostudio start --orchestrator http://localhost:${config.sitePort}/api/avocado --preview http://localhost:${config.sitePort} --port ${config.editorPort}`,
+            build: "next build",
+            start: `next start -p ${config.sitePort}`,
+        },
+        dependencies: {
+            "@avocadostudio-ai/blocks": `^${AVOCADO}`,
+            "@avocadostudio-ai/orchestrator-core": `^${AVOCADO}`,
+            "@avocadostudio-ai/preview-adapter": `^${AVOCADO}`,
+            "@avocadostudio-ai/shared": `^${AVOCADO}`,
+            "@avocadostudio-ai/site-sdk": `^${AVOCADO}`,
+            next: NEXT,
+            react: REACT,
+            "react-dom": REACT,
+        },
+        devDependencies: {
+            "@avocadostudio-ai/cli": `^${AVOCADO}`,
+            "@types/node": TYPES_NODE,
+            "@types/react": TYPES_REACT,
+            "@types/react-dom": TYPES_REACT_DOM,
+            typescript: TYPESCRIPT,
+        },
+    }, null, 2)}\n`;
+}
+function tsconfig() {
+    return `${JSON.stringify({
+        compilerOptions: {
+            target: "ES2022",
+            lib: ["dom", "dom.iterable", "ES2022"],
+            allowJs: true,
+            skipLibCheck: true,
+            strict: true,
+            noEmit: true,
+            esModuleInterop: true,
+            module: "esnext",
+            moduleResolution: "bundler",
+            resolveJsonModule: true,
+            isolatedModules: true,
+            jsx: "preserve",
+            incremental: true,
+            plugins: [{ name: "next" }],
+            paths: { "@/*": ["./*"] },
+        },
+        include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+        exclude: ["node_modules"],
+    }, null, 2)}\n`;
+}
+/**
+ * `.data/` is the line that matters.
+ *
+ * The orchestrator writes its SQLite state there, in the project root, on the
+ * first request — so it does not exist when the scaffold runs and does not
+ * exist when you look at the directory. `create-next-app`'s .gitignore does
+ * not cover it, and the first `git add .` after the first `npm run dev`
+ * commits a database plus its write-ahead log.
+ */
+function gitignore() {
+    return `node_modules/
+.next/
+out/
+build/
+
+# Orchestrator state — SQLite, written on the first request.
+.data/
+
+# public/generated-images/ is deliberately NOT ignored. The editor writes
+# generated and uploaded images there, and they are content: the pages that
+# reference them are committed, so a deploy built from git without them renders
+# broken images. Eleven of this demo's own images live in that directory.
+
+.env.local
+.env*.local
+next-env.d.ts
+*.tsbuildinfo
+.DS_Store
+`;
+}
+/**
+ * Written with no key in it, on purpose.
+ *
+ * The demo renders, selects, and shows its property panel with no API key at
+ * all — so the first run costs nothing to look at and nothing to sign up for.
+ * Chat is the one thing that needs a key, and it says so itself rather than
+ * failing with a stack trace.
+ *
+ * `DRAFT_MODE_SECRET` is not optional even though nothing warns loudly: draft
+ * mode silently does not work without it, which presents as an editor that
+ * loads the published page and ignores every edit.
+ */
+function envLocal(config) {
+    return `# One of these switches chat on. Everything else already works without them.
+#
+#   ANTHROPIC_API_KEY   the best-tested planner
+#   OPENAI_API_KEY      also powers gpt-image image generation
+#   GOOGLE_GENAI_API_KEY  also needs \`npm install @google/genai\` — it is an
+#                         optional peer dependency, so no package manager
+#                         installs it for you and a Gemini plan fails on the
+#                         first call without it.
+#
+# ANTHROPIC_API_KEY=
+
+# The orchestrator runs inside this app, at /api/avocado. There is no third
+# service to start and nothing to deploy separately.
+ORCHESTRATOR_URL=http://localhost:${config.sitePort}/api/avocado
+
+# Where the editor is served from. This site names that origin in two places
+# that must agree — CORS on the editor API, and \`frame-ancestors\` on the
+# preview — and \`withAvocado\` derives both from this one variable.
+#
+# It is not optional here. The default is port 4100, and these ports are chosen
+# at scaffold time from what was actually free, so on a machine already running
+# an editor this is some other port. When the two disagree the halves fail
+# separately and silently: the editor API answers 200 with no
+# access-control-allow-origin, and the browser refuses the frame — so the site
+# reads as offline and the preview is a blank rectangle. Neither failure
+# mentions a port, CORS, or CSP.
+EDITOR_CORS_ORIGINS=http://localhost:${config.editorPort}
+
+# Any long random string. Without it draft mode does not work, and the editor
+# quietly renders the published page instead of your edits.
+DRAFT_MODE_SECRET=${config.draftSecret}
+`;
+}
+/**
+ * One command, two processes.
+ *
+ * Written as a script rather than a `concurrently` dependency because a
+ * scaffold that installs a process runner to run two processes is a scaffold
+ * explaining itself badly — and because the interesting part is not running
+ * them, it is the banner and the shutdown. A person running this for the
+ * first time needs to be told which of the two URLs is the one to open; the
+ * editor is at :4100 and the site at :3000, and opening the site directly
+ * shows the finished page with no editor around it, which reads as "the
+ * product did not start".
+ */
+function devScript(config) {
+    return `#!/usr/bin/env node
+/*
+ * Starts the site and the editor together, then opens the editor.
+ *
+ * The site is a normal \`next dev\`. The editor is a static bundle served by
+ * @avocadostudio-ai/cli, pointed at the orchestrator running inside the site
+ * at /api/avocado. Two processes, one terminal, no third service.
+ */
+import { spawn } from "node:child_process"
+import { createConnection } from "node:net"
+
+const SITE_PORT = process.env.PORT ?? "${config.sitePort}"
+const EDITOR_PORT = process.env.EDITOR_PORT ?? "${config.editorPort}"
+const SITE_URL = \`http://localhost:\${SITE_PORT}\`
+const EDITOR_URL = \`http://localhost:\${EDITOR_PORT}\`
+
+/*
+ * The editor has to be told which site it is editing, and the only channel is
+ * the URL.
+ *
+ * The CLI serves a prebuilt editor bundle and injects the orchestrator and
+ * preview origins into it, but not a site id — so the bundle falls back to its
+ * own built-in default, "avocado-hub". Every draft request then names a
+ * session this project never configured. It happens to work, because the
+ * orchestrator bootstraps an unknown session from the adapter and gets the
+ * same nine pages, and that is exactly what makes it worth pinning: the demo
+ * looks correct while the id in the URL and the id in the route file are
+ * different strings.
+ */
+const SITE_ID = "${config.siteId}"
+const OPEN_URL = \`\${EDITOR_URL}/?siteId=\${SITE_ID}&session=dev\`
+
+const children = []
+
+function run(command, args) {
+  const child = spawn(command, args, { stdio: "inherit", shell: process.platform === "win32" })
+  children.push(child)
+  child.on("exit", (code) => {
+    // If either half dies the other is useless, so take both down rather than
+    // leaving a half-running stack that looks alive.
+    if (!shuttingDown) shutdown(code ?? 0)
+  })
+  return child
+}
+
+let shuttingDown = false
+function shutdown(code) {
+  if (shuttingDown) return
+  shuttingDown = true
+  for (const child of children) child.kill("SIGTERM")
+  process.exit(code)
+}
+process.on("SIGINT", () => shutdown(0))
+process.on("SIGTERM", () => shutdown(0))
+
+/** Resolves once something is listening on \`port\`, or after \`timeoutMs\`. */
+function waitForPort(port, timeoutMs = 60_000) {
+  const deadline = Date.now() + timeoutMs
+  return new Promise((resolve) => {
+    const attempt = () => {
+      const socket = createConnection({ port: Number(port), host: "127.0.0.1" })
+      socket.on("connect", () => { socket.destroy(); resolve(true) })
+      socket.on("error", () => {
+        socket.destroy()
+        if (Date.now() > deadline) resolve(false)
+        else setTimeout(attempt, 250)
+      })
+    }
+    attempt()
+  })
+}
+
+function open(url) {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open"
+  try {
+    spawn(command, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref()
+  } catch {
+    // Headless, or no handler registered. The banner already printed the URL.
+  }
+}
+
+run("npx", ["next", "dev", "-p", SITE_PORT])
+
+// The editor probes the orchestrator's /health on startup, and the
+// orchestrator is inside the site — so starting it first means it reports the
+// site as unreachable and the first thing a new user sees is an error screen.
+const siteUp = await waitForPort(SITE_PORT)
+
+run("npx", [
+  "avocadostudio",
+  "start",
+  "--orchestrator", \`\${SITE_URL}/api/avocado\`,
+  "--preview", SITE_URL,
+  "--port", EDITOR_PORT,
+])
+
+await waitForPort(EDITOR_PORT)
+
+process.stdout.write(
+  \`\\n  \\u25b2 Site     \${SITE_URL}\\n\` +
+    \`  \\u{1F951} Editor   \${OPEN_URL}\\n\` +
+    \`             \\u2191 open this one\\n\\n\`
+)
+
+if (siteUp) open(OPEN_URL)
+`;
+}
+/**
+ * The stylesheet import is the whole reason this file is scaffolded.
+ *
+ * Without \`@avocadostudio-ai/blocks/styles.css\` every block renders correct,
+ * complete, unstyled HTML — which does not read as "a stylesheet is missing",
+ * it reads as "this product produces ugly pages".
+ */
+function globalsCss() {
+    return `@import "@avocadostudio-ai/blocks/styles.css";
+
+:root {
+  color-scheme: light dark;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family:
+    ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+`;
+}
+function layout(config) {
+    return `import type { ReactNode } from "react"
+import "./globals.css"
+
+/*
+ * Deliberately minimal. Every page's own <title> and description come from
+ * \`generateMetadata\` in app/[[...slug]]/page.tsx, which derives them from the
+ * page content — a title set here would be inherited by all nine pages and
+ * override none of them.
+ */
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
+`;
+}
+/**
+ * Library mode: the orchestrator runs inside the site.
+ *
+ * This is the shape most integrations use and the one that makes the demo a
+ * two-process story instead of three. `jsonFileAdapter` points it at the same
+ * `content/pages.json` the pages render from, so a publish from the editor
+ * lands in the file on disk and the next request serves it.
+ *
+ * `createOrchestrator` returns one callable. Assign it to GET, POST and
+ * OPTIONS rather than destructuring — there is nothing to destructure, and
+ * `const { GET } = createOrchestrator()` yields undefined with no type error.
+ */
+function orchestratorRoute(config) {
+    return `import { resolve } from "node:path"
+import { jsonFileAdapter } from "@avocadostudio-ai/orchestrator-core/cms"
+import { createOrchestrator } from "@avocadostudio-ai/site-sdk/server"
+
+export const runtime = "nodejs"
+export const dynamic = "force-dynamic"
+
+const handler = createOrchestrator({
+  // Must match the siteId in app/[[...slug]]/page.tsx. If the two drift, the
+  // page asks for a draft session the orchestrator never seeded and the editor
+  // shows the published content with every edit silently going nowhere.
+  siteId: "${config.siteId}",
+  // The editor title-cases the id when nobody tells it otherwise, so a project
+  // in my-shop/ would be greeted as "My Shop".
+  siteName: "${DEMO_SITE_NAME}",
+  // This project starts on the shipped Avocado Hub content. The editor keys its
+  // first-run suggestions on the answer; without it they fall back to the
+  // generic list written for a site nobody has seen.
+  demoContent: true,
+  adapter: jsonFileAdapter({ path: resolve(process.cwd(), "content/pages.json") }),
+  previewUrl: "http://localhost:${config.sitePort}",
+})
+
+export const GET = handler
+export const POST = handler
+export const OPTIONS = handler
+`;
+}
+function readme(config) {
+    return `# ${config.siteId}
+
+The Avocado Hub demo — nine pages, sixty blocks, every built-in block type —
+running on your machine, editable by chat.
+
+\`\`\`bash
+npm run dev
+\`\`\`
+
+| | |
+|---|---|
+| Editor | http://localhost:${config.editorPort}/?siteId=${config.siteId}&session=dev — **open this one** |
+| Site | http://localhost:${config.sitePort} |
+
+Opening the site directly shows the finished pages with no editor around them.
+The editor is the product; the site is what it edits.
+
+The \`siteId\` on the editor URL is not decoration. The editor is a prebuilt
+bundle that is told the orchestrator's address but not which site to open, so
+without it it falls back to its own default name and asks the orchestrator for
+a session this project never configured.
+
+## Turning chat on
+
+Everything except chat works with no API key: the pages render, click-to-select
+works, and the property panel edits real fields. Chat needs a model. Put one
+key in \`.env.local\` and restart:
+
+\`\`\`
+ANTHROPIC_API_KEY=sk-ant-...
+\`\`\`
+
+\`OPENAI_API_KEY\` and \`GOOGLE_GENAI_API_KEY\` work too. Avocado runs on your key
+and never resells tokens. For Gemini also run \`npm install @google/genai\` — it
+is an optional peer dependency, so nothing installs it for you.
+
+## What is where
+
+| Path | What it is |
+|---|---|
+| \`content/pages.json\` | The nine pages. Publishing from the editor rewrites this file. |
+| \`content/site.json\` | Site name and navigation, including the dropdown groups. |
+| \`lib/content.ts\` | The one module that reads both. |
+| \`app/[[...slug]]/page.tsx\` | Renders every page. |
+| \`app/api/avocado/[[...path]]/route.ts\` | The orchestrator, running inside this app. |
+| \`app/api/editor/[...path]/route.ts\` | What the editor reads and publishes through. |
+| \`.data/\` | The orchestrator's SQLite state. Git-ignored; delete it to start over. |
+
+## Next: your own site
+
+This demo keeps its content in a JSON file so the loop is visible end to end in
+one sitting. Bringing in a real site — your components, your CMS, your content
+— is a different and larger job. The paths for it are at
+https://docs.avocadostudio.dev/sites.
+`;
+}
+/** The files that exist only in a bootstrapped demo, on top of the shared wiring. */
+export function demoAppTemplates(config) {
+    return [
+        { path: "package.json", content: packageJson(config) },
+        { path: "next.config.ts", content: nextConfig() },
+        { path: "tsconfig.json", content: tsconfig() },
+        { path: ".gitignore", content: gitignore() },
+        { path: ".env.local", content: envLocal(config) },
+        { path: "README.md", content: readme(config) },
+        { path: "scripts/dev.mjs", content: devScript(config) },
+        { path: "app/layout.tsx", content: layout(config) },
+        { path: "app/globals.css", content: globalsCss() },
+        { path: "app/api/avocado/[[...path]]/route.ts", content: orchestratorRoute(config) },
+    ];
+}