@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/model/ai-seo.d.ts

@@ -0,0 +1,208 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type SeoListingFieldKey } from '@aglyn/aglyn/app-utils/seo-listing-fields';
+import type { AiJobOutput, AiJobSummary } from './ai-jobs.types';
+/**
+ * SEO by AI (AGL-2910): the proposals an `seo` job produces, in the shape
+ * both the job step and the console cards read. Pure data and readers — no
+ * server import — so a card can type what it renders from the same module
+ * the step writes it with.
+ *
+ * ## Proposals, never writes
+ *
+ * Every value here is a PROPOSAL. A page's search listing is served from the
+ * screen document, so a job never writes it: the values are staged in the
+ * page's SEO card and saved there. A site audit's content fixes — an image
+ * description, a page's one `h1` — become a new unpublished version only
+ * when a person applies them, and the site-wide proposals land in the SEO
+ * form unsaved. Nothing a job produces changes what a published site serves.
+ *
+ * ## The outputs of a job
+ *
+ * - `fields:{screen|product}:{id}` — one listing's values ({@link AiSeoFieldsProposal}).
+ * - `audit:report` — the site audit: every audited page, its findings and
+ *   its score, and which pages need generated fixes ({@link AiSeoAuditReport}).
+ * - `audit:site` — structured data for the site's entity and the agent
+ *   guidance `/llms.txt` leads with ({@link AiSeoSiteBatch}).
+ * - `audit:fixes:{n}` — one batch of page fixes ({@link AiSeoFixesBatch}).
+ */
+/** What an `seo` job is about, as its `inputs.target` names it. */
+export type AiSeoTarget = 'screen' | 'product' | 'site';
+export declare const AI_SEO_TARGETS: readonly AiSeoTarget[];
+/** What an `seo` job is about, or `null` when its inputs name nothing an SEO job writes. */
+export declare function aiSeoJobTarget(inputs: Record<string, unknown> | null | undefined): AiSeoTarget | null;
+/** Proposed values for one listing, by field. */
+export type AiSeoFieldValues = Partial<Record<SeoListingFieldKey, string>>;
+/** Whether, and where, a page already says a target keyword. */
+export interface AiSeoKeywordCoverage {
+    keyword: string;
+    inTitle: boolean;
+    inDescription: boolean;
+    inH1: boolean;
+    inBody: boolean;
+}
+/** A proposal for one page's or one product's search listing. */
+export interface AiSeoFieldsProposal {
+    kind: 'fields';
+    subject: {
+        kind: 'screen' | 'product';
+        /** `null` for a product not saved yet. */
+        id: string | null;
+        name: string;
+        /** The page's public path, for a screen. */
+        path?: string | null;
+    };
+    values: AiSeoFieldValues;
+    /** The target keywords the listing was asked to cover, and where it now does. */
+    keywords: AiSeoKeywordCoverage[];
+    /** Customer-safe lines worth knowing (a field left out, and why). */
+    notes: string[];
+}
+export type AiSeoFindingCode = 'title-missing' | 'title-too-long' | 'title-duplicate' | 'description-missing' | 'description-too-long' | 'description-duplicate' | 'h1-missing' | 'h1-multiple' | 'h1-thin' | 'image-alt-missing' | 'orphan' | 'keyword-missing' | 'search-discouraged' | 'entity-incomplete' | 'llms-guidance-missing';
+export type AiSeoSeverity = 'high' | 'medium' | 'low';
+export interface AiSeoFinding {
+    code: AiSeoFindingCode;
+    severity: AiSeoSeverity;
+    /** One customer-safe sentence. */
+    message: string;
+    /** The elements it is about: the images without a description, the extra headings. */
+    nodeIds?: string[];
+    /** The other pages it involves: a duplicate's twins. */
+    screenIds?: string[];
+    /** The target keyword, for `keyword-missing`. */
+    keyword?: string;
+}
+/** One audited page. */
+export interface AiSeoPageReport {
+    screenId: string;
+    /** The public path, `/` for the home page. */
+    path: string;
+    name: string;
+    /** The published version the page was audited on. */
+    versionId: string | null;
+    /** 100 with nothing found, less for each finding by its severity. */
+    score: number;
+    findings: AiSeoFinding[];
+    keywords: AiSeoKeywordCoverage[];
+}
+/** The site audit: every audited page, what was found, and what still needs generating. */
+export interface AiSeoAuditReport {
+    kind: 'audit';
+    pages: AiSeoPageReport[];
+    /** Published pages past the audit's page cap, not audited. */
+    skipped: number;
+    /** Findings about the site rather than a page. */
+    site: AiSeoFinding[];
+    /** Whether the site-wide proposal (structured data, agent guidance) is owed. */
+    siteProposal: boolean;
+    /** Pages whose fixes need generated text, in the order the batches take them. */
+    queue: string[];
+    /** How many pages one batch of fixes carries. */
+    batchSize: number;
+    /** The average page score. */
+    score: number;
+    /** Customer-safe lines about the audit itself: a keyword line naming no page, say. */
+    notes: string[];
+}
+/** A content fix: applied into a NEW version of the page, never the published one. */
+export type AiSeoContentFix = 
+/** An image with no description gets one. */
+{
+    kind: 'image-alt';
+    nodeId: string;
+    alt: string;
+}
+/** An existing heading becomes the page's `h1`, with this text. */
+ | {
+    kind: 'h1-set';
+    nodeId: string;
+    text: string;
+}
+/** A page with no heading to promote gets a new `h1` at the top of its content. */
+ | {
+    kind: 'h1-insert';
+    text: string;
+}
+/** An extra `h1` becomes an `h2`, so the page keeps one. */
+ | {
+    kind: 'h1-demote';
+    nodeId: string;
+};
+/** Everything proposed for one page. */
+export interface AiSeoPageFix {
+    screenId: string;
+    /** Listing values, staged in the page's SEO card and saved there. */
+    values: AiSeoFieldValues;
+    content: AiSeoContentFix[];
+    /** Findings with no fix a job can make — an orphan needs a person's link. */
+    guidance: string[];
+}
+export interface AiSeoFixesBatch {
+    kind: 'fixes';
+    /** 1-based. */
+    batch: number;
+    fixes: AiSeoPageFix[];
+    notes: string[];
+}
+/** The site's structured-data fields a proposal may fill, by form field name. */
+export declare const AI_SEO_ENTITY_FORM_FIELDS: readonly ["seo.entity.type", "seo.entity.name", "seo.entity.description", "seo.entity.email", "seo.entity.telephone", "seo.entity.contactType"];
+/** The agent guidance fields `/llms.txt` leads with, by form field name. */
+export declare const AI_SEO_AGENT_FORM_FIELDS: readonly ["seo.agent.whenToUse", "seo.agent.howToUse"];
+export type AiSeoSiteFormField = (typeof AI_SEO_ENTITY_FORM_FIELDS)[number] | (typeof AI_SEO_AGENT_FORM_FIELDS)[number];
+export interface AiSeoSiteProposal {
+    /** Values for the site SEO form, by field name; only what the site's pages support. */
+    values: Partial<Record<AiSeoSiteFormField, string>>;
+    /** `/llms.txt` as it would read once the guidance is saved. */
+    llmsPreview: string;
+    notes: string[];
+}
+export interface AiSeoSiteBatch {
+    kind: 'site';
+    site: AiSeoSiteProposal;
+}
+export type AiSeoProposal = AiSeoFieldsProposal | AiSeoAuditReport | AiSeoFixesBatch | AiSeoSiteBatch;
+/** Output ids, one place. */
+export declare const AI_SEO_OUTPUT_IDS: {
+    readonly report: "audit:report";
+    readonly site: "audit:site";
+    readonly fixes: (batch: number) => string;
+    readonly fields: (kind: "screen" | "product", id: string | null) => string;
+};
+/** What each finding is called where it is listed. */
+export declare const AI_SEO_FINDING_LABELS: Record<AiSeoFindingCode, string>;
+/** A stored proposal, or `null` for anything that is not one. */
+export declare function readAiSeoProposal(value: unknown): AiSeoProposal | null;
+/** One site audit, put back together from a job's outputs. */
+export interface AiSeoAuditView {
+    report: AiSeoAuditReport;
+    /** Every page fix proposed so far, by screen id. */
+    fixes: Record<string, AiSeoPageFix>;
+    site: AiSeoSiteProposal | null;
+    /** Batches recorded so far. */
+    batches: number;
+    /** Whether every batch the report queued has been recorded. */
+    complete: boolean;
+}
+/** The audit a job's outputs describe, or `null` when they describe none. */
+export declare function aiSeoAuditView(outputs: readonly AiJobOutput[]): AiSeoAuditView | null;
+/** The listing proposal a job produced, when it produced one. */
+export declare function aiSeoFieldsProposalOf(job: Pick<AiJobSummary, 'outputs'> | null): AiSeoFieldsProposal | null;
+/** How many content fixes, and how many staged listings, an audit view would apply. */
+export declare function aiSeoApplyCounts(view: AiSeoAuditView): {
+    pagesWithContent: number;
+    pagesWithValues: number;
+};

package/src/lib/model/ai-seo.js

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { isSeoListingFieldKey } from "@aglyn/aglyn/app-utils/seo-listing-fields";
+export const AI_SEO_TARGETS = [
+    'screen',
+    'product',
+    'site'
+];
+/** What an `seo` job is about, or `null` when its inputs name nothing an SEO job writes. */ export function aiSeoJobTarget(inputs) {
+    const target = inputs == null ? void 0 : inputs['target'];
+    return typeof target === 'string' && AI_SEO_TARGETS.includes(target) ? target : null;
+}
+/** The site's structured-data fields a proposal may fill, by form field name. */ export const AI_SEO_ENTITY_FORM_FIELDS = [
+    'seo.entity.type',
+    'seo.entity.name',
+    'seo.entity.description',
+    'seo.entity.email',
+    'seo.entity.telephone',
+    'seo.entity.contactType'
+];
+/** The agent guidance fields `/llms.txt` leads with, by form field name. */ export const AI_SEO_AGENT_FORM_FIELDS = [
+    'seo.agent.whenToUse',
+    'seo.agent.howToUse'
+];
+/** Output ids, one place. */ export const AI_SEO_OUTPUT_IDS = {
+    report: 'audit:report',
+    site: 'audit:site',
+    fixes: (batch)=>`audit:fixes:${batch}`,
+    fields: (kind, id)=>`fields:${kind}:${id != null ? id : 'new'}`
+};
+/** What each finding is called where it is listed. */ export const AI_SEO_FINDING_LABELS = {
+    'title-missing': 'No search title',
+    'title-too-long': 'Title too long',
+    'title-duplicate': 'Title used on another page',
+    'description-missing': 'No search description',
+    'description-too-long': 'Description too long',
+    'description-duplicate': 'Description used on another page',
+    'h1-missing': 'No main heading',
+    'h1-multiple': 'More than one main heading',
+    'h1-thin': 'Main heading says little',
+    'image-alt-missing': 'Images without a description',
+    orphan: 'No page links here',
+    'keyword-missing': 'Target keyword not covered',
+    'search-discouraged': 'Search engines are discouraged',
+    'entity-incomplete': 'Structured data incomplete',
+    'llms-guidance-missing': 'No guidance for AI agents'
+};
+const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+const strings = (value)=>Array.isArray(value) ? value.filter((entry)=>typeof entry === 'string') : [];
+function readValues(value) {
+    const out = {};
+    if (!isRecord(value)) return out;
+    for (const [key, entry] of Object.entries(value)){
+        if (isSeoListingFieldKey(key) && typeof entry === 'string') out[key] = entry;
+    }
+    return out;
+}
+/** A stored proposal, or `null` for anything that is not one. */ export function readAiSeoProposal(value) {
+    if (!isRecord(value)) return null;
+    switch(value['kind']){
+        case 'fields':
+            {
+                var _subject_name;
+                const subject = isRecord(value['subject']) ? value['subject'] : null;
+                if (!subject || subject['kind'] !== 'screen' && subject['kind'] !== 'product') return null;
+                return {
+                    kind: 'fields',
+                    subject: {
+                        kind: subject['kind'],
+                        id: typeof subject['id'] === 'string' ? subject['id'] : null,
+                        name: String((_subject_name = subject['name']) != null ? _subject_name : ''),
+                        path: typeof subject['path'] === 'string' ? subject['path'] : null
+                    },
+                    values: readValues(value['values']),
+                    keywords: Array.isArray(value['keywords']) ? value['keywords'] : [],
+                    notes: strings(value['notes'])
+                };
+            }
+        case 'audit':
+            return Array.isArray(value['pages']) ? value : null;
+        case 'fixes':
+            return Array.isArray(value['fixes']) ? value : null;
+        case 'site':
+            return isRecord(value['site']) ? value : null;
+        default:
+            return null;
+    }
+}
+/** The audit a job's outputs describe, or `null` when they describe none. */ export function aiSeoAuditView(outputs) {
+    let report = null;
+    let site = null;
+    const fixes = {};
+    let batches = 0;
+    for (const output of outputs){
+        if (output.resource !== 'seo') continue;
+        const proposal = readAiSeoProposal(output.proposal);
+        if (!proposal) continue;
+        if (proposal.kind === 'audit') report = proposal;
+        else if (proposal.kind === 'site') site = proposal.site;
+        else if (proposal.kind === 'fixes') {
+            batches += 1;
+            for (const fix of proposal.fixes)fixes[fix.screenId] = fix;
+        }
+    }
+    if (!report) return null;
+    const owedBatches = Math.ceil(report.queue.length / Math.max(1, report.batchSize));
+    return {
+        report,
+        fixes,
+        site,
+        batches,
+        complete: batches >= owedBatches && (!report.siteProposal || site !== null)
+    };
+}
+/** The listing proposal a job produced, when it produced one. */ export function aiSeoFieldsProposalOf(job) {
+    var _ref;
+    for (const output of (_ref = job == null ? void 0 : job.outputs) != null ? _ref : []){
+        if (output.resource !== 'seo') continue;
+        const proposal = readAiSeoProposal(output.proposal);
+        if ((proposal == null ? void 0 : proposal.kind) === 'fields') return proposal;
+    }
+    return null;
+}
+/** How many content fixes, and how many staged listings, an audit view would apply. */ export function aiSeoApplyCounts(view) {
+    let pagesWithContent = 0;
+    let pagesWithValues = 0;
+    for (const fix of Object.values(view.fixes)){
+        if (fix.content.length) pagesWithContent += 1;
+        if (Object.keys(fix.values).length) pagesWithValues += 1;
+    }
+    return {
+        pagesWithContent,
+        pagesWithValues
+    };
+}
+
+//# sourceMappingURL=ai-seo.js.map

package/src/lib/model/ai-seo.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-seo.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  isSeoListingFieldKey,\n  type SeoListingFieldKey,\n} from '@aglyn/aglyn/app-utils/seo-listing-fields'\nimport type { AiJobOutput, AiJobSummary } from './ai-jobs.types'\n\n/**\n * SEO by AI (AGL-2910): the proposals an `seo` job produces, in the shape\n * both the job step and the console cards read. Pure data and readers — no\n * server import — so a card can type what it renders from the same module\n * the step writes it with.\n *\n * ## Proposals, never writes\n *\n * Every value here is a PROPOSAL. A page's search listing is served from the\n * screen document, so a job never writes it: the values are staged in the\n * page's SEO card and saved there. A site audit's content fixes — an image\n * description, a page's one `h1` — become a new unpublished version only\n * when a person applies them, and the site-wide proposals land in the SEO\n * form unsaved. Nothing a job produces changes what a published site serves.\n *\n * ## The outputs of a job\n *\n * - `fields:{screen|product}:{id}` — one listing's values ({@link AiSeoFieldsProposal}).\n * - `audit:report` — the site audit: every audited page, its findings and\n *   its score, and which pages need generated fixes ({@link AiSeoAuditReport}).\n * - `audit:site` — structured data for the site's entity and the agent\n *   guidance `/llms.txt` leads with ({@link AiSeoSiteBatch}).\n * - `audit:fixes:{n}` — one batch of page fixes ({@link AiSeoFixesBatch}).\n */\n\n/** What an `seo` job is about, as its `inputs.target` names it. */\nexport type AiSeoTarget = 'screen' | 'product' | 'site'\n\nexport const AI_SEO_TARGETS: readonly AiSeoTarget[] = ['screen', 'product', 'site']\n\n/** What an `seo` job is about, or `null` when its inputs name nothing an SEO job writes. */\nexport function aiSeoJobTarget(inputs: Record<string, unknown> | null | undefined): AiSeoTarget | null {\n  const target = inputs?.['target']\n  return typeof target === 'string' && (AI_SEO_TARGETS as readonly string[]).includes(target)\n    ? (target as AiSeoTarget)\n    : null\n}\n\n/** Proposed values for one listing, by field. */\nexport type AiSeoFieldValues = Partial<Record<SeoListingFieldKey, string>>\n\n/** Whether, and where, a page already says a target keyword. */\nexport interface AiSeoKeywordCoverage {\n  keyword: string\n  inTitle: boolean\n  inDescription: boolean\n  inH1: boolean\n  inBody: boolean\n}\n\n/** A proposal for one page's or one product's search listing. */\nexport interface AiSeoFieldsProposal {\n  kind: 'fields'\n  subject: {\n    kind: 'screen' | 'product'\n    /** `null` for a product not saved yet. */\n    id: string | null\n    name: string\n    /** The page's public path, for a screen. */\n    path?: string | null\n  }\n  values: AiSeoFieldValues\n  /** The target keywords the listing was asked to cover, and where it now does. */\n  keywords: AiSeoKeywordCoverage[]\n  /** Customer-safe lines worth knowing (a field left out, and why). */\n  notes: string[]\n}\n\nexport type AiSeoFindingCode =\n  | 'title-missing'\n  | 'title-too-long'\n  | 'title-duplicate'\n  | 'description-missing'\n  | 'description-too-long'\n  | 'description-duplicate'\n  | 'h1-missing'\n  | 'h1-multiple'\n  | 'h1-thin'\n  | 'image-alt-missing'\n  | 'orphan'\n  | 'keyword-missing'\n  | 'search-discouraged'\n  | 'entity-incomplete'\n  | 'llms-guidance-missing'\n\nexport type AiSeoSeverity = 'high' | 'medium' | 'low'\n\nexport interface AiSeoFinding {\n  code: AiSeoFindingCode\n  severity: AiSeoSeverity\n  /** One customer-safe sentence. */\n  message: string\n  /** The elements it is about: the images without a description, the extra headings. */\n  nodeIds?: string[]\n  /** The other pages it involves: a duplicate's twins. */\n  screenIds?: string[]\n  /** The target keyword, for `keyword-missing`. */\n  keyword?: string\n}\n\n/** One audited page. */\nexport interface AiSeoPageReport {\n  screenId: string\n  /** The public path, `/` for the home page. */\n  path: string\n  name: string\n  /** The published version the page was audited on. */\n  versionId: string | null\n  /** 100 with nothing found, less for each finding by its severity. */\n  score: number\n  findings: AiSeoFinding[]\n  keywords: AiSeoKeywordCoverage[]\n}\n\n/** The site audit: every audited page, what was found, and what still needs generating. */\nexport interface AiSeoAuditReport {\n  kind: 'audit'\n  pages: AiSeoPageReport[]\n  /** Published pages past the audit's page cap, not audited. */\n  skipped: number\n  /** Findings about the site rather than a page. */\n  site: AiSeoFinding[]\n  /** Whether the site-wide proposal (structured data, agent guidance) is owed. */\n  siteProposal: boolean\n  /** Pages whose fixes need generated text, in the order the batches take them. */\n  queue: string[]\n  /** How many pages one batch of fixes carries. */\n  batchSize: number\n  /** The average page score. */\n  score: number\n  /** Customer-safe lines about the audit itself: a keyword line naming no page, say. */\n  notes: string[]\n}\n\n/** A content fix: applied into a NEW version of the page, never the published one. */\nexport type AiSeoContentFix =\n  /** An image with no description gets one. */\n  | { kind: 'image-alt'; nodeId: string; alt: string }\n  /** An existing heading becomes the page's `h1`, with this text. */\n  | { kind: 'h1-set'; nodeId: string; text: string }\n  /** A page with no heading to promote gets a new `h1` at the top of its content. */\n  | { kind: 'h1-insert'; text: string }\n  /** An extra `h1` becomes an `h2`, so the page keeps one. */\n  | { kind: 'h1-demote'; nodeId: string }\n\n/** Everything proposed for one page. */\nexport interface AiSeoPageFix {\n  screenId: string\n  /** Listing values, staged in the page's SEO card and saved there. */\n  values: AiSeoFieldValues\n  content: AiSeoContentFix[]\n  /** Findings with no fix a job can make — an orphan needs a person's link. */\n  guidance: string[]\n}\n\nexport interface AiSeoFixesBatch {\n  kind: 'fixes'\n  /** 1-based. */\n  batch: number\n  fixes: AiSeoPageFix[]\n  notes: string[]\n}\n\n/** The site's structured-data fields a proposal may fill, by form field name. */\nexport const AI_SEO_ENTITY_FORM_FIELDS = [\n  'seo.entity.type',\n  'seo.entity.name',\n  'seo.entity.description',\n  'seo.entity.email',\n  'seo.entity.telephone',\n  'seo.entity.contactType',\n] as const\n\n/** The agent guidance fields `/llms.txt` leads with, by form field name. */\nexport const AI_SEO_AGENT_FORM_FIELDS = ['seo.agent.whenToUse', 'seo.agent.howToUse'] as const\n\nexport type AiSeoSiteFormField =\n  | (typeof AI_SEO_ENTITY_FORM_FIELDS)[number]\n  | (typeof AI_SEO_AGENT_FORM_FIELDS)[number]\n\nexport interface AiSeoSiteProposal {\n  /** Values for the site SEO form, by field name; only what the site's pages support. */\n  values: Partial<Record<AiSeoSiteFormField, string>>\n  /** `/llms.txt` as it would read once the guidance is saved. */\n  llmsPreview: string\n  notes: string[]\n}\n\nexport interface AiSeoSiteBatch {\n  kind: 'site'\n  site: AiSeoSiteProposal\n}\n\nexport type AiSeoProposal =\n  | AiSeoFieldsProposal\n  | AiSeoAuditReport\n  | AiSeoFixesBatch\n  | AiSeoSiteBatch\n\n/** Output ids, one place. */\nexport const AI_SEO_OUTPUT_IDS = {\n  report: 'audit:report',\n  site: 'audit:site',\n  fixes: (batch: number) => `audit:fixes:${batch}`,\n  fields: (kind: 'screen' | 'product', id: string | null) => `fields:${kind}:${id ?? 'new'}`,\n} as const\n\n/** What each finding is called where it is listed. */\nexport const AI_SEO_FINDING_LABELS: Record<AiSeoFindingCode, string> = {\n  'title-missing': 'No search title',\n  'title-too-long': 'Title too long',\n  'title-duplicate': 'Title used on another page',\n  'description-missing': 'No search description',\n  'description-too-long': 'Description too long',\n  'description-duplicate': 'Description used on another page',\n  'h1-missing': 'No main heading',\n  'h1-multiple': 'More than one main heading',\n  'h1-thin': 'Main heading says little',\n  'image-alt-missing': 'Images without a description',\n  orphan: 'No page links here',\n  'keyword-missing': 'Target keyword not covered',\n  'search-discouraged': 'Search engines are discouraged',\n  'entity-incomplete': 'Structured data incomplete',\n  'llms-guidance-missing': 'No guidance for AI agents',\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\nconst strings = (value: unknown): string[] =>\n  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : []\n\nfunction readValues(value: unknown): AiSeoFieldValues {\n  const out: AiSeoFieldValues = {}\n  if (!isRecord(value)) return out\n  for (const [key, entry] of Object.entries(value)) {\n    if (isSeoListingFieldKey(key) && typeof entry === 'string') out[key] = entry\n  }\n  return out\n}\n\n/** A stored proposal, or `null` for anything that is not one. */\nexport function readAiSeoProposal(value: unknown): AiSeoProposal | null {\n  if (!isRecord(value)) return null\n  switch (value['kind']) {\n    case 'fields': {\n      const subject = isRecord(value['subject']) ? value['subject'] : null\n      if (!subject || (subject['kind'] !== 'screen' && subject['kind'] !== 'product')) return null\n      return {\n        kind: 'fields',\n        subject: {\n          kind: subject['kind'],\n          id: typeof subject['id'] === 'string' ? subject['id'] : null,\n          name: String(subject['name'] ?? ''),\n          path: typeof subject['path'] === 'string' ? subject['path'] : null,\n        },\n        values: readValues(value['values']),\n        keywords: Array.isArray(value['keywords']) ? (value['keywords'] as AiSeoKeywordCoverage[]) : [],\n        notes: strings(value['notes']),\n      }\n    }\n    case 'audit':\n      return Array.isArray(value['pages']) ? (value as unknown as AiSeoAuditReport) : null\n    case 'fixes':\n      return Array.isArray(value['fixes']) ? (value as unknown as AiSeoFixesBatch) : null\n    case 'site':\n      return isRecord(value['site']) ? (value as unknown as AiSeoSiteBatch) : null\n    default:\n      return null\n  }\n}\n\n/** One site audit, put back together from a job's outputs. */\nexport interface AiSeoAuditView {\n  report: AiSeoAuditReport\n  /** Every page fix proposed so far, by screen id. */\n  fixes: Record<string, AiSeoPageFix>\n  site: AiSeoSiteProposal | null\n  /** Batches recorded so far. */\n  batches: number\n  /** Whether every batch the report queued has been recorded. */\n  complete: boolean\n}\n\n/** The audit a job's outputs describe, or `null` when they describe none. */\nexport function aiSeoAuditView(outputs: readonly AiJobOutput[]): AiSeoAuditView | null {\n  let report: AiSeoAuditReport | null = null\n  let site: AiSeoSiteProposal | null = null\n  const fixes: Record<string, AiSeoPageFix> = {}\n  let batches = 0\n  for (const output of outputs) {\n    if (output.resource !== 'seo') continue\n    const proposal = readAiSeoProposal(output.proposal)\n    if (!proposal) continue\n    if (proposal.kind === 'audit') report = proposal\n    else if (proposal.kind === 'site') site = proposal.site\n    else if (proposal.kind === 'fixes') {\n      batches += 1\n      for (const fix of proposal.fixes) fixes[fix.screenId] = fix\n    }\n  }\n  if (!report) return null\n  const owedBatches = Math.ceil(report.queue.length / Math.max(1, report.batchSize))\n  return {\n    report,\n    fixes,\n    site,\n    batches,\n    complete: batches >= owedBatches && (!report.siteProposal || site !== null),\n  }\n}\n\n/** The listing proposal a job produced, when it produced one. */\nexport function aiSeoFieldsProposalOf(job: Pick<AiJobSummary, 'outputs'> | null): AiSeoFieldsProposal | null {\n  for (const output of job?.outputs ?? []) {\n    if (output.resource !== 'seo') continue\n    const proposal = readAiSeoProposal(output.proposal)\n    if (proposal?.kind === 'fields') return proposal\n  }\n  return null\n}\n\n/** How many content fixes, and how many staged listings, an audit view would apply. */\nexport function aiSeoApplyCounts(view: AiSeoAuditView): { pagesWithContent: number; pagesWithValues: number } {\n  let pagesWithContent = 0\n  let pagesWithValues = 0\n  for (const fix of Object.values(view.fixes)) {\n    if (fix.content.length) pagesWithContent += 1\n    if (Object.keys(fix.values).length) pagesWithValues += 1\n  }\n  return { pagesWithContent, pagesWithValues }\n}\n"],"names":["isSeoListingFieldKey","AI_SEO_TARGETS","aiSeoJobTarget","inputs","target","includes","AI_SEO_ENTITY_FORM_FIELDS","AI_SEO_AGENT_FORM_FIELDS","AI_SEO_OUTPUT_IDS","report","site","fixes","batch","fields","kind","id","AI_SEO_FINDING_LABELS","orphan","isRecord","value","Array","isArray","strings","filter","entry","readValues","out","key","Object","entries","readAiSeoProposal","subject","name","String","path","values","keywords","notes","aiSeoAuditView","outputs","batches","output","resource","proposal","fix","screenId","owedBatches","Math","ceil","queue","length","max","batchSize","complete","siteProposal","aiSeoFieldsProposalOf","job","aiSeoApplyCounts","view","pagesWithContent","pagesWithValues","content","keys"],"mappings":"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"}

package/src/lib/model/ai-site-inventory.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The site's inventory as a model sees it (AGL-2935): what the site already
+ * has, so a plan reuses before it creates (doctrine rule 7).
+ *
+ * COMPACT by construction (AGL-2937): ids, names, prop shapes and slugs —
+ * never a node tree, never a record's content. A component is its name and
+ * the props an instance fills in; a form is its field names; a dataset its
+ * field names. That is everything a planner needs to decide "reuse this"
+ * and a generator needs to place a reference, and it is a few hundred
+ * tokens where the trees would be tens of thousands.
+ *
+ * CAPPED three times, and the three are different numbers on purpose
+ * (AGL-2937). The reader holds each kind to `AI_SITE_INVENTORY_MAX_PER_KIND`;
+ * the prompt block LISTS only `AI_SITE_INVENTORY_LISTED_PER_KIND` of them and
+ * is held to `AI_SITE_INVENTORY_MAX_CHARS` besides; and the rest are answered
+ * on request, through the lookup tool the generation loop offers beside every
+ * door's own (`tools/ai-inventory-lookup-tool.ts`).
+ *
+ * The listing cap is what a prompt can afford: the block is volatile, so it
+ * is billed at full input rate on every request and every re-ask, and a site
+ * with two hundred components would spend most of a plan's prompt on rows it
+ * will not use. The read cap is what a LOOKUP can answer from, which is a
+ * different question — a search for "pricing card" is worth nothing if the
+ * card was never read. A kind cut by either is named in `truncated`, so the
+ * model is told more exist rather than concluding they do not.
+ *
+ * The shapes live here, apart from the reader (`runtime/site-inventory.ts`),
+ * so the prompt block, the validators and their specs can hold an inventory
+ * without loading the Admin SDK the reader needs.
+ */
+/**
+ * Rows per kind the reader holds. Above the listing cap on purpose: the rows
+ * past it are what the lookup tool searches, and a row never read cannot be
+ * found. One projection of a few fields each, so the read is small even at
+ * this cap.
+ */
+export declare const AI_SITE_INVENTORY_MAX_PER_KIND = 200;
+/** Rows per kind the prompt block lists; the rest are found by lookup. */
+export declare const AI_SITE_INVENTORY_LISTED_PER_KIND = 40;
+/** The rendered block's ceiling: 2,000 tokens at four characters a token. */
+export declare const AI_SITE_INVENTORY_MAX_CHARS = 8000;
+export type AiInventoryKind = 'components' | 'layouts' | 'templates' | 'forms' | 'datasets' | 'collections' | 'screens';
+export declare const AI_INVENTORY_KINDS: readonly AiInventoryKind[];
+/**
+ * A reusable component's declared props as an instance may fill them: prop
+ * name → its declared type (`text`, `image`, `href`, `number`, `boolean`, …).
+ */
+export type AiComponentPropTypes = Record<string, string>;
+export interface AiInventoryComponent {
+    id: string;
+    name: string;
+    /** The props an instance fills in: name → declared type. */
+    props: AiComponentPropTypes;
+    /**
+     * The facts in square brackets each prop's default shows until a page sets
+     * its own, by prop name (AGL-3056): what a page placing the component still
+     * asks the member to fill. Read for the member's note, never listed in a
+     * prompt; absent when no default holds one.
+     */
+    bracketedDefaults?: Record<string, string[]>;
+}
+export interface AiInventoryLayout {
+    id: string;
+    name: string;
+    /** The layout this one nests inside, when it nests. */
+    parentId: string | null;
+}
+export interface AiInventoryTemplate {
+    id: string;
+    name: string;
+    kind: string;
+}
+export interface AiInventoryForm {
+    id: string;
+    name: string;
+    fields: string[];
+}
+export interface AiInventoryDataset {
+    id: string;
+    name: string;
+    fields: string[];
+}
+export interface AiInventoryCollection {
+    id: string;
+    name: string;
+    slug: string;
+}
+export interface AiInventoryScreen {
+    id: string;
+    name: string;
+    slug: string;
+    layoutId: string | null;
+    /** A collection's entry template rather than a page of its own. */
+    template: boolean;
+}
+/**
+ * The site's one theme, as a planner and the email rule read it: a short
+ * description, the light scheme's colors by palette path, and the families
+ * the theme loads.
+ */
+export interface AiInventoryTheme {
+    summary: string[];
+    colors: Record<string, string>;
+    fonts: string[];
+}
+export interface AiSiteInventory {
+    hostId: string;
+    components: AiInventoryComponent[];
+    layouts: AiInventoryLayout[];
+    templates: AiInventoryTemplate[];
+    forms: AiInventoryForm[];
+    datasets: AiInventoryDataset[];
+    collections: AiInventoryCollection[];
+    screens: AiInventoryScreen[];
+    theme: AiInventoryTheme | null;
+    /** Kinds with more records than are listed. */
+    truncated: AiInventoryKind[];
+}
+/** One inventory record, whatever kind it is. */
+export type AiInventoryRow = AiInventoryComponent | AiInventoryLayout | AiInventoryTemplate | AiInventoryForm | AiInventoryDataset | AiInventoryCollection | AiInventoryScreen;
+/**
+ * The rows of one kind. The inventory's fields are named after their kinds,
+ * so this is a lookup rather than a switch, and it is the one place that
+ * relies on the correspondence: the prompt block, the lookup tool and their
+ * specs all read a kind through it.
+ */
+export declare function aiInventoryRows(inventory: AiSiteInventory, kind: AiInventoryKind): readonly AiInventoryRow[];
+/** The heading one kind's lines are listed under, naming its columns in order. */
+export declare const AI_INVENTORY_KIND_HEADINGS: Readonly<Record<AiInventoryKind, string>>;
+/**
+ * One record as a line, in the order its heading names the columns. The one
+ * renderer: the prompt block and the lookup tool's answer read alike, so a
+ * row found by lookup is the same shape as a row that was listed.
+ */
+export declare function aiInventoryLine(kind: AiInventoryKind, row: AiInventoryRow): string;
+/** Every word of a record a lookup searches: its line, which holds them all. */
+export declare function aiInventoryHaystack(kind: AiInventoryKind, row: AiInventoryRow): string;
+/**
+ * The site's home screens, by id (AGL-3056): a screen at the root or at
+ * `home`, as a seeded site stores its first screen, or one named Home. A link
+ * with nowhere to go is sent there, which is why the doctrine names them.
+ */
+export declare function aiHomeScreenIds(inventory: AiSiteInventory | null): string[];
+/** A site the org does not own; the inventory is never read for it. */
+export declare class AiInventoryScopeError extends Error {
+    constructor(hostId: string);
+}
+export declare function emptyAiSiteInventory(hostId: string): AiSiteInventory;