@avocadostudio-ai/site-sdk 0.1.0 → 0.2.0

package/dist/publish/field-diff.test.js

@@ -0,0 +1,286 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { diffFields, diffPage, groupPatches, mergeDiffs, describeUnsupported, deepEqual, sanityPaths, indexPaths } from "./field-diff.js";
+const ctx = { lang: "de" };
+/** The common case: the prop is the field, and the value round-trips. */
+const plain = (key) => ({
+    rehydrate: (props) => props[key]
+});
+test("an unchanged field emits nothing", () => {
+    const specs = { heading: plain("heading") };
+    const diff = diffFields({
+        specs,
+        props: { heading: "Same" },
+        source: { heading: "Same" },
+        ctx,
+        documentId: "doc1",
+        where: "/ → hero"
+    });
+    assert.deepEqual(diff.patches, []);
+    assert.deepEqual(diff.unsupported, []);
+});
+test("a changed field is set at the path that owns it", () => {
+    const diff = diffFields({
+        specs: { heading: plain("heading") },
+        props: { heading: "After" },
+        source: { heading: "Before" },
+        ctx,
+        documentId: "doc1",
+        prefix: 'pageBuilder[_key=="b1"].',
+        where: "/ → hero"
+    });
+    assert.deepEqual(diff.patches, [
+        { documentId: "doc1", path: 'pageBuilder[_key=="b1"].heading', value: "After" }
+    ]);
+});
+test("cmsKey writes to the field the CMS actually has", () => {
+    const diff = diffFields({
+        specs: { heading: { ...plain("heading"), cmsKey: "headingOverride" } },
+        props: { heading: "After" },
+        source: { heading: "Before" },
+        ctx,
+        documentId: "doc1",
+        where: "/ → hero"
+    });
+    assert.equal(diff.patches[0].path, "headingOverride");
+});
+test("rehydrate receives the stored value, so an inversion can be partial", () => {
+    // The whole reason a snapshot contract cannot work: the editor saw
+    // `image.url`, the CMS holds an asset reference beside it, and only the
+    // integration knows how to put one back without destroying the other.
+    const specs = {
+        image: {
+            rehydrate: (props, before) => ({
+                ...before,
+                alt: props.imageAlt ?? undefined
+            })
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { imageAlt: "New alt" },
+        source: { image: { _type: "image", asset: { _ref: "image-abc" }, alt: "Old alt" } },
+        ctx,
+        documentId: "doc1",
+        where: "/ → hero"
+    });
+    assert.deepEqual(diff.patches[0].value, {
+        _type: "image",
+        asset: { _ref: "image-abc" },
+        alt: "New alt"
+    });
+});
+// ---------------------------------------------------------------------------
+// The refusals
+// ---------------------------------------------------------------------------
+test("refusal 1 — a projection that cannot be inverted is reported, not guessed", () => {
+    const specs = {
+        image: {
+            rehydrate: (props, before) => ({ ...before, url: props.imageUrl }),
+            write: ({ before, after, emit, reject, path }) => {
+                const was = before;
+                const now = after;
+                if (was?.alt !== now.alt)
+                    emit(`${path}.alt`, now.alt);
+                if (was?.url !== now.url) {
+                    reject(`the image was replaced (${now.url})`, "The CMS stores an asset reference; the file has to be uploaded first.");
+                }
+            }
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { imageUrl: "https://example.com/new.png" },
+        source: { image: { url: "https://cdn.example.com/old.png", alt: "Old" } },
+        ctx,
+        documentId: "doc1",
+        where: "/ → hero"
+    });
+    assert.deepEqual(diff.patches, [], "nothing may be written for a value that cannot be expressed");
+    assert.equal(diff.unsupported.length, 1);
+    assert.match(diff.unsupported[0].change, /image was replaced/);
+    assert.match(String(diff.unsupported[0].remedy), /uploaded first/);
+});
+test("refusal 2 — adding or removing list items is a document-shaped change", () => {
+    const specs = {
+        cards: {
+            rehydrate: (props) => props.cards,
+            itemFields: { title: plain("title") }
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
+        source: { cards: [{ _key: "k1", title: "One" }] },
+        ctx,
+        documentId: "doc1",
+        where: "/ → cardGrid"
+    });
+    assert.ok(diff.unsupported.some((u) => /added to or removed/.test(u.change)));
+});
+test("refusal 3 — an item the CMS has never seen has no path to patch", () => {
+    const specs = {
+        cards: {
+            rehydrate: (props) => props.cards,
+            itemFields: { title: plain("title") }
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { cards: [{ _key: "k1", title: "One" }, { title: "Brand new" }] },
+        source: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
+        ctx,
+        documentId: "doc1",
+        where: "/ → cardGrid"
+    });
+    assert.ok(diff.unsupported.some((u) => /new item/.test(u.change)));
+    assert.ok(!diff.patches.some((p) => p.value === "Brand new"), "a keyless item must not be written to whatever path happens to be at its index");
+});
+test("refusal 4 — a block with no upstream document is reported, never skipped", () => {
+    const diff = diffPage({
+        page: {
+            slug: "/prices",
+            blocks: [{ id: "b_new", type: "pba_pricingSection", props: { heading: "Hi" } }]
+        },
+        ctx,
+        locate: () => null
+    });
+    assert.deepEqual(diff.patches, []);
+    assert.equal(diff.unsupported.length, 1);
+    assert.match(diff.unsupported[0].change, /new "pba_pricingSection" block/);
+    assert.equal(diff.unsupported[0].where, "/prices → pba_pricingSection");
+});
+// ---------------------------------------------------------------------------
+// Lists, keys, and the reason index addressing is not the default
+// ---------------------------------------------------------------------------
+test("a list item is patched at its own key, not at its position", () => {
+    const specs = {
+        cards: {
+            rehydrate: (props) => props.cards,
+            itemFields: { title: plain("title") }
+        }
+    };
+    // The upstream order is the reverse of the editor's. Index addressing would
+    // write "Renamed" onto the wrong card.
+    const diff = diffFields({
+        specs,
+        props: { cards: [{ _key: "k2", title: "Renamed" }, { _key: "k1", title: "One" }] },
+        source: { cards: [{ _key: "k1", title: "One" }, { _key: "k2", title: "Two" }] },
+        ctx,
+        documentId: "doc1",
+        where: "/ → cardGrid"
+    });
+    assert.deepEqual(diff.patches, [
+        { documentId: "doc1", path: 'cards[_key=="k2"].title', value: "Renamed" }
+    ]);
+});
+test("index addressing is available and says what it costs", () => {
+    const specs = {
+        rows: {
+            rehydrate: (props) => props.rows,
+            itemFields: { label: plain("label") },
+            itemKey: (item) => String(item.id)
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { rows: [{ id: "7", label: "After" }] },
+        source: { rows: [{ id: "7", label: "Before" }] },
+        ctx,
+        documentId: "doc1",
+        where: "/ → table",
+        paths: indexPaths
+    });
+    assert.deepEqual(diff.patches, [{ documentId: "doc1", path: "rows[0].label", value: "After" }]);
+});
+test("a custom itemKey identifies items that have no _key", () => {
+    const specs = {
+        rows: {
+            rehydrate: (props) => props.rows,
+            itemFields: { label: plain("label") },
+            itemKey: (item) => (typeof item.id === "string" ? item.id : undefined)
+        }
+    };
+    const diff = diffFields({
+        specs,
+        props: { rows: [{ id: "r1", label: "After" }] },
+        source: { rows: [{ id: "r1", label: "Before" }] },
+        ctx,
+        documentId: "doc1",
+        where: "/ → table",
+        paths: sanityPaths
+    });
+    assert.deepEqual(diff.patches, [
+        { documentId: "doc1", path: 'rows[_key=="r1"].label', value: "After" }
+    ]);
+});
+// ---------------------------------------------------------------------------
+// Routing across documents
+// ---------------------------------------------------------------------------
+test("one block can write to two documents", () => {
+    // A block placed by a shared section: its heading override belongs to the
+    // page, the rest of it belongs to the section every page shares.
+    const diff = diffPage({
+        page: {
+            slug: "/",
+            blocks: [{ id: "b1", type: "sharedSection", props: { heading: "Page heading", body: "Shared body" } }]
+        },
+        ctx,
+        locate: () => [
+            {
+                documentId: "page-1",
+                prefix: 'pageBuilder[_key=="b1"].',
+                specs: { heading: { ...plain("heading"), cmsKey: "headingOverride" } },
+                source: { heading: "Old page heading" }
+            },
+            {
+                documentId: "section-9",
+                prefix: "content[0].",
+                specs: { body: plain("body") },
+                source: { body: "Old shared body" }
+            }
+        ]
+    });
+    assert.deepEqual(groupPatches(diff.patches), [
+        { documentId: "page-1", set: { 'pageBuilder[_key=="b1"].headingOverride': "Page heading" } },
+        { documentId: "section-9", set: { "content[0].body": "Shared body" } }
+    ]);
+});
+test("a page with nothing changed issues no write at all", () => {
+    const diff = diffPage({
+        page: { slug: "/", blocks: [{ id: "b1", type: "hero", props: { heading: "Same" } }] },
+        ctx,
+        locate: () => ({
+            documentId: "page-1",
+            prefix: "",
+            specs: { heading: plain("heading") },
+            source: { heading: "Same" }
+        })
+    });
+    assert.deepEqual(groupPatches(diff.patches), [], "an unchanged publish must not touch the CMS");
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+test("deepEqual treats null and undefined as the same absence", () => {
+    // A CMS that omits an empty field and an editor that sends `undefined` are
+    // saying the same thing; treating them as a change rewrites every optional
+    // field on every publish.
+    assert.ok(deepEqual(null, undefined));
+    assert.ok(deepEqual({ a: [1, { b: "c" }] }, { a: [1, { b: "c" }] }));
+    assert.ok(!deepEqual({ a: 1 }, { a: 1, b: 2 }));
+    assert.ok(!deepEqual([1, 2], { 0: 1, 1: 2 }));
+});
+test("mergeDiffs and describeUnsupported produce something a person can read", () => {
+    const merged = mergeDiffs([
+        { patches: [{ documentId: "d", path: "a", value: 1 }], unsupported: [] },
+        {
+            patches: [],
+            unsupported: [{ where: "/ → hero", change: "the image was replaced", remedy: "Upload it first." }]
+        }
+    ]);
+    assert.equal(merged.patches.length, 1);
+    assert.deepEqual(describeUnsupported(merged.unsupported), [
+        "/ → hero: the image was replaced — Upload it first."
+    ]);
+});

package/dist/server/orchestrator.d.ts

@@ -1,117 +1 @@
-import { type AIProvider, type ModelKey } from "@avocadostudio-ai/orchestrator-core/state/session-state.js";
-import { type Logger } from "@avocadostudio-ai/orchestrator-core/logger.js";
-import type { CmsAdapter } from "@avocadostudio-ai/orchestrator-core/cms/adapter.js";
-export interface CreateOrchestratorConfig {
-    /**
-     * Provider model overrides. Defaults to env vars (OPENAI_MODEL_*, ANTHROPIC_MODEL_*,
-     * GOOGLE_GENAI_MODEL_*). Pass an explicit object to override per-tier model names.
-     */
-    modelLookup?: Record<AIProvider, Record<ModelKey, string>>;
-    /**
-     * Override available providers. Defaults to whichever API keys are present in
-     * process.env (OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_GENAI_API_KEY).
-     */
-    availableProviders?: AIProvider[];
-    /** Pino-shaped logger. Defaults to a console-backed implementation. */
-    logger?: Logger;
-    /**
-     * Allowed CORS origins. Defaults to "*". For production, pass an explicit
-     * allow-list (Next.js can also handle CORS via middleware — pass null here
-     * to disable the SDK's CORS handling entirely).
-     */
-    corsOrigins?: string[] | "*" | null;
-    /**
-     * Register the default builtin tools (unsplash-search, image-generate,
-     * gdrive-browse). Defaults to `false` — opt in only if you want those
-     * features, since registering them pulls in sharp + googleapis + image-gen
-     * SDKs at module load. Pass `true` for env-gated defaults, or an explicit
-     * subset like `["unsplash-search"]`.
-     */
-    builtinTools?: boolean | Array<"unsplash-search" | "image-generate" | "gdrive-browse">;
-    /**
-     * URL path prefix the handler is mounted under. Everything matching this
-     * prefix is stripped off `url.pathname` before route matching, so the rest
-     * of the handler can reason in terms of `/chat`, `/chat/stream`, etc.
-     *
-     * Defaults to `/api/avocado` (the catch-all path used in the Next.js
-     * example app). Set to `""` if you want to match against the full pathname
-     * yourself, or override to e.g. `/api/orchestrator` if you mount the
-     * catch-all there.
-     */
-    basePath?: string;
-    /**
-     * Source-of-truth adapter for the site's existing content. Called once per
-     * session on the first chat request to seed SQLite with the site's pages.
-     * Without an adapter the orchestrator starts with an empty draft, which
-     * means the planner has no pages to edit — every "edit the homepage" turn
-     * returns `page not found`.
-     *
-     * Provided implementations:
-     *  - `jsonFileAdapter({ path })` — read PageDoc[] from a JSON file
-     *  - `editorApiAdapter({ origin })` — fetch from `${origin}/api/editor/pages`
-     *
-     * Import from `@avocadostudio-ai/orchestrator-core/cms`.
-     */
-    adapter?: CmsAdapter;
-    /**
-     * Site identifier used to scope session state in SQLite. When `adapter` is
-     * set, defaults to `"library"` so the demo-content seed path is bypassed
-     * (an unscoped session falls back to the orchestrator's bundled demo pages).
-     * Override if you want to run multiple distinct sites against one process.
-     *
-     * Precedence on incoming requests:
-     *   - adapter configured: `siteId` (or its `"library"` default) ALWAYS wins
-     *     over `body.siteId`. The library-mode orchestrator owns its identity.
-     *   - no adapter: explicit `siteId` wins; otherwise `body.siteId` is used.
-     */
-    siteId?: string;
-    /**
-     * Register the site's block schemas before the orchestrator's first chat
-     * request. Use this instead of relying on side-effect import order: in
-     * library mode, the orchestrator's transitive imports of
-     * `@avocadostudio-ai/shared` re-register canonical Hero/CTA/etc. on the
-     * shared globalThis registry, often AFTER the host app's overrides.
-     *
-     * **Fires once per orchestrator runtime** — at `buildRuntime` time, not
-     * per-request. For long-lived production processes this is fine, but if
-     * the host re-builds the runtime on hot-reload, ensure the schemas survive
-     * (registerBlock is idempotent — calling again is safe). Pair this with
-     * the same `registerBlocks` passed to `createEditorApiHandler`, which
-     * re-runs on every `/blocks` request, to cover request-time too.
-     */
-    registerBlocks?: () => void;
-    /**
-     * Local directory where `POST /image/upload` writes uploaded files and
-     * `GET /generated-images/:fileName` reads them back. Defaults to
-     * `.data/generated-images` under the host process CWD.
-     *
-     * **POC-grade storage.** Files live on the orchestrator host's local disk
-     * with no CDN, no image transforms, and no durability guarantee — on an
-     * ephemeral filesystem (e.g. a container without a mounted volume) uploads
-     * vanish on redeploy. See `docs/image-storage-options.md` for the path to a
-     * blob/CDN backend; that swap is contained to these two routes.
-     */
-    imageDir?: string;
-}
-/**
- * A handler returned by {@link createOrchestrator}. Callable like the bare
- * Web `(Request) => Promise<Response>` it always was, with an extra
- * `dispose()` method to release the resumable-stream sweep timer (call this
- * during dev hot-reload or test teardown).
- */
-export type OrchestratorHandler = ((request: Request) => Promise<Response>) & {
-    dispose(): Promise<void>;
-};
-export type { CmsAdapter, CmsInlineAsset, CmsPublishContext, CmsPublishResult } from "@avocadostudio-ai/orchestrator-core/cms/adapter.js";
-export { jsonFileAdapter, editorApiAdapter } from "@avocadostudio-ai/orchestrator-core/cms/index.js";
-/**
- * Build a Web-standard request handler that wraps the orchestrator brain.
- *
- * Usage in Next.js App Router (`app/api/avocado/[[...path]]/route.ts`):
- *
- *     export const runtime = "nodejs"
- *     const handler = createOrchestrator()
- *     export const POST = handler
- *     export const OPTIONS = handler
- */
-export declare function createOrchestrator(config?: CreateOrchestratorConfig): OrchestratorHandler;
+export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, type CreateOrchestratorConfig, type OrchestratorHandler, type OrchestratorAuth, type AuthContext, type CmsAdapter, type CmsCapabilities, type CmsInlineAsset, type CmsPublishContext, type CmsPublishResult, type CmsPerspective, type CmsReadOptions, type ResolvedCapabilities } from "@avocadostudio-ai/orchestrator-core";