@avocadostudio-ai/site-sdk 0.1.0 → 0.2.0

package/next-config.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Types for `next-config.mjs`.
+ *
+ * The implementation is plain ESM on purpose — it is imported by `next.config`,
+ * before any of Next's loaders exist — so its types cannot be inferred and have
+ * to be declared here. A `next.config.ts` under `noImplicitAny` fails without
+ * this file.
+ */
+
+/** The linked Avocado packages that still ship TypeScript entry points. */
+export function linkedAvocadoPackages(from?: string): string[]
+
+/** A `next/image` remote pattern, structurally matching Next's own type. */
+export type AvocadoImagePattern = {
+  protocol: "http" | "https"
+  hostname: string
+  port?: string
+  pathname?: string
+}
+
+/**
+ * The image hosts Avocado itself can produce URLs for — stock search, the image
+ * models' blob storage, and the placeholder host. `withAvocado` merges these
+ * into `images.remotePatterns`; exported so an app that opts out with
+ * `{ images: false }` can still reference the list.
+ */
+export const AVOCADO_IMAGE_HOSTS: AvocadoImagePattern[]
+
+/**
+ * The packages that must stay external to the server build — native binaries
+ * (`better-sqlite3`, `sharp`) and the provider SDKs `orchestrator-core` reaches
+ * through `await import(...)`. `withAvocado` applies these; exported so an app
+ * that opts out with `{ serverExternals: false }` can still reference the list.
+ */
+export const AVOCADO_SERVER_EXTERNALS: string[]
+
+/**
+ * Wrap a Next config so `transpilePackages` covers every linked Avocado package,
+ * `images.remotePatterns` covers every host Avocado can serve an image from, and
+ * Avocado's native and provider dependencies stay external to the server build.
+ * Additive, and never throws.
+ */
+export function withAvocado<
+  T extends {
+    transpilePackages?: string[]
+    images?: { remotePatterns?: unknown[] }
+    serverExternalPackages?: string[]
+    /** `null` is in Next's own type for this field, so the constraint admits it. */
+    webpack?: ((config: any, context: any) => any) | null
+  }
+>(
+  config?: T,
+  options?: {
+    cwd?: string
+    silent?: boolean
+    /** Set false to manage `images.remotePatterns` yourself. Defaults to true. */
+    images?: boolean
+    /**
+     * Set false to manage `serverExternalPackages` and the server `externals`
+     * yourself. Defaults to true.
+     */
+    serverExternals?: boolean
+    /** Environment to read the orchestrator origin from. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>
+  }
+): T
+
+export default withAvocado

package/next-config.mjs

@@ -0,0 +1,358 @@
+/**
+ * Next.js config helper.
+ *
+ * Plain ESM, deliberately: it is imported *by* `next.config`, which Next loads
+ * before any of its own loaders exist. Everything else in this package ships
+ * TypeScript source in a workspace checkout, and a config that imported that
+ * would fail to parse — which is the very failure this file exists to prevent.
+ *
+ * ## What it prevents
+ *
+ * Avocado's packages point `main` at `src/index.ts` so a monorepo checkout
+ * needs no build step. Webpack has no idea what to do with that, so every
+ * linked package must be named in `transpilePackages` — and when one is
+ * missing, the error names a file inside `node_modules` and says nothing about
+ * the config the integrator has to change:
+ *
+ *     Module parse failed: Unexpected token (27:7)
+ *     > type InlineToken,
+ *
+ * Nothing catches it earlier. A type-check does not compile a Next app, and a
+ * test suite does not boot one, so the app is green everywhere except in a
+ * browser. It also breaks *retroactively*: adding a package to Avocado, or
+ * re-exporting one from another, silently breaks every consumer that pinned the
+ * old list by hand.
+ *
+ * So the list is not maintained by hand. This reads what is actually linked and
+ * adds whatever ships TypeScript, keeping anything the app already declared.
+ *
+ * ## What else it prevents
+ *
+ * Avocado writes image URLs its host never chose. A generated image comes back
+ * from Unsplash or from an image model's blob storage, and `next/image` refuses
+ * any host not listed in `images.remotePatterns` — so the first image a user
+ * generates 500s, on a config line nothing in the integration docs mentioned.
+ * Four apps in this repo carried the same hand-copied host list to work around
+ * that. It belongs here, next to the other thing an integrator cannot be
+ * expected to know.
+ *
+ * ## And the third thing
+ *
+ * `orchestrator-core` reaches native binaries (`better-sqlite3`, `sharp`) and
+ * heavyweight provider SDKs, some of them through `await import(...)` because
+ * they are optional peers. A bundler must be told to leave all of them alone:
+ *
+ *  - A native `.node` binary that gets bundled crashes when it is loaded, not
+ *    when it is built, so the failure surfaces on the first request.
+ *  - Turbopack statically resolves dynamic imports, so an optional peer that is
+ *    *deliberately absent* fails the build with `Module not found`. "An optional
+ *    peer is genuinely skipped" holds at install time; it does not hold at bundle
+ *    time.
+ *
+ * `serverExternalPackages` alone is not enough, and this is the part nobody
+ * guesses: `transpilePackages` overrides server externals for a transitive
+ * dependency, so `sharp` reached through the transpiled `orchestrator-core` got
+ * bundled anyway. The two options interact, this helper sets both, and it is the
+ * only place that knows it has to.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+/** Scopes whose packages may ship TypeScript source in a linked checkout. */
+const SCOPES = ["@avocadostudio-ai", "@ai-site-editor"]
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"))
+  } catch {
+    return null
+  }
+}
+
+/** Does any entry point in this manifest resolve to TypeScript? */
+function shipsTypeScript(pkg) {
+  const seen = []
+  const walk = (value) => {
+    if (typeof value === "string") seen.push(value)
+    else if (value && typeof value === "object") Object.values(value).forEach(walk)
+  }
+  walk(pkg.main)
+  walk(pkg.types)
+  walk(pkg.exports)
+  return seen.some((entry) => /\.tsx?$/.test(entry))
+}
+
+/** Every `node_modules` directory from `start` up to the filesystem root. */
+function nodeModulesDirs(start) {
+  const dirs = []
+  let current = resolve(start)
+  for (;;) {
+    const candidate = join(current, "node_modules")
+    if (existsSync(candidate)) dirs.push(candidate)
+    const parent = dirname(current)
+    if (parent === current) return dirs
+    current = parent
+  }
+}
+
+/**
+ * The linked Avocado packages that have to be transpiled with the app.
+ *
+ * Resolved from what is on disk rather than from a list in this file, so a
+ * package added to Avocado tomorrow is picked up without anyone editing a
+ * config. A package installed from a registry resolves to built JavaScript and
+ * is correctly left out.
+ */
+export function linkedAvocadoPackages(from = process.cwd()) {
+  const found = new Set()
+  for (const nodeModules of nodeModulesDirs(from)) {
+    for (const scope of SCOPES) {
+      const scopeDir = join(nodeModules, scope)
+      if (!existsSync(scopeDir)) continue
+      let entries
+      try {
+        entries = readdirSync(scopeDir)
+      } catch {
+        continue
+      }
+      for (const name of entries) {
+        const full = `${scope}/${name}`
+        if (found.has(full)) continue
+        const pkg = readJson(join(scopeDir, name, "package.json"))
+        if (pkg && shipsTypeScript(pkg)) found.add(full)
+      }
+    }
+  }
+  return [...found].sort()
+}
+
+/**
+ * Hosts Avocado itself can put in an image URL.
+ *
+ * Unsplash for stock search, the image models' own blob storage for generated
+ * images, `placehold.co` for the placeholder a block renders before an image is
+ * chosen. A host the *site's own CMS* serves from (`cdn.sanity.io`,
+ * `images.ctfassets.net`, …) is not here — that is the app's to declare,
+ * because only the app knows which CMS it uses.
+ */
+export const AVOCADO_IMAGE_HOSTS = [
+  { protocol: "https", hostname: "images.unsplash.com" },
+  { protocol: "https", hostname: "plus.unsplash.com" },
+  { protocol: "https", hostname: "oaidalleapiprodscus.blob.core.windows.net" },
+  { protocol: "https", hostname: "generativelanguage.googleapis.com" },
+  { protocol: "https", hostname: "placehold.co" },
+]
+
+/** `{protocol}://{hostname}` — the identity two patterns are deduped on. */
+function patternKey(pattern) {
+  return `${pattern.protocol ?? "https"}://${pattern.hostname}${pattern.port ? `:${pattern.port}` : ""}${pattern.pathname ?? ""}`
+}
+
+/**
+ * The orchestrator's own origin, when it is somewhere `next/image` would need
+ * permission to reach.
+ *
+ * Uploaded and locally-cached images are served by the orchestrator, so its
+ * host has to be allowed too — and unlike the list above it is per-deployment,
+ * which is exactly why hand-maintained config kept getting it wrong.
+ */
+function orchestratorImagePattern(env) {
+  const configured = (env.NEXT_PUBLIC_ORCHESTRATOR_URL ?? env.ORCHESTRATOR_URL ?? "").trim()
+  /*
+   * The same default `draft-fetch.ts` uses — but only outside production. A
+   * build that never names its orchestrator is a local one, and allowing
+   * `localhost` through the image optimizer of a deployed site is a wider hole
+   * than the convenience is worth.
+   */
+  const raw = configured || (env.NODE_ENV === "production" ? "" : "http://localhost:4200")
+  if (!raw) return null
+  try {
+    const url = new URL(raw)
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null
+    return {
+      protocol: url.protocol.replace(":", ""),
+      hostname: url.hostname,
+      ...(url.port ? { port: url.port } : {}),
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Merge Avocado's image hosts into a Next config's `images.remotePatterns`.
+ *
+ * Additive, like the transpile list: whatever the app declared stays, in its
+ * own order, and a host it already covers is not duplicated.
+ */
+function withAvocadoImages(config, env) {
+  const images = config.images ?? {}
+  const declared = Array.isArray(images.remotePatterns) ? images.remotePatterns : []
+  const seen = new Set(declared.map(patternKey))
+
+  const additions = []
+  for (const pattern of [...AVOCADO_IMAGE_HOSTS, orchestratorImagePattern(env)]) {
+    if (!pattern) continue
+    const key = patternKey(pattern)
+    if (seen.has(key)) continue
+    seen.add(key)
+    additions.push(pattern)
+  }
+  if (additions.length === 0) return config
+
+  return { ...config, images: { ...images, remotePatterns: [...declared, ...additions] } }
+}
+
+/**
+ * Packages a bundler must not bundle into the server build.
+ *
+ * Two kinds, and they fail differently:
+ *
+ *  - **Native binaries** — `better-sqlite3` (the orchestrator's state) and
+ *    `sharp` (image processing). Bundling one produces a build that succeeds and
+ *    a server that dies loading the `.node` file.
+ *  - **Provider SDKs** — reached from `orchestrator-core`, several of them via
+ *    `await import(...)` so that a site which does not use a provider need not
+ *    install it. Turbopack resolves those statically and fails the build over a
+ *    package that was never meant to be there.
+ *
+ * Naming a package that is not installed is a no-op, which is what makes one
+ * list correct for every consumer: a site with no Gemini key still lists
+ * `@google/genai`, and nothing looks for it.
+ */
+export const AVOCADO_SERVER_EXTERNALS = [
+  "better-sqlite3",
+  "sharp",
+  "@anthropic-ai/sdk",
+  "@anthropic-ai/claude-agent-sdk",
+  "openai",
+  "@google/genai",
+  "googleapis",
+  "@modelcontextprotocol/sdk",
+]
+
+/**
+ * Mark every entry in `AVOCADO_SERVER_EXTERNALS` external to the server build,
+ * both ways it has to be said.
+ *
+ * `serverExternalPackages` is the documented knob and is not sufficient on its
+ * own: `transpilePackages` — which the same helper is busy populating — takes
+ * precedence for a *transitive* dependency, so a native binary imported by a
+ * transpiled Avocado package is bundled despite being listed. The webpack
+ * `externals` entry is what actually holds, and it is scoped to `isServer` so a
+ * client bundle is untouched.
+ *
+ * Both halves are additive: an app's own externals and its own `webpack` hook
+ * run first and keep whatever they did.
+ *
+ * The hook is attached even for an app that had none, which has one cosmetic
+ * cost: Next warns "Webpack is configured while Turbopack is not" for a
+ * Turbopack app that declares no `turbopack` key of its own. Under Turbopack the
+ * hook is never called and `serverExternalPackages` is what carries the fix, so
+ * the warning is about an inert function. An app that would rather not see it
+ * can declare `turbopack: {}` or opt out with `{ serverExternals: false }`.
+ */
+function withAvocadoServerExternals(config) {
+  const declared = Array.isArray(config.serverExternalPackages) ? config.serverExternalPackages : []
+  const missing = AVOCADO_SERVER_EXTERNALS.filter((name) => !declared.includes(name))
+
+  const appWebpack = typeof config.webpack === "function" ? config.webpack : null
+
+  return {
+    ...config,
+    ...(missing.length > 0 ? { serverExternalPackages: [...declared, ...missing] } : {}),
+    webpack(webpackConfig, context) {
+      const result = appWebpack ? appWebpack(webpackConfig, context) : webpackConfig
+      if (!context?.isServer) return result
+
+      const existing = result.externals ?? []
+      result.externals = [
+        ...(Array.isArray(existing) ? existing : [existing]),
+        /*
+         * A function rather than a name list so that a deep import
+         * (`sharp/lib/...`) is externalised along with the package root.
+         * Calling back with no arguments means "not external" and hands the
+         * request to the next resolver, which is why this composes.
+         */
+        ({ request }, callback) => {
+          if (!request) return callback()
+          for (const name of AVOCADO_SERVER_EXTERNALS) {
+            if (request === name || request.startsWith(`${name}/`)) {
+              return callback(null, `commonjs ${request}`)
+            }
+          }
+          callback()
+        },
+      ]
+      return result
+    },
+  }
+}
+
+/**
+ * Wrap a Next config so its `transpilePackages` covers every linked Avocado
+ * package.
+ *
+ * Also merges Avocado's own image hosts into `images.remotePatterns`, since a
+ * generated image comes from a host the site never chose, and marks Avocado's
+ * native and provider dependencies external to the server build, since neither
+ * survives being bundled. Pass `{ images: false }` or
+ * `{ serverExternals: false }` to manage either list yourself.
+ *
+ * Additive and total: whatever the app already listed is kept in the order it
+ * wrote it, unrelated entries included, its own `webpack` hook still runs and
+ * still wins, and any failure to read the filesystem leaves the config exactly
+ * as it was. Never throws — a helper that can break `next.config` is worse than
+ * the bug it fixes.
+ */
+export function withAvocado(config = {}, options = {}) {
+  const {
+    cwd = process.cwd(),
+    silent = false,
+    images = true,
+    serverExternals = true,
+    env = process.env,
+  } = options
+
+  /*
+   * Applied before the `transpilePackages` derivation below, which has two
+   * early returns of its own — a config that already lists every linked package
+   * still needs its externals.
+   */
+  const withImages = images ? withAvocadoImages(config, env) : config
+  const result = serverExternals ? withAvocadoServerExternals(withImages) : withImages
+
+  let linked
+  try {
+    linked = linkedAvocadoPackages(cwd)
+  } catch {
+    return result
+  }
+
+  const declared = Array.isArray(result.transpilePackages) ? result.transpilePackages : []
+  const missing = linked.filter((name) => !declared.includes(name))
+  if (missing.length === 0) return result
+
+  if (!silent) {
+    /*
+     * Best-effort only. Next runs `next.config` inside its own reporter, and on
+     * Next 16 neither stdout nor stderr written during that window reaches the
+     * terminal (measured, not assumed). So this is not the mechanism that keeps
+     * an integrator informed — the auto-fix is, and the comment they write next
+     * to their own `withAvocado(...)` call is. It stays because it does surface
+     * on hosts that do not capture the config run, and it costs nothing.
+     */
+    try {
+      process.stderr.write(
+        `[avocado] transpilePackages: added ${missing.join(", ")} — linked from source, so webpack has to compile them.\n`
+      )
+    } catch {
+      // A host with no writable stderr is not a reason to fail the build.
+    }
+  }
+
+  return { ...result, transpilePackages: [...declared, ...missing] }
+}
+
+export default withAvocado

package/package.json

@@ -1,58 +1,94 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     "./package.json": "./package.json",
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "default": "./dist/index.js"
     },
     "./draft": {
+      "types": "./dist/draft.d.ts",
       "import": "./dist/draft.js",
-      "types": "./dist/draft.d.ts"
+      "default": "./dist/draft.js"
     },
     "./editor": {
+      "types": "./dist/editor.d.ts",
       "import": "./dist/editor.js",
-      "types": "./dist/editor.d.ts"
+      "default": "./dist/editor.js"
     },
     "./routes": {
+      "types": "./dist/routes.d.ts",
       "import": "./dist/routes.js",
-      "types": "./dist/routes.d.ts"
+      "default": "./dist/routes.js"
     },
     "./editor-manifest": {
+      "types": "./dist/editor-manifest.d.ts",
       "import": "./dist/editor-manifest.js",
-      "types": "./dist/editor-manifest.d.ts"
+      "default": "./dist/editor-manifest.js"
     },
     "./draft/core": {
+      "types": "./dist/draft-context-core.d.ts",
       "import": "./dist/draft-context-core.js",
-      "types": "./dist/draft-context-core.d.ts"
+      "default": "./dist/draft-context-core.js"
     },
     "./routes/core": {
+      "types": "./dist/draft-routes-core.d.ts",
       "import": "./dist/draft-routes-core.js",
-      "types": "./dist/draft-routes-core.d.ts"
+      "default": "./dist/draft-routes-core.js"
     },
     "./publish-handlers/json-file": {
+      "types": "./dist/publish-handlers/json-file.d.ts",
       "import": "./dist/publish-handlers/json-file.js",
-      "types": "./dist/publish-handlers/json-file.d.ts"
+      "default": "./dist/publish-handlers/json-file.js"
+    },
+    "./publish": {
+      "types": "./dist/publish/field-diff.d.ts",
+      "import": "./dist/publish/field-diff.js",
+      "default": "./dist/publish/field-diff.js"
     },
     "./middleware": {
+      "types": "./dist/middleware.d.ts",
       "import": "./dist/middleware.js",
-      "types": "./dist/middleware.d.ts"
+      "default": "./dist/middleware.js"
+    },
+    "./proxy": {
+      "types": "./dist/proxy.d.ts",
+      "import": "./dist/proxy.js",
+      "default": "./dist/proxy.js"
+    },
+    "./matcher": {
+      "types": "./dist/editor-matcher.d.ts",
+      "import": "./dist/editor-matcher.js",
+      "default": "./dist/editor-matcher.js"
     },
     "./navigation": {
+      "types": "./dist/navigation.d.ts",
       "import": "./dist/navigation.js",
-      "types": "./dist/navigation.d.ts"
+      "default": "./dist/navigation.js"
     },
     "./page": {
+      "types": "./dist/create-site-page.d.ts",
       "import": "./dist/create-site-page.js",
-      "types": "./dist/create-site-page.d.ts"
+      "default": "./dist/create-site-page.js"
+    },
+    "./seo": {
+      "types": "./dist/page-metadata.d.ts",
+      "import": "./dist/page-metadata.js",
+      "default": "./dist/page-metadata.js"
     },
     "./server": {
+      "types": "./dist/server/orchestrator.d.ts",
       "import": "./dist/server/orchestrator.js",
-      "types": "./dist/server/orchestrator.d.ts"
+      "default": "./dist/server/orchestrator.js"
+    },
+    "./next-config": {
+      "types": "./next-config.d.ts",
+      "default": "./next-config.mjs"
     }
   },
   "repository": {
@@ -65,27 +101,34 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "next-config.d.ts",
+    "next-config.mjs"
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "0.1.0",
-    "@avocadostudio-ai/preview-adapter": "0.1.0",
-    "@avocadostudio-ai/shared": "0.1.0"
+    "@avocadostudio-ai/blocks": "0.2.0",
+    "@avocadostudio-ai/preview-adapter": "0.2.0",
+    "@avocadostudio-ai/shared": "0.2.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.1.0"
+    "better-sqlite3": ">=12.0.0",
+    "@avocadostudio-ai/orchestrator-core": "^0.2.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {
       "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/react": "^19.0.10",
+    "tsx": "^4.21.0",
     "typescript": "^5.7.3"
   },
   "description": "SDK for adding Avocado Studio AI editing and live preview to a Next.js site",
@@ -96,7 +139,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "NODE_ENV=test node ../../scripts/run-tests.mjs"
   },
   "bin": {
     "avocado-register": "./dist/cli/register.js"