@avocadostudio-ai/site-sdk 0.1.0 → 0.2.1

package/next-config.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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,
+ * Avocado's native and provider dependencies stay external to the server build,
+ * and a `trailingSlash: true` site stops redirecting the editor's API calls into
+ * a failed CORS preflight. Additive, and never throws.
+ */
+export function withAvocado<
+  T extends {
+    transpilePackages?: string[]
+    images?: { remotePatterns?: unknown[] }
+    serverExternalPackages?: string[]
+    trailingSlash?: boolean
+    skipTrailingSlashRedirect?: boolean
+    /** `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
+    /**
+     * Set false to keep Next's trailing-slash redirect on a `trailingSlash: true`
+     * site — at the cost of the editor, whose API calls cannot survive a 308 on
+     * their CORS preflight. Defaults to true, and pairs with
+     * `createEditorProxy({ trailingSlash: true })`.
+     */
+    trailingSlash?: 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,468 @@
+/**
+ * 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.
+ *
+ * ## And the fourth
+ *
+ * `trailingSlash: true` makes Next answer `/api/editor/blocks` with a 308 to
+ * `/api/editor/blocks/`. `fetch` follows that; a CORS preflight does not — a
+ * browser treats a redirect on `OPTIONS` as a network failure — so on a site
+ * with trailing slashes every editor API call fails before it is sent, and
+ * nothing in the error says why. `skipTrailingSlashRedirect` is the only way
+ * out, because the redirect runs before middleware and cannot be intercepted.
+ * Turning it off is safe only because the SDK's own proxy puts the redirect back
+ * for page routes — see `createEditorProxy({ trailingSlash: true })`, which is
+ * the other half of this and is not optional.
+ */
+
+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
+  }
+}
+
+/**
+ * An entry point that has to be compiled, as opposed to merely described.
+ *
+ * `.d.ts` ends in `.ts` and is not TypeScript that anything compiles — it is
+ * the type description of JavaScript that is already built. Every published
+ * package sets `types: "dist/index.d.ts"`, so a naive `/\.tsx?$/` matched all
+ * of them and this whole helper inverted on a registry install: it added the
+ * published packages to `transpilePackages`, and `transpilePackages` is
+ * precisely what drags `orchestrator-core` into the bundle and fails the build
+ * on an optional peer. The bug it exists to prevent was the bug it caused.
+ *
+ * The declaration test has to run against every string, not just `types` — an
+ * `exports` map carries its own `types` condition.
+ */
+const DECLARATION_FILE = /\.d\.[cm]?tsx?$/
+const TYPESCRIPT_FILE = /\.[cm]?tsx?$/
+
+function isCompilableEntry(entry) {
+  return TYPESCRIPT_FILE.test(entry) && !DECLARATION_FILE.test(entry)
+}
+
+/** Does any entry point in this manifest resolve to TypeScript source? */
+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(isCompilableEntry)
+}
+
+/** 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",
+]
+
+/**
+ * Stop Next issuing the trailing-slash redirect, so the editor's API calls can
+ * reach the site at all.
+ *
+ * Only for an app that asked for `trailingSlash: true`; every other config is
+ * returned untouched. An app that already stated a `skipTrailingSlashRedirect`
+ * of its own — either value — keeps it, because a site that has thought about
+ * this has thought about it harder than a helper can.
+ *
+ * This half alone is a regression: it stops `/about` redirecting to `/about/`,
+ * which for a site that has published slashed URLs for years is an SEO change
+ * nobody asked for. `createEditorProxy({ trailingSlash: true })` re-issues that
+ * 308 for page routes, and the pair is the fix. They are documented together
+ * and neither is useful without the other.
+ */
+function withAvocadoTrailingSlash(config) {
+  if (config.trailingSlash !== true) return config
+  if (config.skipTrailingSlashRedirect !== undefined) return config
+  return { ...config, skipTrailingSlashRedirect: true }
+}
+
+/**
+ * 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, and on Next 16 that is not
+ * cosmetic. Turbopack is the default there, and a config carrying a `webpack`
+ * key with no `turbopack` key is a **build error**, not a warning:
+ *
+ *     ERROR: This build is using Turbopack, with a `webpack` config and no
+ *     `turbopack` config. This may be a mistake.
+ *
+ * Next's own message names the remedy — an empty `turbopack` config — so that is
+ * what goes in whenever we are the ones adding the hook and the app declared no
+ * Turbopack config of its own. It is inert on Next 15 and it never overwrites an
+ * app's own `turbopack` key. Under Turbopack the webpack hook is never called
+ * and `serverExternalPackages` carries the fix; under webpack the hook is what
+ * holds. Declaring both is the only way to be right on both.
+ *
+ * An app that would rather manage all of this itself opts out with
+ * `{ serverExternals: false }`, which attaches nothing.
+ */
+function withAvocadoServerExternals(config, extra = []) {
+  const externals = [...AVOCADO_SERVER_EXTERNALS, ...extra]
+  const declared = Array.isArray(config.serverExternalPackages) ? config.serverExternalPackages : []
+  const missing = externals.filter((name) => !declared.includes(name))
+
+  const appWebpack = typeof config.webpack === "function" ? config.webpack : null
+
+  return {
+    ...config,
+    ...(missing.length > 0 ? { serverExternalPackages: [...declared, ...missing] } : {}),
+    ...(config.turbopack === undefined ? { turbopack: {} } : {}),
+    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 externals) {
+            if (request === name || request.startsWith(`${name}/`)) {
+              return callback(null, `commonjs ${request}`)
+            }
+          }
+          callback()
+        },
+      ]
+      return result
+    },
+  }
+}
+
+/**
+ * `orchestrator-core`, when it arrived built rather than linked.
+ *
+ * Naming its *dependencies* external is not enough. Turbopack resolves a
+ * dynamic import statically, so as long as it walks into
+ * `orchestrator-core/dist` at all it meets `await import("googleapis")` and
+ * fails the build over an optional peer the site deliberately never installed —
+ * `serverExternalPackages` notwithstanding, because that governs what is
+ * bundled, not what is traversed. Externalising the package itself is what
+ * stops the walk, and it is the one fix that appears in no list and no
+ * document; it was found by building a registry install on Next 16.
+ *
+ * Only when it is *not* linked. A workspace checkout points `main` at
+ * `src/index.ts`, and externalising that hands Node a TypeScript file to
+ * require at runtime — trading a build error for a crash on the first request.
+ */
+const ORCHESTRATOR_CORE = "@avocadostudio-ai/orchestrator-core"
+
+function builtOrchestratorCore(from, linked) {
+  if (linked.includes(ORCHESTRATOR_CORE)) return []
+  for (const nodeModules of nodeModulesDirs(from)) {
+    if (existsSync(join(nodeModules, ORCHESTRATOR_CORE, "package.json"))) return [ORCHESTRATOR_CORE]
+  }
+  return []
+}
+
+/**
+ * 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, marks Avocado's
+ * native and provider dependencies external to the server build, since neither
+ * survives being bundled, and — on a site that sets `trailingSlash: true` —
+ * turns off the redirect that would otherwise make every editor API call fail
+ * its CORS preflight. Pass `{ images: false }`, `{ serverExternals: false }` or
+ * `{ trailingSlash: false }` to manage any of them yourself.
+ *
+ * `trailingSlash` is the one that needs a second step: the SDK's proxy has to
+ * re-issue the redirect it turns off. See `withAvocadoTrailingSlash`.
+ *
+ * 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,
+    trailingSlash = true,
+    env = process.env,
+  } = options
+
+  /*
+   * Resolved first because the externals depend on it: whether
+   * `orchestrator-core` has to be external is exactly the question of whether
+   * it is linked. A filesystem this cannot read leaves both lists empty, which
+   * is the same "never throw" contract as before — a helper that can break
+   * `next.config` is worse than the bug it fixes.
+   */
+  let linked = null
+  try {
+    linked = linkedAvocadoPackages(cwd)
+  } catch {
+    linked = null
+  }
+
+  /*
+   * 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 base = trailingSlash ? withAvocadoTrailingSlash(config) : config
+  const withImages = images ? withAvocadoImages(base, env) : base
+  const result = serverExternals
+    ? withAvocadoServerExternals(withImages, linked === null ? [] : builtOrchestratorCore(cwd, linked))
+    : withImages
+
+  if (linked === null) 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