@avocadostudio-ai/orchestrator-core 0.11.4 → 0.11.6

package/dist/chat/chat-pipeline.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { keyFileHint } from "../env-file-location.js";
 import { blockManifestSchema } from "@avocadostudio-ai/shared";
 import { GENERATING_IMAGE_PLACEHOLDER, SEARCHING_IMAGE_PLACEHOLDER, isGeneratingPlaceholder, cleanupImagePlaceholders, buildPageDirectory, isVariationRequestMessage, variationVerbIntent, resolveEffectiveSlug, throwIfCanceled, raceCancel, sleepMs, suppressCancelOnly } from "./chat-pipeline-shared.js";
 import { siteCapabilitiesSchema, isBatchAddRequest, isDuplicateBlockRequest, isBlockCatalogQuery, isInfoQuery, isContentQuery, isPageListQuery, requestsPlanFirst, plannerMessageWithPendingContext, buildSiteContextBlock, infoResponse } from "../nlp/intent-detection.js";
@@ -2997,7 +2998,7 @@ export async function runChatPipeline(ctx, body, options) {
         markPlanningStart();
         try {
             emitStatusTone("planning");
-            const demoPlan = withKeylessNotice(demoPlanFromMessageImpl(plannerMessage, effectiveSlug, planningActiveBlockId, body.activeBlockType));
+            const demoPlan = withKeylessNotice(demoPlanFromMessageImpl(plannerMessage, effectiveSlug, planningActiveBlockId, body.activeBlockType), keyFileHint());
             markPlanningFinish();
             const outcome = await respondFromPlan(demoPlan, "demo", applyMode, undefined, "demo");
             if (outcome.done)

package/dist/env-file-location.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolve the absolute path of the file to add the key to.
+ *
+ * Walks up from `cwd` for a directory that already holds a `package.json`,
+ * taking an existing env file there if there is one and naming the file that
+ * *should* exist if there is not. Returns the caller's best guess rather than
+ * nothing: a path that does not exist yet is still the right answer to "where
+ * do I put this", and creating it is the instruction.
+ */
+export declare function resolveEnvFilePath(cwd?: string): string;
+/**
+ * The path to show a user, or `undefined` when showing one would be wrong.
+ *
+ * Withheld in production for two reasons, and the second is the one that
+ * matters. It would put a server filesystem path into a browser — mildly
+ * careless on its own. But the advice attached to it ("add it to this file and
+ * restart the dev server") is also simply **false** in production: there is no
+ * dev server, the file is not deployed, and a key added to it changes nothing.
+ * A precise path attached to instructions that cannot work is worse than the
+ * vague version, because it reads as authoritative.
+ */
+export declare function keyFileHint(env?: NodeJS.ProcessEnv): string | undefined;

package/dist/env-file-location.js

@@ -0,0 +1,77 @@
+/**
+ * Where the user should actually put their API key.
+ *
+ * Every piece of copy in this product tells someone to "add a key to
+ * `.env.local` in your project root — the same folder as `package.json`", and
+ * none of it says *which* folder that is. The editor runs on its own origin,
+ * usually started by a script the user did not write, from a directory they may
+ * not have chosen; the terminal they are reading is running two processes; and
+ * the instruction arrives inside a browser tab that has no filesystem at all.
+ * "Your project root" is a description, not an address, and the person reading
+ * it is precisely the person who does not yet know the layout.
+ *
+ * The server does know. It is running in that directory. So it says so.
+ *
+ * Only in development, deliberately — see `keyFileHint`.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/**
+ * The env files a key could live in, in the order the reader should prefer.
+ *
+ * `.env.local` first because that is what every doc and the scaffolder name,
+ * and because it is the one git ignores. `.env` second so an existing project
+ * that already keeps its secrets there is told to use the file it has rather
+ * than a second one that will silently take precedence.
+ */
+const CANDIDATES = [".env.local", ".env"];
+/** How far up to look before giving up. A monorepo puts the app a few levels down. */
+const MAX_DEPTH = 5;
+/**
+ * Resolve the absolute path of the file to add the key to.
+ *
+ * Walks up from `cwd` for a directory that already holds a `package.json`,
+ * taking an existing env file there if there is one and naming the file that
+ * *should* exist if there is not. Returns the caller's best guess rather than
+ * nothing: a path that does not exist yet is still the right answer to "where
+ * do I put this", and creating it is the instruction.
+ */
+export function resolveEnvFilePath(cwd = process.cwd()) {
+    let dir = resolve(cwd);
+    for (let depth = 0; depth < MAX_DEPTH; depth++) {
+        for (const candidate of CANDIDATES) {
+            if (existsSync(join(dir, candidate)))
+                return join(dir, candidate);
+        }
+        // No env file here, but if this is the project root then this is where one goes.
+        if (existsSync(join(dir, "package.json")))
+            return join(dir, CANDIDATES[0]);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return join(resolve(cwd), CANDIDATES[0]);
+}
+/**
+ * The path to show a user, or `undefined` when showing one would be wrong.
+ *
+ * Withheld in production for two reasons, and the second is the one that
+ * matters. It would put a server filesystem path into a browser — mildly
+ * careless on its own. But the advice attached to it ("add it to this file and
+ * restart the dev server") is also simply **false** in production: there is no
+ * dev server, the file is not deployed, and a key added to it changes nothing.
+ * A precise path attached to instructions that cannot work is worse than the
+ * vague version, because it reads as authoritative.
+ */
+export function keyFileHint(env = process.env) {
+    if ((env.NODE_ENV ?? "").trim() === "production")
+        return undefined;
+    try {
+        return resolveEnvFilePath();
+    }
+    catch {
+        // A sandboxed or read-only filesystem is not a reason to fail a chat turn.
+        return undefined;
+    }
+}

package/dist/handler/create-orchestrator.js

@@ -21,7 +21,8 @@ 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, EDITOR_PROTOCOL_VERSION, withLoopbackSpellings } from "@avocadostudio-ai/shared";
+import { operationSchema, blockManifestSchema, siteConfigSchema, declareBlockCatalogue, undeclaredBlockTypes, EDITOR_PROTOCOL_VERSION, withLoopbackSpellings, editorAllowHeaders } from "@avocadostudio-ai/shared";
+import { keyFileHint } from "../env-file-location.js";
 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";
@@ -316,6 +317,7 @@ const SUPPORTED_ROUTES = [
     "POST /image/generate",
     "POST /image/generate/chat",
     "POST /image/interpret",
+    "POST /attachment/upload",
     "POST /image/upload",
     "GET /generated-images/:fileName"
 ];
@@ -347,7 +349,14 @@ const EXT_TO_MIME = {
     webp: "image/webp",
     gif: "image/gif",
     avif: "image/avif",
-    svg: "image/svg+xml"
+    svg: "image/svg+xml",
+    /*
+     * Not an image, and it has to be here anyway: `/attachment/upload` accepts
+     * PDFs, and this map is what `/generated-images/` serves them back through.
+     * Without it a PDF uploads successfully and then 415s on the GET — stored,
+     * referenced in the chat, and unreadable.
+     */
+    pdf: "application/pdf"
 };
 export { jsonFileAdapter, editorApiAdapter, resolveCapabilities } from "../cms/index.js";
 function stripBasePath(pathname, basePath) {
@@ -527,7 +536,7 @@ export function createOrchestrator(config = {}) {
                      * would have been unreachable from the very client it is for.
                      */
                     "access-control-allow-methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
-                    "access-control-allow-headers": "content-type, x-access-token, authorization",
+                    "access-control-allow-headers": editorAllowHeaders(),
                     "access-control-max-age": "600"
                 }
             });
@@ -1129,6 +1138,17 @@ export function createOrchestrator(config = {}) {
                     ...(config.siteName ? { name: config.siteName } : {}),
                     demoContent: config.demoContent === true
                 },
+                /*
+                 * Where the user should put their key, as an absolute path.
+                 *
+                 * Every piece of copy naming `.env.local` describes a file without
+                 * addressing it, and the reader is in a browser tab with no
+                 * filesystem, on an origin that is not the site's. The server is
+                 * running in that directory, so it is the only party that can answer.
+                 * Absent in production, where the advice attached to it would be
+                 * false — see `env-file-location.ts`.
+                 */
+                ...(keyFileHint() ? { keyFilePath: keyFileHint() } : {}),
                 features: {
                     googleDrive: false,
                     unsplash: Boolean(process.env.UNSPLASH_ACCESS_KEY),
@@ -1138,6 +1158,23 @@ export function createOrchestrator(config = {}) {
                      * editor offers the picker's CMS tab on it, so silence hides the
                      * tab rather than opening one onto a method nobody implemented. */
                     cmsMedia: runtime.capabilities.readsMedia,
+                    /*
+                     * Whether `/audio/transcribe` can actually answer.
+                     *
+                     * This key was simply absent from library mode's feature list while
+                     * the standalone server has always reported it, and the editor's
+                     * check is `audioTranscription !== false` — so `undefined` read as
+                     * *available* and the microphone shipped visible in every
+                     * scaffolded project, including with no key configured at all.
+                     * Pressing it records audio and posts it to a route that can only
+                     * answer 503.
+                     *
+                     * The same providers as the standalone server, for the same reason:
+                     * transcription tries OpenAI first and falls back to Gemini, so
+                     * either key enables it and neither means the control must not be
+                     * offered.
+                     */
+                    audioTranscription: Boolean(process.env.OPENAI_API_KEY?.trim() || process.env.GOOGLE_GENAI_API_KEY?.trim()),
                     agentMode: false
                 },
                 /*
@@ -1334,8 +1371,29 @@ export function createOrchestrator(config = {}) {
             const scopedSession = scope(body.session, body.siteId);
             await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
             const parsedOps = z.array(operationSchema).safeParse(body.ops);
-            if (!parsedOps.success)
-                return jsonResponse({ error: "invalid ops payload", details: parsedOps.error.issues }, { status: 400, cors });
+            if (!parsedOps.success) {
+                /*
+                 * Name the key, and say what an operation looks like.
+                 *
+                 * Zod reports the *failure*, not the *expectation*: a body with no
+                 * `ops` array produced `{"expected":"array","path":[],"message":
+                 * "expected array, received undefined"}` — a root-level path pointing
+                 * at nothing, never naming `ops`. Someone wiring this by hand from the
+                 * documented op vocabulary needed three consecutive 400s to discover
+                 * the envelope key, then that the discriminator is `op` and not `type`,
+                 * and only then saw the real shape. Each error revealed exactly one
+                 * layer, which is the most expensive way to publish a schema.
+                 *
+                 * `example` is a valid minimal operation on purpose: it answers all
+                 * three of those questions at once, in the first response.
+                 */
+                return jsonResponse({
+                    error: "invalid ops payload",
+                    expected: "a JSON body of { session, siteId, ops: Operation[] }",
+                    example: { session: "dev", siteId: "my-site", ops: [{ op: "update_props", pageSlug: "/", blockId: "hero-1", patch: { heading: "New heading" } }] },
+                    details: parsedOps.error.issues
+                }, { status: 400, cors });
+            }
             if (parsedOps.data.length === 0)
                 return jsonResponse({ error: "ops must not be empty" }, { status: 400, cors });
             let manifest;
@@ -2122,6 +2180,72 @@ export function createOrchestrator(config = {}) {
             const bytes = Buffer.from(await file.arrayBuffer());
             return actionResponse(await interpretImageAction({ bytes, byteLength: bytes.byteLength, mimeType: file.type }, { log: runtime.log }), cors);
         }
+        /*
+         * The composer's paperclip, which library mode never answered.
+         *
+         * The editor's `useMediaInput` posts every chat attachment here,
+         * unconditionally and with no capability probe, and this handler had no
+         * such route — so the control shipped enabled on the first keyless screen
+         * of every scaffolded project and answered `405` with
+         * "not handled by createOrchestrator()" rendered in red under the composer.
+         * It existed only in the standalone Fastify orchestrator
+         * (`apps/orchestrator/src/routes/media.ts`), while library mode is what the
+         * scaffold ships and what the docs call the shape most integrations use.
+         * `features/chat-attachments.md` documents the flow with no caveat.
+         *
+         * Implemented rather than hidden, because nothing was actually missing:
+         * `/image/upload` below already writes to `imageDir` and
+         * `/generated-images/` already serves it back. The route was the only
+         * absent part, and a documented feature is better answered than suppressed.
+         *
+         * Accepts either field name. Fastify's multipart reader takes the first
+         * file part whatever it is called, so the standalone route never had to
+         * care; a Web `FormData` does. The composer sends `file`, the image
+         * endpoints send `image`, and making the two disagree across modes is how
+         * this class of defect started.
+         */
+        if (request.method === "POST" && path === "/attachment/upload") {
+            let form;
+            try {
+                form = await request.formData();
+            }
+            catch {
+                return jsonResponse({ error: "expected multipart/form-data body" }, { status: 400, cors });
+            }
+            const file = form.get("file") ?? form.get("image");
+            if (!(file instanceof File)) {
+                return jsonResponse({ error: "missing 'file' field" }, { status: 400, cors });
+            }
+            /*
+             * PDFs are attachable and are not images, so the image MIME map is not
+             * the right gate here — it is the gate for what a `<img>` can render.
+             */
+            const ext = file.type === "application/pdf" ? "pdf" : MIME_TO_EXT[file.type];
+            if (!ext) {
+                return jsonResponse({ error: `unsupported attachment type: ${file.type || "unknown"}` }, { status: 415, cors });
+            }
+            if (file.size > MAX_UPLOAD_BYTES) {
+                return jsonResponse({ error: `attachment exceeds ${MAX_UPLOAD_BYTES} byte limit` }, { status: 413, cors });
+            }
+            const fileName = `upload_${Date.now()}_${randomUUID().slice(0, 8)}.${ext}`;
+            try {
+                await mkdir(imageDir, { recursive: true });
+                await writeFile(resolve(imageDir, fileName), Buffer.from(await file.arrayBuffer()));
+            }
+            catch (err) {
+                return jsonResponse({ error: "attachment upload failed", detail: err instanceof Error ? err.message : String(err) }, { status: 500, cors });
+            }
+            return jsonResponse({
+                url: `${basePath}/generated-images/${fileName}`,
+                bytes: file.size,
+                mimeType: file.type,
+                // `name` and `kind` are what the composer renders in the attachment
+                // chip. Without them it falls back to the local File, which is right
+                // but makes the two modes' responses differ for no reason.
+                name: file.name,
+                kind: file.type === "application/pdf" ? "pdf" : "image"
+            }, { status: 200, cors });
+        }
         if (request.method === "POST" && path === "/image/upload") {
             let form;
             try {

package/dist/nlp/deterministic-planner-suggestions.d.ts

@@ -74,7 +74,31 @@ export declare function blockContractsSummary(manifest?: BlockManifest): Record<
  * they are the phrasings this planner *can* execute without a key.
  */
 export declare const KEYLESS_PLANNER_NOTICE: string;
-export declare function withKeylessNotice(plan: EditPlan): EditPlan;
+/**
+ * The same notice, without the *path*.
+ *
+ * An earlier version interpolated the absolute path of `.env.local` into the
+ * sentence. Correct, and it read appallingly: an 80-character path mid-
+ * paragraph, wrapping across four lines of a narrow pane, so a two-line
+ * explanation became a wall in which the actual advice was the least visible
+ * part — and it duplicated, word for word, the notice sitting directly below
+ * the conversation.
+ *
+ * The path belongs in exactly one place: the notice, where it is a selectable
+ * code block rather than prose. The variable names stay here, though, and a
+ * first attempt at removing those was wrong — `library-demo-identity.test.ts`
+ * pins them, and it is right to. **The notice is dismissible.** A message that
+ * says "see the notice below" is a dangling reference the moment someone closes
+ * it, and chat messages are also read in transcripts and telemetry where no
+ * notice exists. So this sentence has to stand alone; it just does not have to
+ * carry a filesystem path to do it.
+ *
+ * `envFilePath` is still accepted so callers need not know any of this. It
+ * changes nothing today and keeps the seam if a surface without the notice ever
+ * needs the long form.
+ */
+export declare function keylessPlannerNotice(_envFilePath?: string): string;
+export declare function withKeylessNotice(plan: EditPlan, envFilePath?: string): EditPlan;
 /**
  * Drop the suggestions this planner could not act on.
  *

package/dist/nlp/deterministic-planner-suggestions.js

@@ -625,12 +625,38 @@ export function blockContractsSummary(manifest) {
  * So when the rules produce no operations, say why. The suggestions are kept:
  * they are the phrasings this planner *can* execute without a key.
  */
-export const KEYLESS_PLANNER_NOTICE = "There's no AI key configured, so I'm running on the built-in demo planner — it only handles simple, literal edits. " +
-    "Add ANTHROPIC_API_KEY (or OPENAI_API_KEY) to .env.local and restart the dev server to chat for real.";
-export function withKeylessNotice(plan) {
+export const KEYLESS_PLANNER_NOTICE = "No API key is configured, so this is the built-in demo planner, which handles only simple, literal edits. " +
+    "Set ANTHROPIC_API_KEY or OPENAI_API_KEY in your project's .env.local and restart the dev server for full chat.";
+/**
+ * The same notice, without the *path*.
+ *
+ * An earlier version interpolated the absolute path of `.env.local` into the
+ * sentence. Correct, and it read appallingly: an 80-character path mid-
+ * paragraph, wrapping across four lines of a narrow pane, so a two-line
+ * explanation became a wall in which the actual advice was the least visible
+ * part — and it duplicated, word for word, the notice sitting directly below
+ * the conversation.
+ *
+ * The path belongs in exactly one place: the notice, where it is a selectable
+ * code block rather than prose. The variable names stay here, though, and a
+ * first attempt at removing those was wrong — `library-demo-identity.test.ts`
+ * pins them, and it is right to. **The notice is dismissible.** A message that
+ * says "see the notice below" is a dangling reference the moment someone closes
+ * it, and chat messages are also read in transcripts and telemetry where no
+ * notice exists. So this sentence has to stand alone; it just does not have to
+ * carry a filesystem path to do it.
+ *
+ * `envFilePath` is still accepted so callers need not know any of this. It
+ * changes nothing today and keeps the seam if a surface without the notice ever
+ * needs the long form.
+ */
+export function keylessPlannerNotice(_envFilePath) {
+    return KEYLESS_PLANNER_NOTICE;
+}
+export function withKeylessNotice(plan, envFilePath) {
     if (plan.ops.length > 0)
         return plan;
-    return { ...plan, summary_for_user: KEYLESS_PLANNER_NOTICE };
+    return { ...plan, summary_for_user: keylessPlannerNotice(envFilePath) };
 }
 /**
  * Drop the suggestions this planner could not act on.

package/dist/publish/diff-engine.js

@@ -159,15 +159,53 @@ function diffPage(before, after) {
     const a = after;
     const blockDiffs = diffBlocks(b.blocks, a.blocks);
     const titleChanged = b.title !== a.title;
+    const metaDiffs = diffPageMeta(b, a);
     const hasStructuralChange = blockDiffs.some((bd) => bd.status !== "unchanged");
     return {
         slug: a.slug,
-        status: titleChanged || hasStructuralChange ? "modified" : "unchanged",
+        status: titleChanged || metaDiffs.length > 0 || hasStructuralChange ? "modified" : "unchanged",
         titleBefore: titleChanged ? b.title : undefined,
         titleAfter: titleChanged ? a.title : undefined,
+        ...(metaDiffs.length > 0 ? { metaDiffs } : {}),
         blockDiffs,
     };
 }
+/**
+ * Page-level SEO fields, which the diff did not look at.
+ *
+ * A page's `meta` carries the title, description, Open Graph image and public
+ * path — everything a crawler and a social card read, and the whole content of
+ * the property panel's **SEO** section. None of it reached the publish review,
+ * so a user who edited their page title saw "1 page modified · 1 field changed"
+ * counting only the block they had also touched, and no mention of the title at
+ * all. The draft held the change; the screen that exists to show what will
+ * change did not show it.
+ *
+ * `ogImage` is typed as an image so the UI renders a thumbnail rather than a
+ * URL, matching how block image fields already behave.
+ */
+const PAGE_META_FIELDS = [
+    ["title", "text"],
+    ["description", "text"],
+    ["ogImage", "image"],
+    ["path", "other"]
+];
+function diffPageMeta(before, after) {
+    const b = (before.meta ?? {});
+    const a = (after.meta ?? {});
+    const out = [];
+    for (const [key, kind] of PAGE_META_FIELDS) {
+        const bv = b[key];
+        const av = a[key];
+        // Absent and empty are the same thing to a reader, and treating them as
+        // different produced phantom diffs on pages that had never had a value.
+        const normalise = (v) => (v === undefined || v === null || v === "" ? undefined : v);
+        if (normalise(bv) === normalise(av))
+            continue;
+        out.push({ path: `meta.${key}`, before: bv, after: av, kind });
+    }
+    return out;
+}
 // Keys of SiteConfig that drive the rendered SiteHeader chrome. We diff
 // only these to keep the publish UI focused on user-visible header changes;
 // `purpose`, `tone`, `constraints`, `themeOverrides` are AI/style context
@@ -276,6 +314,15 @@ export function computePublishDiff(draft, published, options) {
             if (bd.fieldDiffs)
                 totalChangedFields += bd.fieldDiffs.length;
         }
+        /*
+         * Page metadata counts as changed fields too.
+         *
+         * Three counters used to disagree on one screen — "1 field changed" here
+         * (blocks only), "2 changes" on the page row (which counted an added
+         * block), and "Publish 1 change" on the button — and a metadata edit moved
+         * none of them.
+         */
+        totalChangedFields += diff.metaDiffs?.length ?? 0;
     }
     const statusOrder = {
         added: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -22,8 +22,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.35.4",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/shared": "^0.11.4",
-    "@avocadostudio-ai/migration-sdk": "^0.11.4"
+    "@avocadostudio-ai/migration-sdk": "^0.11.6",
+    "@avocadostudio-ai/shared": "^0.11.6"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.220",