@avocadostudio-ai/orchestrator-core 0.11.3 → 0.11.5

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 } from "@avocadostudio-ai/shared";
+import { operationSchema, blockManifestSchema, siteConfigSchema, declareBlockCatalogue, undeclaredBlockTypes, EDITOR_PROTOCOL_VERSION, withLoopbackSpellings } 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";
@@ -230,7 +231,22 @@ function corsHeadersFor(request, config) {
          */
         return isProductionEnv() ? {} : { "access-control-allow-origin": origin, "vary": "Origin" };
     }
-    return config.corsOrigins.includes(origin)
+    /*
+     * `localhost` and `127.0.0.1` are the same machine, so an allowlist naming
+     * one grants the other.
+     *
+     * A caller writes one spelling — the scaffold's `.env.local` writes
+     * `localhost`, our own CLI's banner prints `127.0.0.1` on its first line —
+     * and a browser at the other one had every request answered `200` with no
+     * `access-control-allow-origin` and discarded before any code could see it.
+     * The site's `frame-ancestors` list has expanded both spellings since it was
+     * written; this one did not, so the preview frame was permitted and every
+     * call inside it was dropped.
+     *
+     * Only these two names, and only when the configured origin already uses
+     * one. Every other widening of an allowlist stays an explicit decision.
+     */
+    return withLoopbackSpellings(config.corsOrigins).includes(origin)
         ? { "access-control-allow-origin": origin, "vary": "Origin" }
         : {};
 }
@@ -301,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"
 ];
@@ -332,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) {
@@ -1114,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),
@@ -1319,8 +1354,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;
@@ -1571,6 +1627,23 @@ export function createOrchestrator(config = {}) {
                     {
                         id: effectiveSiteId ?? normalizeSiteId(query.siteId),
                         mode: "library",
+                        /*
+                         * The configured name, which this route had never carried.
+                         *
+                         * `/status/planner` reports it and `/sites` did not, so the
+                         * editor's site registry — which is fed from here — had nothing
+                         * to show but the id, and fell back to title-casing it. A
+                         * project in `demo-a/` configured as "The Avocado Hub" was
+                         * greeted as "Demo A" in the header and in the first sentence of
+                         * the welcome message.
+                         *
+                         * `demoContent` for the same reason: it decides which first-screen
+                         * suggestions the editor offers, and depending on a single
+                         * endpoint for it is what made those suggestions lose a race in
+                         * production.
+                         */
+                        ...(config.siteName ? { name: config.siteName } : {}),
+                        demoContent: config.demoContent === true,
                         ...(config.previewUrl ? { previewUrl: config.previewUrl } : {}),
                         ...(config.draftPath ? { draftPath: config.draftPath } : {}),
                         // A registration is more specific than a build-time default, so
@@ -2090,6 +2163,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/http/publish-actions.js

@@ -17,6 +17,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { withLoopbackSpellings } from "@avocadostudio-ai/shared";
 import { normalizeSession, scopedSessionKey, getSessionPages, getSiteConfig, publishedPages, publishStatusBySession, listPublishLog, findPublishLogForStatusUpdate, updatePublishLogStatusById } from "../state/session-state.js";
 import { computePublishDiff } from "../publish/diff-engine.js";
 import { refreshPublishStatusFromVercel } from "../publish/publish-helpers.js";
@@ -165,7 +166,15 @@ export function isSafeOrigin(raw) {
     if (isPrivate) {
         if (process.env.NODE_ENV !== "production")
             return true;
-        const corsOrigins = (process.env.ORCHESTRATOR_CORS_ORIGINS ?? "").split(",").map((s) => s.trim().replace(/\/+$/, ""));
+        /*
+         * Both loopback spellings, for the same reason CORS grants both: the
+         * declaration and the request are written by different hands. The scaffold
+         * writes `ORCHESTRATOR_CORS_ORIGINS=http://localhost:3000`; a site opened
+         * at `127.0.0.1` sends the other one, and `publish/diff` answered
+         * `400 siteOrigin is not an allowed URL` for an origin the deployment had
+         * in fact declared trusted.
+         */
+        const corsOrigins = withLoopbackSpellings((process.env.ORCHESTRATOR_CORS_ORIGINS ?? "").split(",").map((s) => s.trim().replace(/\/+$/, "")));
         const normalized = parsed.origin;
         if (corsOrigins.some((o) => o === normalized))
             return true;

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

@@ -74,7 +74,22 @@ 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, naming the file by its full path when we can.
+ *
+ * "Add it to `.env.local`" is a description of a file, not an address, and the
+ * person reading it is by definition the one who does not yet know the layout:
+ * the message arrives in a browser tab, on an origin that is not the site's,
+ * from a server started by a script they did not write. Saying *which*
+ * `.env.local` removes the only step in this instruction that requires a guess.
+ *
+ * Falls back to the constant above whenever a path would be wrong or
+ * unavailable — in production there is no dev server to restart and the file is
+ * not deployed, so a precise path there would be authoritative and false. See
+ * `keyFileHint`.
+ */
+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

@@ -627,10 +627,30 @@ export function blockContractsSummary(manifest) {
  */
 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) {
+/**
+ * The same notice, naming the file by its full path when we can.
+ *
+ * "Add it to `.env.local`" is a description of a file, not an address, and the
+ * person reading it is by definition the one who does not yet know the layout:
+ * the message arrives in a browser tab, on an origin that is not the site's,
+ * from a server started by a script they did not write. Saying *which*
+ * `.env.local` removes the only step in this instruction that requires a guess.
+ *
+ * Falls back to the constant above whenever a path would be wrong or
+ * unavailable — in production there is no dev server to restart and the file is
+ * not deployed, so a precise path there would be authoritative and false. See
+ * `keyFileHint`.
+ */
+export function keylessPlannerNotice(envFilePath) {
+    if (!envFilePath)
+        return KEYLESS_PLANNER_NOTICE;
+    return ("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 ${envFilePath} and restart the dev server to chat for real.`);
+}
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "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/migration-sdk": "^0.11.3",
-    "@avocadostudio-ai/shared": "^0.11.3"
+    "@avocadostudio-ai/migration-sdk": "^0.11.5",
+    "@avocadostudio-ai/shared": "^0.11.5"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.220",