@jini-ai/cms 0.5.2 → 0.5.3

package/dist/seo/media.js

@@ -0,0 +1,134 @@
+/**
+ * @file `resolveSeoImageRef` (ADR-PIPE-008 Decision §6, C-013, EC-07;
+ * EC-07's "never generates" clause AMENDED 2026-09-05 — see the ADR's
+ * Amendments section) — media-ref-to-URL resolution for
+ * `ogImage`/`twitterImage`. Read-only, over `media`'s existing repos (no new
+ * port). Never throws — resolves `undefined` on any lookup miss (deleted
+ * asset, trashed asset, unregistered transform) so the rest of the head
+ * render never breaks over one bad image reference.
+ *
+ * Does NOT require a rendition to already exist. It always composes the URL
+ * for the LATEST registered version of `transformName` (`buildSeoImageUrl`
+ * below), whether or not that exact rendition row has been generated yet.
+ * This is safe because the public serving route
+ * (`routes/site/media-rendition.ts` -> `resolveMediaRendition` ->
+ * `isLatestTransformVersion`) always allows anonymous lazy generation for a
+ * not-yet-generated rendition of the latest registered version — the same
+ * "latest" this function selects — so every URL this function emits is
+ * guaranteed servable on first fetch. `assetRenditionRepo` stays on
+ * {@link ResolveSeoImageRefDeps} unused by this function today (kept for
+ * shape stability / potential future consumers, e.g. an admin preview that
+ * wants to know whether a rendition already exists) rather than removed as
+ * part of this change.
+ */
+// The host featured-image port replaces the historical helper/repo bindings described above.
+// The unused assetRenditionRepo is no longer required: resolution still checks no rendition row.
+const ABSOLUTE_URL_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
+function isAbsoluteUrl(value) {
+    return ABSOLUTE_URL_PATTERN.test(value) || value.startsWith("//");
+}
+/** Cosmetic only (ADR-027 §4 — never participates in the rendition lookup itself). */
+const EXT_BY_TRANSFORM_FORMAT = {
+    jpeg: "jpg",
+    png: "png",
+    webp: "webp",
+    gif: "gif",
+};
+/** Splits `"{idOrSlug}:{transformName}"` out of a ref string, or `null` when the ref is not that shape. */
+function parseMediaRefParts(ref) {
+    const separatorIndex = ref.indexOf(":");
+    if (separatorIndex <= 0 || separatorIndex === ref.length - 1)
+        return null;
+    return { idOrSlug: ref.slice(0, separatorIndex), transformName: ref.slice(separatorIndex + 1) };
+}
+/** The asset, looked up by either its id or its (possibly retired-and-current, see
+ *  {@link findMediaByIdOrSlug}) slug, or `null` when it does not exist or is trashed (EC-07
+ *  fail-soft miss). Readable-slugs S4: a stored `<slug>:transform` ref must resolve exactly like a
+ *  `<uuid>:transform` one always has. */
+async function resolveVisibleAsset(deps, workspaceId, idOrSlug) {
+    const asset = await deps.featuredImage.findMediaByIdOrSlug({ workspaceId, idOrSlug });
+    if (!asset || asset.status === "trashed")
+        return null;
+    return asset;
+}
+/** The highest-`version` registered definition for `transformName`, or `null` when none is registered. */
+async function resolveLatestTransformVersion(deps, workspaceId, transformName) {
+    const versions = await deps.transformDefinitionRepo.listByName({ workspaceId, name: transformName });
+    if (versions.length === 0)
+        return null;
+    return versions.reduce((a, b) => (b.version > a.version ? b : a));
+}
+/** The `/m/{key}/{transformName}.v{version}/image.{ext}` URL contract (ADR-027 §4), keyed by the
+ *  asset's current slug when it has a valid one (readable-slugs S4), otherwise its id. */
+function buildSeoImageUrl(deps, asset, transformName, latest) {
+    const ext = EXT_BY_TRANSFORM_FORMAT[latest.params.format] ?? latest.params.format;
+    return deps.featuredImage.mediaPublicPath({ key: deps.featuredImage.mediaUrlKey({ asset }), variant: { kind: "transform", name: transformName, version: latest.version, ext } });
+}
+/**
+ * Resolves an `ogImage`/`twitterImage` field to a URL, or `undefined` on any
+ * miss. Returns `ref` unchanged when it is already an absolute URL; otherwise
+ * returns the site-relative `/m/{key}/...` URL contract (ADR-027 §4), keyed by the asset's current
+ * slug when it has a valid one (readable-slugs S4), otherwise its id —
+ * NOT necessarily absolute (this function has no origin to join, by design;
+ * `seo.ts`'s `resolveShareImages` is the one caller and absolutizes the
+ * result via `toAbsoluteUrl`, since `og:image`/`twitter:image` must be
+ * absolute for crawlers, same as `og:url`).
+ *
+ * Does not check whether a rendition row already exists (AMENDED 2026-09-05
+ * — see this file's header doc for the safety argument): the emitted URL
+ * always targets the latest registered transform version, which the public
+ * `/m/` route always lazily generates on first anonymous fetch.
+ *
+ * @complexity O(1) — bounded repo lookups (one asset read, one transform-
+ * version listing).
+ */
+export async function resolveSeoImageRef(required, _optional = {}) {
+    const { deps, input } = required;
+    const ref = input.ref?.trim();
+    if (!ref)
+        return undefined;
+    if (isAbsoluteUrl(ref))
+        return ref;
+    const parts = parseMediaRefParts(ref);
+    if (!parts)
+        return undefined;
+    const { idOrSlug, transformName } = parts;
+    const asset = await resolveVisibleAsset(deps, input.workspaceId, idOrSlug);
+    if (!asset)
+        return undefined;
+    const latest = await resolveLatestTransformVersion(deps, input.workspaceId, transformName);
+    if (!latest)
+        return undefined;
+    return buildSeoImageUrl(deps, asset, transformName, latest);
+}
+/**
+ * The write-path refusal for an `ogImage`/`twitterImage`/`defaultOgImage` value (2026-10-05): the
+ * message to refuse it with, or `null` to accept it. Both SEO write chokepoints call it
+ * (`setEntrySeoOverrides` in `write-service.ts`, `setSeoSettings` in `settings.ts`), so the chat
+ * tools and the admin REST routes share it.
+ *
+ * The check itself is the post featured image's ({@link resolveFeaturedImageRef}), run on the
+ * ref's `{idOrSlug}` half — one content-type rule for every "this must be an image" media field.
+ * Only a KNOWN non-image is refused. A missing or trashed asset is accepted, as before: the head
+ * render already drops such a ref fail-soft (EC-07, {@link resolveSeoImageRef}), and refusing it
+ * here would be a new rule this fix was not asked for. An absolute URL, a non-ref string and
+ * `null`/`undefined` (clear/omitted) are accepted untouched.
+ *
+ * @complexity O(1) — at most two repo reads and one content-type read.
+ */
+export async function seoImageRefRefusal(required, _optional = {}) {
+    const { deps, input } = required;
+    if (typeof input.ref !== "string")
+        return null;
+    const ref = input.ref.trim();
+    if (!ref || isAbsoluteUrl(ref))
+        return null;
+    const parts = parseMediaRefParts(ref);
+    if (!parts)
+        return null;
+    const resolution = await deps.featuredImage.resolveFeaturedImageRef({ workspaceId: input.workspaceId, ref: parts.idOrSlug });
+    if (resolution.ok || resolution.reason !== "not-image")
+        return null;
+    return `${input.field}: media asset '${parts.idOrSlug}' is ${resolution.contentType}, not an image. A social share image must be an image.`;
+}
+//# sourceMappingURL=media.js.map

package/dist/seo/page-head.d.ts

@@ -0,0 +1,18 @@
+import type { HeadElement, PageHeadContext } from "./types.js";
+import { type GetEntryMetaDeps } from "./seo.js";
+/** Builds SEO's own `PageHeadHook`, closing over the deps `getEntryMeta` needs.
+ * The reserved root slug identifies the content-owned home across template, generic, and bare
+ * renders, which all arrive through the same entry-bearing seam. Only a workspace title value
+ * counts: the setting's default and `ctx.siteTitle`'s display-name fallback are not owner-set titles.
+ * @complexity O(1) bounded reads, including one additional settings read for the root entry.
+ */
+export declare function buildHeadElements(required: {
+    deps: GetEntryMetaDeps;
+    ctx: PageHeadContext;
+    rootSlug: string;
+    /** Returns only an explicitly configured workspace title, normalized by its owner. */
+    siteTitle(required: {
+        workspaceId: string;
+    }, optional?: Record<string, never>): Promise<string | undefined>;
+}, _optional?: Record<string, never>): Promise<HeadElement[]>;
+//# sourceMappingURL=page-head.d.ts.map

package/dist/seo/page-head.js

@@ -0,0 +1,114 @@
+import { FEED_PATH } from "./feed.js";
+import { getEntryMeta } from "./seo.js";
+/**
+ * @file `seoPageHeadHook` (ADR-PIPE-008 Decision, C-003) — SEO's own
+ * `PageHeadHook` implementation. Maps `getEntryMeta`'s resolved `SeoMeta`
+ * into ordered `HeadElement[]` per the fixed priority bands
+ * (behavior.spec.md §2.1): title=100, meta-desc=110, canonical=120,
+ * robots=130, og=140-149, twitter=150-159 (as `kind:"meta"` with a
+ * `twitter:*` name — no separate "twitter" `HeadElement` kind exists),
+ * jsonld=900. Registered once at `server/app.ts` boot into
+ * `page-head.ts`'s registry — never imported directly by `render.ts`.
+ */
+/** Default contributor-level priority (irrelevant with a single v1 contributor; kept explicit for future ones). */
+// Contributor registration and its priority remain host-owned; this producer retains element priorities.
+function robotsContent(noindex, nofollow) {
+    return `${noindex ? "noindex" : "index"},${nofollow ? "nofollow" : "follow"}`;
+}
+/** og:* elements (priority 140-149) — title/type/url always present, image/description only when resolved. */
+function buildOpenGraphElements(og) {
+    const elements = [
+        { kind: "og", property: "og:title", content: og.title, priority: 140 },
+        { kind: "og", property: "og:type", content: og.type, priority: 141 },
+        { kind: "og", property: "og:url", content: og.url, priority: 142 },
+    ];
+    if (og.image)
+        elements.push({ kind: "og", property: "og:image", content: og.image, priority: 143 });
+    if (og.description)
+        elements.push({ kind: "og", property: "og:description", content: og.description, priority: 144 });
+    return elements;
+}
+/** twitter:* meta elements (priority 150-159) — card/title always present, the rest only when resolved. */
+function buildTwitterElements(twitter) {
+    const elements = [
+        { kind: "meta", name: "twitter:card", content: twitter.card, priority: 150 },
+        { kind: "meta", name: "twitter:title", content: twitter.title, priority: 151 },
+    ];
+    if (twitter.description)
+        elements.push({ kind: "meta", name: "twitter:description", content: twitter.description, priority: 152 });
+    if (twitter.image)
+        elements.push({ kind: "meta", name: "twitter:image", content: twitter.image, priority: 153 });
+    if (twitter.site)
+        elements.push({ kind: "meta", name: "twitter:site", content: twitter.site, priority: 154 });
+    return elements;
+}
+/** The BreadcrumbList JSON-LD element (priority 900), or `null` when the entry has no ancestors. */
+function buildBreadcrumbJsonLd(ancestors) {
+    if (!ancestors || ancestors.length === 0)
+        return null;
+    return {
+        kind: "jsonld",
+        priority: 900,
+        data: {
+            "@context": "https://schema.org",
+            "@type": "BreadcrumbList",
+            itemListElement: ancestors.map((ancestor, index) => ({
+                "@type": "ListItem",
+                position: index + 1,
+                // JSON has no undefined value; omit an absent title just as serialization would.
+                ...(ancestor.title === undefined ? {} : { name: ancestor.title }),
+                item: ancestor.url,
+            })),
+        },
+    };
+}
+/** RSS auto-discovery (`features/seo/feed.ts`), on every page. Root-relative, so a static export's
+ *  base-path rewrite prefixes it like any other site link. Priority 125: after canonical, before
+ *  robots. */
+function feedAlternateLink(siteTitle) {
+    return { kind: "link", rel: "alternate", type: "application/rss+xml", title: siteTitle, href: FEED_PATH, priority: 125 };
+}
+/** Builds SEO's own `PageHeadHook`, closing over the deps `getEntryMeta` needs.
+ * The reserved root slug identifies the content-owned home across template, generic, and bare
+ * renders, which all arrive through the same entry-bearing seam. Only a workspace title value
+ * counts: the setting's default and `ctx.siteTitle`'s display-name fallback are not owner-set titles.
+ * @complexity O(1) bounded reads, including one additional settings read for the root entry.
+ */
+export async function buildHeadElements(required, _optional = {}) {
+    const { deps, ctx, rootSlug, siteTitle } = required;
+    if (!ctx.entry) {
+        // Home / entry-less route: no per-entry meta to resolve — still emit site-level tags.
+        return [
+            { kind: "title", text: ctx.siteTitle, priority: 100 },
+            { kind: "link", rel: "canonical", href: ctx.canonicalUrl, priority: 120 },
+            feedAlternateLink(ctx.siteTitle),
+        ];
+    }
+    let homeTitle;
+    if (ctx.entry.slug === rootSlug) {
+        homeTitle = await siteTitle({ workspaceId: ctx.workspaceId });
+    }
+    const resolved = await getEntryMeta({ deps, input: { workspaceId: ctx.workspaceId, entryId: ctx.entry.id, homeTitle } });
+    const elements = [{ kind: "title", text: resolved.title, priority: 100 }];
+    if (resolved.description) {
+        elements.push({ kind: "meta", name: "description", content: resolved.description, priority: 110 });
+    }
+    elements.push({ kind: "link", rel: "canonical", href: resolved.canonical, priority: 120 });
+    elements.push(feedAlternateLink(ctx.siteTitle));
+    elements.push({
+        kind: "meta",
+        name: "robots",
+        content: robotsContent(resolved.robots.noindex, resolved.robots.nofollow),
+        priority: 130,
+    });
+    elements.push(...buildOpenGraphElements(resolved.openGraph));
+    elements.push(...buildTwitterElements(resolved.twitter));
+    for (const jsonLdEntry of resolved.jsonLd) {
+        elements.push({ kind: "jsonld", data: jsonLdEntry, priority: 900 });
+    }
+    const breadcrumb = buildBreadcrumbJsonLd(ctx.entry.ancestors);
+    if (breadcrumb)
+        elements.push(breadcrumb);
+    return elements;
+}
+//# sourceMappingURL=page-head.js.map

package/dist/seo/ports.d.ts

@@ -0,0 +1,221 @@
+/**
+ * @file SEO contract interfaces (SPEC-008, ADR-PIPE-008). Interfaces ONLY.
+ *
+ * ADR-006 note (rule-of-two): introduces NO new infrastructure port. Every
+ * dependency `seo` needs is a typed call to an already-ported existing module
+ * (`post` via `PostRepoPort`, `routing` via `urlFor`, `settings` via
+ * `getEffective`/write-service, `media` via its existing read repos,
+ * `identity` via `authorize()`) — plain dependency-injected function params,
+ * not the ADR-032 stub's "capability handle" abstraction
+ * (`SeoContentReadCap`/`SeoUrlCap`/`SeoSettingsCap`/`SeoCacheCap`/
+ * `SeoPluginCaps`). Those five stub-era interfaces are dropped here (zero
+ * call sites existed, ADR-PIPE-008 Context) — every real function in this
+ * module (`src/seo/{seo,write-service,settings,sitemap,media}.ts`) takes its
+ * dependencies the same direct-DI way every other feature module in this repo
+ * does, matching the Contract Map (C-001..C-024), which never mentions a caps
+ * object either. Documented here as a disclosed simplification, not a silent
+ * one.
+ *
+ * `SitemapCollectHook` is kept (OQ-01: a real, empty, in-module registry ships
+ * in v1 — Decision §7). `SeoQueryPort` is kept as the documented single read
+ * surface INV-09 requires every route to go through — Code Review's
+ * architecture check (T058) verifies every admin/public route calls into
+ * `seo.ts`/`sitemap.ts`'s exported functions, matching this shape, rather than
+ * literally constructing one object with these five methods.
+ */
+/**
+ * @file SEO contracts (SPEC-008, ADR-PIPE-008). Interfaces only.
+ *
+ * Dependencies are explicit function ports. The host binds its post, routing, settings and
+ * featured-image owners; SEO never constructs a second implementation of those domains.
+ * `SitemapCollectHook` remains the ordered contribution seam, scoped to a service instance.
+ * `SeoQueryPort` documents the single evaluator every admin/public reader consumes (INV-09).
+ */
+import type { JsonValue } from "@jini-ai/core/primitives";
+import type { MediaRecord } from "../media/types.js";
+import type { TransformDefinitionRepoPort } from "../media/ports.js";
+import type { HeadElement, PageHeadContext, RobotsPolicy, SeoAnalysis, SeoMeta, SeoSettings, SitemapCollectContext, SitemapEntry } from "./types.js";
+/** Only the post fields SEO reads. The host adapter must preserve other fields during row saves. */
+export interface SeoPostRecord {
+    id: string;
+    workspaceId: string;
+    title: string;
+    slug: string;
+    kind: "post" | "page";
+    status: string;
+    bodyFormat: "doc" | "html";
+    bodyJson: JsonValue;
+    bodyHtml: string | null;
+    updatedAt: string;
+    version: number;
+    seoExtJson?: string | null | undefined;
+    deletedAt?: string | null | undefined;
+    publishAt?: string | null | undefined;
+    featuredMediaId?: string | null | undefined;
+    memberAccessJson?: string | null | undefined;
+}
+export interface SeoPostReadPort {
+    findById(required: {
+        workspaceId: string;
+        id: string;
+    }, optional?: Record<string, never>): Promise<SeoPostRecord | null>;
+    extractPlainText(required: {
+        html: string;
+    }, optional?: Record<string, never>): string;
+    isTrashed(required: {
+        post: SeoPostRecord;
+    }, optional?: Record<string, never>): boolean;
+}
+export interface SeoPostListPort extends SeoPostReadPort {
+    list(required: {
+        workspaceId: string;
+    }, optional?: Record<string, never>): Promise<readonly SeoPostRecord[]>;
+}
+/** Conditional row save and revision append must share one transaction, including rollback. */
+export interface SeoPostWritePort extends SeoPostReadPort {
+    transaction<T>(required: {
+        fn: () => Promise<T>;
+    }, optional?: Record<string, never>): Promise<T>;
+    saveIfVersion(required: {
+        record: SeoPostRecord;
+        ifVersion: number;
+    }, optional?: Record<string, never>): Promise<{
+        applied: boolean;
+    }>;
+    appendRevision(required: {
+        postId: string;
+        workspaceId: string;
+        seq: number;
+        op: "update";
+        stateJson: SeoPostRecord;
+        actorId: string;
+        recordedAt: string;
+    }, optional?: Record<string, never>): Promise<unknown>;
+}
+/** Settings namespace and keys remain `site.seo`; defaults and storage belong to the host. */
+export interface SeoSettingsReaderPort {
+    getSeoSettings(required: {
+        workspaceId: string;
+    }, optional?: Record<string, never>): Promise<SeoSettings>;
+    isDefaultRobotsNoindexExplicitlySet(required: {
+        workspaceId: string;
+    }, optional?: Record<string, never>): Promise<boolean>;
+}
+export interface SeoUrlsPort {
+    postPublicPath(required: {
+        slug: string;
+    }, optional?: Record<string, never>): string;
+    urlFor(required: {
+        target: {
+            kind: "entryRef";
+            entryId: string;
+            contentType: "post" | "page";
+        };
+        ctx: {
+            workspaceId: string;
+        };
+    }, optional?: Record<string, never>): Promise<{
+        canonicalUrl: string;
+    } | null>;
+}
+/** Render-time scheduled publication; no background job or implicit wall clock. */
+export interface SeoLivenessPort {
+    isScheduledAt(required: {
+        post: SeoPostRecord;
+        nowIso: string;
+    }, optional?: Record<string, never>): boolean;
+    isLiveAt(required: {
+        post: SeoPostRecord;
+        nowIso: string;
+    }, optional?: Record<string, never>): boolean;
+    postDisplayDateIso(required: {
+        post: SeoPostRecord;
+    }, optional?: Record<string, never>): string;
+}
+/** Existing media/post helper behavior, bound once by the composition root. */
+export interface SeoFeaturedImagePort {
+    findMediaByIdOrSlug(required: {
+        workspaceId: string;
+        idOrSlug: string;
+    }, optional?: Record<string, never>): Promise<MediaRecord | null>;
+    mediaUrlKey(required: {
+        asset: MediaRecord;
+    }, optional?: Record<string, never>): string;
+    mediaPublicPath(required: {
+        key: string;
+        variant: {
+            kind: "transform";
+            name: string;
+            version: number;
+            ext: string;
+        };
+    }, optional?: Record<string, never>): string;
+    resolveFeaturedImageRef(required: {
+        workspaceId: string;
+        ref: string;
+    }, optional?: Record<string, never>): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+        contentType?: string;
+    }>;
+}
+export interface SeoMediaPort {
+    featuredImage: SeoFeaturedImagePort;
+    transformDefinitionRepo: Pick<TransformDefinitionRepoPort, "listByName">;
+}
+/**
+ * `seo.sitemap.collect` lets other plugins/core contribute URL sets without SEO knowing their
+ * routes. Ships live-but-empty in v1 (OQ-01), with no real registrant yet.
+ */
+export interface SitemapCollectHook {
+    readonly priority: number;
+    handle(ctx: SitemapCollectContext, optional?: Record<string, never>): Promise<SitemapEntry[]>;
+}
+/** Single read surface: evaluator, head producer and public documents share these contracts. */
+export interface SeoQueryPort {
+    getEntryMeta(input: {
+        workspaceId: string;
+        entryId: string;
+    }, optional?: Record<string, never>): Promise<SeoMeta>;
+    renderHead(ctx: PageHeadContext, optional?: Record<string, never>): Promise<HeadElement[]>;
+    buildSitemap(input: {
+        workspaceId: string;
+    }, optional?: Record<string, never>): Promise<SitemapEntry[]>;
+    buildRobots(input: {
+        workspaceId: string;
+    }, optional?: Record<string, never>): Promise<RobotsPolicy>;
+    analyzeEntry(input: {
+        workspaceId: string;
+        entryId: string;
+    }, optional?: Record<string, never>): Promise<SeoAnalysis>;
+}
+/** Idempotent outbox subscriptions: content changes invalidate that workspace's sitemap. */
+export interface SeoEventSubscriptions {
+    onSitemapInvalidated(event: {
+        workspaceId: string;
+    }, optional?: Record<string, never>): Promise<void>;
+    onEntryPublished(event: {
+        payload: {
+            entryId: string;
+            contentType: string;
+        };
+        workspaceId: string;
+    }, optional?: Record<string, never>): Promise<void>;
+    onEntryUpdated(event: {
+        payload: {
+            entryId: string;
+            contentType: string;
+        };
+        workspaceId: string;
+    }, optional?: Record<string, never>): Promise<void>;
+    onEntryUnpublished(event: {
+        payload: {
+            entryId: string;
+            contentType: string;
+        };
+        workspaceId: string;
+    }, optional?: Record<string, never>): Promise<void>;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/seo/ports.js

@@ -0,0 +1,27 @@
+/**
+ * @file SEO contract interfaces (SPEC-008, ADR-PIPE-008). Interfaces ONLY.
+ *
+ * ADR-006 note (rule-of-two): introduces NO new infrastructure port. Every
+ * dependency `seo` needs is a typed call to an already-ported existing module
+ * (`post` via `PostRepoPort`, `routing` via `urlFor`, `settings` via
+ * `getEffective`/write-service, `media` via its existing read repos,
+ * `identity` via `authorize()`) — plain dependency-injected function params,
+ * not the ADR-032 stub's "capability handle" abstraction
+ * (`SeoContentReadCap`/`SeoUrlCap`/`SeoSettingsCap`/`SeoCacheCap`/
+ * `SeoPluginCaps`). Those five stub-era interfaces are dropped here (zero
+ * call sites existed, ADR-PIPE-008 Context) — every real function in this
+ * module (`src/seo/{seo,write-service,settings,sitemap,media}.ts`) takes its
+ * dependencies the same direct-DI way every other feature module in this repo
+ * does, matching the Contract Map (C-001..C-024), which never mentions a caps
+ * object either. Documented here as a disclosed simplification, not a silent
+ * one.
+ *
+ * `SitemapCollectHook` is kept (OQ-01: a real, empty, in-module registry ships
+ * in v1 — Decision §7). `SeoQueryPort` is kept as the documented single read
+ * surface INV-09 requires every route to go through — Code Review's
+ * architecture check (T058) verifies every admin/public route calls into
+ * `seo.ts`/`sitemap.ts`'s exported functions, matching this shape, rather than
+ * literally constructing one object with these five methods.
+ */
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/seo/seo.d.ts

@@ -0,0 +1,73 @@
+import type { OriginRegistryPort } from "@jini-ai/http-kit/verified-origin";
+import type { SeoPostRecord as PostRecord, SeoPostReadPort, SeoSettingsReaderPort, SeoUrlsPort, SeoLivenessPort } from "./ports.js";
+import { type ResolveSeoImageRefDeps } from "./media.js";
+import type { SeoAnalysis, SeoMeta } from "./types.js";
+/**
+ * @file `getEntryMeta`/`analyzeEntry` (ADR-PIPE-008 Decision, C-001/C-002) —
+ * the pure effective-meta evaluator, per-field precedence (behavior.spec.md
+ * §1.1): override ▸ site default ▸ derived. Consumed by the
+ * admin preview, the public render (via `page-head-contributor.ts`), and
+ * `analyzeEntry` — the one evaluator, no back door (INV-09). Never writes
+ * anything — reads only, via injected deps.
+ * The public home render supplies its configured site title as a fallback below explicit SEO
+ * overrides; consumers without that render context retain the entry-title template.
+ */
+export declare const SEO_NAMESPACE = "site.seo";
+/** override > site default > derived excerpt (behavior.spec.md §1.1). Derivation reads whichever
+ *  body column `bodyFormat` says is live — `bodyJson` (TipTap doc) or `bodyHtml` (bespoke-HTML
+ *  Page, SPEC-047/ADR-056 Decision 3) — so an html-format Page gets a real excerpt instead of
+ *  silently resolving to `undefined`. Exported for the RSS feed (`feed.ts`), whose item description
+ *  is the post's own excerpt, never the site-wide default. */
+export declare function deriveExcerpt(required: {
+    post: PostRecord;
+    postRepo: Pick<SeoPostReadPort, "extractPlainText">;
+}, _optional?: Record<string, never>): string | undefined;
+/**
+ * behavior.spec.md §1.1's `robots.noindex` row needs to know whether the
+ * workspace's `default_robots_noindex` was EXPLICITLY configured (site
+ * default present) vs. still resting on the ledger's own schema default
+ * (site default effectively absent) — `getSeoSettings` alone can't
+ * distinguish these (it only returns the resolved value, per
+ * `settings.ts`'s doc comment), so this reads the raw `getEffective`
+ * `sourceLayer` directly. Only `noindex` needs this: `nofollow`'s derived
+ * and default outcomes are identical (`false`), so no test/behavior depends
+ * on distinguishing them there.
+ */
+export interface GetEntryMetaDeps {
+    postRepo: SeoPostReadPort;
+    settings: SeoSettingsReaderPort;
+    media: ResolveSeoImageRefDeps;
+    originRegistry: OriginRegistryPort;
+    runtimeMode: string;
+    urls: SeoUrlsPort;
+    liveness: SeoLivenessPort;
+    clock: {
+        nowIso(): string;
+    };
+}
+export interface GetEntryMetaInput {
+    workspaceId: string;
+    entryId: string;
+    /** Public home render only: configured site title, below an explicit SEO title and above the page-title template. */
+    homeTitle?: string | undefined;
+}
+/**
+ * Resolves the effective `SeoMeta` for one entry (override ▸ site default ▸
+ * derived, per field — behavior.spec.md §1.1). Never partial.
+ * The public head contributor can supply `homeTitle` for the root page; callers that omit it
+ * retain the entry-title template. Explicit SEO/share-title overrides still win.
+ *
+ * @complexity O(1) — one post read, one settings resolution (8 bounded
+ * `getEffective` reads), up to 2 media lookups, one origin lookup (2026-09-03,
+ * absolute-URL fix — {@link resolveWorkspaceOrigin}).
+ */
+export declare function getEntryMeta(required: {
+    deps: GetEntryMetaDeps;
+    input: GetEntryMetaInput;
+}, _optional?: Record<string, never>): Promise<SeoMeta>;
+/** REQ-14 — SEO analysis over `getEntryMeta`'s resolved result (pure decision, no additional I/O). */
+export declare function analyzeEntry(required: {
+    deps: GetEntryMetaDeps;
+    input: GetEntryMetaInput;
+}, _optional?: Record<string, never>): Promise<SeoAnalysis>;
+//# sourceMappingURL=seo.d.ts.map