@avocadostudio-ai/orchestrator-core 0.11.4 → 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

@@ -22,6 +22,7 @@ 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 { 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) {
@@ -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),
@@ -1334,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;
@@ -2122,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/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.4",
+  "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/shared": "^0.11.4",
-    "@avocadostudio-ai/migration-sdk": "^0.11.4"
+    "@avocadostudio-ai/migration-sdk": "^0.11.5",
+    "@avocadostudio-ai/shared": "^0.11.5"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.220",