@avocadostudio-ai/orchestrator-core 0.2.0 → 0.2.3

package/README.md

@@ -0,0 +1,102 @@
+# @avocadostudio-ai/orchestrator-core
+
+The Avocado Studio orchestrator as a library: session state, AI planning, the
+operations engine, and publishing, behind one Web-standard
+`(Request) => Promise<Response>`.
+
+This is the package **library mode is built on**. If you are integrating a
+Next.js site you almost certainly want
+[`@avocadostudio-ai/site-sdk`](https://www.npmjs.com/package/@avocadostudio-ai/site-sdk)
+instead — it re-exports everything below from
+`@avocadostudio-ai/site-sdk/server` and adds the Next-specific pieces (draft
+mode, the page factory, the editor API route). Reach for this package directly
+only when your host is not Next.
+
+## Install
+
+```bash
+npm install @avocadostudio-ai/orchestrator-core
+```
+
+`better-sqlite3` is a real dependency, not optional: session state — draft
+pages, undo/redo, the version log, chat history — lives in SQLite. Prebuilt
+binaries ship for linux-x64 (glibc 2.28+), darwin-arm64 and darwin-x64 on
+Node 22.
+
+Two peers are **optional**: `googleapis` and `@google/genai`. They are reached
+through `await import(...)` so a deployment that uses neither need not install
+them — but a bundler resolves dynamic imports statically and will fail the build
+over a package that is deliberately absent. Mark them external. On Next,
+`withAvocado` from `@avocadostudio-ai/site-sdk/next-config` does it for you.
+
+## Mount it
+
+```ts
+import { createOrchestrator } from "@avocadostudio-ai/orchestrator-core"
+
+const handler = createOrchestrator({
+  basePath: "/api/avocado",
+  adapter: myAdapter,
+  auth: async (request) => Boolean(await getSession(request)),
+})
+
+// Any host that speaks Request/Response
+export { handler as GET, handler as POST, handler as OPTIONS }
+```
+
+`createOrchestrator` gates **every** route. With neither an `auth` hook nor a
+credential (`ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`) it refuses
+all requests under `NODE_ENV=production` rather than serving your content
+openly. Only `/auth/status` and `/auth/verify` are public.
+
+## The adapter
+
+`adapter` is your content store. SQLite is the working copy; the adapter is the
+source of truth, read on a cold session and written on publish.
+
+```ts
+import type { CmsAdapter } from "@avocadostudio-ai/orchestrator-core/cms"
+
+const myAdapter: CmsAdapter = {
+  id: "my-cms",
+  perspectives: true,                       // does getPages honour options.perspective?
+  getPages: (options) => fetchPages(options),
+  onPublish: (pages, config, context) => writeBack(pages, context?.published),
+  capabilities: { createPage: false },      // static — /whoami answers it offline
+}
+```
+
+`jsonFileAdapter` and `editorApiAdapter` are bundled from the same subpath. The
+full contract — including why `perspectives` defaults to *no* while capabilities
+default to *yes*, and why `onPublish` has to diff rather than overwrite — is
+documented in
+[the site-sdk README](https://www.npmjs.com/package/@avocadostudio-ai/site-sdk#the-adapter-contract).
+
+## What it does not do
+
+It serves the API. It does not serve the editor UI — that is
+`@avocadostudio-ai/cli` or your own deployment of the Studio — and it does not
+render your pages.
+
+`/health` is **not** a route, so a client that probes it to check compatibility
+gets a 405. The body lists every route that does exist.
+
+## Persistence
+
+| variable | meaning |
+|---|---|
+| `ORCHESTRATOR_DB_FILE` | Path to the SQLite file. Empty for the default; `:memory:` to force ephemeral. Auto-`:memory:` under `NODE_ENV=test` |
+| `ORCHESTRATOR_DB_BACKUP_INTERVAL_HOURS` | Periodic `VACUUM INTO` snapshot interval (default 24) |
+| `ORCHESTRATOR_DB_BACKUP_LIMIT` | Rolling snapshots to keep (default 14) |
+
+Undo/redo is capped at 50 entries per slug per direction, the version log at
+100, recent edits at 10, chat history at 6 messages.
+
+## Providers
+
+At least one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or `GOOGLE_GENAI_API_KEY`
+is required for planning. Keys never leave the process that holds them.
+
+## License
+
+Apache-2.0

package/dist/handler/auth.js

@@ -29,7 +29,13 @@ import { isAccessGateEnabled, isValidAccessToken, extractAccessToken } from "../
  * gating it would blank every uploaded image in the live site, not just in the
  * editor. Both are read-only and neither reveals session content.
  */
-const PUBLIC_PATHS = new Set(["/auth/status", "/auth/verify"]);
+/*
+ * `/health` is here because a probe that needs a credential is not a probe. The
+ * CLI calls it before it has one, to compare protocol versions, and it answers
+ * nothing about the site's content — only that this is an Avocado orchestrator
+ * and which protocol it speaks.
+ */
+const PUBLIC_PATHS = new Set(["/auth/status", "/auth/verify", "/health"]);
 export function isPublicPath(path, method) {
     if (method === "OPTIONS")
         return true;

package/dist/handler/create-orchestrator.js

@@ -21,7 +21,7 @@ import { mkdir, writeFile, readFile } from "node:fs/promises";
 import { resolve, basename } from "node:path";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
-import { operationSchema, blockManifestSchema, siteConfigSchema, declareBlockCatalogue, undeclaredBlockTypes } from "@avocadostudio-ai/shared";
+import { operationSchema, blockManifestSchema, siteConfigSchema, declareBlockCatalogue, undeclaredBlockTypes, EDITOR_PROTOCOL_VERSION } from "@avocadostudio-ai/shared";
 import { chatRequestBodySchema } from "../nlp/intent-detection.js";
 import { applyOpsAtomically, pickFocusBlockId, pickUpdatedSlug, toErrorDetail, classifyGuardrailError } from "../ops/ops-engine.js";
 import { runChatStream, formatSseFrame } from "../http/chat-stream.js";
@@ -196,6 +196,7 @@ function jsonResponse(body, init = {}) {
  * only thing that keeps a list like this honest.
  */
 const SUPPORTED_ROUTES = [
+    "GET /health",
     "GET /auth/status",
     "POST /auth/verify",
     "POST /chat",
@@ -899,7 +900,9 @@ export function createOrchestrator(config = {}) {
                 })),
                 // Which content this is — see orchestrator-core/http/draft-provenance.ts.
                 ...describeDraft({
-                    requestedSiteId: siteId ?? effectiveSiteId,
+                    // Config first, matching every other route: a mount that names its
+                    // site knows better than a request that forgot to.
+                    requestedSiteId: effectiveSiteId ?? siteId,
                     scopedSession,
                     pageCount: pages.length,
                     hasAdapter: Boolean(runtime.adapter)
@@ -1243,12 +1246,38 @@ export function createOrchestrator(config = {}) {
             }
             return actionResponse(blocksManifestAction(), cors);
         }
+        /*
+         * Liveness and protocol version, for a client deciding whether it can talk
+         * to this build at all.
+         *
+         * The standalone orchestrator has always answered this; library mode never
+         * did, so `avocado-cli start` probed it, got a 405, and printed
+         * "Orchestrator /health returned 405. CLI started anyway." on every start —
+         * a warning that means nothing, from the CLI's only compatibility check,
+         * which could therefore never pass against an embedded mount.
+         *
+         * Deliberately before the auth gate (see `PUBLIC_PATHS`) and deliberately
+         * content-free: it says what this process is, never what it holds.
+         */
+        if (request.method === "GET" && path === "/health") {
+            return jsonResponse({ ok: true, mode: "library", protocolVersion: EDITOR_PROTOCOL_VERSION }, { cors });
+        }
         if (request.method === "GET" && path === "/whoami") {
             const runtime = await getRuntime();
             await runtime.ready;
             const query = Object.fromEntries(url.searchParams);
             await runtime.bootstrapCache.ensure(scope(query.session, query.siteId), runtime.adapter, runtime.log);
-            return actionResponse(whoamiAction(query, url.origin, { hasAdapter: Boolean(runtime.adapter) }), cors);
+            /*
+             * `scope()` resolves the site the mount serves; `whoamiAction` re-derives
+             * the session key from what it is handed. Handing it the raw query meant
+             * the two disagreed whenever the caller omitted `siteId` — the bootstrap
+             * seeded `library::default` and the answer was read from the legacy key,
+             * so a correctly configured mount reported Avocado's bundled demo
+             * content, `source: "demo"`, and all-true capabilities in place of the
+             * adapter's own. The note even said "No siteId was supplied", which was
+             * true of the request and false of the configuration.
+             */
+            return actionResponse(whoamiAction({ ...query, siteId: effectiveSiteId ?? query.siteId }, url.origin, { hasAdapter: Boolean(runtime.adapter) }), cors);
         }
         /*
          * Publishing status, history and preview.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -23,8 +23,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.34.5",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/migration-sdk": "0.2.0",
-    "@avocadostudio-ai/shared": "0.2.0"
+    "@avocadostudio-ai/migration-sdk": "0.2.3",
+    "@avocadostudio-ai/shared": "0.2.3"
   },
   "devDependencies": {
     "@google/genai": "^1.46.0",
@@ -44,6 +44,17 @@
     "dist"
   ],
   "description": "Core Avocado Studio orchestrator — session state, AI planning, operations engine, publishing",
+  "keywords": [
+    "avocado",
+    "avocado-studio",
+    "cms",
+    "ai",
+    "llm",
+    "content-editor",
+    "page-builder",
+    "headless-cms",
+    "visual-editing"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://github.com/avocadostudio-ai/avocado/tree/main/packages/orchestrator-core#readme",
   "bugs": {