@aglyn/aglyn 1.0.0-beta.143

package/src/lib/plugin-manager/plugin-config.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Per-plugin configuration (AGL-428) — Strapi `config` parity. A plugin
+ * DECLARES its settings schema (fields + defaults + validation) at module
+ * scope; the org stores overrides in `orgs/{orgId}/pluginSettings/
+ * {pluginId}`; every consumer reads the DEFAULTS-MERGED view:
+ *
+ * - server handlers via `getPluginConfig(orgId, pluginId)`
+ *   (tenant-data-admin);
+ * - client surfaces via `usePluginConfig(orgId, pluginId)`
+ *   (tenant-feature-instance);
+ * - the console's Plugins & add-ons hub renders a generic settings form
+ *   from the schema, so a plugin gets a settings UI without writing one.
+ *
+ * Register at MODULE SCOPE in a file imported by both the client barrel
+ * and the `/server` entry, so whichever surface loads first the schema is
+ * there. Values are coerced defensively on merge — the settings doc is
+ * client-writable (org managers), so readers never trust its types.
+ */
+export interface PluginConfigField {
+    key: string;
+    label: string;
+    type: 'string' | 'number' | 'boolean' | 'select';
+    description?: string;
+    /** For `select` fields. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** For `number` fields. */
+    min?: number;
+    max?: number;
+}
+export interface PluginConfigSchema {
+    pluginId: string;
+    fields: PluginConfigField[];
+    defaults: Record<string, unknown>;
+    /** Cross-field validation; returns an error message or null. */
+    validate?: (values: Record<string, unknown>) => string | null;
+}
+/** Idempotent by pluginId — re-registration replaces the schema. */
+export declare function registerPluginConfigSchema(schema: PluginConfigSchema): void;
+export declare function getPluginConfigSchema(pluginId: string): PluginConfigSchema | undefined;
+export declare function listPluginConfigSchemas(): PluginConfigSchema[];
+/**
+ * The defaults-merged, type-coerced config view. Safe against a missing
+ * or junk settings doc — unknown keys are dropped, wrong-typed values
+ * fall back to the declared default.
+ */
+export declare function mergePluginConfig(schema: PluginConfigSchema, stored: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/** Pre-save validation for the settings UI (coerce + custom validate). */
+export declare function validatePluginConfigValues(schema: PluginConfigSchema, values: Record<string, unknown>): {
+    ok: boolean;
+    error?: string;
+};
+/**
+ * A plugin's declared fields, read from its MANIFEST rather than the registry
+ * (AGL-428).
+ *
+ * The registry is a module-scope map, filled by `registerPluginConfigSchema`
+ * at import time. A marketplace plugin cannot fill it: its bundle runs in a
+ * sandboxed frame on a separate origin and never executes in the console
+ * process, so there is no moment at which its registration could happen. The
+ * settings form therefore rendered NOTHING for every plugin a workspace
+ * installed, and `resolvePluginConfig` — which is entirely plugin-agnostic and
+ * would have layered a third-party plugin's org default under a per-site
+ * override without changing a line — was never reached for one.
+ *
+ * The manifest is denormalized onto every install pin, so it is the one
+ * declaration of a marketplace plugin the console already holds.
+ *
+ * Everything here is re-validated rather than trusted. The manifest is
+ * publisher-authored, it is stored on a client-readable document, and a form
+ * built from it is a form an org manager saves through — so a junk `type`
+ * drops the field rather than rendering an unknown control, and the field
+ * count is capped so one manifest cannot turn a settings page into thousands
+ * of inputs. Being reviewed once is not the same as being safe to render
+ * verbatim forever.
+ *
+ * Returns `undefined` when the manifest declares nothing usable, which callers
+ * must treat as "this plugin has no settings" rather than as an error: most
+ * plugins take none.
+ */
+export declare function pluginConfigSchemaFromManifest(pluginId: string, manifest: unknown): PluginConfigSchema | undefined;
+/**
+ * The three levels a plugin setting can be answered at.
+ *
+ * A workspace sets a value once and every site it enabled the plugin on
+ * follows it; a site that needs a different answer overrides that one field
+ * and keeps inheriting the rest. Bookings is the shape this is for — one
+ * booking horizon across a chain, with the flagship branch taking bookings
+ * further out — and it generalizes to every plugin because none of them get
+ * to invent their own inheritance.
+ */
+export interface PluginConfigSources {
+    /** `orgs/{orgId}/pluginSettings/{pluginId}` — the workspace's answer. */
+    org?: Record<string, unknown> | null;
+    /** `hosts/{hostId}/pluginSettings/{pluginId}` — only the keys this site overrides. */
+    host?: Record<string, unknown> | null;
+}
+/**
+ * Which keys a site is answering for itself.
+ *
+ * A key is an override when it is PRESENT on the host document, and inherited
+ * when it is absent. `undefined` counts as absent, deliberately: a UI that
+ * writes `{key: undefined}` to mean "stop overriding" is doing the same thing
+ * as one that never wrote the key, and treating the two differently would make
+ * "revert to the workspace value" depend on which code path cleared it.
+ *
+ * ⚠️ Which is also why clearing an override must DELETE the key rather than
+ * write an empty value. `setDoc(..., {merge: true})` leaves an existing field
+ * exactly as it is when the new object omits it, so a form that drops empty
+ * inputs cannot clear anything by saving — the override survives, invisibly,
+ * and the site keeps ignoring a workspace value the operator has since
+ * changed. Deleting is the only write that returns a field to inherited.
+ *
+ * Keys the schema does not declare are ignored, so a stale field left behind
+ * by a plugin update does not read as an override of a setting that no longer
+ * exists.
+ */
+export declare function pluginConfigOverrides(schema: PluginConfigSchema, host: Record<string, unknown> | null | undefined): string[];
+/**
+ * What a plugin actually runs with on one site.
+ *
+ * Schema defaults, then the workspace's stored values, then only the keys the
+ * site overrides — each layer narrowing the one before it. Type coercion
+ * happens once at the end rather than per level, so a site override of the
+ * wrong type falls back to the WORKSPACE value it was trying to replace
+ * instead of skipping past it to the schema default. Getting that backwards
+ * would have one malformed site setting silently discard a workspace answer
+ * the operator can see in their own console.
+ */
+export declare function resolvePluginConfig(schema: PluginConfigSchema, sources: PluginConfigSources): Record<string, unknown>;

package/src/lib/plugin-manager/plugin-config.js

@@ -0,0 +1,228 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Per-plugin configuration (AGL-428) — Strapi `config` parity. A plugin
+ * DECLARES its settings schema (fields + defaults + validation) at module
+ * scope; the org stores overrides in `orgs/{orgId}/pluginSettings/
+ * {pluginId}`; every consumer reads the DEFAULTS-MERGED view:
+ *
+ * - server handlers via `getPluginConfig(orgId, pluginId)`
+ *   (tenant-data-admin);
+ * - client surfaces via `usePluginConfig(orgId, pluginId)`
+ *   (tenant-feature-instance);
+ * - the console's Plugins & add-ons hub renders a generic settings form
+ *   from the schema, so a plugin gets a settings UI without writing one.
+ *
+ * Register at MODULE SCOPE in a file imported by both the client barrel
+ * and the `/server` entry, so whichever surface loads first the schema is
+ * there. Values are coerced defensively on merge — the settings doc is
+ * client-writable (org managers), so readers never trust its types.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+const schemas = new Map();
+/** Idempotent by pluginId — re-registration replaces the schema. */ export function registerPluginConfigSchema(schema) {
+    schemas.set(schema.pluginId, schema);
+}
+export function getPluginConfigSchema(pluginId) {
+    return schemas.get(pluginId);
+}
+export function listPluginConfigSchemas() {
+    return [
+        ...schemas.values()
+    ];
+}
+const coerce = (field, raw, fallback)=>{
+    switch(field.type){
+        case 'boolean':
+            return typeof raw === 'boolean' ? raw : fallback;
+        case 'number':
+            {
+                const value = typeof raw === 'number' && Number.isFinite(raw) ? raw : NaN;
+                if (Number.isNaN(value)) return fallback;
+                if (field.min != null && value < field.min) return field.min;
+                if (field.max != null && value > field.max) return field.max;
+                return value;
+            }
+        case 'select':
+            {
+                var _field_options;
+                const value = typeof raw === 'string' ? raw : undefined;
+                return ((_field_options = field.options) == null ? void 0 : _field_options.some((option)=>option.value === value)) ? value : fallback;
+            }
+        default:
+            return typeof raw === 'string' ? raw : fallback;
+    }
+};
+/**
+ * The defaults-merged, type-coerced config view. Safe against a missing
+ * or junk settings doc — unknown keys are dropped, wrong-typed values
+ * fall back to the declared default.
+ */ export function mergePluginConfig(schema, stored) {
+    const merged = _extends({}, schema.defaults);
+    if (!stored) return merged;
+    for (const field of schema.fields){
+        if (field.key in stored) {
+            merged[field.key] = coerce(field, stored[field.key], schema.defaults[field.key]);
+        }
+    }
+    return merged;
+}
+/** Pre-save validation for the settings UI (coerce + custom validate). */ export function validatePluginConfigValues(schema, values) {
+    var _ref;
+    const merged = mergePluginConfig(schema, values);
+    const error = (_ref = schema.validate == null ? void 0 : schema.validate.call(schema, merged)) != null ? _ref : null;
+    return error ? {
+        ok: false,
+        error
+    } : {
+        ok: true
+    };
+}
+const MANIFEST_CONFIG_FIELD_LIMIT = 50;
+const FIELD_TYPES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'select'
+]);
+/**
+ * A plugin's declared fields, read from its MANIFEST rather than the registry
+ * (AGL-428).
+ *
+ * The registry is a module-scope map, filled by `registerPluginConfigSchema`
+ * at import time. A marketplace plugin cannot fill it: its bundle runs in a
+ * sandboxed frame on a separate origin and never executes in the console
+ * process, so there is no moment at which its registration could happen. The
+ * settings form therefore rendered NOTHING for every plugin a workspace
+ * installed, and `resolvePluginConfig` — which is entirely plugin-agnostic and
+ * would have layered a third-party plugin's org default under a per-site
+ * override without changing a line — was never reached for one.
+ *
+ * The manifest is denormalized onto every install pin, so it is the one
+ * declaration of a marketplace plugin the console already holds.
+ *
+ * Everything here is re-validated rather than trusted. The manifest is
+ * publisher-authored, it is stored on a client-readable document, and a form
+ * built from it is a form an org manager saves through — so a junk `type`
+ * drops the field rather than rendering an unknown control, and the field
+ * count is capped so one manifest cannot turn a settings page into thousands
+ * of inputs. Being reviewed once is not the same as being safe to render
+ * verbatim forever.
+ *
+ * Returns `undefined` when the manifest declares nothing usable, which callers
+ * must treat as "this plugin has no settings" rather than as an error: most
+ * plugins take none.
+ */ export function pluginConfigSchemaFromManifest(pluginId, manifest) {
+    if (!pluginId) return undefined;
+    const declared = manifest == null ? void 0 : manifest.config;
+    const rawFields = declared == null ? void 0 : declared.fields;
+    if (!Array.isArray(rawFields)) return undefined;
+    const seen = new Set();
+    const fields = [];
+    for (const raw of rawFields){
+        var _ref;
+        if (fields.length >= MANIFEST_CONFIG_FIELD_LIMIT) break;
+        const entry = raw;
+        const key = typeof (entry == null ? void 0 : entry['key']) === 'string' ? entry['key'].trim() : '';
+        // A duplicate key would give two controls one storage slot, so the second
+        // is dropped rather than allowed to shadow the first.
+        if (!key || seen.has(key)) continue;
+        const type = String((_ref = entry == null ? void 0 : entry['type']) != null ? _ref : 'string');
+        if (!FIELD_TYPES.has(type)) continue;
+        const options = Array.isArray(entry == null ? void 0 : entry['options']) ? entry['options'].map((option)=>option).filter((option)=>typeof (option == null ? void 0 : option['value']) === 'string' && typeof (option == null ? void 0 : option['label']) === 'string').map((option)=>({
+                value: String(option == null ? void 0 : option['value']),
+                label: String(option == null ? void 0 : option['label'])
+            })) : undefined;
+        // A `select` with nothing to select is a dropdown that cannot be answered,
+        // so it is dropped rather than rendered empty.
+        if (type === 'select' && !(options == null ? void 0 : options.length)) continue;
+        seen.add(key);
+        fields.push({
+            key,
+            label: typeof (entry == null ? void 0 : entry['label']) === 'string' && entry['label'].trim() ? String(entry['label']).slice(0, 120) : key,
+            type: type,
+            description: typeof (entry == null ? void 0 : entry['description']) === 'string' ? String(entry['description']).slice(0, 400) : undefined,
+            options,
+            min: typeof (entry == null ? void 0 : entry['min']) === 'number' ? entry['min'] : undefined,
+            max: typeof (entry == null ? void 0 : entry['max']) === 'number' ? entry['max'] : undefined
+        });
+    }
+    if (!fields.length) return undefined;
+    const rawDefaults = declared == null ? void 0 : declared.defaults;
+    const defaults = {};
+    for (const field of fields){
+        var _field_min, _ref1;
+        var _field_options_, _field_options;
+        // Defaults are coerced through the same path stored values take, so a
+        // manifest default of the wrong type cannot become the value a site
+        // inherits. An absent one falls back to the type's empty value rather than
+        // `undefined`, which `pluginConfigOverrides` reads as "not answered".
+        const supplied = rawDefaults && typeof rawDefaults === 'object' ? rawDefaults[field.key] : undefined;
+        const empty = field.type === 'boolean' ? false : field.type === 'number' ? (_field_min = field.min) != null ? _field_min : 0 : field.type === 'select' ? (_ref1 = (_field_options = field.options) == null ? void 0 : (_field_options_ = _field_options[0]) == null ? void 0 : _field_options_.value) != null ? _ref1 : '' : '';
+        defaults[field.key] = coerce(field, supplied, empty);
+    }
+    return {
+        pluginId,
+        fields,
+        defaults
+    };
+}
+/**
+ * Which keys a site is answering for itself.
+ *
+ * A key is an override when it is PRESENT on the host document, and inherited
+ * when it is absent. `undefined` counts as absent, deliberately: a UI that
+ * writes `{key: undefined}` to mean "stop overriding" is doing the same thing
+ * as one that never wrote the key, and treating the two differently would make
+ * "revert to the workspace value" depend on which code path cleared it.
+ *
+ * ⚠️ Which is also why clearing an override must DELETE the key rather than
+ * write an empty value. `setDoc(..., {merge: true})` leaves an existing field
+ * exactly as it is when the new object omits it, so a form that drops empty
+ * inputs cannot clear anything by saving — the override survives, invisibly,
+ * and the site keeps ignoring a workspace value the operator has since
+ * changed. Deleting is the only write that returns a field to inherited.
+ *
+ * Keys the schema does not declare are ignored, so a stale field left behind
+ * by a plugin update does not read as an override of a setting that no longer
+ * exists.
+ */ export function pluginConfigOverrides(schema, host) {
+    if (!host) return [];
+    return schema.fields.filter((field)=>field.key in host && host[field.key] !== undefined).map((field)=>field.key);
+}
+/**
+ * What a plugin actually runs with on one site.
+ *
+ * Schema defaults, then the workspace's stored values, then only the keys the
+ * site overrides — each layer narrowing the one before it. Type coercion
+ * happens once at the end rather than per level, so a site override of the
+ * wrong type falls back to the WORKSPACE value it was trying to replace
+ * instead of skipping past it to the schema default. Getting that backwards
+ * would have one malformed site setting silently discard a workspace answer
+ * the operator can see in their own console.
+ */ export function resolvePluginConfig(schema, sources) {
+    const org = mergePluginConfig(schema, sources.org);
+    const overrides = pluginConfigOverrides(schema, sources.host);
+    if (!overrides.length) return org;
+    const host = sources.host;
+    const merged = _extends({}, org);
+    for (const field of schema.fields){
+        if (!overrides.includes(field.key)) continue;
+        merged[field.key] = coerce(field, host[field.key], org[field.key]);
+    }
+    return merged;
+}
+
+//# sourceMappingURL=plugin-config.js.map

package/src/lib/plugin-manager/plugin-config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-config.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Per-plugin configuration (AGL-428) — Strapi `config` parity. A plugin\n * DECLARES its settings schema (fields + defaults + validation) at module\n * scope; the org stores overrides in `orgs/{orgId}/pluginSettings/\n * {pluginId}`; every consumer reads the DEFAULTS-MERGED view:\n *\n * - server handlers via `getPluginConfig(orgId, pluginId)`\n *   (tenant-data-admin);\n * - client surfaces via `usePluginConfig(orgId, pluginId)`\n *   (tenant-feature-instance);\n * - the console's Plugins & add-ons hub renders a generic settings form\n *   from the schema, so a plugin gets a settings UI without writing one.\n *\n * Register at MODULE SCOPE in a file imported by both the client barrel\n * and the `/server` entry, so whichever surface loads first the schema is\n * there. Values are coerced defensively on merge — the settings doc is\n * client-writable (org managers), so readers never trust its types.\n */\n\nexport interface PluginConfigField {\n  key: string\n  label: string\n  type: 'string' | 'number' | 'boolean' | 'select'\n  description?: string\n  /** For `select` fields. */\n  options?: Array<{ value: string; label: string }>\n  /** For `number` fields. */\n  min?: number\n  max?: number\n}\n\nexport interface PluginConfigSchema {\n  pluginId: string\n  fields: PluginConfigField[]\n  defaults: Record<string, unknown>\n  /** Cross-field validation; returns an error message or null. */\n  validate?: (values: Record<string, unknown>) => string | null\n}\n\nconst schemas = new Map<string, PluginConfigSchema>()\n\n/** Idempotent by pluginId — re-registration replaces the schema. */\nexport function registerPluginConfigSchema(schema: PluginConfigSchema): void {\n  schemas.set(schema.pluginId, schema)\n}\n\nexport function getPluginConfigSchema(\n  pluginId: string,\n): PluginConfigSchema | undefined {\n  return schemas.get(pluginId)\n}\n\nexport function listPluginConfigSchemas(): PluginConfigSchema[] {\n  return [...schemas.values()]\n}\n\nconst coerce = (\n  field: PluginConfigField,\n  raw: unknown,\n  fallback: unknown,\n): unknown => {\n  switch (field.type) {\n    case 'boolean':\n      return typeof raw === 'boolean' ? raw : fallback\n    case 'number': {\n      const value = typeof raw === 'number' && Number.isFinite(raw) ? raw : NaN\n      if (Number.isNaN(value)) return fallback\n      if (field.min != null && value < field.min) return field.min\n      if (field.max != null && value > field.max) return field.max\n      return value\n    }\n    case 'select': {\n      const value = typeof raw === 'string' ? raw : undefined\n      return field.options?.some((option) => option.value === value)\n        ? value\n        : fallback\n    }\n    default:\n      return typeof raw === 'string' ? raw : fallback\n  }\n}\n\n/**\n * The defaults-merged, type-coerced config view. Safe against a missing\n * or junk settings doc — unknown keys are dropped, wrong-typed values\n * fall back to the declared default.\n */\nexport function mergePluginConfig(\n  schema: PluginConfigSchema,\n  stored: Record<string, unknown> | null | undefined,\n): Record<string, unknown> {\n  const merged: Record<string, unknown> = { ...schema.defaults }\n  if (!stored) return merged\n  for (const field of schema.fields) {\n    if (field.key in stored) {\n      merged[field.key] = coerce(\n        field,\n        stored[field.key],\n        schema.defaults[field.key],\n      )\n    }\n  }\n  return merged\n}\n\n/** Pre-save validation for the settings UI (coerce + custom validate). */\nexport function validatePluginConfigValues(\n  schema: PluginConfigSchema,\n  values: Record<string, unknown>,\n): { ok: boolean; error?: string } {\n  const merged = mergePluginConfig(schema, values)\n  const error = schema.validate?.(merged) ?? null\n  return error ? { ok: false, error } : { ok: true }\n}\n\nconst MANIFEST_CONFIG_FIELD_LIMIT = 50\nconst FIELD_TYPES: ReadonlySet<string> = new Set([\n  'string',\n  'number',\n  'boolean',\n  'select',\n])\n\n/**\n * A plugin's declared fields, read from its MANIFEST rather than the registry\n * (AGL-428).\n *\n * The registry is a module-scope map, filled by `registerPluginConfigSchema`\n * at import time. A marketplace plugin cannot fill it: its bundle runs in a\n * sandboxed frame on a separate origin and never executes in the console\n * process, so there is no moment at which its registration could happen. The\n * settings form therefore rendered NOTHING for every plugin a workspace\n * installed, and `resolvePluginConfig` — which is entirely plugin-agnostic and\n * would have layered a third-party plugin's org default under a per-site\n * override without changing a line — was never reached for one.\n *\n * The manifest is denormalized onto every install pin, so it is the one\n * declaration of a marketplace plugin the console already holds.\n *\n * Everything here is re-validated rather than trusted. The manifest is\n * publisher-authored, it is stored on a client-readable document, and a form\n * built from it is a form an org manager saves through — so a junk `type`\n * drops the field rather than rendering an unknown control, and the field\n * count is capped so one manifest cannot turn a settings page into thousands\n * of inputs. Being reviewed once is not the same as being safe to render\n * verbatim forever.\n *\n * Returns `undefined` when the manifest declares nothing usable, which callers\n * must treat as \"this plugin has no settings\" rather than as an error: most\n * plugins take none.\n */\nexport function pluginConfigSchemaFromManifest(\n  pluginId: string,\n  manifest: unknown,\n): PluginConfigSchema | undefined {\n  if (!pluginId) return undefined\n  const declared = (manifest as { config?: unknown } | null | undefined)?.config\n  const rawFields = (declared as { fields?: unknown } | undefined)?.fields\n  if (!Array.isArray(rawFields)) return undefined\n  const seen = new Set<string>()\n  const fields: PluginConfigField[] = []\n  for (const raw of rawFields) {\n    if (fields.length >= MANIFEST_CONFIG_FIELD_LIMIT) break\n    const entry = raw as Record<string, unknown> | null\n    const key = typeof entry?.['key'] === 'string' ? entry['key'].trim() : ''\n    // A duplicate key would give two controls one storage slot, so the second\n    // is dropped rather than allowed to shadow the first.\n    if (!key || seen.has(key)) continue\n    const type = String(entry?.['type'] ?? 'string')\n    if (!FIELD_TYPES.has(type)) continue\n    const options = Array.isArray(entry?.['options'])\n      ? (entry['options'] as unknown[])\n          .map((option) => option as Record<string, unknown> | null)\n          .filter(\n            (option) =>\n              typeof option?.['value'] === 'string' &&\n              typeof option?.['label'] === 'string',\n          )\n          .map((option) => ({\n            value: String(option?.['value']),\n            label: String(option?.['label']),\n          }))\n      : undefined\n    // A `select` with nothing to select is a dropdown that cannot be answered,\n    // so it is dropped rather than rendered empty.\n    if (type === 'select' && !options?.length) continue\n    seen.add(key)\n    fields.push({\n      key,\n      label:\n        typeof entry?.['label'] === 'string' && entry['label'].trim()\n          ? String(entry['label']).slice(0, 120)\n          : key,\n      type: type as PluginConfigField['type'],\n      description:\n        typeof entry?.['description'] === 'string'\n          ? String(entry['description']).slice(0, 400)\n          : undefined,\n      options,\n      min: typeof entry?.['min'] === 'number' ? entry['min'] : undefined,\n      max: typeof entry?.['max'] === 'number' ? entry['max'] : undefined,\n    })\n  }\n  if (!fields.length) return undefined\n  const rawDefaults = (declared as { defaults?: unknown } | undefined)?.defaults\n  const defaults: Record<string, unknown> = {}\n  for (const field of fields) {\n    // Defaults are coerced through the same path stored values take, so a\n    // manifest default of the wrong type cannot become the value a site\n    // inherits. An absent one falls back to the type's empty value rather than\n    // `undefined`, which `pluginConfigOverrides` reads as \"not answered\".\n    const supplied =\n      rawDefaults && typeof rawDefaults === 'object'\n        ? (rawDefaults as Record<string, unknown>)[field.key]\n        : undefined\n    const empty =\n      field.type === 'boolean'\n        ? false\n        : field.type === 'number'\n          ? (field.min ?? 0)\n          : field.type === 'select'\n            ? (field.options?.[0]?.value ?? '')\n            : ''\n    defaults[field.key] = coerce(field, supplied, empty)\n  }\n  return { pluginId, fields, defaults }\n}\n\n/**\n * The three levels a plugin setting can be answered at.\n *\n * A workspace sets a value once and every site it enabled the plugin on\n * follows it; a site that needs a different answer overrides that one field\n * and keeps inheriting the rest. Bookings is the shape this is for — one\n * booking horizon across a chain, with the flagship branch taking bookings\n * further out — and it generalizes to every plugin because none of them get\n * to invent their own inheritance.\n */\nexport interface PluginConfigSources {\n  /** `orgs/{orgId}/pluginSettings/{pluginId}` — the workspace's answer. */\n  org?: Record<string, unknown> | null\n  /** `hosts/{hostId}/pluginSettings/{pluginId}` — only the keys this site overrides. */\n  host?: Record<string, unknown> | null\n}\n\n/**\n * Which keys a site is answering for itself.\n *\n * A key is an override when it is PRESENT on the host document, and inherited\n * when it is absent. `undefined` counts as absent, deliberately: a UI that\n * writes `{key: undefined}` to mean \"stop overriding\" is doing the same thing\n * as one that never wrote the key, and treating the two differently would make\n * \"revert to the workspace value\" depend on which code path cleared it.\n *\n * ⚠️ Which is also why clearing an override must DELETE the key rather than\n * write an empty value. `setDoc(..., {merge: true})` leaves an existing field\n * exactly as it is when the new object omits it, so a form that drops empty\n * inputs cannot clear anything by saving — the override survives, invisibly,\n * and the site keeps ignoring a workspace value the operator has since\n * changed. Deleting is the only write that returns a field to inherited.\n *\n * Keys the schema does not declare are ignored, so a stale field left behind\n * by a plugin update does not read as an override of a setting that no longer\n * exists.\n */\nexport function pluginConfigOverrides(\n  schema: PluginConfigSchema,\n  host: Record<string, unknown> | null | undefined,\n): string[] {\n  if (!host) return []\n  return schema.fields\n    .filter((field) => field.key in host && host[field.key] !== undefined)\n    .map((field) => field.key)\n}\n\n/**\n * What a plugin actually runs with on one site.\n *\n * Schema defaults, then the workspace's stored values, then only the keys the\n * site overrides — each layer narrowing the one before it. Type coercion\n * happens once at the end rather than per level, so a site override of the\n * wrong type falls back to the WORKSPACE value it was trying to replace\n * instead of skipping past it to the schema default. Getting that backwards\n * would have one malformed site setting silently discard a workspace answer\n * the operator can see in their own console.\n */\nexport function resolvePluginConfig(\n  schema: PluginConfigSchema,\n  sources: PluginConfigSources,\n): Record<string, unknown> {\n  const org = mergePluginConfig(schema, sources.org)\n  const overrides = pluginConfigOverrides(schema, sources.host)\n  if (!overrides.length) return org\n  const host = sources.host as Record<string, unknown>\n  const merged: Record<string, unknown> = { ...org }\n  for (const field of schema.fields) {\n    if (!overrides.includes(field.key)) continue\n    merged[field.key] = coerce(field, host[field.key], org[field.key])\n  }\n  return merged\n}\n"],"names":["schemas","Map","registerPluginConfigSchema","schema","set","pluginId","getPluginConfigSchema","get","listPluginConfigSchemas","values","coerce","field","raw","fallback","type","value","Number","isFinite","NaN","isNaN","min","max","undefined","options","some","option","mergePluginConfig","stored","merged","defaults","fields","key","validatePluginConfigValues","error","validate","ok","MANIFEST_CONFIG_FIELD_LIMIT","FIELD_TYPES","Set","pluginConfigSchemaFromManifest","manifest","declared","config","rawFields","Array","isArray","seen","length","entry","trim","has","String","map","filter","label","add","push","slice","description","rawDefaults","supplied","empty","pluginConfigOverrides","host","resolvePluginConfig","sources","org","overrides","includes"],"mappings":"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"}

package/src/lib/plugin-manager/plugin-console-crons.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A plugin's own scheduled jobs, run by the CONSOLE (AGL-2981).
+ *
+ * The platform already has a beat for work that belongs on the tenant — the
+ * job runner behind `pluginJobsBeat` — and it is the wrong place for a job
+ * that holds a credential only the console may hold: a provider key, a
+ * sealed grant to a person's mailbox. Those jobs have to run in the console,
+ * and until now the only way to get one there was a console route of its own
+ * and a literal in the scheduler's route list, which is a plugin's route in
+ * the platform's code.
+ *
+ * So a plugin DECLARES a console job here instead, and the platform runs
+ * every declared job from one route, `/api/admin/plugin-crons`, which the
+ * Cloud Scheduler job that drives the console's fifteen-minute sweeps posts
+ * like any other of its routes. A plugin that adds a job adds a declaration;
+ * the scheduler, its firewall rule and its deploy are unchanged.
+ *
+ * ## One schedule
+ *
+ * Every declared job runs on that tick: {@link PLUGIN_CONSOLE_CRON_SCHEDULE}.
+ * A job that has nothing to do returns at once. A job that needs a slower
+ * cadence keeps its own "last ran" mark and skips; one that needs a faster
+ * one is not a job for this runner.
+ *
+ * ## Watched like every other job
+ *
+ * Each job has its own row on `/api/health/crons` —
+ * {@link pluginConsoleCronScheduledJobs} — and the runner stamps that row's
+ * `platformCronBeats` mark when it invokes the job, BEFORE the work, the rule
+ * every console cron follows: the mark answers "is this job still being
+ * scheduled", and a job that throws was still scheduled. A job that stops
+ * being run — its plugin unregistered it, the route stopped being posted —
+ * goes red on the board within its grace.
+ *
+ * ## Isolated, and bounded
+ *
+ * Jobs run concurrently, each in its own try: a throw is logged against its
+ * plugin and reported as `null`, and never stops another job. Each is handed
+ * a deadline, and a job that starts no new unit of work after it lets the
+ * route answer before its caller gives up.
+ *
+ * Declared from a plugin's `consoleServerDeclarations` — the console's boot
+ * registrations — with the job's body imported lazily, so boot pays for the
+ * declaration and the tick pays for the work.
+ */
+import { type ScheduledJob } from '../app-utils/health-report';
+/** The console route that runs every declared job, as the scheduler posts it. */
+export declare const PLUGIN_CONSOLE_CRONS_ROUTE = "/api/admin/plugin-crons";
+/** The runner's own row on `/api/health/crons`: is the route being posted at all. */
+export declare const PLUGIN_CONSOLE_CRONS_JOB_ID = "plugin-console-crons";
+/**
+ * The tick every declared job runs on, five-field UTC: the console's
+ * fifteen-minute sweep (`CONSOLE_FAST_CRON_SCHEDULE` in `cloud/functions`).
+ */
+export declare const PLUGIN_CONSOLE_CRON_SCHEDULE = "*/15 * * * *";
+/** How late a declared job may be before its row goes red: three missed ticks. */
+export declare const PLUGIN_CONSOLE_CRON_GRACE_MINUTES = 45;
+/** What one run of a job is handed. */
+export interface PluginConsoleCronContext {
+    /** When the tick began, epoch ms. */
+    nowMs: number;
+    /** Start no new unit of work after this, epoch ms. */
+    deadlineMs: number;
+}
+/** What a job reports for the tick's answer and log: counts, flags, a word — never content. */
+export type PluginConsoleCronReport = Readonly<Record<string, number | boolean | string | null>>;
+export interface PluginConsoleCronJob {
+    /**
+     * The job's id: its `platformCronBeats` document and its health row.
+     * Starts with the plugin's own id — `acme-mail-sync` for `acme-mail` — so
+     * two plugins' jobs, and a plugin's job and the platform's, never share one.
+     */
+    id: string;
+    /** What the health board calls it. */
+    label: string;
+    /** What stops happening when it stops, in a sentence the board renders. */
+    drives: string;
+    run(context: PluginConsoleCronContext): Promise<PluginConsoleCronReport>;
+}
+/** A declared job, without its body. */
+export interface PluginConsoleCronDeclaration {
+    pluginId: string;
+    id: string;
+    label: string;
+    drives: string;
+}
+/**
+ * Declares a plugin's console job. Owner = the loader's marker inside a
+ * register fn, else `options.pluginId`; a job with neither throws, as does
+ * an id that is not the plugin's own (`<pluginId>-…`), one the platform's
+ * inventory holds, one another plugin declared, and a job with no label or
+ * no consequence. The same plugin declaring the same id again replaces its
+ * job in place.
+ */
+export declare function registerPluginConsoleCron(job: PluginConsoleCronJob, options?: {
+    pluginId?: string;
+}): void;
+/** Every declared job, in declaration order, without its body. */
+export declare function listPluginConsoleCrons(): PluginConsoleCronDeclaration[];
+/**
+ * The declared jobs as rows of the scheduled-job inventory, for
+ * `/api/health/crons` to judge beside the platform's own.
+ */
+export declare function pluginConsoleCronScheduledJobs(): ScheduledJob[];
+export interface RunPluginConsoleCronsOptions {
+    nowMs: number;
+    deadlineMs: number;
+    /** Only these jobs, by id — a manual re-run of one. Absent runs every job. */
+    jobIds?: readonly string[] | null;
+    /**
+     * Stamps a job's `platformCronBeats` mark. Must not throw; the runner
+     * awaits it before the job starts.
+     */
+    beat(jobId: string, nowMs: number): Promise<unknown>;
+}
+/**
+ * Runs the declared jobs — every one, or the ones named — concurrently,
+ * each after its beat. Answers each job's report by id, or `null` for one
+ * that threw. Never throws.
+ */
+export declare function runPluginConsoleCrons(options: RunPluginConsoleCronsOptions): Promise<Record<string, PluginConsoleCronReport | null>>;
+/** Test seam: forget every declared job. */
+export declare function resetPluginConsoleCronsForTests(): void;