@simmalugnt-se/payload-content-health 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.8.0
+
+- The editor assistant (0.15.0 or later, with `extensions: { "content-health": true }`) reads the
+  findings itself: `content-health.findings` and `content-health.open`. Editors can ask what to fix
+  first or what is wrong with a page, and be taken to the work list or a batch.
+
 ## 0.7.1
 
 - npm links to simmalugnt.se instead of the private source repository.

package/README.md

@@ -22,11 +22,11 @@ Requires Payload `>=3.90.2 <4`, Next 16 and React 19. The widget uses Payload's
    import { contentHealthPlugin } from "@simmalugnt-se/payload-content-health";
 
    plugins: [
-     seoPlugin({ collections: ["pages"], uploadsCollection: "media" }),
+     seoPlugin({ collections: ["pages"], uploadsCollection: "images" }),
      contentHealthPlugin({
        collections: {
          pages: { seo: true },
-         media: { altText: true },
+         images: { altText: true },
        },
      }),
    ];
@@ -71,7 +71,7 @@ pages: {
     duplicates: false,
   },
 },
-media: { altText: { field: "altText" } },
+images: { altText: { field: "altText" } },
 ```
 
 ### Page body
@@ -167,6 +167,13 @@ other; they share these names:
 | `config.admin.custom.editorAssistant`        | assistant → this plugin | `{ collections, batchCollections }`      |
 | `?batch=…&batchScope=…&ask=…`                | link → assistant        | Documents to fix at once, and the prompt |
 
+With the assistant's `extensions: { "content-health": true }` (editor-assistant 0.15.0 or later),
+the assistant also reads the findings itself, through the extension this plugin registers in
+`config.custom.editorAssistantExtensions`: `content-health.findings` (a summary per category, then
+findings filtered by category, check, collection, document or locale, at most 30) and
+`content-health.open` (the work list, or the batch for one check). Editors can ask "what should I
+fix first?" on the dashboard or "what is wrong with this page?" on a document.
+
 Both parameters are removed from the address once read. `editURL(adminRoute, finding, prompt?)` and
 `listURL(adminRoute, filters)` build these links.
 

package/dist/assistant.d.ts

@@ -0,0 +1,56 @@
+import type { PayloadRequest } from "payload";
+import { type ScanResult, scanContentHealth } from "./scan.ts";
+/**
+ * How content health gives `@simmalugnt-se/payload-editor-assistant` its findings, without an
+ * import: an extension in `config.custom[EXTENSIONS_CUSTOM_KEY]`, which the assistant uses once the
+ * host turns it on (`extensions: { "content-health": true }`). The key and types are copies of the
+ * assistant's (`extensions/contract.ts`); the assistant's contract tests compare them.
+ */
+export declare const EXTENSIONS_CUSTOM_KEY = "editorAssistantExtensions";
+export type AssistantExtension = {
+    id: string;
+    instructions?: string;
+    views?: Array<{
+        path: string;
+        description: string;
+    }>;
+    tools?: AssistantExtensionTool[];
+};
+export type AssistantExtensionTool = {
+    name: string;
+    description: string;
+    input: Record<string, unknown>;
+    risk: "auto";
+    run: (input: Record<string, unknown>, context: AssistantExtensionContext) => Promise<AssistantExtensionResult>;
+};
+export type AssistantExtensionContext = {
+    req: PayloadRequest;
+    path?: string;
+    open?: {
+        collection?: string;
+        global?: string;
+        id?: string | number;
+        locale: string;
+    };
+};
+export type AssistantExtensionResult = {
+    ok: true;
+    data: unknown;
+    navigate?: {
+        href: string;
+        label: string;
+    };
+} | {
+    ok: false;
+    error: string;
+    message: string;
+};
+export declare const EXTENSION_ID = "content-health";
+/** Findings one call returns at most; `more` says how many the filters left out. */
+export declare const MAX_FINDINGS = 30;
+type Scan = (args: Parameters<typeof scanContentHealth>[0]) => Promise<ScanResult>;
+/** `scan` is replaceable for tests. */
+export declare function assistantExtension({ scan: run, }?: {
+    scan?: Scan;
+}): AssistantExtension;
+export {};

package/dist/assistant.js

@@ -0,0 +1,204 @@
+import { CATEGORY_IDS, categoryOf, categoryStats } from "./categories.js";
+import { BATCH_ASK, CATEGORY_LABELS, CHECK_LABELS, findingDetail, uiLanguage } from "./copy.js";
+import { checkStats, countDocuments, sortFindings } from "./group.js";
+import { assistantCollections, BATCH_CHECKS, batchCollections, batchTarget, batchURL, listURL, MAX_BATCH_TARGETS, matchesFilters, VIEW_PATH, } from "./links.js";
+import { scanContentHealth } from "./scan.js";
+import { CHECK_IDS } from "./types.js";
+/**
+ * How content health gives `@simmalugnt-se/payload-editor-assistant` its findings, without an
+ * import: an extension in `config.custom[EXTENSIONS_CUSTOM_KEY]`, which the assistant uses once the
+ * host turns it on (`extensions: { "content-health": true }`). The key and types are copies of the
+ * assistant's (`extensions/contract.ts`); the assistant's contract tests compare them.
+ */
+export const EXTENSIONS_CUSTOM_KEY = "editorAssistantExtensions";
+export const EXTENSION_ID = "content-health";
+/** Findings one call returns at most; `more` says how many the filters left out. */
+export const MAX_FINDINGS = 30;
+const DEFAULT_FINDINGS = 20;
+/** One scan per turn: the turn's tool calls share the editor's request. */
+function scanOncePerRequest(run) {
+    const scans = new WeakMap();
+    return (req) => {
+        let pending = scans.get(req);
+        if (!pending) {
+            pending = run({ payload: req.payload, user: req.user ?? null });
+            scans.set(req, pending);
+        }
+        return pending;
+    };
+}
+const filterInput = {
+    category: {
+        type: "string",
+        enum: [...CATEGORY_IDS],
+        description: "seo, structure, translations or accessibility.",
+    },
+    check: { type: "string", enum: [...CHECK_IDS], description: "One check, by id." },
+    collection: { type: "string", description: "Collection slug, such as pages or images." },
+    locale: { type: "string", description: "Only findings in this content language." },
+};
+/** `scan` is replaceable for tests. */
+export function assistantExtension({ scan: run = scanContentHealth, } = {}) {
+    const scan = scanOncePerRequest(run);
+    return {
+        id: EXTENSION_ID,
+        instructions: [
+            "Content health checks the site's content: SEO (meta titles, descriptions, share images, duplicates), structure (H1, heading levels, thin content, broken internal links), translations (fields empty in a language) and accessibility (image alt texts).",
+            "When the editor asks what needs work, how the site or a page is doing, or what to fix first, call content-health.findings and answer from it, naming pages and problems. Never ask for a screenshot of content health.",
+            'Each finding says how it is fixed: "batch" (many documents at once from the work list), "assistant" (on the document, with you) or "by hand". To start fixing, call content-health.open: with batch true for a batch check, else the work list. It takes the editor there; they start the fix and review each change themselves. Say where they are now ("The 9 missing alt texts are open; Fix 9 with the assistant starts them."); never say anything is fixed or started, and do not propose changes yourself for findings outside the open document. Do not mention findings the tool left out unless the editor asks for more.',
+        ].join(" "),
+        views: [
+            {
+                path: VIEW_PATH,
+                description: "The editor is on the content health work list: issues by category and check, each with a link to the document, and buttons to fix one with the assistant or several at once.",
+            },
+            {
+                path: "/",
+                description: "The dashboard shows a content health widget: the share of checked fields in order, per category.",
+            },
+        ],
+        tools: [
+            {
+                name: `${EXTENSION_ID}.findings`,
+                description: `Content health's findings: first a summary per category (issues, fields checked, documents needing attention), then the findings that match the filters, at most ${MAX_FINDINGS}, each with the document, the problem, the field, the language and how to fix it. Without filters and with a document open: that document's findings; on other views: the whole site's. Read with the editor's access.`,
+                input: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        ...filterInput,
+                        documentId: {
+                            type: ["string", "number"],
+                            description: "Only this document (with collection).",
+                        },
+                        site: {
+                            type: "boolean",
+                            description: "The whole site even when a document is open.",
+                        },
+                        limit: { type: "integer", minimum: 1, maximum: MAX_FINDINGS },
+                    },
+                },
+                risk: "auto",
+                run: async (input, context) => findings(input, context, await scan(context.req)),
+            },
+            {
+                name: `${EXTENSION_ID}.open`,
+                description: `Takes the editor to the content health work list, filtered, or with batch true to the batch that fixes up to ${MAX_BATCH_TARGETS} documents of one check at once (the editor starts it and reviews each). Needs check for a batch.`,
+                input: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: { ...filterInput, batch: { type: "boolean" } },
+                },
+                risk: "auto",
+                run: async (input, context) => open(input, context, () => scan(context.req)),
+            },
+        ],
+    };
+}
+async function findings(input, { req, open }, result) {
+    const custom = req.payload.config.admin?.custom;
+    const withAssistant = new Set(assistantCollections(custom));
+    const inBatches = new Set(batchCollections(custom));
+    const filters = readInput(input);
+    const filtered = Boolean(filters.category || filters.check || filters.collection || input.documentId || input.site);
+    // With a document open and nothing asked for, its own findings.
+    const document = input.documentId !== undefined
+        ? { collection: filters.collection, id: String(input.documentId) }
+        : !filtered && open?.collection && open.id !== undefined
+            ? { collection: open.collection, id: String(open.id) }
+            : undefined;
+    const matching = sortFindings(result.findings).filter((finding) => matchesFilters(finding, filters) &&
+        (!document ||
+            ((!document.collection || finding.collection === document.collection) &&
+                String(finding.id) === document.id)));
+    const limit = typeof input.limit === "number" ? input.limit : DEFAULT_FINDINGS;
+    const stats = checkStats(result.checks, result.checked, result.findings);
+    const documents = Object.values(result.documents).reduce((sum, count) => sum + count, 0);
+    return {
+        ok: true,
+        data: {
+            summary: {
+                documentsChecked: documents,
+                documentsNeedingAttention: countDocuments(result.findings),
+                categories: categoryStats(stats).map((stat) => ({
+                    category: stat.category,
+                    label: CATEGORY_LABELS.en[stat.category],
+                    issues: stat.failing,
+                    fieldsChecked: stat.checked,
+                })),
+            },
+            scope: document ? "one document" : filtered ? "filtered" : "whole site",
+            findings: matching.slice(0, limit).map((finding) => ({
+                check: finding.check,
+                problem: CHECK_LABELS.en[finding.check],
+                detail: findingDetail("en", finding),
+                collection: finding.collection,
+                id: finding.id,
+                title: finding.title,
+                field: finding.path,
+                ...(finding.locale ? { locale: finding.locale } : {}),
+                ...(finding.status === "draft" ? { draft: true } : {}),
+                fix: fixFor(finding, inBatches, withAssistant),
+            })),
+            more: Math.max(0, matching.length - limit),
+            ...(result.problems.length ? { notChecked: result.problems } : {}),
+        },
+    };
+}
+async function open(input, { req }, scan) {
+    const filters = readInput(input);
+    const adminRoute = req.payload.config.routes.admin;
+    if (input.batch !== true) {
+        const category = filters.category ?? (filters.check ? categoryOf(filters.check) : undefined);
+        return {
+            ok: true,
+            data: { link: "work list" },
+            navigate: {
+                href: listURL(adminRoute, { ...filters, category, check: undefined }),
+                label: "Content health",
+            },
+        };
+    }
+    const check = filters.check;
+    if (!check || !BATCH_CHECKS[check]) {
+        return {
+            ok: false,
+            error: "not_batchable",
+            message: "Only some checks can be fixed in a batch: name one whose findings say batch.",
+        };
+    }
+    const inBatches = new Set(batchCollections(req.payload.config.admin?.custom));
+    const targets = sortFindings((await scan()).findings).filter((finding) => matchesFilters(finding, filters) && inBatches.has(finding.collection));
+    if (!targets.length) {
+        return { ok: false, error: "nothing_to_fix", message: "No findings of that check to fix." };
+    }
+    const language = uiLanguage(req.i18n?.language);
+    const ask = BATCH_ASK[language][check]?.(targets[0]) ?? "";
+    const count = Math.min(targets.length, MAX_BATCH_TARGETS);
+    return {
+        ok: true,
+        data: { documents: count, more: targets.length - count },
+        navigate: {
+            href: batchURL(adminRoute, { ...filters, check }, targets.map(batchTarget), ask),
+            label: language === "sv" ? `Åtgärda ${count} med assistenten` : `Fix ${count} with the assistant`,
+        },
+    };
+}
+/** How a finding is fixed: many at once, on its document with the assistant, or by hand. */
+function fixFor(finding, inBatches, withAssistant) {
+    if (BATCH_CHECKS[finding.check] && inBatches.has(finding.collection))
+        return "batch";
+    return withAssistant.has(finding.collection) ? "assistant" : "by hand";
+}
+function readInput(input) {
+    const text = (value) => (typeof value === "string" && value ? value : undefined);
+    const category = text(input.category);
+    const check = text(input.check);
+    return {
+        ...(category && CATEGORY_IDS.includes(category)
+            ? { category: category }
+            : {}),
+        ...(check && CHECK_IDS.includes(check) ? { check: check } : {}),
+        ...(text(input.collection) ? { collection: text(input.collection) } : {}),
+        ...(text(input.locale) ? { locale: text(input.locale) } : {}),
+    };
+}

package/dist/group.d.ts

@@ -25,3 +25,5 @@ export type CheckStats = {
 };
 /** Per check that ran: how many values it looked at and which ones need work. */
 export declare function checkStats(checks: CheckId[], checked: Partial<Record<CheckId, number>>, findings: Finding[]): CheckStats[];
+/** By check, then document, then locale, so a document's locales sit together. */
+export declare function sortFindings(findings: Finding[]): Finding[];

package/dist/group.js

@@ -36,3 +36,12 @@ export function checkStats(checks, checked, findings) {
         return { check, checked: checked[check] ?? 0, failing, documents };
     });
 }
+/** By check, then document, then locale, so a document's locales sit together. */
+export function sortFindings(findings) {
+    return [...findings].sort((a, b) => CHECK_IDS.indexOf(a.check) - CHECK_IDS.indexOf(b.check) ||
+        a.collection.localeCompare(b.collection) ||
+        a.title.localeCompare(b.title) ||
+        String(a.id).localeCompare(String(b.id)) ||
+        a.path.localeCompare(b.path) ||
+        (a.locale ?? "").localeCompare(b.locale ?? ""));
+}

package/dist/plugin.js

@@ -1,3 +1,4 @@
+import { assistantExtension, EXTENSIONS_CUSTOM_KEY } from "./assistant.js";
 import { CHECK_LABELS } from "./copy.js";
 import { VIEW_PATH } from "./links.js";
 import { CLIENT_ENTRY, RSC_ENTRY } from "./package-name.js";
@@ -65,7 +66,15 @@ export function contentHealthPlugin(options) {
                     ...(defaultLayout ? { defaultLayout } : {}),
                 },
             },
-            custom: { ...config.custom, [CUSTOM_KEY]: options },
+            custom: {
+                ...config.custom,
+                [CUSTOM_KEY]: options,
+                // Used by the editor assistant once the host turns it on; harmless without it.
+                [EXTENSIONS_CUSTOM_KEY]: [
+                    ...(config.custom?.[EXTENSIONS_CUSTOM_KEY] ?? []),
+                    assistantExtension(),
+                ],
+            },
         };
     };
 }

package/dist/view/ContentHealthView.js

@@ -4,10 +4,10 @@ import { Gutter, SetStepNav } from "@payloadcms/ui";
 import { redirect } from "next/navigation";
 import { categoryOf, categoryStats, categoryTone, defaultCategory, } from "../categories.js";
 import { ASK, BATCH_ASK, CATEGORY_LABELS, CHECK_LABELS, COPY, findingDetail, LIST_COPY, uiLanguage, } from "../copy.js";
-import { checkStats, countDocuments } from "../group.js";
+import { checkStats, countDocuments, sortFindings } from "../group.js";
 import { accessRedirect, assistantCollections, BATCH_CHECKS, batchCollections, batchTarget, editURL, readFilters, } from "../links.js";
 import { scanContentHealth } from "../scan.js";
-import { CHECK_IDS } from "../types.js";
+import {} from "../types.js";
 import { Ring } from "../widget/Ring.js";
 import { WorkList, } from "./WorkList.js";
 import "../styles/tokens.css";
@@ -95,15 +95,6 @@ export async function ContentHealthView({ initPageResult, params, searchParams,
                                         ? copy.summary(result.findings.length, countDocuments(result.findings))
                                         : copy.none })] })] }), _jsx(WorkList, { adminRoute: adminRoute, batchAsk: batchAsk, categories: categories, collections: collections, initialFilters: initialFilters, language: language, locales: locales, rows: rows }), result.problems.length ? (_jsx("ul", { className: "content-health-list__problems", children: result.problems.map((problem) => (_jsx("li", { children: problem }, problem))) })) : null] }) }));
 }
-/** By check, then document, then locale, so a document's locales sit together. */
-function sortFindings(findings) {
-    return [...findings].sort((a, b) => CHECK_IDS.indexOf(a.check) - CHECK_IDS.indexOf(b.check) ||
-        a.collection.localeCompare(b.collection) ||
-        a.title.localeCompare(b.title) ||
-        String(a.id).localeCompare(String(b.id)) ||
-        a.path.localeCompare(b.path) ||
-        (a.locale ?? "").localeCompare(b.locale ?? ""));
-}
 /** A config label: a string, or one per language. Functions are left to Payload. */
 function label(value, language) {
     if (typeof value === "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simmalugnt-se/payload-content-health",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Content health checks and dashboard widgets for Payload Admin: alt texts, SEO fields and more",
   "keywords": [
     "payload",