@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/extensions/org-levels.d.ts

@@ -0,0 +1,37 @@
+import { type JsonSchema } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/**
+ * The org level of a deployment config field (spec A §5.1): `hidden` (platform only, orgs never
+ * see it; a field without `orgAccess`), `readonly` (orgs see it, cannot change it) or `override`
+ * (the platform sets the default, an org may bring its own value). Levels sit on top-level keys of
+ * the deployment schema only (§5.2); a nested field has its top-level key's level.
+ */
+export type FieldLevel = "hidden" | "readonly" | "override";
+/** The top-level keys of a `ZodObject` deployment schema with their level; empty otherwise. */
+export declare function fieldLevels(schema: z.ZodTypeAny | undefined): Map<string, FieldLevel>;
+/**
+ * The same levels read from a package's static form schema (`x-org` on top-level properties), for
+ * an install record whose module this replica has not loaded.
+ */
+export declare function jsonSchemaFieldLevels(schema: JsonSchema | undefined): Map<string, FieldLevel>;
+/**
+ * The platform's relaxed schema (§5.4a): a plain object rebuilt from the shape with every
+ * `override` key optional, so the platform may leave overridable fields empty (each org then
+ * brings its own); hidden and read-only fields stay as declared. Object-level refinements
+ * (`.refine` / `.superRefine`) are not carried over: they may read the absent fields, and zod
+ * refuses `.extend()` on a refined object. The identity when there is no `override` key. Parse
+ * through {@link parseLoadGate}, which uses this only when an overridable field is missing.
+ */
+export declare function relaxOverridable(schema: z.ZodTypeAny): z.ZodTypeAny;
+/**
+ * The platform's load gate (§5.4a): the original schema, refinements included, whenever the
+ * platform config `raw` leaves no required overridable field empty; otherwise the relaxed plain
+ * object ({@link relaxOverridable}). Following orgs are then `needsConfig` and never called, and
+ * an org copy is parsed with the full schema.
+ */
+export declare function parseLoadGate(schema: z.ZodTypeAny, raw: unknown): z.ZodSafeParseResult<unknown>;
+/**
+ * The required `override` keys the platform config `raw` leaves empty (absent and refused by the
+ * key's own schema), in schema order: orgs that follow the platform must configure them.
+ */
+export declare function missingOverridable(schema: z.ZodTypeAny, raw: unknown): string[];

package/dist/extensions/org-levels.js

@@ -0,0 +1,71 @@
+import { orgAccessOf } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/** The top-level keys of a `ZodObject` deployment schema with their level; empty otherwise. */
+export function fieldLevels(schema) {
+    const out = new Map();
+    if (!(schema instanceof z.ZodObject))
+        return out;
+    for (const [key, field] of Object.entries(schema.shape)) {
+        out.set(key, orgAccessOf(field) ?? "hidden");
+    }
+    return out;
+}
+/**
+ * The same levels read from a package's static form schema (`x-org` on top-level properties), for
+ * an install record whose module this replica has not loaded.
+ */
+export function jsonSchemaFieldLevels(schema) {
+    const out = new Map();
+    const props = schema?.properties;
+    if (typeof props !== "object" || props === null)
+        return out;
+    for (const [key, prop] of Object.entries(props)) {
+        const v = prop?.["x-org"];
+        out.set(key, v === "readonly" || v === "override" ? v : "hidden");
+    }
+    return out;
+}
+const overrideKeys = (schema) => [...fieldLevels(schema)].filter(([, l]) => l === "override").map(([k]) => k);
+/**
+ * The platform's relaxed schema (§5.4a): a plain object rebuilt from the shape with every
+ * `override` key optional, so the platform may leave overridable fields empty (each org then
+ * brings its own); hidden and read-only fields stay as declared. Object-level refinements
+ * (`.refine` / `.superRefine`) are not carried over: they may read the absent fields, and zod
+ * refuses `.extend()` on a refined object. The identity when there is no `override` key. Parse
+ * through {@link parseLoadGate}, which uses this only when an overridable field is missing.
+ */
+export function relaxOverridable(schema) {
+    const keys = overrideKeys(schema);
+    if (keys.length === 0)
+        return schema;
+    const obj = schema;
+    const shape = { ...obj.shape };
+    for (const k of keys)
+        shape[k] = shape[k].optional();
+    const plain = z.object(shape);
+    const catchall = obj._zod.def.catchall;
+    return catchall ? plain.catchall(catchall) : plain;
+}
+/**
+ * The platform's load gate (§5.4a): the original schema, refinements included, whenever the
+ * platform config `raw` leaves no required overridable field empty; otherwise the relaxed plain
+ * object ({@link relaxOverridable}). Following orgs are then `needsConfig` and never called, and
+ * an org copy is parsed with the full schema.
+ */
+export function parseLoadGate(schema, raw) {
+    if (missingOverridable(schema, raw).length === 0)
+        return schema.safeParse(raw);
+    return relaxOverridable(schema).safeParse(raw);
+}
+/**
+ * The required `override` keys the platform config `raw` leaves empty (absent and refused by the
+ * key's own schema), in schema order: orgs that follow the platform must configure them.
+ */
+export function missingOverridable(schema, raw) {
+    const keys = overrideKeys(schema);
+    if (keys.length === 0)
+        return [];
+    const shape = schema.shape;
+    const value = typeof raw === "object" && raw !== null ? raw : {};
+    return keys.filter((k) => value[k] === undefined && !shape[k].safeParse(undefined).success);
+}

package/dist/extensions/org-overrides.d.ts

@@ -0,0 +1,151 @@
+import { type Keyring } from "../ctx/secrets.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { type ConfigIssue } from "./config-issues.js";
+import { type JsonSchema } from "./config-json-schema.js";
+import { type SecretEntry } from "./deployment-config.js";
+import { EffectiveConfigs } from "./effective-config.js";
+import { ExtensionHost } from "./host.js";
+import { type FieldLevel } from "./org-levels.js";
+/** One field of {@link OrgOverrideView}: a read-only or overridable deployment field. */
+export interface OrgOverrideField {
+    path: string;
+    level: "readonly" | "override";
+    secret: boolean;
+    /** The platform's current value (non-secret) or only whether it is set (secret). */
+    platform: {
+        value?: unknown;
+        set?: boolean;
+    };
+    /** With a copy, on an overridable field: the copy's value, or whether its secret is set. */
+    org?: {
+        value?: unknown;
+        set?: boolean;
+    };
+    /** With a copy, on an overridable non-secret field: the copy's value differs from the platform's. */
+    differs?: boolean;
+}
+/**
+ * What an org admin sees of an extension's two-level config (spec A §5.3 to §5.6): whether the org
+ * follows the platform or keeps a copy, the read-only and overridable fields (hidden fields never
+ * appear), and whether the effective config is valid. Secrets give `set` only, never a value, and
+ * are never compared.
+ */
+export interface OrgOverrideView {
+    state: "following" | "copy";
+    /**
+     * The deployment form JSON Schema restricted to the read-only and overridable top-level
+     * properties (as the platform form gets it, with `x-ui`, `x-secret`, `x-org`); hidden properties,
+     * their `required` entries and hints naming them are removed. Null when the extension has no
+     * deployment schema or it cannot be converted.
+     */
+    schema: JsonSchema | null;
+    createdAt?: string;
+    fields: OrgOverrideField[];
+    valid: boolean;
+    issues: ConfigIssue[];
+}
+/** One org copy in the admin's extension detail (spec A §5.7). */
+export interface OrgOverrideSummary {
+    orgId: string;
+    orgName: string;
+    createdAt: string;
+    /** The overridable non-secret fields whose copy value differs from the platform's. */
+    differing: string[];
+    secrets: {
+        path: string;
+        set: boolean;
+    }[];
+}
+interface Actor {
+    accountId: string;
+    tokenId?: string | undefined;
+}
+/**
+ * Org copies of an extension's overridable deployment config (spec A §5.4, §5.5, §5.8): one row of
+ * `extension_org_overrides` per copy (its non-secret values), each secret in `capybara.secrets`
+ * under the org (namespace `kernel`, key `plugin-override:<plugin>:<path>`), written in the same
+ * transaction under the org row lock. Writes are org-audited and evict the cached copy after the
+ * commit. Platform secrets never enter a copy.
+ */
+export declare class OrgOverrides {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly keyring;
+    private readonly host;
+    /** The org row lock: re-checks `org.extensions.manage` under the lock. */
+    private readonly orgLock;
+    private readonly effective;
+    private readonly log;
+    constructor(kdb: KernelDb, txHost: TransactionHost, keyring: Keyring, host: ExtensionHost, 
+    /** The org row lock: re-checks `org.extensions.manage` under the lock. */
+    orgLock: OrgLock, effective: EffectiveConfigs, log: KernelLogger);
+    private get db();
+    private running;
+    /**
+     * The running extension, for an org: one the org does not see under plugin scope (a `named`
+     * plugin without it) is answered like an unknown one, so its platform values never reach it.
+     */
+    private runningFor;
+    /** The org's view (read-only and overridable fields, the copy state and validity). */
+    view(orgId: string, plugin: string): Promise<OrgOverrideView>;
+    /**
+     * Saves overridable fields (`values` keyed by field dot path: `null` clears, omitted keeps;
+     * secret fields too, as in the platform form) and secret record entries. The first save creates
+     * the copy from the platform's non-secret overridable values plus `values` (secret fields start
+     * empty). A path that is not an overridable field of the schema (read-only, hidden, unknown) ->
+     * 400 `extension.field_not_overridable`; an invalid result (an empty required secret included)
+     * -> 400 `extension.config_invalid`, nothing written. Audits `extension.org_override_saved`.
+     */
+    save(orgId: string, plugin: string, values: Record<string, unknown>, secretEntries: readonly SecretEntry[], actor: Actor): Promise<OrgOverrideView>;
+    private writeSave;
+    /**
+     * Takes the platform's current values of non-secret overridable fields into the copy (spec A
+     * §5.5); the copy stays a copy. A secret, read-only, hidden or unknown path -> 400
+     * `extension.field_not_overridable`; no copy -> 404 `extension.no_org_override`. Audits
+     * `extension.org_override_taken`.
+     */
+    take(orgId: string, plugin: string, paths: string[], actor: Actor): Promise<OrgOverrideView>;
+    private writeTake;
+    /**
+     * Drops the copy and every secret of it in one transaction; the org follows the platform again
+     * (spec A §5.5). No copy -> 404 `extension.no_org_override`. Audits `extension.org_override_reset`.
+     */
+    reset(orgId: string, plugin: string, actor: Actor): Promise<OrgOverrideView>;
+    private writeReset;
+    /**
+     * The orgs (not deleted) holding a copy of the extension, oldest first, with the overridable
+     * non-secret fields that differ from the platform and whether each copy secret is set (spec A
+     * §5.7); never a secret value. Differences need the running schema: an extension not running on
+     * this replica lists no differences and only the secrets the copies hold.
+     */
+    listForPlugin(plugin: string): Promise<OrgOverrideSummary[]>;
+    /** The merged copy validated with the full schema; invalid -> 400 `extension.config_invalid`. */
+    private validated;
+    private messagesOf;
+    /** The deployment form JSON Schema (hints dropped when invalid; one warning). Never throws. */
+    private formSchemaOf;
+    private lockedRow;
+    /** The keys of the org's copy secrets for `plugin` (any path, current or stale). */
+    private secretKeys;
+    private readSecrets;
+    /** Writes the copy's secrets of the current schema and drops stale keys (paths no longer secret). */
+    private writeSecrets;
+    private render;
+    private secretPathsHeld;
+}
+/**
+ * The form JSON Schema an org may see (spec A §5.6, "hidden fields are not sent to the org at
+ * all"): a copy with only the read-only and overridable top-level properties, `required` limited
+ * to them, and root `x-ui` hints naming a hidden field dropped (`secrets[]` by path; `order` lists
+ * none). Values are never in it: `configJsonSchema` already strips secret defaults and examples.
+ */
+export declare function orgFormSchema(js: JsonSchema, levels: Map<string, FieldLevel>): JsonSchema;
+/**
+ * Issues as an org may see them: an issue on a hidden field would name a field the org never
+ * sees, so those collapse into one root issue.
+ */
+export declare function orgIssues(issues: ConfigIssue[], levels: Map<string, FieldLevel>): ConfigIssue[];
+export {};