@avocadostudio-ai/orchestrator-core 0.1.0 → 0.2.1

package/dist/http/restore-actions.js

@@ -0,0 +1,145 @@
+/**
+ * Publish-snapshot restore — list, apply, delete — as transport-agnostic actions.
+ *
+ * These lived only in `apps/orchestrator/src/routes/publishing.ts`, wired
+ * directly into Fastify, even though the three git helpers they wrap have been
+ * in orchestrator-core all along. Library mode — `createOrchestrator()` in the
+ * site SDK — serves the same editor from a plain `Request`/`Response` handler
+ * and reimplements by hand whichever routes somebody remembered to add. It
+ * never had these, so the editor's restore panel answered "not handled by
+ * createOrchestrator()" for a UI that offers Restore unconditionally.
+ *
+ * As with `history-actions.ts`, a second hand-kept copy would drift the way the
+ * first one did, so the logic lives here and both transports call it. Each
+ * function returns the status code and body to send; neither Fastify nor
+ * `Response` appears in this file.
+ */
+import { normalizeSession, scopedSessionKey, getSessionDraft, ensureHeroImageProps, bumpVersion, markRecentlyRestored, schedulePersistState } from "../state/session-state.js";
+import { listRestoreSnapshots, loadPublishedSnapshotFromCommit, deletePublishSnapshot } from "../publish/publish-helpers.js";
+import { toErrorDetail } from "../errors.js";
+const realDeps = {
+    listSnapshots: listRestoreSnapshots,
+    loadSnapshot: loadPublishedSnapshotFromCommit,
+    deleteSnapshot: deletePublishSnapshot
+};
+const badRequest = (error) => ({ code: 400, body: { error } });
+/**
+ * Snapshots are addressed by git hash and nothing else, so anything that is not
+ * a hash is rejected before it can reach `git show`/`git revert` as an argument.
+ */
+const COMMIT_PATTERN = /^[0-9a-f]{7,40}$/i;
+const readCommit = (value) => (typeof value === "string" ? value.trim() : "");
+/**
+ * Whether the failure is "there is no git history to read here" rather than a
+ * fault worth a 500.
+ *
+ * `listRestoreSnapshots` runs `git log` in the repository root. A library-mode
+ * consumer's site is not the Avocado monorepo, and a container image often
+ * copies the build without its `.git` directory — both are ordinary situations
+ * where the honest answer is "no snapshots", and a restore panel showing an
+ * empty list is correct where one showing a red server error is not.
+ *
+ * The patterns are the three exact things git says in that situation. A bare
+ * `ENOENT` is deliberately not one of them: it appears in any failed file read
+ * anywhere below this call, and matching it would turn a genuine fault into a
+ * silent empty list — the failure mode this predicate exists to avoid causing.
+ */
+function isMissingGitHistory(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /not a git repository|does not have any commits yet|spawn git ENOENT/i.test(message);
+}
+/**
+ * The publish snapshots available to restore, newest first.
+ *
+ * One deliberate departure from the Fastify handler this replaces: that one
+ * answered 500 for *any* `git log` failure, including "this is not a
+ * repository". The editor prints `error` from the body straight into the
+ * restore panel, so an embedded site — which is never a checkout of this
+ * monorepo — got a red server error where the truthful answer is the panel's
+ * own "No snapshots available yet." Rewiring the standalone server through
+ * here changes that one case from 500 to 200 with an empty list.
+ */
+export async function restoreSnapshotsList(query, deps = realDeps) {
+    // An empty or blank `limit` is the absent case, not a limit of zero:
+    // `?limit=` reaches here as "", and `Number("")` is 0, which the git helper
+    // floors to 1 — one snapshot in a panel that asked for thirty.
+    const raw = typeof query.limit === "string" ? (query.limit.trim() || undefined) : query.limit;
+    const requested = typeof raw === "string" ? Number(raw) : raw;
+    const limit = typeof requested === "number" && Number.isFinite(requested) ? requested : 30;
+    const siteId = typeof query.siteId === "string" ? query.siteId.trim() : "";
+    try {
+        const snapshots = await deps.listSnapshots(limit, siteId || undefined);
+        return { code: 200, body: { snapshots } };
+    }
+    catch (error) {
+        if (isMissingGitHistory(error))
+            return { code: 200, body: { snapshots: [] } };
+        return { code: 500, body: { error: toErrorDetail(error) } };
+    }
+}
+/**
+ * Replace the session draft with the pages published in one commit.
+ *
+ * The draft is cleared and refilled rather than merged: a snapshot restore is
+ * meant to reproduce that commit exactly, and leaving pages behind that the
+ * snapshot does not contain would silently resurrect deleted ones.
+ *
+ * `markRecentlyRestored` is what stops the restore being undone a moment later
+ * — bootstrap seeding treats a session it has not seen as empty and would
+ * overwrite the freshly restored pages with demo or CMS content.
+ */
+export async function restoreSnapshotApply(body, log, deps = realDeps) {
+    const commit = readCommit(body.commit);
+    if (!COMMIT_PATTERN.test(commit))
+        return badRequest("commit is required (7-40 hex chars)");
+    const session = normalizeSession(body.session);
+    const scopedSession = scopedSessionKey(session, body.siteId);
+    try {
+        const pages = await deps.loadSnapshot(commit);
+        const draft = getSessionDraft(scopedSession);
+        draft.clear();
+        for (const page of pages) {
+            const clone = structuredClone(page);
+            ensureHeroImageProps(clone);
+            draft.set(clone.slug, clone);
+        }
+        const previewVersion = bumpVersion(scopedSession);
+        markRecentlyRestored(scopedSession);
+        schedulePersistState(log);
+        return {
+            code: 200,
+            body: {
+                status: "restored",
+                commit: commit.slice(0, 7),
+                session,
+                scopedSession,
+                slugs: pages.map((page) => page.slug),
+                previewVersion
+            }
+        };
+    }
+    catch (error) {
+        // A commit that does not exist, or whose published-content.json fails the
+        // page schema, is a bad request about the caller's commit — not a fault of
+        // this server.
+        return { code: 400, body: { error: toErrorDetail(error) } };
+    }
+}
+/** Drop a snapshot by reverting the commit that published it. */
+export async function restoreSnapshotDelete(body, deps = realDeps) {
+    const commit = readCommit(body.commit);
+    if (!COMMIT_PATTERN.test(commit))
+        return badRequest("commit is required (7-40 hex chars)");
+    try {
+        const ok = await deps.deleteSnapshot(commit);
+        if (!ok)
+            return badRequest("Failed to delete snapshot.");
+        return { code: 200, body: { status: "deleted", commit } };
+    }
+    catch (error) {
+        // `deletePublishSnapshot` catches every git failure itself and reports it
+        // as `false`, so a throw that gets this far is not the caller's commit
+        // being wrong — it is this server misbehaving, and 500 says so.
+        return { code: 500, body: { error: toErrorDetail(error) } };
+    }
+}

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

@@ -0,0 +1,108 @@
+/**
+ * `POST /preview/screenshot`, as a transport-agnostic action.
+ *
+ * It lived only in `apps/orchestrator/src/routes/preview.ts`, wired straight
+ * into Fastify. Library mode — `createOrchestrator()` in the site SDK — serves
+ * the same editor from a plain `Request`/`Response` handler and reimplements
+ * whichever routes somebody remembered to add. It never had this one, so every
+ * caller that screenshots a page — the MCP `screenshot-page` tool, the sites
+ * agent's own eyes on its work — answered "not handled by createOrchestrator()"
+ * against a library-mode host.
+ *
+ * A scaffolded site exposes `/preview-draft/[[...slug]]?session=X&siteId=Y`,
+ * which renders the orchestrator's draft content directly (no cookie dance —
+ * the route reads session + siteId from query params). We target that route by
+ * default so screenshots reflect in-progress edits, not just the last published
+ * snapshot. Callers can pass `published: true` to screenshot the public route
+ * instead (useful for before/after comparisons).
+ *
+ * `/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
+ * 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 })`.
+ */
+import type { Logger } from "../logger.js";
+import type { ActionResult } from "./history-actions.js";
+export type { ActionResult };
+export type ScreenshotParams = {
+    session?: string;
+    siteId?: string;
+    /** Page slug to screenshot — defaults to the home page ("/"). */
+    slug?: string;
+    /** Override the preview URL from the registered site config. */
+    previewUrl?: string;
+    /**
+     * Override the site's draft-preview route. Either a prefix the slug is
+     * appended to (`/avocado`) or a template naming where the slug goes
+     * (`/preview/{slug}/draft`). Defaults to the registered site's `draftPath`,
+     * then to `/preview-draft`.
+     */
+    draftPath?: string;
+    /** Screenshot the published route instead of the draft preview. Defaults to false. */
+    published?: boolean;
+};
+/** What `takeScreenshot` from the migration SDK returns, narrowed to what we read. */
+export type ScreenshotCapture = (url: string) => Promise<{
+    base64: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}>;
+export type ScreenshotDeps = {
+    /**
+     * Overrides the capture implementation. Tests inject a stub; nothing else
+     * needs to pass it.
+     */
+    takeScreenshot?: ScreenshotCapture;
+    /**
+     * What the host declared about itself, used when neither the request nor a
+     * registered site config says. A library-mode site knows its own URL and its
+     * own draft route at `createOrchestrator()` time, and making it call
+     * `/sites/register` against itself to say so is ceremony — but a registration
+     * that *did* happen is more specific than a build-time default, so these lose
+     * to it.
+     */
+    fallbackPreviewUrl?: string;
+    fallbackDraftPath?: string;
+    /**
+     * The state key to read the site config and the page under, when the caller
+     * has already computed one.
+     *
+     * `scopedSessionKey(session, siteId)` is the right answer for the standalone
+     * server, where the caller's `siteId` *is* the site's identity. Library mode
+     * owns its identity in `createOrchestrator({ siteId })` and overrides what
+     * the caller sent, so recomputing here reads a key nothing was written to —
+     * the same double-scoping that made `/publish/status` answer 404 forever.
+     * The raw `session` and `siteId` still go into the URL: they are what the
+     * site itself will hand back to `/draft/pages`, which scopes them the same
+     * way this caller did.
+     */
+    scopedSession?: string;
+};
+export type ScreenshotSuccessBody = {
+    url: string;
+    slug: string;
+    mode: "published" | "draft";
+    mimeType: "image/jpeg";
+    base64: string;
+    width: number;
+    height: number;
+};
+/** The route a site renders its orchestrator drafts on, when it declares none. */
+export declare const DEFAULT_DRAFT_PATH = "/preview-draft";
+/**
+ * Resolve a site's draft route for one slug.
+ *
+ * Two spellings, because two things are natural to write. A template naming
+ * `{slug}` puts the slug wherever the site's route wants it; anything else is a
+ * prefix and the slug is appended — which is what `/preview-draft` always was.
+ * The home page contributes nothing in either spelling, so `/` does not become
+ * a trailing slash the site has to be tolerant of.
+ */
+export declare function resolveDraftPath(template: string, normalizedSlug: string): string;
+/** Capture a full-page screenshot of one draft or published page. */
+export declare function screenshotAction(params: ScreenshotParams, log: Logger, deps?: ScreenshotDeps): Promise<ActionResult>;

package/dist/http/screenshot-actions.js

@@ -0,0 +1,181 @@
+/**
+ * `POST /preview/screenshot`, as a transport-agnostic action.
+ *
+ * It lived only in `apps/orchestrator/src/routes/preview.ts`, wired straight
+ * into Fastify. Library mode — `createOrchestrator()` in the site SDK — serves
+ * the same editor from a plain `Request`/`Response` handler and reimplements
+ * whichever routes somebody remembered to add. It never had this one, so every
+ * caller that screenshots a page — the MCP `screenshot-page` tool, the sites
+ * agent's own eyes on its work — answered "not handled by createOrchestrator()"
+ * against a library-mode host.
+ *
+ * A scaffolded site exposes `/preview-draft/[[...slug]]?session=X&siteId=Y`,
+ * which renders the orchestrator's draft content directly (no cookie dance —
+ * the route reads session + siteId from query params). We target that route by
+ * default so screenshots reflect in-progress edits, not just the last published
+ * snapshot. Callers can pass `published: true` to screenshot the public route
+ * instead (useful for before/after comparisons).
+ *
+ * `/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
+ * 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 })`.
+ */
+import { getPage, getSiteConfig, scopedSessionKey } from "../state/session-state.js";
+const badRequest = (error) => ({ code: 400, body: { error } });
+/** The route a site renders its orchestrator drafts on, when it declares none. */
+export const DEFAULT_DRAFT_PATH = "/preview-draft";
+/**
+ * Resolve a site's draft route for one slug.
+ *
+ * Two spellings, because two things are natural to write. A template naming
+ * `{slug}` puts the slug wherever the site's route wants it; anything else is a
+ * prefix and the slug is appended — which is what `/preview-draft` always was.
+ * The home page contributes nothing in either spelling, so `/` does not become
+ * a trailing slash the site has to be tolerant of.
+ */
+export function resolveDraftPath(template, normalizedSlug) {
+    const slugPart = normalizedSlug === "/" ? "" : normalizedSlug;
+    if (template.includes("{slug}"))
+        return template.replaceAll("{slug}", slugPart);
+    return template.replace(/\/+$/, "") + slugPart;
+}
+/*
+ * Injected dep with a lazy default, resolved through an import a bundler
+ * cannot see.
+ *
+ * `@avocadostudio-ai/migration-sdk` pulls in Playwright, which ships a browser
+ * driver and native binaries. A static import would drag all of it into every
+ * consumer of orchestrator-core — including a Next.js site that only wants
+ * `createOrchestrator()` and will never take a screenshot. A plain `await
+ * import(...)` is not enough either: webpack traces dynamic specifiers too, and
+ * wiring this route into library mode made a real Next 16 host answer 500 with
+ * "Module parse failed: Unexpected character '\u0000'" — it had tried to bundle
+ * a binary.
+ *
+ * Hiding the specifier behind `new Function` defeats that analysis, which is
+ * the point: the module is resolved by Node at call time, and only when
+ * somebody actually asks for a screenshot. The alternative — making every
+ * integrator add the package to `serverExternalPackages` — pushes our
+ * dependency's shape into their config.
+ *
+ * The injected dep on top of that buys the test seam: stubbing the capture is
+ * what lets the URL-building rules below be asserted without a browser.
+ */
+const runtimeImport = new Function("specifier", "return import(specifier)");
+async function resolveCapture() {
+    const { takeScreenshot } = await runtimeImport("@avocadostudio-ai/migration-sdk");
+    if (typeof takeScreenshot !== "function") {
+        throw new Error("@avocadostudio-ai/migration-sdk exported no takeScreenshot");
+    }
+    return takeScreenshot;
+}
+/** Capture a full-page screenshot of one draft or published page. */
+export async function screenshotAction(params, log, deps = {}) {
+    if (!params.session)
+        return badRequest("session is required");
+    if (!params.siteId)
+        return badRequest("siteId is required");
+    const scopedSession = deps.scopedSession ?? scopedSessionKey(params.session, params.siteId);
+    const config = getSiteConfig(scopedSession);
+    // `previewUrl` is not in `siteConfigSchema` — `/sites/register` merges it in
+    // as an unvalidated extra, so it can only be read off the config as unknown.
+    const previewUrl = params.previewUrl ?? config.previewUrl ?? deps.fallbackPreviewUrl;
+    if (typeof previewUrl !== "string" || previewUrl.length === 0) {
+        return badRequest("no previewUrl configured for this site. Register it via POST /sites/register, pass `previewUrl` in the body, " +
+            "or (in library mode) set `previewUrl` on createOrchestrator().");
+    }
+    const slug = params.slug ?? "/";
+    // Guard against absolute URLs in `slug` — only allow path-like values.
+    if (/^https?:\/\//i.test(slug)) {
+        return badRequest("slug must be a path, not a full URL");
+    }
+    const normalizedSlug = slug.startsWith("/") ? slug : `/${slug}`;
+    const base = previewUrl.replace(/\/+$/, "");
+    /*
+     * The published route is the page's *path*, which is not always its slug.
+     * A site with locale prefixes or its own routing declares the difference
+     * in `meta.path`; screenshotting the slug there photographs a 404. Draft
+     * mode is unaffected — `/preview-draft` is keyed by slug, because that is
+     * the draft's own identifier rather than a route the site owns.
+     */
+    const publicPath = getPage(scopedSession, normalizedSlug)?.meta?.path ?? normalizedSlug;
+    /*
+     * Draft mode: target the site's draft route so the orchestrator's draft
+     * content is rendered directly, without needing a signed cookie. Published
+     * mode: hit the plain public route.
+     *
+     * `session` and `siteId` are appended rather than assigned, so a declared
+     * path may carry query params of its own (a locale, a perspective) without
+     * losing them.
+     */
+    const declaredDraftPath = params.draftPath ?? config.draftPath ?? deps.fallbackDraftPath;
+    const draftTemplate = typeof declaredDraftPath === "string" && declaredDraftPath.length > 0
+        ? declaredDraftPath
+        : DEFAULT_DRAFT_PATH;
+    const draftPath = resolveDraftPath(draftTemplate, normalizedSlug);
+    const draftQuery = `session=${encodeURIComponent(params.session)}&siteId=${encodeURIComponent(params.siteId)}`;
+    const fullUrl = params.published === true
+        ? base + publicPath
+        : base + draftPath + (draftPath.includes("?") ? "&" : "?") + draftQuery;
+    /*
+     * Resolving the capture is its own failure, reported separately from taking
+     * one. A host that has not installed the migration SDK gets "Cannot find
+     * package '@avocadostudio-ai/migration-sdk'" out of Node, which reads as a
+     * broken orchestrator rather than as the configuration choice it is — the
+     * package is heavy and deliberately not a dependency of the site. Say what
+     * to do about it, and use 503: the route is unavailable here, not failing.
+     */
+    let capture = deps.takeScreenshot;
+    if (!capture) {
+        try {
+            capture = await resolveCapture();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log.warn({ err: message }, "preview screenshot unavailable: no capture backend");
+            return {
+                code: 503,
+                body: {
+                    error: "screenshots are not available in this process. Install @avocadostudio-ai/migration-sdk " +
+                        "alongside the host app, or pass `screenshot` to createOrchestrator() to supply your own " +
+                        "capture function.",
+                    detail: message
+                }
+            };
+        }
+    }
+    try {
+        const result = await capture(fullUrl);
+        return {
+            code: 200,
+            body: {
+                url: fullUrl,
+                slug: normalizedSlug,
+                mode: params.published === true ? "published" : "draft",
+                mimeType: "image/jpeg",
+                base64: result.base64,
+                width: result.viewport.width,
+                height: result.viewport.height
+            }
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.warn({ err: message, fullUrl }, "preview screenshot failed");
+        // The URL and mode ride along on the failure because they are the only way
+        // a caller can tell "the site is down" from "we photographed the wrong
+        // route" — the two failures read identically from the message alone.
+        return {
+            code: 502,
+            body: {
+                error: message,
+                url: fullUrl,
+                mode: params.published === true ? "published" : "draft"
+            }
+        };
+    }
+}

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

@@ -0,0 +1,35 @@
+/**
+ * "Which draft am I editing?" — as a transport-agnostic action.
+ *
+ * `/whoami` existed only on the Fastify app, which was defensible while the
+ * editor was the only client: the editor already knows its own session, so it
+ * never asks. The MCP server does ask, and it asks first — every install is
+ * bound to exactly one (session, siteId) pair and `avocado-whoami` is how you
+ * confirm you are about to mutate the draft you think you are.
+ *
+ * So an MCP install pointed at a site running library mode answered "not
+ * handled by createOrchestrator()" to the one question worth asking before a
+ * destructive edit. That is the same class of gap as Undo: a second client
+ * grew needs the second copy of the route table never heard about.
+ *
+ * `/sessions` — the directory of every session on the orchestrator — stays
+ * behind. It is a property of a host running many sites, not of one site
+ * embedding its own editor, and it would answer a question no embedded caller
+ * should be asking.
+ */
+import type { ActionResult } from "./history-actions.js";
+export type { ActionResult };
+/**
+ * The caller's bound session and a summary of its state.
+ *
+ * `origin` is passed in rather than derived: the Fastify app knows it from the
+ * request's protocol and hostname, a `Request` handler from its own URL, and
+ * neither shape belongs in here. It is echoed so a mismatch between what the
+ * client thinks it is talking to and what answered is visible in the reply.
+ */
+export declare function whoamiAction(query: {
+    session?: string;
+    siteId?: string;
+}, origin: string, options?: {
+    hasAdapter?: boolean;
+}): ActionResult;

package/dist/http/session-actions.js

@@ -0,0 +1,98 @@
+/**
+ * "Which draft am I editing?" — as a transport-agnostic action.
+ *
+ * `/whoami` existed only on the Fastify app, which was defensible while the
+ * editor was the only client: the editor already knows its own session, so it
+ * never asks. The MCP server does ask, and it asks first — every install is
+ * bound to exactly one (session, siteId) pair and `avocado-whoami` is how you
+ * confirm you are about to mutate the draft you think you are.
+ *
+ * So an MCP install pointed at a site running library mode answered "not
+ * handled by createOrchestrator()" to the one question worth asking before a
+ * destructive edit. That is the same class of gap as Undo: a second client
+ * grew needs the second copy of the route table never heard about.
+ *
+ * `/sessions` — the directory of every session on the orchestrator — stays
+ * behind. It is a property of a host running many sites, not of one site
+ * embedding its own editor, and it would answer a question no embedded caller
+ * should be asking.
+ */
+import { DEFAULT_SESSION, getSessionSummary, getSessionCapabilities, capabilitiesBySession, publishedPageCountGlobal, scopedSessionKey } from "../state/session-state.js";
+import { describeDraft } from "./draft-provenance.js";
+/**
+ * The caller's bound session and a summary of its state.
+ *
+ * `origin` is passed in rather than derived: the Fastify app knows it from the
+ * request's protocol and hostname, a `Request` handler from its own URL, and
+ * neither shape belongs in here. It is echoed so a mismatch between what the
+ * client thinks it is talking to and what answered is visible in the reply.
+ */
+export function whoamiAction(query, origin, options) {
+    const sessionKey = scopedSessionKey(query.session ?? DEFAULT_SESSION, query.siteId);
+    const summary = getSessionSummary(sessionKey);
+    /*
+     * Whose content this is. `whoami` is the first call an agent makes to
+     * confirm it is about to mutate the draft it thinks it is — and until now
+     * it could confirm the session key while saying nothing about whether the
+     * pages behind it belong to the site that was asked for. A mistyped
+     * `siteId` produced a confident answer either way.
+     */
+    const provenance = describeDraft({
+        requestedSiteId: query.siteId,
+        scopedSession: sessionKey,
+        pageCount: summary.draftPageCount,
+        hasAdapter: options?.hasAdapter
+    });
+    return {
+        code: 200,
+        body: {
+            ...summary,
+            ...provenance,
+            ...publishedPageCountFor(provenance.source),
+            orchestratorUrl: origin,
+            /*
+             * What this site can honour, so an agent finds out before it plans a
+             * page the CMS can never store. `declared` is false when nobody has
+             * said anything, which is the common case and reads as "everything is
+             * permitted, but nothing has been promised" — a caller that needs to
+             * tell that apart from an explicit yes has it here.
+             */
+            capabilities: {
+                ...getSessionCapabilities(sessionKey),
+                declared: capabilitiesBySession.has(sessionKey)
+            }
+        }
+    };
+}
+/**
+ * How many pages are live — but only where this process can actually know.
+ *
+ * `publishedPageCount` used to be `publishedPages.size`, unconditionally. That
+ * Map is seeded from the bundled demo pages at import time and *nothing writes
+ * it on publish*, so the field was the constant 8 on every deployment: an
+ * agent editing a 45-page Sanity site was told "45 draft, 8 published" and
+ * reasonably read it as 37 pages waiting to go out. It sat inside a
+ * session-scoped report, next to `draftPageCount`, which is what made it read
+ * as this site's number rather than a process-wide leftover.
+ *
+ * This is the same defect `describeDraft` was written for — a plausible count
+ * that belongs to nobody's site — one field over, and it survived that fix
+ * because it is computed from a different map. So it now answers from the same
+ * provenance: on the demo site the Map genuinely is what is published, and
+ * everywhere else the honest answer is that this process does not track it.
+ *
+ * `null` rather than an omitted key, because a caller reading a missing field
+ * learns nothing; one reading `null` beside the note learns where the real
+ * answer is. `GET /publish/diff` is that answer — in library mode it reads the
+ * live side through the site's own adapter.
+ */
+function publishedPageCountFor(source) {
+    if (source === "demo")
+        return { publishedPageCount: publishedPageCountGlobal() };
+    return {
+        publishedPageCount: null,
+        publishedPageCountNote: "This process does not track what is live for this site. Its only published-page store holds " +
+            "Avocado's bundled demo pages, seeded at startup and never written on publish, so its size is " +
+            "a constant rather than this site's page count. Call GET /publish/diff for the live side."
+    };
+}

package/dist/http/telemetry-feedback-actions.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Thumbs-up / thumbs-down on a chat trace, as transport-agnostic actions.
+ *
+ * `POST /telemetry/chat/feedback` was written inline in
+ * `apps/orchestrator/src/index.ts` rather than in a route plugin, so library
+ * mode — `createOrchestrator()` in the site SDK, which reimplements by hand
+ * whichever routes somebody remembered to add — never got it. The editor sends
+ * the rating best-effort and ignores the response, so on a library-mode site
+ * every thumb the user clicked was answered "not handled by
+ * createOrchestrator()" and silently thrown away: the UI kept showing the
+ * button as accepted and no signal ever reached the store.
+ *
+ * A second hand-kept copy would drift the way the first one did, so the
+ * validation lives here and both transports call it. Each function returns the
+ * status code and body to send; neither Fastify nor `Response` appears in this
+ * file.
+ */
+import type { FeedbackStore } from "../telemetry/feedback-store.js";
+import type { ActionResult } from "./history-actions.js";
+export type { ActionResult };
+/**
+ * The store is a parameter, not a module singleton.
+ *
+ * Unlike the session state the other action files reach for, a feedback store
+ * is constructed per process from `FEEDBACK_FILE` / `FEEDBACK_LIMIT` and a
+ * logger — the standalone server and a library-mode host each own their own.
+ * Only the two methods a request path touches are required, which also keeps a
+ * test double from having to fake disk I/O.
+ */
+export type FeedbackSink = Pick<FeedbackStore, "push" | "list">;
+/**
+ * Record one rating against a chat trace.
+ *
+ * The rating is compared against the two literals rather than merely checked
+ * for being a string: the store's readers filter and count by rating, and a
+ * third value would quietly split the totals. An unusable payload is rejected
+ * rather than stored partially, because the editor fires this and forgets it —
+ * a row nobody can attribute to a trace is worse than no row.
+ */
+export declare function telemetryFeedbackSubmitAction(raw: unknown, store: FeedbackSink): ActionResult;
+/**
+ * Read the ratings back, filtered.
+ *
+ * `limit` arrives as a query string over HTTP and as a number from anything
+ * calling this directly, so it is coerced here; the store clamps the range.
+ * Left absent rather than defaulted so the store's own default still applies.
+ */
+export declare function telemetryFeedbackListAction(query: {
+    session?: string;
+    rating?: string;
+    traceId?: string;
+    limit?: string | number;
+}, store: FeedbackSink): ActionResult;