@avocadostudio-ai/orchestrator-core 0.1.0 → 0.2.0

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

@@ -0,0 +1,153 @@
+/**
+ * Publish status, publish diff and the publish log, as transport-agnostic
+ * actions.
+ *
+ * These lived only in `apps/orchestrator/src/routes/publishing.ts`, wired
+ * directly into Fastify. 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 three, so a library-mode editor polls `GET /publish/status` after
+ * every publish and gets "not handled by createOrchestrator()" back, and its
+ * publish-diff panel has nothing to render.
+ *
+ * As with `history-actions.ts` and `restore-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 type { PageDoc, SiteConfig } from "@avocadostudio-ai/shared";
+import type { PublishLogStatus } from "../state/session-state.js";
+import { refreshPublishStatusFromVercel } from "../publish/publish-helpers.js";
+import type { Logger } from "../logger.js";
+import type { ActionResult } from "./history-actions.js";
+export type { ActionResult };
+/**
+ * What "the site as it is currently live" resolves to.
+ *
+ * `siteConfig: null` asserts the published site genuinely has no header
+ * config; `siteConfig` left absent means the source cannot tell. The
+ * distinction matters because `computePublishDiff` reads a missing published
+ * config as "the entire site chrome was just added" and reports every nav
+ * label as a change. A source that does not know must say so rather than
+ * guess null — see `publishDiffAction`.
+ */
+export type PublishedContent = {
+    pages: PageDoc[];
+    siteConfig?: SiteConfig | null;
+};
+/**
+ * Where the published side comes from. The monorepo answers it from the site
+ * app; a library-mode consumer answers it from its CMS adapter, whose
+ * `getPages()` is the only thing that knows what is actually live there.
+ */
+export type PublishedSource = {
+    load(opts: {
+        siteOrigin?: string;
+        logger: Logger;
+    }): Promise<PublishedContent>;
+};
+/**
+ * Load the authoritative published pages for diff computation.
+ *
+ * Priority (first hit wins):
+ *   1. `${siteOrigin}/api/editor/pages` — accurate in both dev and prod.
+ *   2. `PUBLISHED_CONTENT_PATH` env var — direct file read (ops override).
+ *   3. `apps/site/lib/published-content.json` — monorepo default for local dev.
+ *   4. In-memory `publishedPages` Map — stale demo seed, last resort.
+ *
+ * The in-memory Map is NOT authoritative: it is seeded from demo data at
+ * startup and never updated on publish. Relying on it produces bogus diffs
+ * (e.g. "all pages added" when the site already has them published).
+ */
+export declare function loadPublishedForDiff(opts: {
+    siteOrigin?: string;
+    logger: Logger;
+}): Promise<{
+    pages: PageDoc[];
+    siteConfig: SiteConfig | null;
+}>;
+/**
+ * The default source: the four-step monorepo chain above, unchanged, so the
+ * Fastify routes keep answering exactly what they answered before.
+ */
+export declare const monorepoPublishedSource: PublishedSource;
+/**
+ * Reject origins that point at private/loopback IPs or non-http protocols.
+ *
+ * `siteOrigin` arrives from the caller and is fetched server-side, so an
+ * unchecked value turns the orchestrator into an SSRF proxy onto whatever the
+ * host can reach. Local addresses stay allowed outside production because that
+ * is what dev *is*; in production they are allowed only when the deployment
+ * has already declared the origin trusted via `ORCHESTRATOR_CORS_ORIGINS`.
+ */
+export declare function isSafeOrigin(raw: string): boolean;
+/**
+ * Map a refreshed Vercel `vercelState` to a publish-log status. READY counts
+ * as success; ERROR/CANCELED count as failed. Any other state (BUILDING,
+ * QUEUED, INITIALIZING, UNKNOWN, …) leaves the row at `triggered`.
+ */
+export declare function publishStatusFromVercelState(state: string | undefined): PublishLogStatus | null;
+/**
+ * Build a short human-readable summary of what was published, biased toward
+ * *changes* rather than the full site contents. Falls back to "republished N
+ * pages" when no diff is available.
+ *
+ * Exported because both transports write publish-log rows and a log whose
+ * wording depends on which server wrote it is a log nobody can read.
+ */
+export declare function buildPublishSummary(opts: {
+    changedSlugs: string[];
+    removedSlugs: string[];
+    totalPages: number;
+    hasDiff: boolean;
+}): string;
+/**
+ * The publish history for a session, newest rows last.
+ *
+ * The limit is clamped rather than trusted: the rows carry per-page slugs and
+ * diff summaries, and an unbounded `?limit=` would let a caller pull the whole
+ * table into one response.
+ */
+export declare function publishLogAction(query: {
+    session?: string;
+    siteId?: string;
+    limit?: string | number;
+}): ActionResult;
+/**
+ * The Vercel poll, injectable so the status action is testable.
+ *
+ * The real one talks to `api.vercel.com` (or waits out a grace period when no
+ * token is configured), which a unit test can neither reach nor hurry.
+ */
+export type PublishStatusDeps = {
+    refresh: typeof refreshPublishStatusFromVercel;
+};
+/**
+ * Poll the deployment a publish kicked off, and mature its log row when the
+ * deployment finally resolves.
+ *
+ * A publish-log row is born "triggered" because `POST /publish` returns while
+ * the build is still running on the host's side. This poll is the only place
+ * that ever learns the outcome, so it is also where the row becomes "success"
+ * or "failed" — without that, every publish would stay pending in the history
+ * panel forever. The row is matched by deployment id where there is one, and
+ * only a still-`triggered` row is touched, so a re-poll after resolution
+ * cannot overwrite a finished row.
+ *
+ * The tracker lives in a non-persisted in-memory Map, so a session that has
+ * not published since the process started genuinely has no status: that is a
+ * 404, not an empty success.
+ */
+export declare function publishStatusAction(query: {
+    session?: string;
+    siteId?: string;
+}, deps?: PublishStatusDeps): Promise<ActionResult>;
+/**
+ * What the editor's "review changes" panel shows: the session draft against
+ * whatever is currently live.
+ */
+export declare function publishDiffAction(query: {
+    session?: string;
+    siteId?: string;
+    siteOrigin?: string;
+}, log: Logger, source?: PublishedSource): Promise<ActionResult>;

package/dist/http/publish-actions.js

@@ -0,0 +1,323 @@
+/**
+ * Publish status, publish diff and the publish log, as transport-agnostic
+ * actions.
+ *
+ * These lived only in `apps/orchestrator/src/routes/publishing.ts`, wired
+ * directly into Fastify. 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 three, so a library-mode editor polls `GET /publish/status` after
+ * every publish and gets "not handled by createOrchestrator()" back, and its
+ * publish-diff panel has nothing to render.
+ *
+ * As with `history-actions.ts` and `restore-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 { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { normalizeSession, scopedSessionKey, getSessionPages, getSiteConfig, publishedPages, publishStatusBySession, listPublishLog, findPublishLogForStatusUpdate, updatePublishLogStatusById } from "../state/session-state.js";
+import { computePublishDiff } from "../publish/diff-engine.js";
+import { refreshPublishStatusFromVercel } from "../publish/publish-helpers.js";
+const badRequest = (error) => ({ code: 400, body: { error } });
+/**
+ * Read published content off disk.
+ *
+ * Priority (first hit wins):
+ *   1. `PUBLISHED_CONTENT_PATH` env var — direct file read (ops override).
+ *   2. `apps/site/lib/published-content.json` — monorepo default for local dev.
+ */
+async function readPublishedJsonFile() {
+    const paths = [];
+    if (process.env.PUBLISHED_CONTENT_PATH?.trim())
+        paths.push(process.env.PUBLISHED_CONTENT_PATH.trim());
+    // Monorepo default — orchestrator cwd is apps/orchestrator in dev.
+    paths.push(resolve(process.cwd(), "../../apps/site/lib/published-content.json"));
+    paths.push(resolve(process.cwd(), "../site/lib/published-content.json"));
+    for (const path of paths) {
+        try {
+            const raw = await readFile(path, "utf8");
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed)) {
+                return { pages: parsed, siteConfig: null };
+            }
+            if (Array.isArray(parsed.pages)) {
+                return { pages: parsed.pages, siteConfig: parsed.siteConfig ?? null };
+            }
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    return { pages: null, siteConfig: null };
+}
+/**
+ * Load the authoritative published pages for diff computation.
+ *
+ * Priority (first hit wins):
+ *   1. `${siteOrigin}/api/editor/pages` — accurate in both dev and prod.
+ *   2. `PUBLISHED_CONTENT_PATH` env var — direct file read (ops override).
+ *   3. `apps/site/lib/published-content.json` — monorepo default for local dev.
+ *   4. In-memory `publishedPages` Map — stale demo seed, last resort.
+ *
+ * The in-memory Map is NOT authoritative: it is seeded from demo data at
+ * startup and never updated on publish. Relying on it produces bogus diffs
+ * (e.g. "all pages added" when the site already has them published).
+ */
+export async function loadPublishedForDiff(opts) {
+    const { siteOrigin, logger } = opts;
+    let remotePages = null;
+    let remoteSiteConfig = null;
+    if (siteOrigin) {
+        try {
+            const res = await fetch(`${siteOrigin.replace(/\/+$/, "")}/api/editor/pages`, {
+                headers: { accept: "application/json" },
+            });
+            if (res.ok) {
+                const data = (await res.json());
+                if (Array.isArray(data.pages)) {
+                    remotePages = data.pages;
+                    remoteSiteConfig = data.siteConfig ?? null;
+                }
+            }
+            else {
+                logger.warn({ siteOrigin, status: res.status }, "publish/diff: site pages endpoint not ok, falling back");
+            }
+        }
+        catch (err) {
+            logger.warn({ siteOrigin, err: String(err) }, "publish/diff: site fetch failed, falling back");
+        }
+    }
+    // Hot path: remote returned both pages and siteConfig.
+    if (remotePages && remoteSiteConfig) {
+        return { pages: remotePages, siteConfig: remoteSiteConfig };
+    }
+    // Either the remote didn't run, didn't include siteConfig (older SDK or
+    // site dev not yet restarted), or didn't include pages. Read the JSON file
+    // to backfill the missing pieces — without it, a missing siteConfig would
+    // be misread as "header added · all fields" on every publish-diff load.
+    const fromFile = await readPublishedJsonFile();
+    const pages = remotePages ?? fromFile.pages;
+    const siteConfig = remoteSiteConfig ?? fromFile.siteConfig;
+    if (pages)
+        return { pages, siteConfig };
+    logger.warn("publish/diff: falling back to in-memory publishedPages — diff may be inaccurate");
+    return { pages: Array.from(publishedPages.values()), siteConfig };
+}
+/**
+ * The default source: the four-step monorepo chain above, unchanged, so the
+ * Fastify routes keep answering exactly what they answered before.
+ */
+export const monorepoPublishedSource = {
+    load: (opts) => loadPublishedForDiff(opts)
+};
+// ---------------------------------------------------------------------------
+// Shared publish helpers (also used by the POST /publish handlers)
+// ---------------------------------------------------------------------------
+/**
+ * Reject origins that point at private/loopback IPs or non-http protocols.
+ *
+ * `siteOrigin` arrives from the caller and is fetched server-side, so an
+ * unchecked value turns the orchestrator into an SSRF proxy onto whatever the
+ * host can reach. Local addresses stay allowed outside production because that
+ * is what dev *is*; in production they are allowed only when the deployment
+ * has already declared the origin trusted via `ORCHESTRATOR_CORS_ORIGINS`.
+ */
+export function isSafeOrigin(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return false;
+    const host = parsed.hostname;
+    const isPrivate = host === "localhost" ||
+        host === "127.0.0.1" ||
+        host === "[::1]" ||
+        host === "0.0.0.0" ||
+        host.startsWith("10.") ||
+        host.startsWith("192.168.") ||
+        host.startsWith("169.254.") ||
+        /^172\.(1[6-9]|2\d|3[01])\./.test(host);
+    if (isPrivate) {
+        if (process.env.NODE_ENV !== "production")
+            return true;
+        const corsOrigins = (process.env.ORCHESTRATOR_CORS_ORIGINS ?? "").split(",").map((s) => s.trim().replace(/\/+$/, ""));
+        const normalized = parsed.origin;
+        if (corsOrigins.some((o) => o === normalized))
+            return true;
+        return false;
+    }
+    return true;
+}
+/**
+ * Map a refreshed Vercel `vercelState` to a publish-log status. READY counts
+ * as success; ERROR/CANCELED count as failed. Any other state (BUILDING,
+ * QUEUED, INITIALIZING, UNKNOWN, …) leaves the row at `triggered`.
+ */
+export function publishStatusFromVercelState(state) {
+    if (!state)
+        return null;
+    const upper = state.toUpperCase();
+    if (upper === "READY")
+        return "success";
+    if (upper === "ERROR" || upper === "CANCELED")
+        return "failed";
+    return null;
+}
+function slugToTitle(slug) {
+    return slug === "/" ? "Home" : slug.replace(/^\//, "");
+}
+/**
+ * Build a short human-readable summary of what was published, biased toward
+ * *changes* rather than the full site contents. Falls back to "republished N
+ * pages" when no diff is available.
+ *
+ * Exported because both transports write publish-log rows and a log whose
+ * wording depends on which server wrote it is a log nobody can read.
+ */
+export function buildPublishSummary(opts) {
+    const { changedSlugs, removedSlugs, totalPages, hasDiff } = opts;
+    if (totalPages === 0 && removedSlugs.length === 0)
+        return "Published (no pages)";
+    if (!hasDiff) {
+        return `Republished ${totalPages} ${totalPages === 1 ? "page" : "pages"}`;
+    }
+    if (changedSlugs.length === 0 && removedSlugs.length === 0) {
+        return "Republished — no content changes";
+    }
+    const titles = changedSlugs.map(slugToTitle);
+    const removed = removedSlugs.map(slugToTitle);
+    const parts = [];
+    if (titles.length === 1)
+        parts.push(`Published ${titles[0]}`);
+    else if (titles.length === 2)
+        parts.push(`Published ${titles[0]} and ${titles[1]}`);
+    else if (titles.length === 3)
+        parts.push(`Published ${titles.join(", ")}`);
+    else if (titles.length > 0)
+        parts.push(`Published ${titles.slice(0, 2).join(", ")} +${titles.length - 2} more`);
+    if (removed.length === 1)
+        parts.push(`removed ${removed[0]}`);
+    else if (removed.length > 1)
+        parts.push(`removed ${removed.length} pages`);
+    return parts.join(", ") || `Republished ${totalPages} pages`;
+}
+// ---------------------------------------------------------------------------
+// GET /publish/log
+// ---------------------------------------------------------------------------
+/**
+ * The publish history for a session, newest rows last.
+ *
+ * The limit is clamped rather than trusted: the rows carry per-page slugs and
+ * diff summaries, and an unbounded `?limit=` would let a caller pull the whole
+ * table into one response.
+ */
+export function publishLogAction(query) {
+    if (!query.session)
+        return badRequest("session is required");
+    const scopedSession = scopedSessionKey(normalizeSession(query.session), query.siteId);
+    const requested = typeof query.limit === "string" ? Number(query.limit) : query.limit;
+    const limit = typeof requested === "number" && Number.isFinite(requested) ? Math.max(1, Math.min(100, requested)) : 50;
+    return { code: 200, body: { entries: listPublishLog(scopedSession, limit) } };
+}
+const realStatusDeps = { refresh: refreshPublishStatusFromVercel };
+/**
+ * Poll the deployment a publish kicked off, and mature its log row when the
+ * deployment finally resolves.
+ *
+ * A publish-log row is born "triggered" because `POST /publish` returns while
+ * the build is still running on the host's side. This poll is the only place
+ * that ever learns the outcome, so it is also where the row becomes "success"
+ * or "failed" — without that, every publish would stay pending in the history
+ * panel forever. The row is matched by deployment id where there is one, and
+ * only a still-`triggered` row is touched, so a re-poll after resolution
+ * cannot overwrite a finished row.
+ *
+ * The tracker lives in a non-persisted in-memory Map, so a session that has
+ * not published since the process started genuinely has no status: that is a
+ * 404, not an empty success.
+ */
+export async function publishStatusAction(query, deps = realStatusDeps) {
+    const scopedSession = scopedSessionKey(normalizeSession(query.session), query.siteId);
+    const current = publishStatusBySession.get(scopedSession);
+    /*
+     * Never having published is a state, not an error.
+     *
+     * This answered 404 with "no publish status for session", and an agent
+     * checking whether it was safe to publish read that as publishing being
+     * broken and stopped. It is neither: the tracker is an in-memory row about
+     * *this process's* last attempt, so it is empty before the first publish and
+     * again after every restart, on a site that publishes perfectly well.
+     *
+     * The reply says which question it is answering and names the two endpoints
+     * that answer the other ones — `/publish/diff` for what a publish would
+     * change, `/publish/log` for attempts that outlived this process.
+     */
+    if (!current) {
+        return {
+            code: 200,
+            body: {
+                session: scopedSession,
+                status: "idle",
+                message: "No publish has been attempted for this session in this process. Publish status is held in memory, " +
+                    "so it is also empty after a restart — it is not a report about whether this site can publish. " +
+                    "GET /publish/diff for what a publish would change; GET /publish/log for earlier attempts."
+            }
+        };
+    }
+    const refreshed = await deps.refresh(current);
+    publishStatusBySession.set(scopedSession, refreshed);
+    // Falls back to the most-recent "triggered" row when the deployment id is
+    // missing (deploy-hook targets that don't parse one out of their response).
+    const terminalStatus = publishStatusFromVercelState(refreshed.vercelState);
+    if (terminalStatus) {
+        const target = findPublishLogForStatusUpdate(scopedSession, refreshed.deploymentId);
+        if (target && target.status === "triggered") {
+            updatePublishLogStatusById(target.id, {
+                status: terminalStatus,
+                deploymentId: refreshed.deploymentId ?? target.deploymentId,
+                deploymentUrl: refreshed.deploymentUrl ?? target.deploymentUrl,
+                inspectUrl: refreshed.inspectUrl ?? target.inspectUrl,
+                error: terminalStatus === "failed"
+                    ? refreshed.lastCheckError ?? `vercel_state_${refreshed.vercelState}`
+                    : undefined,
+            });
+        }
+    }
+    return { code: 200, body: refreshed };
+}
+// ---------------------------------------------------------------------------
+// GET /publish/diff
+// ---------------------------------------------------------------------------
+/**
+ * What the editor's "review changes" panel shows: the session draft against
+ * whatever is currently live.
+ */
+export async function publishDiffAction(query, log, source = monorepoPublishedSource) {
+    if (!query.session)
+        return badRequest("session is required");
+    const siteOrigin = typeof query.siteOrigin === "string" ? query.siteOrigin.trim().replace(/\/+$/, "") : "";
+    if (siteOrigin && !isSafeOrigin(siteOrigin)) {
+        log.warn({ siteOrigin, session: query.session, siteId: query.siteId }, "publish/diff: rejected siteOrigin");
+        return badRequest("siteOrigin is not an allowed URL");
+    }
+    const scopedSession = scopedSessionKey(normalizeSession(query.session), query.siteId);
+    const draft = getSessionPages(scopedSession);
+    const draftSiteConfig = getSiteConfig(scopedSession);
+    const published = await source.load({ siteOrigin: siteOrigin || undefined, logger: log });
+    // A source that cannot report the published site config (a CMS adapter has
+    // pages and nothing else) gets the draft's own config compared against
+    // itself, which reads as "unchanged". The alternative — passing null —
+    // would announce the entire site header as newly added on every load, which
+    // is worse than admitting we don't know.
+    const publishedSiteConfig = published.siteConfig === undefined ? draftSiteConfig : published.siteConfig;
+    return {
+        code: 200,
+        body: computePublishDiff(draft, published.pages, { draftSiteConfig, publishedSiteConfig })
+    };
+}

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

@@ -0,0 +1,67 @@
+/**
+ * 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 { listRestoreSnapshots, loadPublishedSnapshotFromCommit, deletePublishSnapshot } from "../publish/publish-helpers.js";
+import type { Logger } from "../logger.js";
+import type { ActionResult } from "./history-actions.js";
+export type { ActionResult };
+/**
+ * The three git-backed helpers, injectable so the actions are testable.
+ *
+ * The real ones shell out to `git log`/`git show`/`git revert` against the
+ * repository root, which a unit test cannot stage without writing commits.
+ * Callers pass nothing and get the real thing.
+ */
+export type RestoreDeps = {
+    listSnapshots: typeof listRestoreSnapshots;
+    loadSnapshot: typeof loadPublishedSnapshotFromCommit;
+    deleteSnapshot: typeof deletePublishSnapshot;
+};
+/**
+ * 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 declare function restoreSnapshotsList(query: {
+    limit?: string | number;
+    siteId?: string;
+}, deps?: RestoreDeps): Promise<ActionResult>;
+/**
+ * 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 declare function restoreSnapshotApply(body: {
+    commit?: string;
+    session?: string;
+    siteId?: string;
+}, log: Logger, deps?: RestoreDeps): Promise<ActionResult>;
+/** Drop a snapshot by reverting the commit that published it. */
+export declare function restoreSnapshotDelete(body: {
+    commit?: string;
+}, deps?: RestoreDeps): Promise<ActionResult>;