@simmalugnt-se/payload-editor-assistant 0.1.0

package/dist/form/hash.d.ts

@@ -0,0 +1,2 @@
+export declare function canonicalJson(value: unknown): string;
+export declare function hashFormRevision(value: unknown): Promise<string>;

package/dist/form/hash.js

@@ -0,0 +1,22 @@
+export function canonicalJson(value) {
+    return JSON.stringify(sortValue(value));
+}
+export async function hashFormRevision(value) {
+    const encoded = new TextEncoder().encode(canonicalJson(value));
+    const digest = await crypto.subtle.digest("SHA-256", encoded);
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortValue);
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        const sorted = {};
+        for (const key of Object.keys(record).sort()) {
+            sorted[key] = sortValue(record[key]);
+        }
+        return sorted;
+    }
+    return value;
+}

package/dist/form/operations.d.ts

@@ -0,0 +1,52 @@
+export type FieldPath = string;
+export type FormOperation = {
+    op: "set";
+    path: FieldPath;
+    value: unknown;
+} | {
+    op: "unset";
+    path: FieldPath;
+} | {
+    op: "array.insert";
+    path: FieldPath;
+    index: number;
+    value: unknown;
+} | {
+    op: "array.remove";
+    path: FieldPath;
+    index: number;
+} | {
+    op: "array.move";
+    path: FieldPath;
+    from: number;
+    to: number;
+} | {
+    op: "array.replace";
+    path: FieldPath;
+    index: number;
+    value: unknown;
+} | {
+    op: "blocks.insert";
+    path: FieldPath;
+    index: number;
+    blockType: string;
+    data: Record<string, unknown>;
+} | {
+    op: "blocks.remove";
+    path: FieldPath;
+    index: number;
+} | {
+    op: "blocks.move";
+    path: FieldPath;
+    from: number;
+    to: number;
+} | {
+    op: "blocks.replace";
+    path: FieldPath;
+    index: number;
+    blockType: string;
+    data: Record<string, unknown>;
+};
+export declare const FORM_OPERATIONS: readonly ["set", "unset", "array.insert", "array.remove", "array.move", "array.replace", "blocks.insert", "blocks.remove", "blocks.move", "blocks.replace"];
+export declare function isFormOperation(value: unknown): value is FormOperation;
+export declare function normalizeOperations(raw: unknown): unknown[];

package/dist/form/operations.js

@@ -0,0 +1,52 @@
+export const FORM_OPERATIONS = [
+    "set",
+    "unset",
+    "array.insert",
+    "array.remove",
+    "array.move",
+    "array.replace",
+    "blocks.insert",
+    "blocks.remove",
+    "blocks.move",
+    "blocks.replace",
+];
+export function isFormOperation(value) {
+    if (!value || typeof value !== "object" || !("op" in value)) {
+        return false;
+    }
+    return FORM_OPERATIONS.includes(value.op);
+}
+export function normalizeOperations(raw) {
+    const parsed = parseOperations(raw);
+    return parsed.map(normalizeOperation);
+}
+function parseOperations(raw) {
+    if (typeof raw === "string") {
+        try {
+            return parseOperations(JSON.parse(raw));
+        }
+        catch {
+            return [];
+        }
+    }
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    if (raw && typeof raw === "object") {
+        return [raw];
+    }
+    return [];
+}
+function normalizeOperation(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return value;
+    }
+    const record = value;
+    const op = record.op ?? record.operation ?? record.type;
+    const path = typeof record.path === "string" ? record.path.replaceAll(/\[(\d+)\]/g, ".$1") : record.path;
+    return {
+        ...record,
+        op,
+        path,
+    };
+}

package/dist/form/path.d.ts

@@ -0,0 +1,5 @@
+export type PathSegment = string | number;
+export declare function parseFieldPath(path: string): PathSegment[];
+export declare function getAtPath(data: unknown, path: PathSegment[]): unknown;
+export declare function setAtPath(data: Record<string, unknown>, path: PathSegment[], value: unknown): void;
+export declare function cloneData<T>(value: T): T;

package/dist/form/path.js

@@ -0,0 +1,79 @@
+export function parseFieldPath(path) {
+    if (!path || path.includes("..") || path.startsWith(".") || path.endsWith(".")) {
+        throw new Error(`Invalid field path "${path}".`);
+    }
+    return path.split(".").map((segment) => {
+        if (segment === "") {
+            throw new Error(`Invalid field path "${path}".`);
+        }
+        if (/^\d+$/.test(segment)) {
+            return Number(segment);
+        }
+        return segment;
+    });
+}
+export function getAtPath(data, path) {
+    let current = data;
+    for (const segment of path) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof segment === "number") {
+            if (!Array.isArray(current)) {
+                return undefined;
+            }
+            current = current[segment];
+            continue;
+        }
+        if (typeof current !== "object" || Array.isArray(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+export function setAtPath(data, path, value) {
+    if (path.length === 0) {
+        throw new Error("Cannot set the document root.");
+    }
+    let current = data;
+    for (let index = 0; index < path.length - 1; index += 1) {
+        const segment = path[index];
+        const next = path[index + 1];
+        if (typeof segment === "number") {
+            if (!Array.isArray(current)) {
+                throw new Error("Path expected an array.");
+            }
+            const list = current;
+            if (list[segment] === undefined || list[segment] === null) {
+                list[segment] = typeof next === "number" ? [] : {};
+            }
+            current = list[segment];
+        }
+        else {
+            if (typeof current !== "object" || current === null || Array.isArray(current)) {
+                throw new Error("Path expected an object.");
+            }
+            const record = current;
+            if (!(segment in record) || record[segment] === undefined || record[segment] === null) {
+                record[segment] = typeof next === "number" ? [] : {};
+            }
+            current = record[segment];
+        }
+    }
+    const last = path[path.length - 1];
+    if (typeof last === "number") {
+        if (!Array.isArray(current)) {
+            throw new Error("Path expected an array.");
+        }
+        current[last] = value;
+        return;
+    }
+    if (typeof current !== "object" || current === null || Array.isArray(current)) {
+        throw new Error("Path expected an object.");
+    }
+    current[last] = value;
+}
+export function cloneData(value) {
+    return structuredClone(value);
+}

package/dist/form/shape.d.ts

@@ -0,0 +1,19 @@
+import type { FieldNode } from "../schema/fields.ts";
+/**
+ * Make compiled data safe to store: plain text in rich text fields becomes editor state,
+ * then every block must be typed. Mutates `data`.
+ */
+export declare function finalizeCompiled(data: Record<string, unknown>, fields: FieldNode[]): {
+    ok: true;
+    data: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Check that every blocks field in compiled data holds typed blocks the schema knows.
+ * Drafts skip Payload validation, so an untyped block would otherwise be stored and break Admin.
+ */
+export declare function blockShapeError(data: Record<string, unknown>, fields: FieldNode[]): string | null;
+/** Minimal Lexical editor state: one paragraph per blank-line-separated chunk. */
+export declare function plainTextToLexical(text: string): Record<string, unknown>;

package/dist/form/shape.js

@@ -0,0 +1,137 @@
+/**
+ * Make compiled data safe to store: plain text in rich text fields becomes editor state,
+ * then every block must be typed. Mutates `data`.
+ */
+export function finalizeCompiled(data, fields) {
+    coerceRichText(data, fields);
+    const error = blockShapeError(data, fields);
+    return error ? { ok: false, error } : { ok: true, data };
+}
+/**
+ * Check that every blocks field in compiled data holds typed blocks the schema knows.
+ * Drafts skip Payload validation, so an untyped block would otherwise be stored and break Admin.
+ */
+export function blockShapeError(data, fields) {
+    return checkFields(data, fields, "");
+}
+function checkFields(data, fields, prefix) {
+    for (const field of fields) {
+        const value = data[field.name];
+        if (value === undefined || value === null) {
+            continue;
+        }
+        const path = prefix ? `${prefix}.${field.name}` : field.name;
+        const error = checkField(field, value, path);
+        if (error) {
+            return error;
+        }
+    }
+    return null;
+}
+function checkField(field, value, path) {
+    if (field.type === "blocks") {
+        if (!Array.isArray(value)) {
+            return `"${path}" must be a list of blocks.`;
+        }
+        const blocks = field.blocks ?? [];
+        const slugs = blocks.map((block) => block.slug);
+        for (const [index, item] of value.entries()) {
+            const blockType = isRecord(item) ? item.blockType : undefined;
+            const block = blocks.find((entry) => entry.slug === blockType);
+            if (!isRecord(item) || !block) {
+                return `"${path}.${index}" needs a block type (one of: ${slugs.join(", ")}). Add blocks with blocks.insert, then set their fields.`;
+            }
+            const error = checkFields(item, block.fields, `${path}.${index}`);
+            if (error) {
+                return error;
+            }
+        }
+        return null;
+    }
+    if (!field.fields) {
+        return null;
+    }
+    if (field.type === "array") {
+        if (!Array.isArray(value)) {
+            return `"${path}" must be a list.`;
+        }
+        for (const [index, item] of value.entries()) {
+            if (!isRecord(item)) {
+                return `"${path}.${index}" must be an object.`;
+            }
+            const error = checkFields(item, field.fields, `${path}.${index}`);
+            if (error) {
+                return error;
+            }
+        }
+        return null;
+    }
+    return isRecord(value) ? checkFields(value, field.fields, path) : null;
+}
+function coerceRichText(data, fields) {
+    for (const field of fields) {
+        const value = data[field.name];
+        if (field.type === "richText" && typeof value === "string") {
+            data[field.name] = plainTextToLexical(value);
+        }
+        else if (field.type === "blocks" && Array.isArray(value)) {
+            for (const item of value) {
+                const block = isRecord(item)
+                    ? field.blocks?.find((entry) => entry.slug === item.blockType)
+                    : undefined;
+                if (block && isRecord(item)) {
+                    coerceRichText(item, block.fields);
+                }
+            }
+        }
+        else if (field.fields && Array.isArray(value)) {
+            for (const item of value) {
+                if (isRecord(item)) {
+                    coerceRichText(item, field.fields);
+                }
+            }
+        }
+        else if (field.fields && isRecord(value)) {
+            coerceRichText(value, field.fields);
+        }
+    }
+}
+/** Minimal Lexical editor state: one paragraph per blank-line-separated chunk. */
+export function plainTextToLexical(text) {
+    const paragraphs = text
+        .split(/\n\s*\n/)
+        .map((chunk) => chunk.trim())
+        .filter(Boolean);
+    return {
+        root: {
+            type: "root",
+            format: "",
+            indent: 0,
+            version: 1,
+            direction: "ltr",
+            children: paragraphs.map((chunk) => ({
+                type: "paragraph",
+                format: "",
+                indent: 0,
+                version: 1,
+                direction: "ltr",
+                textFormat: 0,
+                textStyle: "",
+                children: [
+                    {
+                        type: "text",
+                        text: chunk,
+                        format: 0,
+                        style: "",
+                        mode: "normal",
+                        detail: 0,
+                        version: 1,
+                    },
+                ],
+            })),
+        },
+    };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { BuiltinCapability, CapabilityRisk, EntityCapability } from "./capabilities.ts";
+export { BUILTIN_CAPABILITIES, BUILTIN_RISK, ENTITY_CAPABILITIES } from "./capabilities.ts";
+export { editorAssistantPlugin } from "./plugin.ts";
+export type { AssistantShortcut, EditorAssistantPluginOptions, EntityAllowlist, FieldAllowlist, HostLanguageModel, HostToolDefinition, ModelResolver, ProposalValidationResult, } from "./types.ts";
+export { defineEditorAssistantConfig } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { BUILTIN_CAPABILITIES, BUILTIN_RISK, ENTITY_CAPABILITIES } from "./capabilities.js";
+export { editorAssistantPlugin } from "./plugin.js";
+export { defineEditorAssistantConfig } from "./types.js";

package/dist/package-name.d.ts

@@ -0,0 +1,7 @@
+export declare const PACKAGE_NAME = "@simmalugnt-se/payload-editor-assistant";
+export declare const CLIENT_ENTRY = "@simmalugnt-se/payload-editor-assistant/client";
+export declare const ENDPOINT_PREFIX = "/editor-assistant";
+export declare const DEFAULT_AUDIT_SLUG = "editor-assistant-audit";
+export declare const DEFAULT_APPROVAL_SLUG = "editor-assistant-approvals";
+export declare const CSRF_COOKIE = "payload-editor-assistant-csrf";
+export declare const CSRF_HEADER = "x-editor-assistant-csrf";

package/dist/package-name.js

@@ -0,0 +1,7 @@
+export const PACKAGE_NAME = "@simmalugnt-se/payload-editor-assistant";
+export const CLIENT_ENTRY = `${PACKAGE_NAME}/client`;
+export const ENDPOINT_PREFIX = "/editor-assistant";
+export const DEFAULT_AUDIT_SLUG = "editor-assistant-audit";
+export const DEFAULT_APPROVAL_SLUG = "editor-assistant-approvals";
+export const CSRF_COOKIE = "payload-editor-assistant-csrf";
+export const CSRF_HEADER = "x-editor-assistant-csrf";

package/dist/plugin.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from "payload";
+import type { EditorAssistantPluginOptions } from "./types.ts";
+export declare function editorAssistantPlugin(options?: EditorAssistantPluginOptions): (config: Config) => Config;

package/dist/plugin.js

@@ -0,0 +1,110 @@
+import { createApprovalCollection } from "./collections/approvals.js";
+import { createAuditCollection } from "./collections/audit.js";
+import { isDeniedCollectionSlug } from "./config/denied-fields.js";
+import { validateEditorAssistantOptions } from "./config/validate.js";
+import { createChatEndpoint } from "./endpoints/chat.js";
+import { createCsrfEndpoint } from "./endpoints/csrf.js";
+import { createDecideEndpoint } from "./endpoints/decide.js";
+import { createProposeEndpoint } from "./endpoints/propose.js";
+import { CLIENT_ENTRY, DEFAULT_APPROVAL_SLUG } from "./package-name.js";
+export function editorAssistantPlugin(options = {}) {
+    const validated = validateEditorAssistantOptions(options);
+    return (config) => {
+        if (validated.disabled) {
+            return config;
+        }
+        const collections = [...(config.collections ?? [])];
+        const globals = [...(config.globals ?? [])];
+        for (const [index, collection] of collections.entries()) {
+            if (collection.auth && validated.collections[collection.slug]) {
+                throw new Error(`payload-editor-assistant: auth collection "${collection.slug}" cannot be allowlisted.`);
+            }
+            if (validated.collections[collection.slug]) {
+                collections[index] = withDocumentBridge(collection);
+            }
+        }
+        for (const [index, global] of globals.entries()) {
+            if (validated.globals[global.slug]) {
+                globals[index] = withGlobalBridge(global);
+            }
+        }
+        const existingSlugs = new Set(collections.map((collection) => collection.slug));
+        if (!existingSlugs.has(validated.audit.collection)) {
+            collections.push(createAuditCollection(validated.audit.collection));
+        }
+        if (!existingSlugs.has(DEFAULT_APPROVAL_SLUG) &&
+            !isDeniedCollectionSlug(DEFAULT_APPROVAL_SLUG)) {
+            collections.push(createApprovalCollection());
+        }
+        return {
+            ...config,
+            admin: {
+                ...config.admin,
+                components: {
+                    ...config.admin?.components,
+                    providers: [
+                        ...(config.admin?.components?.providers ?? []),
+                        {
+                            path: `${CLIENT_ENTRY}#EditorAssistantProvider`,
+                            clientProps: {
+                                shortcuts: validated.shortcuts,
+                                collections: Object.keys(validated.collections),
+                            },
+                        },
+                    ],
+                    actions: [
+                        ...(config.admin?.components?.actions ?? []),
+                        `${CLIENT_ENTRY}#EditorAssistantAction`,
+                    ],
+                },
+            },
+            collections,
+            globals,
+            endpoints: [
+                ...(config.endpoints ?? []),
+                createCsrfEndpoint(),
+                createChatEndpoint(validated),
+                createProposeEndpoint(validated),
+                createDecideEndpoint(validated),
+            ],
+        };
+    };
+}
+function withDocumentBridge(collection) {
+    const edit = collection.admin?.components?.edit;
+    return {
+        ...collection,
+        admin: {
+            ...collection.admin,
+            components: {
+                ...collection.admin?.components,
+                edit: {
+                    ...edit,
+                    beforeDocumentControls: [
+                        ...(edit?.beforeDocumentControls ?? []),
+                        `${CLIENT_ENTRY}#EditorAssistantDocumentBridge`,
+                    ],
+                },
+            },
+        },
+    };
+}
+function withGlobalBridge(global) {
+    const elements = global.admin?.components?.elements;
+    return {
+        ...global,
+        admin: {
+            ...global.admin,
+            components: {
+                ...global.admin?.components,
+                elements: {
+                    ...elements,
+                    beforeDocumentControls: [
+                        ...(elements?.beforeDocumentControls ?? []),
+                        `${CLIENT_ENTRY}#EditorAssistantDocumentBridge`,
+                    ],
+                },
+            },
+        },
+    };
+}

package/dist/runtime/agent.d.ts

@@ -0,0 +1,42 @@
+import type { PayloadRequest } from "payload";
+import type { ValidatedEditorAssistantOptions } from "../config/validate.ts";
+import { type ToolContext, type ToolOutcome } from "./tools.ts";
+export type AgentChatResult = {
+    ok: true;
+    text: string;
+    pendingApproval?: {
+        title: string;
+        summary: string;
+        approvalId: string;
+        nonce: string;
+        capability: "form.propose" | "draft.create";
+    };
+    navigate?: {
+        href: string;
+        label: string;
+    } | {
+        candidates: Array<{
+            href: string;
+            label: string;
+        }>;
+    };
+} | {
+    ok: false;
+    error: string;
+    message?: string;
+};
+type ChatMessage = {
+    role: "user" | "assistant" | "system";
+    text: string;
+};
+export declare function runAgentTurn(req: PayloadRequest, options: ValidatedEditorAssistantOptions, input: {
+    message: string;
+    messages?: ChatMessage[];
+    bridge: ToolContext["bridge"];
+    formData?: Record<string, unknown>;
+}): Promise<AgentChatResult>;
+export declare function collectResult(text: string, result: {
+    steps?: unknown;
+    toolResults?: unknown;
+}, captured: ToolOutcome[], locale: string, expectedProposal?: boolean): AgentChatResult;
+export {};