@aphexcms/cms-core 9.4.0 → 9.5.1

package/dist/theme/schemes.js

@@ -0,0 +1,149 @@
+import { sanitizeTokenValue } from './css.js';
+const FALLBACK = {
+    surface: '#ffffff',
+    text: '#15171a',
+    primary: '#3eb0ef'
+};
+/** Slugify a scheme name into a stable, safe CSS class fragment. */
+export function schemeSlug(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || 'scheme';
+}
+/** The CSS class that carries a scheme's tokens, e.g. `scheme-dark`. */
+export function schemeClass(name) {
+    return `scheme-${schemeSlug(name)}`;
+}
+/** Parse a 3/6-digit hex to [r,g,b] in 0–255, or null if not a plain hex. */
+function parseHex(hex) {
+    const m = hex.trim().match(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/);
+    const group = m?.[1];
+    if (!group)
+        return null;
+    const h = group.length === 3
+        ? group
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : group;
+    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+/** WCAG relative luminance (0 black → 1 white) of an sRGB triple. */
+function luminance([r, g, b]) {
+    const lin = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+/**
+ * Pick a readable on-color (near-black or white) for text/icons that sit on top
+ * of `background`. Falls back to white when the color can't be parsed.
+ */
+export function contrastColor(background) {
+    const rgb = parseHex(background);
+    if (!rgb)
+        return '#ffffff';
+    // Compare contrast against white vs near-black; whichever is higher wins.
+    const L = luminance(rgb);
+    const contrastWhite = 1.05 / (L + 0.05);
+    const contrastBlack = (L + 0.05) / 0.05;
+    return contrastWhite >= contrastBlack ? '#ffffff' : '#0b0b0c';
+}
+/**
+ * Resolve a scheme's three seeds into the full CSS-var role map. Seeds are
+ * sanitized; anything invalid falls back to a sensible default so a scheme always
+ * emits a complete, coherent palette. The derived roles are `color-mix`
+ * expressions over `var(--ink)`/`var(--paper)`, so they recompute correctly for
+ * whichever scheme is in scope — no per-shade user input, no drift.
+ */
+export function resolveSchemeVars(scheme) {
+    const surface = sanitizeTokenValue(scheme.surface) ?? FALLBACK.surface;
+    const text = sanitizeTokenValue(scheme.text) ?? FALLBACK.text;
+    const primary = sanitizeTokenValue(scheme.primary) ?? FALLBACK.primary;
+    return {
+        '--paper': surface,
+        '--ink': text,
+        '--accent': primary,
+        '--accent-contrast': contrastColor(primary),
+        // Derived — relative to this scheme's ink/paper.
+        '--paper-raised': 'color-mix(in srgb, var(--ink) 2%, var(--paper))',
+        '--ink-soft': 'color-mix(in srgb, var(--ink) 58%, var(--paper))',
+        '--ink-faint': 'color-mix(in srgb, var(--ink) 38%, var(--paper))',
+        '--rule': 'color-mix(in srgb, var(--ink) 12%, transparent)',
+        '--rule-soft': 'color-mix(in srgb, var(--ink) 7%, transparent)',
+        '--accent-ink': 'color-mix(in srgb, var(--accent) 82%, var(--ink))'
+    };
+}
+/**
+ * Emit one scoped rule per scheme, prefixed so it only styles the site subtree
+ * (never `:root`/admin chrome). Returns `''` when there are no schemes.
+ *
+ * @param scopeSelector Ancestor selector the scheme classes live under, e.g. `.blog-shell`.
+ */
+export function emitSchemeStyles(schemes, scopeSelector) {
+    const rules = [];
+    for (const scheme of schemes) {
+        const vars = resolveSchemeVars(scheme);
+        const decls = Object.entries(vars)
+            .map(([k, v]) => `${k}: ${v};`)
+            .join(' ');
+        const cls = schemeClass(scheme.name);
+        // Match the shell itself when it wears the scheme, and any descendant that does.
+        rules.push(`${scopeSelector}.${cls}, ${scopeSelector} .${cls} { ${decls} }`);
+    }
+    return rules.join('\n');
+}
+/** Read a theme document's `schemes` array, falling back to `defaults` when absent. */
+export function readSchemes(values, defaults) {
+    const doc = {};
+    if (values && typeof values === 'object')
+        Object.assign(doc, values);
+    const raw = doc.schemes;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return defaults;
+    const parsed = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const rec = item;
+        const name = typeof rec.name === 'string' && rec.name.trim() !== '' ? rec.name : 'Scheme';
+        parsed.push({
+            name,
+            surface: typeof rec.surface === 'string' ? rec.surface : FALLBACK.surface,
+            text: typeof rec.text === 'string' ? rec.text : FALLBACK.text,
+            primary: typeof rec.primary === 'string' ? rec.primary : FALLBACK.primary
+        });
+    }
+    return parsed.length > 0 ? parsed : defaults;
+}
+/**
+ * Build the `schemes` array field for the theme singleton — a repeatable object
+ * of { name, surface, text, primary }. The first scheme is the site default.
+ */
+export function deriveSchemesField(defaults, group) {
+    return {
+        name: 'schemes',
+        type: 'array',
+        title: 'Color schemes',
+        description: 'Reusable palettes. The first is the site default; sections can opt into any other. Set the background, text, and accent — the rest is derived.',
+        group,
+        initialValue: defaults,
+        of: [
+            {
+                type: 'object',
+                name: 'colorScheme',
+                title: 'Scheme',
+                preview: { select: { title: 'name', subtitle: 'primary' } },
+                fields: [
+                    { name: 'name', type: 'string', title: 'Name' },
+                    { name: 'surface', type: 'string', input: 'color', title: 'Background' },
+                    { name: 'text', type: 'string', input: 'color', title: 'Text' },
+                    { name: 'primary', type: 'string', input: 'color', title: 'Accent' }
+                ]
+            }
+        ]
+    };
+}

package/dist/theme/tokens.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Theme token *types* — the shape of a design-system token.
+ *
+ * cms-core owns the machinery (turn a token list into a schema + scoped CSS); the
+ * consuming app owns the concrete token list, its default colors, and font choices
+ * (that's design opinion, not engine concern). See ./derive.ts and ./css.ts for
+ * the functions that operate on these, and the app's own `theme/tokens.ts` for a
+ * concrete set.
+ */
+/** A curated font choice — the stored `value` resolves to a full CSS `stack`. */
+export interface FontOption {
+    title: string;
+    value: string;
+    stack: string;
+}
+interface BaseToken {
+    /** Field name in the theme schema and the token's identity. */
+    name: string;
+    title: string;
+    description?: string;
+    /** The CSS custom property this token drives, e.g. `--accent`. */
+    cssVar: string;
+    /** Field group in the admin form. */
+    group: string;
+}
+export interface ColorToken extends BaseToken {
+    kind: 'color';
+    default: string;
+}
+export interface FontToken extends BaseToken {
+    kind: 'font';
+    /** The stored `value` of the default option. */
+    default: string;
+    options: FontOption[];
+}
+/** A numeric slider — widths, radii, sizes. Emitted as `${value}${unit}`. */
+export interface RangeToken extends BaseToken {
+    kind: 'range';
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+    /** CSS unit appended to the value, e.g. `'px'`, `'rem'`. Defaults to `''`. */
+    unit?: string;
+}
+/** A fixed-choice dropdown — weights, styles. The stored value is emitted verbatim. */
+export interface SelectToken extends BaseToken {
+    kind: 'select';
+    default: string;
+    options: Array<{
+        title: string;
+        value: string;
+    }>;
+}
+export type ThemeToken = ColorToken | FontToken | RangeToken | SelectToken;
+export {};
+//# sourceMappingURL=tokens.d.ts.map

package/dist/theme/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/lib/theme/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iFAAiF;AACjF,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd;AAED,UAAU,SAAS;IAClB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC5C,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAU,SAAQ,SAAS;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC5C,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,uFAAuF;AACvF,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC7C,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC"}

package/dist/theme/tokens.js

@@ -0,0 +1,10 @@
+/**
+ * Theme token *types* — the shape of a design-system token.
+ *
+ * cms-core owns the machinery (turn a token list into a schema + scoped CSS); the
+ * consuming app owns the concrete token list, its default colors, and font choices
+ * (that's design opinion, not engine concern). See ./derive.ts and ./css.ts for
+ * the functions that operate on these, and the app's own `theme/tokens.ts` for a
+ * concrete set.
+ */
+export {};

package/dist/type-gen.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Type generator for Aphex CMS
+ * Generates TypeScript types from schema definitions with module augmentation
+ */
+import type { SchemaType, Field } from './types/schemas.js';
+/**
+ * The depth=0 write shape (TypeScript type string) for a single field, e.g.
+ * `string` for a slug, `Reference<author>` for a reference, `ImageValue` for an
+ * image. Same mapping `generate-types` uses to emit `generated-types.ts`, so
+ * agent-facing schema introspection (MCP `get_schema`) can derive value shapes
+ * from the one source of truth instead of hand-authoring a parallel list.
+ */
+export declare function fieldWriteShape(field: Field, schemas: SchemaType[]): string;
+/**
+ * Generate complete TypeScript types file with module augmentation
+ */
+export declare function generateTypes(schemas: SchemaType[]): string;
+export declare function generateTypesFromConfig(schemaPath: string, outputPath: string, pluginsPath?: string): Promise<void>;
+//# sourceMappingURL=type-gen.d.ts.map

package/dist/type-gen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-gen.d.ts","sourceRoot":"","sources":["../src/lib/type-gen.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAoJzD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAG3E;AA6VD;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CA8I3D;AAwFD,wBAAsB,uBAAuB,CAC5C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAoDf"}

package/dist/{cli/generate-types.js → type-gen.js}

@@ -1,5 +1,6 @@
-import { isFieldRequired } from '../lib/field-validation/utils.js';
-import { toPascalCase } from '../lib/utils/string-case.js';
+import { createPartResolver } from './plugins/resolver.js';
+import { isFieldRequired } from './field-validation/utils.js';
+import { toPascalCase } from './utils/string-case.js';
 /**
  * Map Aphex field types to TypeScript types
  */
@@ -538,79 +539,112 @@ ${collectionsAugmentation}
 /**
  * CLI helper to generate types from schema file
  */
-export async function generateTypesFromConfig(schemaPath, outputPath) {
+/**
+ * Compile a `.ts` module with esbuild (stubbing icons + Svelte components, which never
+ * affect types) and dynamically import it, returning the module namespace. Used for both
+ * the schema module and the optional plugins module.
+ */
+async function compileAndImportModule(absolutePath, tempName, opts = {}) {
+    const path = await import('path');
+    const { pathToFileURL } = await import('url');
+    const fs = await import('fs/promises');
+    let modulePath = absolutePath;
+    let tempFile = null;
+    if (absolutePath.endsWith('.ts')) {
+        const { build } = await import('esbuild');
+        const tempOutFile = path.join(path.dirname(absolutePath), tempName);
+        // The plugins module imports plugin *main* entries (Svelte-laden) and cms-core
+        // runtime utils — so bundle the plugins (the Svelte-stub strips their components)
+        // and alias cms-core to its built dist (real JS; source `.ts` can't load in Node).
+        // The schema module keeps `@aphexcms/*` external (its plugin imports use the
+        // server-safe `/schema` subpath, which loads fine).
+        const alias = opts.bundlePlugins && opts.cmsCoreDist
+            ? { '@aphexcms/cms-core': opts.cmsCoreDist }
+            : undefined;
+        await build({
+            entryPoints: [absolutePath],
+            bundle: true,
+            format: 'esm',
+            platform: 'node',
+            outfile: tempOutFile,
+            external: opts.bundlePlugins ? ['sharp', 'graphql', 'graphql-yoga'] : ['@aphexcms/*'],
+            alias,
+            plugins: [
+                {
+                    name: 'remove-icons',
+                    setup(build) {
+                        build.onResolve({ filter: /^@lucide\/svelte/ }, (args) => {
+                            return { path: args.path, namespace: 'lucide-stub' };
+                        });
+                        build.onLoad({ filter: /.*/, namespace: 'lucide-stub' }, () => {
+                            return { contents: 'export default {}', loader: 'js' };
+                        });
+                        // Stub .svelte components — a schema/plugin module can transitively
+                        // import component parts (actions, tools, widgets) that never affect types.
+                        build.onResolve({ filter: /\.svelte(\?.*)?$/ }, (args) => {
+                            return { path: args.path, namespace: 'svelte-stub' };
+                        });
+                        build.onLoad({ filter: /.*/, namespace: 'svelte-stub' }, () => {
+                            return { contents: 'export default {}', loader: 'js' };
+                        });
+                        build.onLoad({ filter: /\.(ts|js)$/ }, async (args) => {
+                            const contents = await fs.readFile(args.path, 'utf8');
+                            const transformed = contents.replace(/icon:\s*\w+/g, 'icon: undefined');
+                            return { contents: transformed, loader: args.path.endsWith('.ts') ? 'ts' : 'js' };
+                        });
+                    }
+                }
+            ]
+        });
+        modulePath = tempOutFile;
+        tempFile = tempOutFile;
+    }
+    // @vite-ignore: path is resolved at CLI runtime, not statically analyzable.
+    const mod = await import(/* @vite-ignore */ pathToFileURL(modulePath).href);
+    if (tempFile) {
+        try {
+            await fs.unlink(tempFile);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+    return mod;
+}
+export async function generateTypesFromConfig(schemaPath, outputPath, pluginsPath) {
     try {
-        // Resolve paths relative to current working directory
         const path = await import('path');
-        const { pathToFileURL } = await import('url');
         const fs = await import('fs/promises');
         const absoluteSchemaPath = path.resolve(process.cwd(), schemaPath);
         const absoluteOutputPath = path.resolve(process.cwd(), outputPath);
-        // If the schema file is TypeScript, compile it with esbuild first
-        let schemaModulePath = absoluteSchemaPath;
-        let tempFile = null;
-        if (absoluteSchemaPath.endsWith('.ts')) {
-            const { build } = await import('esbuild');
-            const fs = await import('fs/promises');
-            const tempOutFile = path.join(path.dirname(absoluteSchemaPath), '.temp-schema.mjs');
-            await build({
-                entryPoints: [absoluteSchemaPath],
-                bundle: true,
-                format: 'esm',
-                platform: 'node',
-                outfile: tempOutFile,
-                external: ['@aphexcms/*'],
-                plugins: [
-                    {
-                        name: 'remove-icons',
-                        setup(build) {
-                            // Intercept lucide icon imports and provide empty stub module
-                            build.onResolve({ filter: /^@lucide\/svelte/ }, (args) => {
-                                return { path: args.path, namespace: 'lucide-stub' };
-                            });
-                            // Return empty stub for lucide modules
-                            build.onLoad({ filter: /.*/, namespace: 'lucide-stub' }, () => {
-                                return {
-                                    contents: 'export default {}',
-                                    loader: 'js'
-                                };
-                            });
-                            // Transform source files to remove icon usage in schemas
-                            build.onLoad({ filter: /\.(ts|js)$/ }, async (args) => {
-                                const contents = await fs.readFile(args.path, 'utf8');
-                                // Remove icon usage in schema definitions (icon: IconName -> icon: undefined)
-                                const transformed = contents.replace(/icon:\s*\w+/g, 'icon: undefined');
-                                return {
-                                    contents: transformed,
-                                    loader: args.path.endsWith('.ts') ? 'ts' : 'js'
-                                };
-                            });
-                        }
-                    }
-                ]
-            });
-            schemaModulePath = tempOutFile;
-            tempFile = tempOutFile;
-        }
-        // Dynamic import the schema types
-        // Use file:// URL for proper ESM import. The path is resolved at CLI runtime
-        // (a temp-compiled or the consumer's schema module), so Vite can't statically
-        // analyze it — @vite-ignore silences the SSR-graph warning when this file is
-        // pulled into a dev bundle.
-        const schemaModule = await import(/* @vite-ignore */ pathToFileURL(schemaModulePath).href);
-        const schemas = schemaModule.schemaTypes || schemaModule.default;
-        // Clean up temp file if created
-        if (tempFile) {
-            try {
-                await fs.unlink(tempFile);
-            }
-            catch {
-                // Ignore cleanup errors
-            }
-        }
+        const schemaModule = await compileAndImportModule(absoluteSchemaPath, '.temp-schema.mjs');
+        let schemas = schemaModule.schemaTypes || schemaModule.default;
         if (!schemas || !Array.isArray(schemas)) {
             throw new Error('Invalid schema file: expected schemaTypes array export');
         }
+        // Apply plugin schema-transforms so plugin-provided field types (e.g. `type: 'color'`)
+        // desugar exactly as they do at runtime — without this, codegen emits `unknown` for
+        // them. `pluginsPath` points at the app's client-safe plugin registry (e.g.
+        // `src/lib/plugins.ts`, exporting `plugins`).
+        if (pluginsPath) {
+            const absolutePluginsPath = path.resolve(process.cwd(), pluginsPath);
+            // Resolve cms-core's built dist so the plugins' cms-core runtime imports load
+            // (the source `.ts` entry can't run in Node). Present in both the monorepo
+            // (symlink) and real installs (published dist).
+            const fsSync = await import('fs');
+            const cmsCoreDistCandidate = path.join(process.cwd(), 'node_modules/@aphexcms/cms-core/dist/index.js');
+            const cmsCoreDist = fsSync.existsSync(cmsCoreDistCandidate)
+                ? cmsCoreDistCandidate
+                : undefined;
+            const pluginsModule = await compileAndImportModule(absolutePluginsPath, '.temp-plugins.mjs', {
+                bundlePlugins: true,
+                cmsCoreDist
+            });
+            const plugins = (pluginsModule.plugins || pluginsModule.default);
+            if (Array.isArray(plugins)) {
+                schemas = createPartResolver(plugins).applySchemaTransforms(schemas);
+            }
+        }
         const generatedTypes = generateTypes(schemas);
         // Write to output file
         await fs.writeFile(absoluteOutputPath, generatedTypes, 'utf-8');
@@ -621,4 +655,3 @@ export async function generateTypesFromConfig(schemaPath, outputPath) {
         throw error;
     }
 }
-//# sourceMappingURL=generate-types.js.map

package/dist/types/auth.d.ts

@@ -1,6 +1,5 @@
 import type { CMSUser } from './user.js';
 import type { OrganizationRole } from './organization.js';
-import type { Capability } from './capabilities.js';
 export interface SessionAuth {
     type: 'session';
     user: CMSUser;
@@ -19,11 +18,13 @@ export interface SessionAuth {
      */
     organizationRole: OrganizationRole | string;
     /**
-     * Capabilities resolved for this session by the auth hook (RolesService).
-     * Present for fully-authenticated sessions. When absent, callers fall
-     * back to built-in seed values — see `resolveCapabilities`.
+     * Capability ids granted to this session, resolved by the auth hook (RolesService).
+     * `string[]`, not `Capability[]`: a role can grant plugin-declared capabilities that
+     * aren't in the built-in `Capability` union. Present for fully-authenticated
+     * sessions; when absent, callers fall back to built-in seed values — see
+     * `resolveCapabilities`.
      */
-    capabilities?: Capability[];
+    capabilities?: string[];
     organizations?: Array<{
         id: string;
         name: string;
@@ -57,12 +58,11 @@ export interface ApiKeyAuth {
      */
     permissions: ('read' | 'write')[];
     /**
-     * Fine-grained capability allowlist for this API key. When present,
-     * overrides the coarse `permissions` mapping — the key can do exactly
-     * what's listed and nothing else. Storage format on the key metadata
-     * matches the Capability union.
+     * Fine-grained capability-id allowlist for this API key. When present, overrides
+     * the coarse `permissions` mapping — the key can do exactly what's listed and
+     * nothing else. `string[]` so keys can be scoped to plugin capabilities too.
      */
-    capabilities?: Capability[];
+    capabilities?: string[];
     organizationId: string;
     environment?: string;
     lastUsedAt?: Date;

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/lib/types/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,IAAI,CAAC;KAChB,CAAC;IACF,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,gBAAgB,EAAE,gBAAgB,GAAG,MAAM,CAAC;IAC5C;;;;OAIG;IACH,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,KAAK,CAAC;QACrB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAAC;QAChC,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,GAAG,CAAC;KACf,CAAC,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,IAAI,CAAC;KAChB,CAAC;CACF;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,WAAW,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;IAClC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,MAAM,IAAI,GAAG,WAAW,GAAG,kBAAkB,GAAG,UAAU,CAAC;AAYjE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAO5C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAMpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE5C"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/lib/types/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,IAAI,CAAC;KAChB,CAAC;IACF,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,gBAAgB,EAAE,gBAAgB,GAAG,MAAM,CAAC;IAC5C;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,KAAK,CAAC;QACrB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAAC;QAChC,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,GAAG,CAAC;KACf,CAAC,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,IAAI,CAAC;KAChB,CAAC;CACF;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,WAAW,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,MAAM,IAAI,GAAG,WAAW,GAAG,kBAAkB,GAAG,UAAU,CAAC;AAYjE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAO5C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAMpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE5C"}

package/dist/types/capabilities.d.ts

@@ -6,11 +6,44 @@ import type { OrganizationRole } from './organization.js';
  * Append-only: removing or renaming a value silently weakens every call site.
  * If a capability is no longer needed, leave the string and stop granting it.
  */
-export type Capability = 'document.read' | 'document.create' | 'document.update' | 'document.delete' | 'document.publish' | 'document.unpublish' | 'asset.read' | 'asset.upload' | 'asset.delete' | 'member.invite' | 'member.remove' | 'member.changeRole' | 'apiKey.manage' | 'role.manage' | 'org.settings';
+export type Capability = 'document.read' | 'document.create' | 'document.update' | 'document.delete' | 'document.publish' | 'document.unpublish' | 'asset.read' | 'asset.upload' | 'asset.delete' | 'member.invite' | 'member.remove' | 'member.changeRole' | 'apiKey.manage' | 'role.manage' | 'org.settings' | 'plugin.settings.manage';
 /**
  * Enumerate every capability. Useful for owner seeding and validation.
  */
 export declare const ALL_CAPABILITIES: readonly Capability[];
+/**
+ * Metadata for one capability — a registry entry. Turns a bare permission string
+ * into something the roles UI can present (title, help text, grouping). Built-ins
+ * are defined below; plugins add their own via the `aphex/capabilities` part, and
+ * the part resolver merges both into one catalog (`resolver.capabilityCatalog()`).
+ */
+export interface CapabilityDefinition {
+    /** The permission string checked at runtime, e.g. `'document.publish'`. */
+    id: string;
+    /** Human label shown in the roles UI. */
+    title: string;
+    /** One-line explanation shown under the title. */
+    description?: string;
+    /** Group heading in the roles UI, e.g. `'Documents'`. */
+    group?: string;
+}
+/**
+ * Define a capability with metadata. Plugins pass these to the `aphex/capabilities`
+ * part so their permissions appear (and are assignable) in the roles UI.
+ *
+ * @example
+ * defineCapability('forms.export', { title: 'Export submissions', group: 'Forms' })
+ */
+export declare function defineCapability(id: string, meta?: Partial<Omit<CapabilityDefinition, 'id'>>): CapabilityDefinition;
+/** Fallback label for a bare id: `document.publish` → `Publish` (last segment, title-cased). */
+export declare function prettifyCapabilityId(id: string): string;
+/** The built-in capability catalog — metadata for every core capability. */
+export declare const BUILTIN_CAPABILITY_DEFS: readonly CapabilityDefinition[];
+/**
+ * Merge the built-in catalog with extra (plugin) definitions, deduped by id — the
+ * first definition of an id wins, so plugins can't silently redefine a core cap.
+ */
+export declare function mergeCapabilityCatalog(extra?: readonly CapabilityDefinition[]): CapabilityDefinition[];
 /**
  * Built-in role names. These are the guaranteed defaults every org receives.
  * Custom role names are any other string.
@@ -19,9 +52,15 @@ export declare const BUILTIN_ROLE_NAMES: readonly OrganizationRole[];
 /**
  * Seed data for the four built-in roles.
  *
- * This is the **default floor** — the set of capabilities a freshly-created
- * org starts with. Once seeded, rows live in `cms_roles` and can be edited by
- * admins (via future Roles UI). Custom roles live alongside these.
+ * For viewer/editor/admin this is the **default floor** — the set of capabilities
+ * a freshly-created org starts with. Once seeded, rows live in `cms_roles` and can
+ * be edited by admins via the Roles UI; they are never force-updated afterwards,
+ * so a capability added by a later core upgrade is not granted retroactively.
+ *
+ * `owner` is different: it is an **invariant**, not a floor. It is always the whole
+ * of ALL_CAPABILITIES, is rejected by the roles PATCH route, and is reconciled on
+ * every boot (see CMSEngine.reconcileBuiltinRoles) so new capabilities reach orgs
+ * that were seeded before those capabilities existed.
  *
  * Also acts as the defense-in-depth fallback: if a role lookup misses (e.g.
  * a row got deleted out-of-band for a built-in name), the checker falls back
@@ -34,8 +73,10 @@ export declare const BUILTIN_ROLE_SEED: Record<OrganizationRole, {
 /**
  * Idempotently expand a capability list so that any write cap drags in the
  * corresponding read. Used by both the role schema and the API-key schema.
+ * Accepts `string[]` since a granted list may include plugin capability ids; the
+ * built-in read/write implications only touch known core ids and pass others through.
  */
-export declare function normalizeCapabilities(caps: readonly Capability[]): Capability[];
+export declare function normalizeCapabilities(caps: readonly string[]): string[];
 /**
  * A persisted role row (per organization).
  */
@@ -44,7 +85,7 @@ export interface Role {
     organizationId: string;
     name: string;
     description: string | null;
-    capabilities: Capability[];
+    capabilities: string[];
     isBuiltIn: boolean;
     createdAt: Date;
     updatedAt: Date;
@@ -53,7 +94,7 @@ export interface NewRole {
     organizationId: string;
     name: string;
     description?: string | null;
-    capabilities: Capability[];
+    capabilities: string[];
     isBuiltIn?: boolean;
 }
 /**
@@ -69,7 +110,7 @@ export declare function isInstanceRole(auth: Auth): boolean;
  * RolesService. If absent (e.g. legacy call site), falls back to the built-in
  * seed for the org role so behavior remains safe.
  */
-export declare function hasCapability(auth: Auth, capability: Capability): boolean;
+export declare function hasCapability(auth: Auth, capability: Capability | (string & {})): boolean;
 /**
  * Resolve the effective capability set for an Auth.
  *
@@ -80,7 +121,7 @@ export declare function hasCapability(auth: Auth, capability: Capability): boole
  *   4. Session fallback → built-in seed for the org role.
  *   5. Partial session → empty set.
  */
-export declare function resolveCapabilities(auth: Auth): ReadonlySet<Capability>;
+export declare function resolveCapabilities(auth: Auth): ReadonlySet<string>;
 /**
  * Resolve the effective organization role name for an Auth, honoring
  * instance-role overrides. Returns the role name as a string — built-in or

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

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/lib/types/capabilities.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAEnB,eAAe,GACf,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,oBAAoB,GAEpB,YAAY,GACZ,cAAc,GACd,cAAc,GAEd,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,eAAe,GACf,aAAa,GACb,cAAc,CAAC;AAMlB;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,UAAU,EAgBxC,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAKzD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CACrC,gBAAgB,EAChB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CA4C5D,CAAC;AAeF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,EAAE,CAK/E;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,EAAE,CAQtE;AAWD,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAEzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,CAAC,UAAU,CAAC,CAoCvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAInE;AAID;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,0EAA0E;IAC1E,YAAY,EAAE,UAAU,EAAE,CAAC;CAC3B"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/lib/types/capabilities.ts"],"names":[],"mappings":"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"}