@avocadostudio-ai/orchestrator-core 0.3.2 → 0.4.0

package/dist/cms/media-sources.js

@@ -1,3 +1,5 @@
+/** Sanity's dated API: one version for both the query and the asset endpoints. */
+const SANITY_API_VERSION = "v2024-01-01";
 const LABELS = {
     contentful: "Contentful",
     sanity: "Sanity",
@@ -69,20 +71,33 @@ async function contentfulMedia(config, { query, page, limit }) {
 // ---------------------------------------------------------------------------
 // Sanity — GROQ, slice paging, a second query for the count.
 // ---------------------------------------------------------------------------
-async function sanityMedia(config, { query, page, limit }) {
+async function sanityMedia(config, { query, page, limit, kind }) {
     const label = LABELS.sanity;
     const dataset = config.dataset ?? "production";
     const offset = (page - 1) * limit;
     const end = offset + limit - 1;
+    const wantsFiles = kind === "file";
+    /*
+     * Sanity keeps documents in a second asset type. A PDF uploaded through the
+     * Studio — or through `cmsMediaUploader` below — is a `sanity.fileAsset`,
+     * and asking for `sanity.imageAsset` finds none of them however many the
+     * project holds. Before this branch existed, a request for documents was
+     * answered with the image list, and the route's own kind filter then dropped
+     * every item: an empty Documents tab on a project full of menus.
+     */
+    const assetType = wantsFiles ? "sanity.fileAsset" : "sanity.imageAsset";
     // GROQ is interpolated, so the filter term is stripped of the two characters
     // that could close the string literal it lands inside.
     const safeQuery = (query ?? "").replace(/["\\]/g, "");
     const filter = safeQuery
-        ? `_type == "sanity.imageAsset" && originalFilename match "*${safeQuery}*"`
-        : `_type == "sanity.imageAsset"`;
-    const groq = `*[${filter}] | order(_createdAt desc) [${offset}..${end}] { _id, url, originalFilename, metadata { dimensions } }`;
+        ? `_type == "${assetType}" && originalFilename match "*${safeQuery}*"`
+        : `_type == "${assetType}"`;
+    const projection = wantsFiles
+        ? `{ _id, url, originalFilename, mimeType, size }`
+        : `{ _id, url, originalFilename, metadata { dimensions } }`;
+    const groq = `*[${filter}] | order(_createdAt desc) [${offset}..${end}] ${projection}`;
     const countGroq = `count(*[${filter}])`;
-    const base = `https://${config.projectId}.api.sanity.io/v2024-01-01/data/query/${dataset}`;
+    const base = `https://${config.projectId}.api.sanity.io/${SANITY_API_VERSION}/data/query/${dataset}`;
     const headers = {};
     if (config.token)
         headers.authorization = `Bearer ${config.token}`;
@@ -95,17 +110,37 @@ async function sanityMedia(config, { query, page, limit }) {
     const assets = (await assetsRes.json());
     const count = countRes.ok ? (await countRes.json()).result ?? 0 : 0;
     return {
-        items: (assets.result ?? []).map((asset) => ({
+        items: (assets.result ?? []).map((asset) => wantsFiles ? sanityFileItem(asset) : {
             id: asset._id,
             name: asset.originalFilename,
             alt: asset.originalFilename,
             imageUrl: asset.url,
             thumbUrl: `${asset.url}?w=200&h=200&fit=crop`
-        })),
+        }),
         totalPages: Math.ceil(count / limit),
         label
     };
 }
+/**
+ * One `sanity.fileAsset` as the picker's document tab renders it.
+ *
+ * `url` rather than `imageUrl`, because this is a link target and not something
+ * to draw, and `thumbUrl: ""` for the same reason — the picker draws an icon
+ * from `contentType` when there is nothing to show. The URL is Sanity's own
+ * `cdn.sanity.io/files/…` address: durable, CDN-served, and unchanged by any
+ * redeploy of the site that links to it.
+ */
+function sanityFileItem(asset) {
+    return {
+        id: asset._id,
+        kind: "file",
+        name: asset.originalFilename,
+        url: asset.url,
+        thumbUrl: "",
+        contentType: asset.mimeType ?? "application/octet-stream",
+        ...(typeof asset.size === "number" ? { size: asset.size } : {})
+    };
+}
 // ---------------------------------------------------------------------------
 // Strapi — upload plugin, page/pageSize paging, count in a response header.
 // ---------------------------------------------------------------------------
@@ -142,6 +177,152 @@ async function strapiMedia(config, { query, page, limit }) {
         label
     };
 }
+// ---------------------------------------------------------------------------
+// Adding one — the write half, for the CMSes whose asset API is a single call.
+// ---------------------------------------------------------------------------
+/**
+ * Build a media writer from the same connection details as the reader, or
+ * `null` when this provider (or this configuration) cannot take an upload.
+ *
+ * ```ts
+ * const uploadMedia = cmsMediaUploader({ provider: "sanity", projectId, dataset, token })
+ * return { id: "sanity", getPages, getMedia, ...(uploadMedia ? { uploadMedia } : {}) }
+ * ```
+ *
+ * Null rather than a stub that throws, and spread rather than assigned,
+ * because `writesMedia` is derived from whether the method *exists*
+ * (`resolveCapabilities`) and the editor shows its upload control on the
+ * strength of that. A method that is always present and always fails is a
+ * button that is always there and never works.
+ *
+ * So a project with a read-only token gets no upload control at all, which is
+ * the truth about it: Sanity's query API answers a viewer token and its asset
+ * API does not, and that difference is invisible until somebody picks a file.
+ *
+ * **Sanity only, for now.** Uploading to Contentful is a three-step
+ * asynchronous dance — create the asset, ask for processing, poll, publish —
+ * and Strapi's is a multipart POST to its upload plugin; neither is written
+ * yet, and both answer `null` so that an adapter which spreads the result
+ * simply offers no upload rather than offering a broken one.
+ */
+export function cmsMediaUploader(config) {
+    if (config.provider !== "sanity")
+        return null;
+    const token = config.token?.trim();
+    if (!token)
+        return null;
+    return (input) => sanityUpload({ ...config, token }, input);
+}
+/**
+ * MIME types for the document extensions a site is likely to be handed, used
+ * only when the browser reported none.
+ *
+ * Sanity sniffs the bytes and would usually get there on its own; sending
+ * `application/octet-stream` for a PDF, though, is how an asset ends up in the
+ * library with a type the picker cannot draw an icon for.
+ */
+const UPLOAD_MIME_BY_EXT = {
+    pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    csv: "text/csv",
+    txt: "text/plain",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    webp: "image/webp",
+    gif: "image/gif",
+    svg: "image/svg+xml"
+};
+function uploadContentType(input) {
+    const declared = input.contentType.trim();
+    if (declared)
+        return declared;
+    const ext = input.filename.toLowerCase().split(".").pop() ?? "";
+    return UPLOAD_MIME_BY_EXT[ext] ?? "application/octet-stream";
+}
+/**
+ * The filename Sanity records as `originalFilename`.
+ *
+ * It is not a path — the asset's own URL is derived from a content hash — so
+ * this strips directory segments and control characters and otherwise leaves
+ * the name a person chose intact, accents and spaces included. The picker
+ * shows this string, and "Menükarte Winter 2026.pdf" is what makes a document
+ * recognisable in a list of twenty.
+ */
+function uploadFilename(raw) {
+    const base = raw.split(/[\\/]/).pop() ?? "";
+    // Control characters, written as escapes: a literal one in the source is
+    // invisible to every reader and turns the file binary to `grep`.
+    return base.replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, 120);
+}
+async function sanityUpload(config, input) {
+    const dataset = config.dataset ?? "production";
+    /*
+     * Two buckets, and picking the wrong one is not a detail: `images` runs the
+     * bytes through image processing and refuses anything that is not a picture,
+     * which is exactly the refusal a PDF sent there produces. `kind` is what the
+     * editor said it was uploading, so it decides.
+     */
+    const bucket = input.kind === "file" ? "files" : "images";
+    const filename = uploadFilename(input.filename);
+    const params = new URLSearchParams();
+    if (filename)
+        params.set("filename", filename);
+    const res = await fetch(`https://${config.projectId}.api.sanity.io/${SANITY_API_VERSION}/assets/${bucket}/${dataset}?${params}`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${config.token}`,
+            "content-type": uploadContentType(input)
+        },
+        body: new Uint8Array(input.data)
+    });
+    /*
+     * Throwing is the contract's way of refusing an upload, and the message
+     * reaches the person who picked the file — so it has to say what Sanity
+     * said, not that something went wrong.
+     */
+    if (!res.ok)
+        throw new Error(await sanityUploadError(res));
+    const body = (await res.json());
+    const doc = body.document;
+    if (!doc?._id || !doc.url) {
+        throw new Error("Sanity accepted the upload but returned no asset.");
+    }
+    if (input.kind === "file") {
+        return sanityFileItem({ _id: doc._id, url: doc.url, originalFilename: doc.originalFilename, mimeType: doc.mimeType, size: doc.size });
+    }
+    return {
+        id: doc._id,
+        name: doc.originalFilename,
+        alt: doc.originalFilename,
+        imageUrl: doc.url,
+        thumbUrl: `${doc.url}?w=200&h=200&fit=crop`
+    };
+}
+async function sanityUploadError(res) {
+    /*
+     * 401/403 has one overwhelmingly likely cause and it is not obvious from
+     * Sanity's own wording: the token reads fine — the picker's grid is full of
+     * images, which is what makes it confusing — and simply has no write grant.
+     */
+    const suffix = res.status === 401 || res.status === 403
+        ? " The API token needs write access to this dataset; a read token fills the picker but cannot upload."
+        : "";
+    const fallback = `Sanity refused the upload (${res.status}).${suffix}`;
+    try {
+        const body = (await res.json());
+        const described = typeof body.error === "string"
+            ? body.error
+            : body.error?.description ?? body.error?.message ?? body.message;
+        return described ? `Sanity refused the upload: ${described}${suffix}` : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
 /**
  * Build a reader from an untrusted object, or `null` if it is not one of the
  * three shapes.

package/dist/durable/durable-store-singleton.d.ts

@@ -0,0 +1,37 @@
+import type { DurableStore } from "./types.ts";
+export declare function getDurableStore(): DurableStore;
+/**
+ * Whether findings, memory and proposals are reaching disk, and why not.
+ *
+ * Deliberately separate from `persistenceHealth()`, which answers the same
+ * question about page state and whose warning text is about losing edits.
+ */
+export declare function durableHealth(): {
+    ok: boolean;
+    reason: string | null;
+};
+/**
+ * Record a durable-store write failure. Separate from the page-state channel:
+ * a proposal row that did not save must not tell the user their edits are gone.
+ */
+export declare function noteDurableFailure(reason: string): void;
+/**
+ * True when findings, memory and proposals are living in memory only. Callers
+ * that are about to promise durability — a scheduled run leaving a plan for the
+ * morning — should say so rather than assume.
+ */
+export declare function durableStoreIsEphemeral(): boolean;
+/** Drop the singleton. Tests and graceful shutdown; `getStore()` owns closing. */
+export declare function resetDurableStore(): void;
+/** Swap in a store — for tests, and for a host that brings its own backend. */
+export declare function setDurableStore(next: DurableStore | null, ephemeral?: boolean): void;
+export declare function isDiscardInFlight(scopeKey: string): boolean;
+/**
+ * Discard any pending proposal for a session being deleted.
+ *
+ * Without this, deleting a session leaves a `pending` row behind, and the next
+ * session with that id would rehydrate a plan the user had already thrown away.
+ */
+export declare function discardPendingProposalsForSession(scopeKey: string): void;
+/** Sweep proposals past their TTL, alongside the ephemeral-map eviction pass. */
+export declare function sweepExpiredProposals(): void;

package/dist/durable/durable-store-singleton.js

@@ -0,0 +1,179 @@
+import { getStore } from "../state/sqlite-store-singleton.js";
+import { SqliteDurableStore } from "./sqlite-durable-store.js";
+import { InMemoryDurableStore } from "./in-memory-durable-store.js";
+/*
+ * Singleton access to the durable store, mirroring `getStore()` next door.
+ *
+ * The one interesting decision here is what to do when SQLite is unavailable.
+ * `getStore()` throws: the driver could not load, and there is no page state
+ * without it. This one falls back to `InMemoryDurableStore` instead, for the
+ * same reason `createOrchestrator()` already keeps serving edits in that
+ * situation — a findings panel that 500s because a native module is missing is
+ * worse than one that works and says it is not saving anything.
+ *
+ * The failure is recorded here rather than through `notePersistenceFailure`.
+ * That channel is about *page state*: its warning tells the user "this edit was
+ * applied in memory but could not be saved", and every mutation response starts
+ * carrying `persisted: false`. Reporting a failed *proposal* row through it
+ * would tell somebody their content edits are being lost when they are not —
+ * a worse lie than the one the channel exists to prevent.
+ *
+ * Findings and proposals are capable of exactly the same lie on their own
+ * account, and an overnight run is precisely when nobody is watching the log,
+ * so they get their own flag with its own wording.
+ */
+let store = null;
+let usingFallback = false;
+let overridden = false;
+let failureReason = null;
+let lastAttemptAt = 0;
+/** How long to stay on the fallback before re-trying SQLite. */
+const RETRY_COOLDOWN_MS = 30_000;
+/*
+ * The connection `store` was built against.
+ *
+ * `resetStore()` next door closes the database and drops its singleton, and the
+ * next `getStore()` opens a fresh one — which used to leave this module holding
+ * prepared statements on a closed handle. Rather than have `resetStore()` call
+ * in here (a cycle: this module imports that one), we notice: a different `db`
+ * object means a different database, and the store is rebuilt against it.
+ */
+let boundDb = null;
+export function getDurableStore() {
+    // An explicitly-set store is sticky; the fallback is not.
+    if (store && overridden)
+        return store;
+    /*
+     * The fallback must not be permanent. `getStore()` next door leaves its own
+     * singleton null on a constructor throw and retries on the next call, so page
+     * state recovers from a transient failure — a `.data` directory not yet
+     * writable at boot, say — while this store, if it latched, would stay
+     * memory-only for the life of the process with no way back.
+     *
+     * Retrying on a cooldown rather than every call keeps a genuinely broken
+     * install from paying for a constructor on every finding. Whatever the
+     * fallback accumulated is lost on a successful retry; it was never durable,
+     * and saying so is the honest trade.
+     */
+    if (store && usingFallback && Date.now() - lastAttemptAt < RETRY_COOLDOWN_MS)
+        return store;
+    try {
+        lastAttemptAt = Date.now();
+        // Share `SqliteStore`'s connection: one WAL, one backup, one VACUUM INTO.
+        const db = getStore().db;
+        if (!store || usingFallback || boundDb !== db) {
+            store = new SqliteDurableStore(db);
+            boundDb = db;
+            usingFallback = false;
+            failureReason = null;
+        }
+    }
+    catch (err) {
+        failureReason = err instanceof Error ? err.message : String(err);
+        if (!store || !usingFallback) {
+            store = new InMemoryDurableStore();
+            boundDb = null;
+            usingFallback = true;
+        }
+    }
+    return store;
+}
+/**
+ * Whether findings, memory and proposals are reaching disk, and why not.
+ *
+ * Deliberately separate from `persistenceHealth()`, which answers the same
+ * question about page state and whose warning text is about losing edits.
+ */
+export function durableHealth() {
+    return { ok: !usingFallback, reason: usingFallback ? failureReason : null };
+}
+/**
+ * Record a durable-store write failure. Separate from the page-state channel:
+ * a proposal row that did not save must not tell the user their edits are gone.
+ */
+export function noteDurableFailure(reason) {
+    failureReason ??= reason;
+}
+/**
+ * True when findings, memory and proposals are living in memory only. Callers
+ * that are about to promise durability — a scheduled run leaving a plan for the
+ * morning — should say so rather than assume.
+ */
+export function durableStoreIsEphemeral() {
+    if (!store)
+        getDurableStore();
+    return usingFallback;
+}
+/** Drop the singleton. Tests and graceful shutdown; `getStore()` owns closing. */
+export function resetDurableStore() {
+    store = null;
+    usingFallback = false;
+    overridden = false;
+    boundDb = null;
+    failureReason = null;
+    lastAttemptAt = 0;
+}
+/** Swap in a store — for tests, and for a host that brings its own backend. */
+export function setDurableStore(next, ephemeral = false) {
+    store = next;
+    usingFallback = next ? ephemeral : false;
+    overridden = next !== null;
+    boundDb = null;
+}
+/*
+ * The two lifecycle hooks `session-state.ts` needs, living here rather than in
+ * `pending-plan-store.ts` so that session-state can call them without importing
+ * a module that imports session-state back. The cycle would probably work —
+ * neither side touches the other at module scope — but this repo has already
+ * been bitten by ESM evaluation order once, and a cleanup call is not worth
+ * finding out a second time.
+ *
+ * Both are fire-and-forget: they are called from synchronous state mutators
+ * whose signatures a durability concern has no business changing, and neither
+ * result affects what the caller returns.
+ */
+/**
+ * Sessions whose pending rows are being discarded right now.
+ *
+ * The set is added to *synchronously*, before the async discard starts, and the
+ * rehydration path consults it. `forgetSession` is a synchronous mutator, so
+ * without this a caller that forgets a session and immediately opens a new chat
+ * on the same id — ids are caller-supplied and routinely reused — races the
+ * discard and reads back the plan the delete was meant to remove.
+ *
+ * It lives here rather than in `pending-plan-store.ts` for the same reason the
+ * hooks below do: session-state must be able to reach it without importing a
+ * module that imports session-state back.
+ */
+const discardInFlight = new Set();
+export function isDiscardInFlight(scopeKey) {
+    return discardInFlight.has(scopeKey);
+}
+/**
+ * Discard any pending proposal for a session being deleted.
+ *
+ * Without this, deleting a session leaves a `pending` row behind, and the next
+ * session with that id would rehydrate a plan the user had already thrown away.
+ */
+export function discardPendingProposalsForSession(scopeKey) {
+    discardInFlight.add(scopeKey);
+    void (async () => {
+        const active = getDurableStore();
+        const rows = await active.listProposals({ scopeKey, status: "pending" });
+        for (const row of rows)
+            await active.setProposalStatus(row.id, "discarded");
+    })()
+        .catch(() => {
+        /* best-effort: an orphan row is inert until something reads it, and the
+           read path re-checks expiry and payload validity anyway. */
+    })
+        .finally(() => discardInFlight.delete(scopeKey));
+}
+/** Sweep proposals past their TTL, alongside the ephemeral-map eviction pass. */
+export function sweepExpiredProposals() {
+    void getDurableStore()
+        .expireProposals()
+        .catch(() => {
+        /* best-effort */
+    });
+}

package/dist/durable/finding-impact.d.ts

@@ -0,0 +1,30 @@
+import type { FindingSeverity } from "./types.ts";
+/**
+ * What a severity is worth before the page is taken into account.
+ *
+ * Not linear, and deliberately: `info` is defined in `rules-draft.ts` as "worth
+ * a look, and safe to ignore forever", so an info finding on the home page
+ * should sit below a warning on a secondary page, and 0.3 × 1.0 < 0.6 × 0.55
+ * is what makes that true.
+ */
+export declare const SEVERITY_WEIGHT: Record<FindingSeverity, number>;
+/**
+ * The weight given to a page nothing has scored — a row written by a build
+ * before impact existed, or by a caller that supplied no weights.
+ *
+ * Mid-scale rather than 1, so old rows interleave with scored ones instead of
+ * sorting above every finding on the site until the next run corrects them.
+ */
+export declare const NEUTRAL_PAGE_WEIGHT = 0.5;
+/** Severity × page weight, rounded to something a human can read in a log. */
+export declare function impactFor(severity: FindingSeverity, pageWeight: number): number;
+/** What an unscored finding is worth. Must match `IMPACT_FALLBACK_SQL`. */
+export declare function fallbackImpact(severity: FindingSeverity): number;
+/**
+ * The same fallback, for SQLite's ORDER BY.
+ *
+ * Generated from the constants above rather than written out, because the one
+ * failure mode here is the two drifting apart — the list would then be sorted
+ * by one rule and explained by another, and nothing would look wrong.
+ */
+export declare const IMPACT_FALLBACK_SQL: string;

package/dist/durable/finding-impact.js

@@ -0,0 +1,53 @@
+/*
+ * Impact — severity times how much the page matters.
+ *
+ * It lives beside the types rather than in `checks/` because both stores need
+ * it: a finding written before this shipped has no `impact` column, and the
+ * ORDER BY has to put it somewhere defensible rather than at one end.
+ *
+ * The two axes stay separate on the record. Severity is a claim about the
+ * problem and belongs to the rule; impact is a claim about the page and is
+ * recomputed by every run, because the link graph moves. Multiplying them into
+ * one stored number instead would make a finding's severity unrecoverable, and
+ * severity is what the icon in the panel means.
+ */
+/**
+ * What a severity is worth before the page is taken into account.
+ *
+ * Not linear, and deliberately: `info` is defined in `rules-draft.ts` as "worth
+ * a look, and safe to ignore forever", so an info finding on the home page
+ * should sit below a warning on a secondary page, and 0.3 × 1.0 < 0.6 × 0.55
+ * is what makes that true.
+ */
+export const SEVERITY_WEIGHT = {
+    error: 1,
+    warning: 0.6,
+    info: 0.3
+};
+/**
+ * The weight given to a page nothing has scored — a row written by a build
+ * before impact existed, or by a caller that supplied no weights.
+ *
+ * Mid-scale rather than 1, so old rows interleave with scored ones instead of
+ * sorting above every finding on the site until the next run corrects them.
+ */
+export const NEUTRAL_PAGE_WEIGHT = 0.5;
+/** Severity × page weight, rounded to something a human can read in a log. */
+export function impactFor(severity, pageWeight) {
+    const clamped = Math.max(0, Math.min(pageWeight, 1));
+    return Math.round(SEVERITY_WEIGHT[severity] * clamped * 1000) / 1000;
+}
+/** What an unscored finding is worth. Must match `IMPACT_FALLBACK_SQL`. */
+export function fallbackImpact(severity) {
+    return impactFor(severity, NEUTRAL_PAGE_WEIGHT);
+}
+/**
+ * The same fallback, for SQLite's ORDER BY.
+ *
+ * Generated from the constants above rather than written out, because the one
+ * failure mode here is the two drifting apart — the list would then be sorted
+ * by one rule and explained by another, and nothing would look wrong.
+ */
+export const IMPACT_FALLBACK_SQL = `COALESCE(impact, CASE severity ${Object.keys(SEVERITY_WEIGHT)
+    .map((severity) => `WHEN '${severity}' THEN ${fallbackImpact(severity)}`)
+    .join(" ")} END)`;