@aphexcms/cms-core 9.4.0 → 9.5.0

package/dist/mcp/tools.js

@@ -10,6 +10,7 @@
 import { z } from 'zod';
 import { VALID_FIELD_TYPES, RESERVED_FIELDS, validateSchemaReferences } from '../schema-utils/validator.js';
 import { validateDocumentData } from '../field-validation/utils.js';
+import { validateFile } from '../utils/mime-detect.js';
 import { fieldWriteShape } from '../../cli/generate-types.js';
 import { DEFAULT_BLOCK_STYLES, DEFAULT_BLOCK_DECORATORS, DEFAULT_BLOCK_LISTS } from '../components/admin/fields/richtext/block-defaults.js';
 const ok = (data) => ({
@@ -499,6 +500,73 @@ export function buildContentTools({ aphexCMS, context }) {
                     return fail(`List assets failed: ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
+        },
+        {
+            name: 'upload_asset',
+            description: 'Upload an image or file from base64 data and get back a ready-to-reference value. ' +
+                'The response includes `imageValue` and `fileValue` — drop the matching one straight ' +
+                'into a document field (e.g. a blog post `coverImage`, an author `avatar`, or an inline ' +
+                '`image` block) via update_document. File type is verified from the actual bytes, not the ' +
+                'declared name.',
+            inputSchema: {
+                data: z.string().min(1).describe('Base64-encoded file contents (no data: URI prefix).'),
+                filename: z
+                    .string()
+                    .min(1)
+                    .describe('Original filename, e.g. "cover.png". Its extension helps typing.'),
+                mimeType: z
+                    .string()
+                    .optional()
+                    .describe('Declared MIME type. Optional — the bytes are sniffed regardless.'),
+                alt: z.string().optional().describe('Default alt text, shared across every placement.'),
+                title: z.string().optional(),
+                description: z.string().optional()
+            },
+            handler: async (args) => {
+                const base64 = asString(args, 'data');
+                const filename = asString(args, 'filename');
+                if (!base64)
+                    return fail("'data' (base64 file contents) is required.");
+                if (!filename)
+                    return fail("'filename' is required.");
+                let buffer;
+                try {
+                    buffer = Buffer.from(base64, 'base64');
+                }
+                catch {
+                    return fail("'data' is not valid base64.");
+                }
+                if (buffer.length === 0)
+                    return fail("'data' decoded to zero bytes.");
+                const declaredMime = asString(args, 'mimeType') ?? '';
+                const validation = validateFile(buffer, filename, declaredMime);
+                if (!validation.valid) {
+                    return fail(`Upload rejected: ${validation.error ?? 'file failed validation.'}`);
+                }
+                const mimeType = validation.detectedMimeType || declaredMime || 'application/octet-stream';
+                try {
+                    const asset = await assetService.uploadAsset(orgId, {
+                        buffer,
+                        originalFilename: filename,
+                        mimeType,
+                        size: buffer.length,
+                        alt: asString(args, 'alt') ?? undefined,
+                        title: asString(args, 'title') ?? undefined,
+                        description: asString(args, 'description') ?? undefined,
+                        createdBy: context.user?.id
+                    });
+                    const ref = { _type: 'reference', _ref: asset.id };
+                    return ok({
+                        asset,
+                        // Referenceable field values — use the one matching the target field's type.
+                        imageValue: { _type: 'image', asset: ref },
+                        fileValue: { _type: 'file', asset: ref }
+                    });
+                }
+                catch (err) {
+                    return fail(`Upload failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
         }
     ];
 }

package/dist/permissions-context.svelte.d.ts

@@ -8,12 +8,15 @@ export interface PermissionsContext {
      * such as field-level access lists.
      */
     readonly role: string | null;
-    /** True if the session has the named capability. */
-    can(cap: Capability): boolean;
+    /**
+     * True if the session has the named capability. Accepts core `Capability` ids
+     * (with autocomplete) or any plugin-declared capability string.
+     */
+    can(cap: Capability | (string & {})): boolean;
     /** True if the session has at least one of the capabilities. */
-    canAny(...caps: Capability[]): boolean;
+    canAny(...caps: (Capability | (string & {}))[]): boolean;
     /** True if the session has every one of the capabilities. */
-    canAll(...caps: Capability[]): boolean;
+    canAll(...caps: (Capability | (string & {}))[]): boolean;
 }
 /**
  * Publish a capability context to descendants.

package/dist/permissions-context.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions-context.svelte.d.ts","sourceRoot":"","sources":["../src/lib/permissions-context.svelte.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvD,MAAM,WAAW,kBAAkB;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oDAAoD;IACpD,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC;IAC9B,gEAAgE;IAChE,MAAM,CAAC,GAAG,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACvC,6DAA6D;IAC7D,MAAM,CAAC,GAAG,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;CACvC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACpC,eAAe,EAAE,MAAM,SAAS,MAAM,EAAE,EACxC,OAAO,GAAE,MAAM,MAAM,GAAG,IAAiB,GACvC,kBAAkB,CAsBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,kBAAkB,CAKnD"}
+{"version":3,"file":"permissions-context.svelte.d.ts","sourceRoot":"","sources":["../src/lib/permissions-context.svelte.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvD,MAAM,WAAW,kBAAkB;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC;IAC9C,gEAAgE;IAChE,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC;IACzD,6DAA6D;IAC7D,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC;CACzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACpC,eAAe,EAAE,MAAM,SAAS,MAAM,EAAE,EACxC,OAAO,GAAE,MAAM,MAAM,GAAG,IAAiB,GACvC,kBAAkB,CAsBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,kBAAkB,CAKnD"}

package/dist/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './resolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/plugins/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC"}

package/dist/plugins/index.js

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './resolver.js';

package/dist/plugins/resolver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Part resolver — indexes a plugin list by extension point and answers the
+ * queries core needs (schemas to merge, routes to mount, document actions for a
+ * given type, a field component for an `input` key). Built once at boot from
+ * `config.plugins` and exposed on the engine so both server and admin consult the
+ * same resolved model. Validates duplicate part ids up front — no silent overrides.
+ */
+import type { AdminToolPart, CMSPlugin, DocumentActionPart, FieldComponentPart, PartKind, PluginPart, ServerRoutePart, SettingsPart } from './types.js';
+import type { SchemaType } from '../types/schemas.js';
+import { type CapabilityDefinition } from '../types/capabilities.js';
+type PartOf<K extends PartKind> = Extract<PluginPart, {
+    implements: K;
+}>;
+export interface PartResolver {
+    readonly plugins: CMSPlugin[];
+    /** All parts implementing a given extension point, typed to that part kind. */
+    getParts<K extends PartKind>(kind: K): PartOf<K>[];
+    /** Flattened schema contributions, ready to merge into `schemaTypes`. */
+    schemaTypes(): SchemaType[];
+    /** Apply every `aphex/schema/transform` part, in order, to a schema list. */
+    applySchemaTransforms(schemas: SchemaType[]): SchemaType[];
+    /** Server-route parts to mount under `/api`. */
+    serverRoutes(): ServerRoutePart[];
+    /** Deduplicated capability id strings declared by plugins. */
+    capabilities(): string[];
+    /** The full capability catalog — built-in definitions plus plugin-declared ones,
+     *  deduped by id. This is the registry the roles UI renders. */
+    capabilityCatalog(): CapabilityDefinition[];
+    /** Document actions applicable to a document type, capability- and order-filtered. */
+    documentActions(args: {
+        schemaName: string;
+        capabilities?: string[];
+        overrideAccess?: boolean;
+    }): DocumentActionPart[];
+    /** Admin tools, capability- and order-filtered. */
+    adminTools(args?: {
+        capabilities?: string[];
+        overrideAccess?: boolean;
+    }): AdminToolPart[];
+    /** The field component registered for a given `input` key, if any. */
+    fieldComponent(input: string): FieldComponentPart | undefined;
+    /** All plugin settings declarations, in registration order. */
+    settingsDeclarations(): SettingsPart[];
+    /** The settings declaration for a given plugin id, if any. */
+    settingsDeclaration(pluginId: string): SettingsPart | undefined;
+}
+export declare function createPartResolver(plugins?: CMSPlugin[]): PartResolver;
+export {};
+//# sourceMappingURL=resolver.d.ts.map

package/dist/plugins/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/lib/plugins/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EACX,aAAa,EACb,SAAS,EACT,kBAAkB,EAClB,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,eAAe,EACf,YAAY,EACZ,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAGN,KAAK,oBAAoB,EACzB,MAAM,uBAAuB,CAAC;AAE/B,KAAK,MAAM,CAAC,CAAC,SAAS,QAAQ,IAAI,OAAO,CAAC,UAAU,EAAE;IAAE,UAAU,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC;AAEzE,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IACnD,yEAAyE;IACzE,WAAW,IAAI,UAAU,EAAE,CAAC;IAC5B,6EAA6E;IAC7E,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAAC;IAC3D,gDAAgD;IAChD,YAAY,IAAI,eAAe,EAAE,CAAC;IAClC,8DAA8D;IAC9D,YAAY,IAAI,MAAM,EAAE,CAAC;IACzB;oEACgE;IAChE,iBAAiB,IAAI,oBAAoB,EAAE,CAAC;IAC5C,sFAAsF;IACtF,eAAe,CAAC,IAAI,EAAE;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,cAAc,CAAC,EAAE,OAAO,CAAC;KACzB,GAAG,kBAAkB,EAAE,CAAC;IACzB,mDAAmD;IACnD,UAAU,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,aAAa,EAAE,CAAC;IAC1F,sEAAsE;IACtE,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAC;IAC9D,+DAA+D;IAC/D,oBAAoB,IAAI,YAAY,EAAE,CAAC;IACvC,8DAA8D;IAC9D,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;CAChE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,SAAS,EAAO,GAAG,YAAY,CAgF1E"}

package/dist/plugins/resolver.js

@@ -0,0 +1,65 @@
+import { defineCapability, mergeCapabilityCatalog } from '../types/capabilities.js';
+export function createPartResolver(plugins = []) {
+    const allParts = plugins.flatMap((p) => p.parts ?? []);
+    // Duplicate-id validation, per extension point. Parts without an id (schema,
+    // capabilities, field-component) are exempt.
+    const seen = new Map();
+    for (const part of allParts) {
+        if ('id' in part && typeof part.id === 'string') {
+            const bucket = seen.get(part.implements) ?? new Set();
+            if (bucket.has(part.id)) {
+                throw new Error(`Duplicate plugin part id "${part.id}" for ${part.implements}. ` +
+                    `Part ids must be unique per extension point.`);
+            }
+            bucket.add(part.id);
+            seen.set(part.implements, bucket);
+        }
+    }
+    // Settings parts key on `pluginId` (not `id`), so guard their uniqueness separately —
+    // two declarations for one plugin would fight over the same storage row.
+    const settingsIds = new Set();
+    for (const part of allParts) {
+        if (part.implements !== 'aphex/settings')
+            continue;
+        if (settingsIds.has(part.pluginId)) {
+            throw new Error(`Duplicate plugin settings declaration for "${part.pluginId}". ` +
+                `Each plugin may declare settings once.`);
+        }
+        settingsIds.add(part.pluginId);
+    }
+    const getParts = (kind) => allParts.filter((p) => p.implements === kind);
+    const hasCaps = (required, caps, overrideAccess) => overrideAccess || !required || required.length === 0 || required.every((c) => caps.includes(c));
+    return {
+        plugins,
+        getParts,
+        schemaTypes: () => getParts('aphex/schema').flatMap((p) => p.schemas),
+        applySchemaTransforms: (schemas) => getParts('aphex/schema/transform').reduce((acc, part) => part.transform(acc), schemas),
+        serverRoutes: () => getParts('aphex/server/route'),
+        capabilities: () => {
+            const set = new Set();
+            for (const p of getParts('aphex/capabilities'))
+                for (const c of p.capabilities)
+                    set.add(typeof c === 'string' ? c : c.id);
+            return [...set];
+        },
+        capabilityCatalog: () => {
+            // Normalize each plugin-declared capability (bare id or full definition),
+            // then merge with the built-in catalog — first definition of an id wins.
+            const pluginDefs = [];
+            for (const p of getParts('aphex/capabilities'))
+                for (const c of p.capabilities)
+                    pluginDefs.push(typeof c === 'string' ? defineCapability(c) : c);
+            return mergeCapabilityCatalog(pluginDefs);
+        },
+        documentActions: ({ schemaName, capabilities = [], overrideAccess = false }) => getParts('aphex/document/action')
+            .filter((a) => !a.appliesTo || a.appliesTo.includes(schemaName))
+            .filter((a) => hasCaps(a.requiredCapabilities, capabilities, overrideAccess))
+            .sort((a, b) => (a.order ?? 0) - (b.order ?? 0)),
+        adminTools: ({ capabilities = [], overrideAccess = false } = {}) => getParts('aphex/admin/tool')
+            .filter((t) => hasCaps(t.requiredCapabilities, capabilities, overrideAccess))
+            .sort((a, b) => (a.order ?? 0) - (b.order ?? 0)),
+        fieldComponent: (input) => getParts('aphex/field/component').find((f) => f.input === input),
+        settingsDeclarations: () => getParts('aphex/settings'),
+        settingsDeclaration: (pluginId) => getParts('aphex/settings').find((s) => s.pluginId === pluginId)
+    };
+}

package/dist/plugins/types.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Plugin type system — the public authoring surface.
+ *
+ * A plugin is a manifest of typed "parts", each implementing a named extension
+ * point. The kinds are split into two planes (see PLUGIN_SYSTEM_PLAN.md §Constraint):
+ *
+ *  - SERVER / serializable plane — schemas, server routes, capabilities. Collected
+ *    by the engine at boot; safe to reason about without loading any component.
+ *  - COMPONENT plane — document actions, admin tools, field components. These carry
+ *    Svelte components and are only ever imported into admin module code, never
+ *    passed through SvelteKit `load` (load data must stay serializable).
+ *
+ * All imports here are type-only, so this module is safe on both planes.
+ */
+import type { Component } from 'svelte';
+import type { Context, Hono } from 'hono';
+import type { AphexEnv } from '../server/api/index.js';
+import type { Field, SettingsField, SchemaType } from '../types/schemas.js';
+import type { AdminArea } from '../admin/types.js';
+import type { CapabilityDefinition } from '../types/capabilities.js';
+/** Known extension points. Plugins may also register custom string kinds. */
+export type PartKind = 'aphex/schema' | 'aphex/schema/transform' | 'aphex/server/route' | 'aphex/capabilities' | 'aphex/settings' | 'aphex/document/action' | 'aphex/admin/tool' | 'aphex/field/component';
+/** Contributes content schemas, merged into the app's `schemaTypes`. */
+export interface SchemaPart {
+    implements: 'aphex/schema';
+    schemas: SchemaType[];
+}
+/**
+ * Transforms the resolved schema list — decorate existing types, not just add new
+ * ones (e.g. inject an SEO field group into a set of collections). Runs after all
+ * `aphex/schema` parts merge, on both the server engine and the admin, so the
+ * transform must be pure and deterministic. This is what lets a plugin "enable"
+ * itself on chosen document types the way Payload's `collections: [...]` does.
+ */
+export interface SchemaTransformPart {
+    implements: 'aphex/schema/transform';
+    transform: (schemas: SchemaType[]) => SchemaType[];
+}
+/**
+ * Contributes an HTTP endpoint under `/api`. `path: '/bookings'` + `method: 'POST'`
+ * becomes `POST /api/bookings`. The handler gets the same Hono context as built-ins
+ * (`c.var.aphexCMS`, `c.var.auth`).
+ */
+export interface ServerRoutePart {
+    implements: 'aphex/server/route';
+    /** Unique across all plugins — collisions are a startup error. */
+    id: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    handler: (c: Context<AphexEnv>) => Response | Promise<Response>;
+    /**
+     * Who may call this route. Mandatory and with no default: a plugin route is an
+     * ordinary internet-facing endpoint, and "I forgot" must not be spellable as
+     * "anyone may call this". Say which of the three you mean:
+     *
+     * - `['forms.export']` — must be authenticated AND hold every listed capability.
+     *   The usual answer. The CMS gates the route before the handler runs (401 with no
+     *   session/api-key, 403 when capabilities are missing), so the check can't be
+     *   forgotten in the handler.
+     * - `[]` — must be authenticated, but any role will do. Use when membership of the
+     *   organization is itself the authorization.
+     * - `'public'` — no gate; anyone on the internet can call it. For webhook receivers
+     *   and the like, where the handler does its own verification (a signature, a shared
+     *   secret). Opting out is deliberate and greppable.
+     */
+    requiredCapabilities: string[] | 'public';
+}
+/**
+ * Declares custom capabilities this plugin introduces — surfaced (and assignable) in
+ * the roles UI. Pass `defineCapability(id, { title, description, group })` for full
+ * metadata, or a bare id string (labelled from its last segment). Merged with the
+ * built-in catalog by the part resolver (`capabilityCatalog()`); a plugin can't
+ * redefine a core capability.
+ */
+export interface CapabilitiesPart {
+    implements: 'aphex/capabilities';
+    capabilities: (string | CapabilityDefinition)[];
+}
+/**
+ * Declares a plugin's **settings surface** — configuration a user edits in the
+ * admin UI (connection details, toggles, and — in phase 2 — secrets), stored
+ * per-`(organization, plugin)` and injected back into the plugin's server code.
+ *
+ * This is CONFIG, not content: settings are deliberately NOT content schema types.
+ * They never enter document lists, draft/published perspectives, versioning, the
+ * content REST/GraphQL API, MCP tools, or generated types. Only the field *renderer*
+ * is reused (the same UI that draws a document field), never the type registry,
+ * content storage, or content API. See references/plugin-settings-and-secrets-scope.md.
+ *
+ * Declaration only, like every other serializable part — the host owns rendering,
+ * storage, encryption, gating, and injection. A plugin only says what its settings
+ * look like.
+ */
+export interface SettingsPart {
+    implements: 'aphex/settings';
+    /**
+     * Which plugin these settings belong to — the storage key alongside the org.
+     * Use the plugin's package name (e.g. `@aphexcms/forms`) so it's stable and unique.
+     */
+    pluginId: string;
+    /** Human label for the settings section in the admin UI. */
+    title: string;
+    /** Optional one-line description shown under the title. */
+    description?: string;
+    /**
+     * The settings fields. `SettingsField` is a deliberately narrow subset — `string`,
+     * `text`, `number`, `boolean`, plus the settings-only `secret` (write-only,
+     * encrypted at rest) — so every declared field is one the panel really renders and
+     * the service really validates. No content-schema features (references, portable
+     * text, assets) and no custom `input` widgets. Values are type-checked against
+     * these declarations on save.
+     */
+    fields: SettingsField[];
+    /**
+     * Capabilities required to view/edit this settings section. Defaults to the
+     * built-in `plugin.settings.manage` when omitted — set a narrower capability to
+     * gate a specific plugin's settings more tightly.
+     */
+    requiredCapabilities?: string[];
+}
+/**
+ * A minimal, stable context handed to a document-action component. Deliberately
+ * decoupled from editor internals — actions get exactly this and nothing more, so
+ * the editor can be refactored without breaking plugins.
+ */
+export interface DocumentActionProps {
+    /** Null while the document is new and unsaved. */
+    documentId: string | null;
+    schema: SchemaType;
+    /** The live edited draft data. */
+    data: Record<string, unknown>;
+    status: 'new' | 'draft' | 'published' | 'unpublished';
+    /** Shallow-merge a patch into the document's data. */
+    updateData: (patch: Record<string, unknown>) => void;
+    save: () => Promise<void>;
+    publish: () => Promise<void>;
+}
+/** Adds a button/action to the document editor toolbar. */
+export interface DocumentActionPart {
+    implements: 'aphex/document/action';
+    /** Unique across all plugins. */
+    id: string;
+    title: string;
+    icon?: Component;
+    component: Component<{
+        action: DocumentActionProps;
+    }>;
+    /** Document type names this applies to. Omit for all types. */
+    appliesTo?: string[];
+    requiredCapabilities?: string[];
+    order?: number;
+}
+/**
+ * The stable context handed to an admin-tool component — enough to read the
+ * environment, gate on capabilities, and navigate, without touching AdminApp
+ * internals. For document data, tools use the REST client (session-authenticated).
+ */
+export interface AdminToolProps {
+    organizationId: string | null;
+    capabilities: readonly string[];
+    role: string | null;
+    /** True if the session has the capability (privileged roles bypass). */
+    can: (capability: string) => boolean;
+    /** All content schemas (read-only), for listing document types etc. */
+    schemas: SchemaType[];
+    /** Switch the active admin area/tab (e.g. back to `'structure'`). */
+    navigate: (area: AdminArea) => void;
+    /** Open a document in the editor. */
+    openDocument: (documentType: string, documentId: string) => void;
+}
+/** Adds a top-level admin section (its own tool). */
+export interface AdminToolPart {
+    implements: 'aphex/admin/tool';
+    /** Unique across all plugins; also the tool's route key. */
+    id: string;
+    title: string;
+    icon?: Component;
+    component: Component<{
+        tool: AdminToolProps;
+    }>;
+    requiredCapabilities?: string[];
+    order?: number;
+    /**
+     * Where the tool's trigger renders. `'tab'` (default) puts it in the top tab
+     * strip alongside Content/Media/Vision; `'sidebar'` puts it in the left sidebar
+     * nav instead — better once several plugins are installed and the tab strip
+     * would overflow. Either way the tool opens the same `plugin:<id>` area.
+     */
+    placement?: 'tab' | 'sidebar';
+}
+/**
+ * The stable props a field-input widget receives — the same shape the built-in
+ * field renderers use, so a plugin widget is a drop-in replacement.
+ */
+export interface FieldComponentProps {
+    field: Field;
+    value: unknown;
+    onUpdate: (value: unknown) => void;
+    readonly?: boolean;
+    /** Validation-state CSS classes to spread onto the control (optional). */
+    validationClasses?: string;
+    /** The whole document's data — for widgets that read sibling fields (e.g. an SEO preview). */
+    documentData?: Record<string, unknown>;
+    /** The document's type name (e.g. `'author'`) — for widgets that vary by type. */
+    schemaType?: string;
+}
+/**
+ * Provides a custom input widget, selected by a field's `input` key in the schema
+ * (e.g. `{ type: 'string', input: 'color' }`).
+ */
+export interface FieldComponentPart {
+    implements: 'aphex/field/component';
+    /** Matched against a field's `input` property. */
+    input: string;
+    component: Component<FieldComponentProps>;
+}
+export type PluginPart = SchemaPart | SchemaTransformPart | ServerRoutePart | CapabilitiesPart | SettingsPart | DocumentActionPart | AdminToolPart | FieldComponentPart;
+/** A plugin manifest. Returned by `definePlugin`. */
+export interface CMSPlugin {
+    /** Package-style name, e.g. `@acme/aphex-plugin-seo`. Used in error messages. */
+    name: string;
+    version?: string;
+    parts?: PluginPart[];
+}
+/** Registration hook available to server-route parts (kept for the api-mount seam). */
+export type RegisterRoutes = (app: Hono<AphexEnv>) => void;
+/**
+ * Identity helper that pins the `CMSPlugin` type for authoring. Kept a pure
+ * pass-through so bundlers can tree-shake unused plugins; validation (duplicate
+ * ids/names) happens in the part resolver at boot, where it can see all plugins.
+ */
+export declare function definePlugin(plugin: CMSPlugin): CMSPlugin;
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/plugins/types.ts"],"names":[],"mappings":"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"}

package/dist/plugins/types.js

@@ -0,0 +1,8 @@
+/**
+ * Identity helper that pins the `CMSPlugin` type for authoring. Kept a pure
+ * pass-through so bundlers can tree-shake unused plugins; validation (duplicate
+ * ids/names) happens in the part resolver at boot, where it can see all plugins.
+ */
+export function definePlugin(plugin) {
+    return plugin;
+}

package/dist/schema-utils/desugar.d.ts

@@ -0,0 +1,27 @@
+import type { Field, SchemaType } from '../types/schemas.js';
+export interface DesugarOptions {
+    /** The authored `type` keyword to replace, e.g. `'color'`. */
+    type: string;
+    /**
+     * Build the replacement from the authored field. Own the *shape* only — `type`,
+     * `fields`, and the default `input`/`inputOptions`. Anything you copy off the
+     * authored field here is redundant: it is layered back on afterwards.
+     */
+    build: (authored: Field) => Field;
+    /**
+     * Keys that exist only on the sugar type and must not survive onto the expanded
+     * field (e.g. color's `alpha`, which becomes `inputOptions.alpha`). Everything
+     * else the author wrote is preserved.
+     */
+    sugarKeys?: readonly string[];
+}
+/**
+ * Desugar every `{ type: <options.type> }` field across a schema list, recursing into
+ * nested objects and array members, preserving everything the author declared.
+ *
+ * Intended as the body of an `aphex/schema/transform` part, so it runs identically in
+ * the engine, the admin, and the type generator — nothing downstream ever sees the
+ * sugar keyword.
+ */
+export declare function desugarFieldType(schemas: SchemaType[], options: DesugarOptions): SchemaType[];
+//# sourceMappingURL=desugar.d.ts.map

package/dist/schema-utils/desugar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desugar.d.ts","sourceRoot":"","sources":["../../src/lib/schema-utils/desugar.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAiB,MAAM,kBAAkB,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC9B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,EAAE,CAAC,QAAQ,EAAE,KAAK,KAAK,KAAK,CAAC;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AA6ED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,UAAU,EAAE,CAM7F"}

package/dist/schema-utils/desugar.js

@@ -0,0 +1,101 @@
+// schema-utils/desugar.ts
+//
+// Shared machinery for `aphex/schema/transform` parts that desugar a custom field
+// keyword into a real field — e.g. `{ type: 'color' }` → the color `object`, or
+// `{ type: 'seo' }` → the SEO `object`.
+//
+// Every such transform has the same two jobs, and the second is easy to get wrong:
+//
+//   1. Walk the whole schema list — fields, nested object fields, and array members.
+//   2. Replace the sugar field WITHOUT losing what the author wrote on it.
+//
+// Hand-rolled transforms tended to rebuild the field from a hand-picked subset
+// (`name`/`title`/`description`/`group`), which silently dropped `access` — turning a
+// restricted field unrestricted — along with `validation` and every group after the
+// first. Preservation is the default here so a plugin author can't forget it: the
+// builder supplies only the shape, and the authored field is layered back on top.
+/**
+ * Layer the authored field back over the built one.
+ *
+ * The builder owns structure (`type`, `fields`); the author owns intent (`group`,
+ * `validation`, `access`, and any property added to BaseField later — hence a
+ * spread rather than an allowlist, which would silently go stale).
+ */
+function preserveAuthored(authored, built, sugarKeys) {
+    const rest = { ...authored };
+    delete rest.type;
+    for (const key of sugarKeys)
+        delete rest[key];
+    const builtRecord = built;
+    const merged = {
+        ...builtRecord,
+        ...rest,
+        // Re-assert what the desugaring defines: the author wrote `type: 'color'`,
+        // not the object it expands to.
+        type: builtRecord.type,
+        // An author who explicitly asked for a different widget still wins; otherwise
+        // the builder's widget is the whole point of the field type.
+        input: rest.input ?? builtRecord.input,
+        // Merged, not replaced: the builder derives options from the sugar keys
+        // (color's `alpha` → `inputOptions.alpha`), so letting an authored
+        // `inputOptions` win wholesale would silently drop them. Authored keys still
+        // win individually.
+        inputOptions: mergeInputOptions(builtRecord.inputOptions, rest.inputOptions)
+    };
+    if ('fields' in builtRecord)
+        merged.fields = builtRecord.fields;
+    return merged;
+}
+/** Combine the builder's derived widget options with any the author declared. */
+function mergeInputOptions(built, authored) {
+    const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+    if (!isRecord(built))
+        return isRecord(authored) ? authored : undefined;
+    if (!isRecord(authored))
+        return built;
+    return { ...built, ...authored };
+}
+function expandFields(fields, options) {
+    const sugarKeys = options.sugarKeys ?? [];
+    return fields.map((field) => {
+        if (field.type === options.type) {
+            return preserveAuthored(field, options.build(field), sugarKeys);
+        }
+        if (field.type === 'object' && Array.isArray(field.fields)) {
+            return { ...field, fields: expandFields(field.fields, options) };
+        }
+        if (field.type === 'array' && Array.isArray(field.of)) {
+            return { ...field, of: field.of.map((member) => expandMember(member, options)) };
+        }
+        return field;
+    });
+}
+/** Array `of` members are `TypeReference`s, not `Field`s — expand them the same way. */
+function expandMember(member, options) {
+    if (member.type === options.type) {
+        // A member names a *type*, so `name` is often absent — but builders take a
+        // named field. Fall back to the sugar keyword so the expansion keeps its
+        // identity (`{ of: [{ type: 'color' }] }` stays a recognisable color member
+        // instead of becoming an anonymous object).
+        const authored = { ...member, name: member.name ?? options.type };
+        const built = options.build(authored);
+        return preserveAuthored(authored, built, options.sugarKeys ?? []);
+    }
+    if (Array.isArray(member.fields)) {
+        return { ...member, fields: expandFields(member.fields, options) };
+    }
+    return member;
+}
+/**
+ * Desugar every `{ type: <options.type> }` field across a schema list, recursing into
+ * nested objects and array members, preserving everything the author declared.
+ *
+ * Intended as the body of an `aphex/schema/transform` part, so it runs identically in
+ * the engine, the admin, and the type generator — nothing downstream ever sees the
+ * sugar keyword.
+ */
+export function desugarFieldType(schemas, options) {
+    return schemas.map((schema) => 'fields' in schema && Array.isArray(schema.fields)
+        ? { ...schema, fields: expandFields(schema.fields, options) }
+        : schema);
+}

package/dist/schema-utils/index.d.ts

@@ -1,4 +1,6 @@
 export * from './cleanup.js';
+export * from './desugar.js';
+export * from './settings.js';
 export * from './utils.js';
 export * from './validator.js';
 export * from './singleton.js';

package/dist/schema-utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/schema-utils/index.ts"],"names":[],"mappings":"AACA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/schema-utils/index.ts"],"names":[],"mappings":"AACA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/schema-utils/index.js

@@ -1,5 +1,7 @@
 // Schema utilities - all schema-related helper functions
 export * from './cleanup.js';
+export * from './desugar.js';
+export * from './settings.js';
 export * from './utils.js';
 export * from './validator.js';
 export * from './singleton.js';