@avocadostudio-ai/orchestrator-core 0.3.0 → 0.3.1

package/dist/agent/sites-agent-tools.js

@@ -19,7 +19,7 @@ import { scopedSessionKey, setPage, bumpVersion, getSiteConfig, setSiteConfig }
 import { listImages as listGdriveImages, downloadImage as downloadGdriveImage, isGdriveConfigured, resolveGdriveFolderId, fileNameToAlt, } from "../image/gdrive-client.js";
 import sharp from "sharp";
 import { sanitizeSiteId, monorepoRoot, findAvailablePort, patchGlobalsCssVars, validateAndCorrectProps, fixFooterLinks, analyzeCodebase, cloneRepo, detectSitePort, startAndWaitForDevServer, getDraftModeSecret, packageJson, nextConfigTs, tsconfigJson, postcssConfig, layoutTsx, globalsCss, defaultsTs, editorApiRoute, pageTsx, hybridPageTsx, blocksRegisterTsx, samplePagesJson, defaultLogoSvg, faviconSvg, } from "./sites-agent-shared.js";
-/** Convert a package name like "villa-puravida-web" → "Villa Puravida Web" */
+/** Convert a package name like "coastal-villa-web" → "Coastal Villa Web" */
 function humanizePkgName(name) {
     return name
         .replace(/^@[^/]+\//, "") // strip scope

package/dist/cms/bootstrap.d.ts

@@ -43,12 +43,36 @@ export interface CmsBootstrapCache {
      * clone and no extra adapter read. Re-reading upstream at publish time would
      * cost 45 sequential CMS calls on the integration that motivated this.
      *
-     * Bounded and best-effort by construction. It is null after a restart that
-     * reloaded the draft from SQLite (the seed never ran), and it is evicted
-     * FIFO past `maxBaselines`, so a caller must treat null as "no baseline
-     * available" and never as "the site was empty".
+     * Bounded and best-effort by construction. A restart that reloads the draft
+     * from SQLite skips the seed but not the baseline — `ensure` re-reads the
+     * adapter for it, which is sound because nothing was published in between —
+     * but it is still evicted FIFO past `maxBaselines`, and still null when the
+     * adapter read failed. A caller must treat null as "no baseline available"
+     * and never as "the site was empty".
      */
     baselineFor(session: string): PageDoc[] | null;
+    /**
+     * Discard this session's draft and seed it again from the adapter.
+     *
+     * `ensure()` is deliberately once-per-session: it exists to not clobber a
+     * draft that SQLite already holds. That is right for every ordinary request
+     * and wrong for the one case an integrator hits constantly while building an
+     * adapter — they change how their projection shapes pages, and the
+     * orchestrator keeps serving the shapes it read before the change. The only
+     * way out used to be deleting `.data/` and restarting the process, which is
+     * a much larger hammer than the problem.
+     *
+     * **This destroys unpublished edits in the session draft**, which is what
+     * makes it a separate, explicitly-requested call rather than something
+     * `ensure()` could decide to do on its own.
+     *
+     * It discards nothing until the adapter has answered: a failed read rejects
+     * and leaves the draft, the baseline and the attempt marker untouched, so a
+     * reseed against a CMS that happens to be down cannot cost anyone their
+     * work. A read that succeeds and returns no pages *is* an answer, and empties
+     * the draft accordingly.
+     */
+    reseed(session: string, adapter: CmsAdapter | null | undefined, log: Logger): Promise<void>;
     /** Test helper — drop all remembered state. */
     reset(): void;
     /** Inspection — number of remembered attempts (post-eviction). */

package/dist/cms/bootstrap.js

@@ -129,7 +129,31 @@ export function createCmsBootstrapCache(opts = {}) {
             return existing;
         const promise = (async () => {
             const draft = getSessionDraft(session);
-            if (draft.size > 0)
+            /*
+             * A draft that is already populated came from SQLite, not from us, and
+             * for a long time that was the end of the matter: seeding was the only
+             * thing this function did, so a loaded draft meant there was nothing to
+             * do. But the seed also produces the publish baseline, and that made the
+             * early return silently disable publishing. The draft survives a
+             * restart, so `ensure` returned here, so `rememberBaseline` never ran, so
+             * `context.published` was `undefined` for the rest of the process's life
+             * — and a publisher written the documented way (diff against the
+             * baseline, refuse when there is none) can then never publish again.
+             * Restarting to fix it is the one thing guaranteed not to.
+             *
+             * So the two jobs are now separate. A loaded draft still skips the seed;
+             * it no longer skips the baseline. Recovering it costs one
+             * `getPages()` — the same call the seed would have made, usually served
+             * from the warm cache — and it is correct to read upstream for it,
+             * because nothing has been published: the CMS still holds exactly the
+             * pre-edit content the lost baseline was a copy of.
+             *
+             * This is the same shape as the `setSessionCapabilities` hoist above.
+             * Anything the seed produces besides the draft has to survive a restart
+             * that reloads the draft.
+             */
+            const seeded = draft.size > 0;
+            if (seeded && baselines.has(session))
                 return; // finally-block records the attempt
             try {
                 const warmed = warmedPages(adapter);
@@ -139,13 +163,17 @@ export function createCmsBootstrapCache(opts = {}) {
                     return;
                 }
                 /*
-                 * Keep the pre-edit copy. The pages are already being cloned into the
-                 * draft, so a baseline for the eventual publish diff costs one more
+                 * Keep the pre-edit copy. When we are also seeding, the pages are
+                 * already being cloned into the draft, so the baseline costs one more
                  * clone and — the point — no second adapter read. Re-reading upstream
                  * at publish time is 45 sequential CMS calls on the integration that
                  * motivated this.
                  */
                 rememberBaseline(session, pages.map((page) => structuredClone(page)));
+                if (seeded) {
+                    log.info({ session, adapter: adapter.id, count: pages.length }, "cms-bootstrap: recovered publish baseline for a draft reloaded from storage");
+                    return;
+                }
                 for (const page of pages) {
                     const copy = structuredClone(page);
                     ensureHeroImageProps(copy);
@@ -174,9 +202,48 @@ export function createCmsBootstrapCache(opts = {}) {
             inFlight.delete(session);
         }
     }
+    async function reseed(session, adapter, log) {
+        if (!adapter)
+            return;
+        setSessionCapabilities(session, resolveCapabilities(adapter, capabilityOverride));
+        // Wait out a seed already in flight, so the discard below cannot land
+        // between that seed's adapter read and its writes and leave half a draft.
+        const existing = inFlight.get(session);
+        if (existing)
+            await existing.catch(() => { });
+        /*
+         * Read before discarding, not after. Clearing the draft and then calling
+         * `ensure` reads well and fails badly: `ensure` swallows an adapter error
+         * and marks the session attempted on the way out, so an adapter that was
+         * merely down turned a stale draft into an empty one that nothing would
+         * ever retry. The caller asked to replace the draft with what the adapter
+         * says; if the adapter says nothing, there is no replacement to make and
+         * the right answer is to leave the session exactly as we found it.
+         *
+         * This deliberately does not consult the warmed list. That list is a
+         * cold-start bridge and may predate whatever change prompted the reseed —
+         * serving it here would return the exact staleness we were asked to clear.
+         */
+        const pages = await adapter.getPages({ perspective: "draft" });
+        const draft = getSessionDraft(session);
+        const discarded = draft.size;
+        draft.clear();
+        for (const page of pages) {
+            const copy = structuredClone(page);
+            ensureHeroImageProps(copy);
+            draft.set(copy.slug, copy);
+        }
+        rememberBaseline(session, pages.map((page) => structuredClone(page)));
+        markAttempted(session);
+        warmEntry = null;
+        bumpVersion(session);
+        schedulePersistState(log);
+        log.info({ session, adapter: adapter.id, discarded, count: pages.length }, "cms-bootstrap: reseeded session draft from the adapter");
+    }
     return {
         ensure,
         warm,
+        reseed,
         baselineFor(session) {
             return baselines.get(session) ?? null;
         },

package/dist/cms/json-file-adapter.js

@@ -2,7 +2,7 @@
 //
 // Smallest possible adapter. Suitable for sites that keep their content as
 // a checked-in JSON array (the shape the orchestrator + blocks already
-// understand). villa-puravida-web's lib/published-content.json is the
+// understand). A consumer site's lib/published-content.json is the
 // canonical example.
 //
 // If `writeOnPublish` is true, onPublish() will overwrite the file with the

package/dist/handler/create-orchestrator.js

@@ -123,7 +123,7 @@ async function buildRuntime(config) {
      * Start the adapter's page read now rather than on the first request.
      *
      * `ensure()` is lazy, so without this the first caller pays for the whole
-     * CMS read: Paintball Arena Bern's adapter is 45 sequential Sanity reads
+     * CMS read: a tri-lingual site's adapter is 45 sequential Sanity reads
      * behind a dev-server compile, and the `whoami` an MCP agent opens with took
      * four minutes — long enough that the host times out and the agent reports
      * the site as down. Fire-and-forget by contract: a failed warm logs and is
@@ -872,10 +872,24 @@ export function createOrchestrator(config = {}) {
             await runtime.ready;
             const session = url.searchParams.get("session") ?? undefined;
             const siteId = url.searchParams.get("siteId") ?? undefined;
-            const slug = url.searchParams.get("slug") ?? undefined;
-            if (!session || !slug) {
+            const slug = url.searchParams.get("slug");
+            if (!session || slug === null) {
                 return jsonResponse({ error: "session and slug are required" }, { status: 400, cors });
             }
+            /*
+             * `?slug=` is a parameter that is present and empty, and answering
+             * "required" sends the integrator to look for a bug in their query
+             * string. What it actually means is that their projection emitted bare
+             * paths: a slug is a leading-slash path and the home page's is `"/"`.
+             * Every other bare slug resolves by string equality, so the home page is
+             * the only one that fails, and it fails as the site's own 404 rendered
+             * inside the editor iframe — which reads as "my site is broken".
+             */
+            if (slug === "") {
+                return jsonResponse({
+                    error: 'slug must not be empty: a page slug is a path beginning with "/", and the home page is "/" rather than ""'
+                }, { status: 400, cors });
+            }
             const scopedSession = scope(session, siteId);
             await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
             const page = getPage(scopedSession, slug);
@@ -915,9 +929,25 @@ export function createOrchestrator(config = {}) {
                 })
             }, { status: 200, cors });
         }
-        // Editor bootstrap probe. In library mode the adapter is the source of
-        // truth (already seeded by ensure), so this is effectively a confirm — we
-        // don't clobber the draft with the posted pages.
+        /*
+         * Editor bootstrap probe. In library mode the adapter is the source of
+         * truth (already seeded by ensure), so this is effectively a confirm — we
+         * don't clobber the draft with the posted pages.
+         *
+         * `force` was accepted by the standalone orchestrator and silently dropped
+         * here: the body was read as `{session, siteId}` and nothing else, so a
+         * caller asking to re-read the adapter got the cached page list back with
+         * a 200 and the word "bootstrapped" on it. That is worse than refusing,
+         * because the shape an integrator is in when they send it is "I changed my
+         * projection and the orchestrator is still serving the old shapes" — and
+         * the answer looks like confirmation that it re-read. The documented
+         * escape was deleting `.data/` and restarting.
+         *
+         * It now does what it says, including the destructive half: the session
+         * draft is discarded and rebuilt from the adapter, so unpublished edits in
+         * it are lost. `forced` comes back in the response so a caller can tell
+         * which of the two things happened.
+         */
         if (request.method === "POST" && path === "/draft/bootstrap") {
             const runtime = await getRuntime();
             await runtime.ready;
@@ -930,9 +960,31 @@ export function createOrchestrator(config = {}) {
             }
             const body = (raw ?? {});
             const scopedSession = scope(body.session, body.siteId);
-            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            const force = body.force === true;
+            if (force) {
+                try {
+                    await runtime.bootstrapCache.reseed(scopedSession, runtime.adapter, runtime.log);
+                }
+                catch (err) {
+                    /*
+                     * A forced reseed reaches the adapter and can fail there, and the
+                     * one thing this route must not do is answer "bootstrapped" when it
+                     * did not bootstrap — that is the failure being fixed, in a new
+                     * costume. The reseed discards nothing before the read succeeds, so
+                     * the draft is intact and saying so is the useful half of the reply.
+                     */
+                    return jsonResponse({
+                        error: "reseed failed: the adapter could not be read",
+                        detail: err instanceof Error ? err.message : String(err),
+                        draft: "unchanged"
+                    }, { status: 502, cors });
+                }
+            }
+            else {
+                await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            }
             const pages = getSessionPages(scopedSession);
-            return jsonResponse({ status: "bootstrapped", count: pages.length, slugs: pages.map((p) => p.slug) }, { status: 200, cors });
+            return jsonResponse({ status: "bootstrapped", forced: force, count: pages.length, slugs: pages.map((p) => p.slug) }, { status: 200, cors });
         }
         // Site config — drives the page-level nav-label + SEO fields shown in the
         // property panel when no block is selected.

package/dist/http/screenshot-actions.d.ts

@@ -19,7 +19,7 @@
  * `/preview-draft` is only the *default*, though, and it was hardcoded — which
  * meant this route worked on sites `create-ai-site-editor` scaffolded and on no
  * others. An existing site that wires Avocado into its own app has its own
- * draft route (Paintball Arena Bern's is `/avocado/<lang>/<slug>`), and the
+ * draft route (one such site's is `/avocado/<lang>/<slug>`), and the
  * screenshot an agent took to check its own work photographed that site's 404
  * page. So the path is declarable: per request, per registered site, or via
  * `createOrchestrator({ draftPath })`.

package/dist/http/screenshot-actions.js

@@ -19,7 +19,7 @@
  * `/preview-draft` is only the *default*, though, and it was hardcoded — which
  * meant this route worked on sites `create-ai-site-editor` scaffolded and on no
  * others. An existing site that wires Avocado into its own app has its own
- * draft route (Paintball Arena Bern's is `/avocado/<lang>/<slug>`), and the
+ * draft route (one such site's is `/avocado/<lang>/<slug>`), and the
  * screenshot an agent took to check its own work photographed that site's 404
  * page. So the path is declarable: per request, per registered site, or via
  * `createOrchestrator({ draftPath })`.

package/dist/ops/ops-engine.js

@@ -423,7 +423,7 @@ function _resolveBlockIndex(blocks, blockId, fuzzyMatches) {
  * Drop an adapter's provenance keys from a block that is being copied.
  *
  * A projected block carries the adapter's answer to "which upstream thing is
- * this", and the adapter routes the write by it: Paintball Arena Bern marks a
+ * this", and the adapter routes the write by it: a field-level-i18n CMS marks a
  * block with `props._sectionId` and publishes anything carrying one into the
  * *shared section document* rather than into the page. Copied verbatim onto a
  * duplicate, the first edit to that duplicate's hero is written back into the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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.3.0",
-    "@avocadostudio-ai/shared": "^0.3.0"
+    "@avocadostudio-ai/migration-sdk": "^0.3.1",
+    "@avocadostudio-ai/shared": "^0.3.1"
   },
   "devDependencies": {
     "@google/genai": "^1.46.0",
@@ -56,7 +56,7 @@
     "visual-editing"
   ],
   "license": "Apache-2.0",
-  "homepage": "https://github.com/avocadostudio-ai/avocado/tree/main/packages/orchestrator-core#readme",
+  "homepage": "https://docs.avocadostudio.dev",
   "bugs": {
     "url": "https://github.com/avocadostudio-ai/avocado/issues"
   },