@zackbart/connecta 0.28.0 → 0.29.0

package/dist/config-schema.js

@@ -0,0 +1,435 @@
+// The combinators behind ConnectaConfig's one schema (src/config.ts).
+//
+// A schema here is a value that does three jobs at once, so they cannot drift
+// apart: its type parameters produce the TypeScript type a deployment writes
+// (`ConfigInput`) and the resolved shape core reads (`ConfigOutput`); its
+// object shapes drive unknown-key rejection; and each field's `parse` and
+// `absent` carry its validation and its default. There is one validation
+// policy: a value that is present and wrong throws, with its path, before
+// createConnecta does any work (INV-11). Nothing warns and falls back.
+//
+// Deliberately small. Opaque fields (connectors, modules, functions) are
+// checked by identity or shape and passed through untouched, never cloned, so
+// a private-field receiver or a frozen object reaches core as configured.
+/** A structural configuration mistake, thrown before construction does work. */
+export class ConfigError extends TypeError {
+    name = "ConfigError";
+}
+function fail(message) {
+    throw new ConfigError(message);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function ownValue(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key) ? value[key] : undefined;
+}
+export function whole(options) {
+    const kind = options.min === 1 ? "positive" : "non-negative";
+    return {
+        optional: true,
+        parse: (value, path) => {
+            if (typeof value !== "number" || !Number.isSafeInteger(value) || value < options.min) {
+                fail(`${path} must be a ${kind} whole number.`);
+            }
+            if (options.max !== undefined && value > options.max) {
+                fail(`${path} must be at most ${options.max.toLocaleString("en-US")}` + (options.unit ? ` ${options.unit}.` : "."));
+            }
+            return value;
+        },
+        absent: () => options.default,
+    };
+}
+/** A non-negative finite number, fractions allowed. */
+export function seconds(options) {
+    return {
+        optional: true,
+        parse: (value, path) => {
+            if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+                fail(`${path} must be a non-negative number of seconds.`);
+            }
+            return value;
+        },
+        absent: () => options.default,
+    };
+}
+export function text() {
+    return {
+        optional: true,
+        parse: (value, path) => {
+            if (typeof value !== "string")
+                fail(`${path} must be a string.`);
+            return value;
+        },
+        absent: () => undefined,
+    };
+}
+/**
+ * A value core checks by shape and passes through untouched: a connector, a
+ * module, an executor. `check` throws its own message for a wrong value;
+ * `resolve` maps the accepted value (or `undefined`, when omitted) to what
+ * core reads.
+ */
+export function opaque(options = {}) {
+    const resolve = options.resolve ?? ((value) => value);
+    return {
+        optional: true,
+        parse: (value, path) => {
+            options.check?.(value, path);
+            return resolve(value);
+        },
+        absent: () => resolve(undefined),
+    };
+}
+/** A function, never called, read, or serialized by configuration. */
+export function fn() {
+    return opaque({
+        check: (value, path) => {
+            if (typeof value !== "function")
+                fail(`${path} must be a function.`);
+        },
+    });
+}
+/** The same field, but a deployment must supply it. */
+export function required(field, message) {
+    return {
+        ...field,
+        optional: false,
+        parse: field.parse,
+        absent: (path) => fail(message ? message(path) : `${path} is required.`),
+    };
+}
+/**
+ * A closed object. Its keys are the shape's keys; anything else is refused
+ * by the unknown-key walk before any value is read. An omitted object
+ * resolves to its children's defaults.
+ */
+export function object(shape) {
+    const resolve = (value, path) => {
+        const out = {};
+        for (const [key, field] of Object.entries(shape)) {
+            const child = value === undefined ? undefined : ownValue(value, key);
+            const resolved = child === undefined ? field.absent(`${path}.${key}`) : field.parse(child, `${path}.${key}`);
+            // An unset field without a default stays absent, as it was configured.
+            if (resolved !== undefined)
+                out[key] = resolved;
+        }
+        return Object.freeze(out);
+    };
+    return {
+        optional: true,
+        shape,
+        parse: (value, path) => {
+            if (!isPlainObject(value))
+                fail(`${path} must be an object.`);
+            return resolve(value, path);
+        },
+        absent: (path) => resolve(undefined, path),
+    };
+}
+/** A list whose items each satisfy `item`. */
+export function array(item) {
+    return {
+        optional: true,
+        element: item,
+        parse: (value, path) => {
+            if (!Array.isArray(value))
+                fail(`${path} must be an array.`);
+            return Object.freeze(value.map((entry, index) => item.parse(entry, `${path}[${index}]`)));
+        },
+        absent: () => undefined,
+    };
+}
+/** An object keyed by caller-chosen names, each value satisfying `value`. */
+export function record(value) {
+    return {
+        optional: true,
+        element: value,
+        keyed: true,
+        parse: (input, path) => {
+            if (!isPlainObject(input))
+                fail(`${path} must be an object.`);
+            // Keys are caller-chosen, so `__proto__`, `constructor`, and the like
+            // must stay ordinary entries: no prototype to assign through or inherit.
+            const out = Object.create(null);
+            for (const key of Object.keys(input)) {
+                // An explicitly undefined entry is an omitted one, as for any field.
+                if (input[key] === undefined)
+                    continue;
+                out[key] = value.parse(input[key], `${path}.${key}`);
+            }
+            return Object.freeze(out);
+        },
+        absent: () => undefined,
+    };
+}
+/**
+ * A map of caller-chosen names to strings, such as static headers or extra
+ * OAuth parameters. The walk copies it through property descriptors, so an
+ * accessor is refused by path unrun and a non-string value by path unechoed.
+ */
+export function strings() {
+    return { ...record(text()), strings: true };
+}
+/**
+ * A closed object that carries behaviour, such as an `api()` tool. The walk
+ * checks it like any closed object (own keys declared, no own accessor, and
+ * no inherited accessor at a declared key) but returns the original rather
+ * than a copy, so a prototype method keeps its receiver and a handler that
+ * reads `#private` fields still finds them. It may be a class instance.
+ */
+export function instance(field) {
+    return { ...field, instance: true };
+}
+/**
+ * A closed object whose allowed keys depend on a discriminant, such as
+ * `remoteMcp({ auth: { type: "headers", headers } })`. An omitted
+ * discriminant selects `otherwise` when given; an omitted one without it, an
+ * unrecognized one, or a value that is not an object throws with its path and
+ * the valid values, so no union falls through to "no case". Only the walk
+ * reads variants; the factory validates the remaining values itself.
+ */
+export function variants(key, cases, otherwise) {
+    return {
+        ...opaque(),
+        variants: { key, cases, ...(otherwise !== undefined ? { otherwise } : {}) },
+    };
+}
+/**
+ * A closed object for the unknown-key walk only: each named key may hold
+ * anything, which its factory validates. For the options of a built-in
+ * factory, where `object()` would resolve values the factory already owns.
+ */
+export function keys(...names) {
+    const field = opaque();
+    return Object.fromEntries(names.map((name) => [name, field]));
+}
+/**
+ * The closed options of a built-in factory, checked against its options type:
+ * a key the type declares but the shape omits, or the reverse, fails to
+ * compile, so the runtime walk cannot drift from the published type.
+ */
+export function optionsOf() {
+    return (shape) => ({ ...opaque(), shape });
+}
+/**
+ * Refuse a factory's unknown options and accessors before it reads any value,
+ * naming each path: `api("crm").maxResultByte`. Returns the options as a
+ * plain copy read through property descriptors, which the factory reads in
+ * place of what it was given, so no getter or Proxy trap of the caller's runs
+ * later either. Custom implementations a factory accepts (stores, handlers,
+ * executors) are `opaque()` in its shape and pass through untouched; an
+ * object that carries behaviour (an `api()` tool) is `instance()`, checked in
+ * place and passed through as given.
+ */
+export function assertKnownOptions(value, path, field) {
+    const read = readPlain(value, path, field);
+    if (read.unknown.length === 0)
+        return read.value;
+    return fail(`Unknown option${read.unknown.length === 1 ? "" : "s"}: ${read.unknown.join(", ")}. ` +
+        "Check the spelling against the factory's options type.");
+}
+/**
+ * Own property descriptors, read without invoking any accessor. A config
+ * object that cannot be inspected (a Proxy whose trap throws, or a revoked
+ * one) is refused by path; the trap's own message never surfaces.
+ */
+function inspect(value, path) {
+    try {
+        const proto = Reflect.getPrototypeOf(value);
+        return {
+            array: Array.isArray(value),
+            plain: proto === null || Reflect.getPrototypeOf(proto) === null,
+            proto,
+            own: Reflect.ownKeys(value).flatMap((key) => {
+                const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+                return descriptor ? [[key, descriptor]] : [];
+            }),
+        };
+    }
+    catch {
+        return fail(`${path} could not be read as plain configuration.`);
+    }
+}
+/** Whether `Array.isArray` holds, refusing by path a value that cannot say. */
+function isArrayAt(value, path) {
+    try {
+        return Array.isArray(value);
+    }
+    catch {
+        return fail(`${path} could not be read as plain configuration.`);
+    }
+}
+const isAccessor = (descriptor) => "get" in descriptor || "set" in descriptor;
+/** A data property's value, or `undefined` for an accessor, recorded by path and never run. */
+function dataValue(descriptor, path, state) {
+    if (!isAccessor(descriptor))
+        return descriptor.value;
+    state.refused.push(`${path} must be a plain value, not a getter or setter.`);
+    return undefined;
+}
+/**
+ * The descriptor a declared key inherits, read along the prototype chain
+ * without invoking an accessor. A chain that cannot be inspected is refused
+ * by path like the object itself.
+ */
+function inherited(proto, key, path) {
+    const seen = new Set();
+    try {
+        for (let at = proto; at !== null && !seen.has(at); at = Reflect.getPrototypeOf(at)) {
+            seen.add(at);
+            const descriptor = Reflect.getOwnPropertyDescriptor(at, key);
+            if (descriptor)
+                return descriptor;
+        }
+        return undefined;
+    }
+    catch {
+        return fail(`${path} could not be read as plain configuration.`);
+    }
+}
+/**
+ * Inspect a value a closed object or record slot holds. An array, or a
+ * class instance where only plain data belongs, is refused by path before
+ * any of its keys is read: `remoteMcp([...])` must not pass for options.
+ */
+function inspectRecord(value, path, field) {
+    const inspected = inspect(value, path);
+    if (inspected.array)
+        fail(`${path} must be an object.`);
+    if (!inspected.plain && !field.instance)
+        fail(`${path} must be a plain object.`);
+    return inspected;
+}
+/**
+ * The case a discriminant selects. A missing one selects `otherwise` when the
+ * union has a default; any other missing, unrecognized, or computed
+ * discriminant throws with the valid values, so a misspelled
+ * `type: "header"` cannot construct as if no case applied. The value itself
+ * is never echoed.
+ */
+function selectShape(inspected, path, variants) {
+    const at = `${path}.${variants.key}`;
+    const valid = Object.keys(variants.cases)
+        .map((name) => JSON.stringify(name))
+        .join(", ");
+    const descriptor = inspected.own.find(([key]) => key === variants.key)?.[1];
+    if (descriptor && isAccessor(descriptor))
+        fail(`${at} must be a plain value, not a getter or setter.`);
+    const discriminant = descriptor?.value;
+    if (discriminant === undefined) {
+        if (variants.otherwise !== undefined)
+            return variants.cases[variants.otherwise];
+        return fail(`${at} is required: one of ${valid}.`);
+    }
+    if (typeof discriminant !== "string" || !Object.hasOwn(variants.cases, discriminant)) {
+        return fail(`${at} must be one of ${valid}.`);
+    }
+    return variants.cases[discriminant];
+}
+/**
+ * Read a configuration value the way the schema sees it: every own key it
+ * does not declare, as paths, and the value as a plain copy built only from
+ * the property descriptors this walk inspected. Callers resolve that copy,
+ * never the original, so no property is read through `[[Get]]` twice or at
+ * all: no getter runs, a Proxy's `get` trap never fires, and no value is
+ * echoed.
+ *
+ * Unknown keys anywhere are reported first. With none, a declared key holding
+ * an accessor is refused by path, since a plain configuration object has no
+ * reason to compute a value, and a getter that throws or changes between
+ * reads would break the one-read guarantee. Only own string keys count, so a
+ * prototype contributes nothing. A closed object or record slot takes a
+ * plain object only; an array or class instance there is refused by path.
+ * Arrays are walked by the same rules, the items of an `opaque()` array
+ * included (`allowedOrigins`, `auth`); an `instance()` object (an `api()`
+ * tool) is checked the same way but returned as given; any other `opaque()`
+ * value (a connector, module, executor, storage, or logger) is never entered
+ * and passes through as configured. Configuration is operator-authored and
+ * trusted: the walk refuses mistakes by path without echoing a value; it is
+ * not a sandbox for hostile objects.
+ */
+export function readPlain(value, path, field) {
+    const state = { unknown: [], refused: [] };
+    const plain = walk(value, path, field, state);
+    if (state.unknown.length === 0 && state.refused.length > 0)
+        fail(state.refused[0]);
+    return { unknown: state.unknown, value: plain };
+}
+function walk(value, path, field, state) {
+    if (field.variants &&
+        value !== undefined &&
+        (typeof value !== "object" || value === null || isArrayAt(value, path))) {
+        return fail(`${path} must be an object.`);
+    }
+    if (typeof value !== "object" || value === null)
+        return value;
+    if (field.shape || field.variants) {
+        const inspected = inspectRecord(value, path, field);
+        const shape = field.shape ?? selectShape(inspected, path, field.variants);
+        const unknown = inspected.own
+            .filter(([key]) => typeof key !== "string" || !Object.hasOwn(shape, key))
+            .map(([key]) => `${path}.${String(key)}`)
+            .sort();
+        if (unknown.length > 0) {
+            state.unknown.push(...unknown);
+            return undefined;
+        }
+        const out = {};
+        for (const [key, descriptor] of inspected.own) {
+            const child = `${path}.${String(key)}`;
+            out[key] = walk(dataValue(descriptor, child, state), child, shape[key], state);
+        }
+        if (!field.instance)
+            return out;
+        // A declared key the object inherits, such as a class's `handler()`, is
+        // read from its prototype when called; it must not be a computed one.
+        for (const key of Object.keys(shape)) {
+            if (Object.hasOwn(out, key))
+                continue;
+            const descriptor = inherited(inspected.proto, key, `${path}.${key}`);
+            if (descriptor)
+                dataValue(descriptor, `${path}.${key}`, state);
+        }
+        return value;
+    }
+    if (field.keyed) {
+        const inspected = inspectRecord(value, path, field);
+        // Keys are caller-chosen, so the copy has no prototype for `__proto__` to reach.
+        const out = Object.create(null);
+        for (const [key, descriptor] of inspected.own) {
+            if (typeof key !== "string" || !descriptor.enumerable)
+                continue;
+            const child = `${path}.${key}`;
+            const entry = dataValue(descriptor, child, state);
+            if (field.strings && !isAccessor(descriptor) && typeof entry !== "string") {
+                state.refused.push(`${child} must be a string.`);
+            }
+            out[key] = walk(entry, child, field.element, state);
+        }
+        return out;
+    }
+    if (!field.element && !isArrayAt(value, path))
+        return value;
+    const inspected = inspect(value, path);
+    if (!inspected.array)
+        return value;
+    const element = field.element ?? OPAQUE;
+    const out = [];
+    for (const [key, descriptor] of inspected.own) {
+        if (key === "length") {
+            const length = descriptor.value;
+            if (Number.isInteger(length) && length >= 0 && length <= 0xffff_ffff) {
+                out.length = length;
+            }
+            continue;
+        }
+        // Only indices are items; any other key on an array is never read.
+        if (typeof key !== "string" || String(Number(key) >>> 0) !== key)
+            continue;
+        const child = `${path}[${key}]`;
+        out[Number(key)] = walk(dataValue(descriptor, child, state), child, element, state);
+    }
+    return out;
+}
+const OPAQUE = opaque();

package/dist/config-value-sources.js

@@ -0,0 +1,102 @@
+/** Walk only serialized keys. Stable connector/pool keys survive viewer filtering. */
+export function configValuePaths(value, path = "config") {
+    if (value === null || typeof value !== "object")
+        return [path];
+    const entries = Object.entries(value);
+    if (!entries.length)
+        return [path];
+    if ("value" in value && "source" in value && entries.length === 2)
+        return [path];
+    return entries.flatMap(([key, item]) => {
+        const stableKey = Array.isArray(value) &&
+            (path === "config.connectors" || path === "config.pools") &&
+            item &&
+            typeof item === "object"
+            ? String(path === "config.connectors" ? item.id : item.name)
+            : key;
+        return configValuePaths(item, `${path}.${stableKey}`);
+    });
+}
+/** Read only provenance literals; custom describe hooks may throw or return unknown data. */
+function factorySources(factory) {
+    try {
+        const description = factory?.describe?.();
+        if (!description || typeof description !== "object" || !("optionSources" in description))
+            return {};
+        const sources = description.optionSources;
+        if (!sources || typeof sources !== "object")
+            return {};
+        return Object.fromEntries(Object.entries(sources).filter((entry) => entry[1] === "default" || entry[1] === "config"));
+    }
+    catch {
+        return {};
+    }
+}
+function factorySource(sources, parts) {
+    for (let length = parts.length; length > 0; length--) {
+        const source = sources[parts.slice(0, length).join(".")];
+        if (source === "default" || source === "config")
+            return source;
+    }
+    return undefined;
+}
+/** Provenance is presence in code, not equality to a default value. No raw value leaves this function. */
+export function describeConfigSources(snapshot, raw) {
+    const sources = {};
+    const connectorSources = new Map(raw.connectors.map((connector) => [connector.id, factorySources(connector)]));
+    const moduleSources = { accessTokens: factorySources(raw.accessTokens) };
+    const provided = (value) => (value === undefined ? "default" : "config");
+    for (const path of configValuePaths(snapshot)) {
+        const parts = path.split(".").slice(1);
+        const [group, key, field] = parts;
+        let source = "config";
+        if (group === "schemaVersion" || group === "connectaVersion")
+            source = "default";
+        else if (group === "server")
+            source = provided(raw.serverInfo?.[key]);
+        else if (group === "urls")
+            source = key === "mcpPath" ? "default" : provided(raw[key]);
+        else if (group === "trust")
+            source = provided(raw.trust);
+        else if (group === "identity")
+            source = provided(raw.identity?.[key]);
+        else if (group === "storage")
+            source = provided(raw.storage);
+        else if (group === "deploymentInfo")
+            source = provided(raw.deploymentInfo);
+        else if (group === "classification")
+            source = provided(raw.classification);
+        else if (group === "pools")
+            source = field === "trust" ? provided(raw.pools?.[key]?.trust) : provided(raw.pools);
+        else if (group === "modules") {
+            const module = key === "ui" ? raw.ui : key === "vault" ? raw.vault : key === "activity" ? raw.activity : raw.accessTokens;
+            const factory = moduleSources[key];
+            source = (factory ? factorySource(factory, parts.slice(2)) : undefined) ?? provided(module);
+        }
+        else if (group === "branding") {
+            const brand = raw.ui?.branding;
+            const brandKey = key === "faviconHref" ? "favicon" : key;
+            source =
+                key === "theme"
+                    ? provided(brand?.theme?.[field])
+                    : provided(brand?.[brandKey]);
+        }
+        else if (group === "connectors") {
+            const connector = raw.connectors.find((c) => c.id === key);
+            source = factorySource(connectorSources.get(key) ?? {}, parts.slice(2)) ?? source;
+            if (field === "authScope")
+                source = provided(connector?.authScope);
+            else if (field === "maxResultBytes")
+                source = provided(connector?.maxResultBytes ?? raw.calls?.maxResultBytes);
+        }
+        else if (group === "limits" || (group === "executor" && key === "admission")) {
+            let limit = snapshot;
+            for (const part of parts)
+                limit = limit && typeof limit === "object" ? limit[part] : undefined;
+            source =
+                limit && typeof limit === "object" && "source" in limit && limit.source === "default" ? "default" : "config";
+        }
+        sources[path] = source;
+    }
+    return sources;
+}