@vantageos/mcp-boilerplate 0.2.4 → 0.3.0

package/dist/declaredVariables.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Configuration extension point for a server derived from this boilerplate. The derived server
+ * DECLARES the environment variables it reads (name, type, required or optional, default, secret
+ * flag, bilingual description) and receives a typed, validated, frozen configuration object at
+ * start — or ONE refusal naming every missing or invalid variable.
+ *
+ * ```ts
+ * // src/settings.ts — evaluated once per process
+ * import { defineVariables, loadVariables } from "@vantageos/mcp-boilerplate";
+ *
+ * export const declared = defineVariables({
+ *   apiBaseUrl: { env: "UPSTREAM_API_BASE_URL", type: "url", description: { en: "…", fr: "…" } },
+ *   readKey: { env: "LAKE_READ_KEY", type: "string", secret: true, description: { en: "…", fr: "…" } },
+ *   pageSize: { env: "UPSTREAM_PAGE_SIZE", type: "integer", min: 1, max: 500, required: false,
+ *               default: 100, description: { en: "…", fr: "…" } },
+ *   fieldMap: { env: "FIELD_MAPPINGS", type: "json", description: { en: "…", fr: "…" } },
+ * });
+ * export const settings = loadVariables(declared); // throws ConfigurationError, or is fully typed
+ * ```
+ *
+ * The variable names above are examples: the derived server chooses them, nothing here hardcodes one.
+ *
+ * TYPES. The set is derived from the readers `src/envKnobs.ts` already provides — `rawKnob`
+ * (string), `integerKnob` (integer), `flagKnob` (boolean), `originListKnob` (originList) — which
+ * are reused here, not reimplemented, plus the three a derived server reading an upstream API
+ * needs: `url` (an endpoint: https, http on loopback only — the rule of `src/oauth/settings.ts`
+ * and `src/upstream/clientCredentials.ts`), `enum` (a closed set of values) and `json` (an object
+ * or array, e.g. a field-mapping table). `VARIABLE_TYPES` is that list; anything else is refused.
+ *
+ * GUARANTEES.
+ * - Reading: unset or EMPTY is "missing" (the `rawKnob` rule). A required variable that is missing
+ *   and every variable that is set but invalid are collected — ALL of them — before ONE
+ *   `ConfigurationError` is thrown. Its `problems` list `{ key, env, reason, expected }`; its
+ *   message (English / French in one string, like `src/serverManifest.ts`) names each variable
+ *   and the expected form. A VALUE never appears in it, secret or not: a value in a log is a leak
+ *   waiting for the next variable. A set-but-invalid optional variable is refused, never replaced
+ *   by its default (the `envKnobs.ts` rule).
+ * - Result: frozen (lists and json values deeply). The returned object is a Proxy: reading a key
+ *   that was not declared throws, naming it — at runtime as at compile time, where the type is
+ *   inferred from the declaration (required -> value, optional without default -> `| undefined`,
+ *   enum -> union of its literals) and an undeclared key does not compile. Declared divergence:
+ *   symbol keys and `then` read through as `undefined`, so the object can be returned from an
+ *   async function; the serialisation keys of `PROTOCOL_KEYS` read through too (below); no other
+ *   undeclared string key does.
+ * - Serialisation: `JSON.stringify`, `String()`, template literals and `util.inspect` (hence
+ *   `console.log`) never throw and render every declared key, a `secret: true` one as the fixed
+ *   `SECRET_MASK` (never the value, never its length). A declared key named like a protocol key
+ *   wins over it; a secret stays masked or hidden either way.
+ * - Enumeration: a `secret: true` value is NON-enumerable, so `{ ...config }`, `Object.entries`,
+ *   `Object.keys`, `Object.assign` and `for…in` never copy it. A secret is read by name only
+ *   (`config.readKey`); an operator who wants the value asks for it explicitly. Declared
+ *   divergence: an explicit reflective read (`Object.getOwnPropertyDescriptor`, or `util.inspect`
+ *   with `customInspect: false` and `showHidden: true`) is asking by name, and shows it.
+ * - Declaration: `defineVariables` refuses, when it is called, a duplicate env name, an unknown
+ *   type, an unknown property (a typo such as `requried` would otherwise be silently ignored), a
+ *   default that does not itself validate, a default on a required variable (`required` defaults
+ *   to true: a default needs `required: false`), and any field it cannot read. Its errors
+ *   (`VariableDeclarationError`, English: they are programmer errors, raised while the code is
+ *   written) name the key and the env name, never a default value.
+ * - `describeVariables` lists the contract (`--help`, docs) with no value and no default.
+ *
+ * DECLARED DIVERGENCE, NOT DONE HERE: the boilerplate's own readers — `OAUTH_ENV` and
+ * `readAuthorizeSettings` (`src/oauth/settings.ts`), the knobs read through `src/envKnobs.ts`, and
+ * `clientCredentialsFromEnv` (`src/upstream/clientCredentials.ts`) — are candidates to migrate
+ * onto this registry. They are left untouched in this delivery; the https-or-loopback URL rule is
+ * therefore held in three places until that migration.
+ */
+/** Every type a variable can declare. Derived from `envKnobs.ts` readers + url, enum, json. */
+export declare const VARIABLE_TYPES: readonly ["string", "integer", "boolean", "url", "originList", "enum", "json"];
+export type VariableType = (typeof VARIABLE_TYPES)[number];
+export interface BilingualText {
+    readonly en: string;
+    readonly fr: string;
+}
+/** A parsed `json` value: an object or an array, frozen. */
+export type JsonContainer = {
+    readonly [key: string]: unknown;
+} | readonly unknown[];
+interface VariableBase {
+    /** The environment variable name, e.g. `UPSTREAM_API_BASE_URL`. Unique within one declaration. */
+    readonly env: string;
+    /** Default true. A variable with a `default` must say `required: false`. */
+    readonly required?: boolean;
+    /**
+     * Marks a credential. It is masked when the configuration is serialised, non-enumerable (spread
+     * and `Object.entries` skip it, read it by name), and flagged by `describeVariables`.
+     */
+    readonly secret?: boolean;
+    readonly description: BilingualText;
+}
+export interface StringVariable extends VariableBase {
+    readonly type: "string";
+    readonly default?: string;
+}
+export interface IntegerVariable extends VariableBase {
+    readonly type: "integer";
+    /** Default 0. Non-negative: the `integerKnob` reader accepts digits only. */
+    readonly min?: number;
+    readonly max?: number;
+    readonly default?: number;
+}
+/** Exactly "0" or "1" in the environment (the `flagKnob` rule). */
+export interface BooleanVariable extends VariableBase {
+    readonly type: "boolean";
+    readonly default?: boolean;
+}
+/** https, or http on a loopback host only. */
+export interface UrlVariable extends VariableBase {
+    readonly type: "url";
+    readonly default?: string;
+}
+/** Comma-separated origins (the `originListKnob` rule). */
+export interface OriginListVariable extends VariableBase {
+    readonly type: "originList";
+    readonly default?: readonly string[];
+}
+export interface EnumVariable extends VariableBase {
+    readonly type: "enum";
+    readonly values: readonly string[];
+    readonly default?: string;
+}
+/** A JSON document whose top level is an object or an array. */
+export interface JsonVariable extends VariableBase {
+    readonly type: "json";
+    readonly default?: JsonContainer;
+}
+export type VariableSpec = StringVariable | IntegerVariable | BooleanVariable | UrlVariable | OriginListVariable | EnumVariable | JsonVariable;
+export type VariablesSpec = {
+    readonly [key: string]: VariableSpec;
+};
+type ValueOf<V> = V extends {
+    type: "string" | "url";
+} ? string : V extends {
+    type: "integer";
+} ? number : V extends {
+    type: "boolean";
+} ? boolean : V extends {
+    type: "originList";
+} ? readonly string[] : V extends {
+    type: "enum";
+    values: readonly (infer E)[];
+} ? E : V extends {
+    type: "json";
+} ? JsonContainer : never;
+type Resolved<V> = V extends {
+    required: false;
+} ? V extends {
+    default: unknown;
+} ? ValueOf<V> : ValueOf<V> | undefined : ValueOf<V>;
+/** The configuration object inferred from a declaration. Read-only; undeclared keys do not exist. */
+export type VariablesOf<S extends VariablesSpec> = {
+    readonly [K in keyof S]: Resolved<S[K]>;
+};
+/** A declaration validated by `defineVariables`. Only such a value is accepted by the readers. */
+export interface DeclaredVariables<S extends VariablesSpec> {
+    readonly spec: S;
+}
+export type ProblemReason = "missing" | "invalid";
+export interface ConfigurationProblem {
+    /** The logical key in the declaration. */
+    readonly key: string;
+    /** The environment variable name. */
+    readonly env: string;
+    readonly reason: ProblemReason;
+    readonly expected: VariableType;
+}
+export interface VariableDescription {
+    readonly key: string;
+    readonly env: string;
+    readonly type: VariableType;
+    readonly required: boolean;
+    readonly secret: boolean;
+    readonly hasDefault: boolean;
+    readonly description: BilingualText;
+}
+/** A broken declaration, raised by `defineVariables`. Names the key and env, never a default. */
+export declare class VariableDeclarationError extends Error {
+    constructor(message: string);
+}
+/**
+ * The environment does not satisfy the declaration. `problems` lists every one of them; the
+ * message (built by `loadVariables`) names each variable and its expected form. No value, ever.
+ */
+export declare class ConfigurationError extends Error {
+    readonly problems: readonly ConfigurationProblem[];
+    constructor(message: string, problems: readonly ConfigurationProblem[]);
+}
+/**
+ * https, or http on a loopback host. Same rule as `src/oauth/settings.ts` (`originOf`). Exported
+ * for the package's own modules (src/lake/convex.ts), not from the package root.
+ */
+export declare function isSecureUrl(raw: string): boolean;
+/**
+ * Validates a declaration and returns it, typed. Throws `VariableDeclarationError` on anything it
+ * cannot read: a broken declaration fails here, not silently when the environment is read.
+ */
+export declare function defineVariables<const S extends VariablesSpec>(spec: S): DeclaredVariables<S>;
+/**
+ * Reads every declared variable from `env`. Returns the frozen, typed configuration, or throws ONE
+ * `ConfigurationError` listing every missing or invalid variable — names and expected types only.
+ */
+export declare function loadVariables<S extends VariablesSpec>(declared: DeclaredVariables<S>, env?: NodeJS.ProcessEnv): VariablesOf<S>;
+/** The configuration contract, for `--help` or documentation. Carries no value and no default. */
+export declare function describeVariables<S extends VariablesSpec>(declared: DeclaredVariables<S>): readonly VariableDescription[];
+export {};

package/dist/declaredVariables.js

@@ -0,0 +1,451 @@
+/**
+ * Configuration extension point for a server derived from this boilerplate. The derived server
+ * DECLARES the environment variables it reads (name, type, required or optional, default, secret
+ * flag, bilingual description) and receives a typed, validated, frozen configuration object at
+ * start — or ONE refusal naming every missing or invalid variable.
+ *
+ * ```ts
+ * // src/settings.ts — evaluated once per process
+ * import { defineVariables, loadVariables } from "@vantageos/mcp-boilerplate";
+ *
+ * export const declared = defineVariables({
+ *   apiBaseUrl: { env: "UPSTREAM_API_BASE_URL", type: "url", description: { en: "…", fr: "…" } },
+ *   readKey: { env: "LAKE_READ_KEY", type: "string", secret: true, description: { en: "…", fr: "…" } },
+ *   pageSize: { env: "UPSTREAM_PAGE_SIZE", type: "integer", min: 1, max: 500, required: false,
+ *               default: 100, description: { en: "…", fr: "…" } },
+ *   fieldMap: { env: "FIELD_MAPPINGS", type: "json", description: { en: "…", fr: "…" } },
+ * });
+ * export const settings = loadVariables(declared); // throws ConfigurationError, or is fully typed
+ * ```
+ *
+ * The variable names above are examples: the derived server chooses them, nothing here hardcodes one.
+ *
+ * TYPES. The set is derived from the readers `src/envKnobs.ts` already provides — `rawKnob`
+ * (string), `integerKnob` (integer), `flagKnob` (boolean), `originListKnob` (originList) — which
+ * are reused here, not reimplemented, plus the three a derived server reading an upstream API
+ * needs: `url` (an endpoint: https, http on loopback only — the rule of `src/oauth/settings.ts`
+ * and `src/upstream/clientCredentials.ts`), `enum` (a closed set of values) and `json` (an object
+ * or array, e.g. a field-mapping table). `VARIABLE_TYPES` is that list; anything else is refused.
+ *
+ * GUARANTEES.
+ * - Reading: unset or EMPTY is "missing" (the `rawKnob` rule). A required variable that is missing
+ *   and every variable that is set but invalid are collected — ALL of them — before ONE
+ *   `ConfigurationError` is thrown. Its `problems` list `{ key, env, reason, expected }`; its
+ *   message (English / French in one string, like `src/serverManifest.ts`) names each variable
+ *   and the expected form. A VALUE never appears in it, secret or not: a value in a log is a leak
+ *   waiting for the next variable. A set-but-invalid optional variable is refused, never replaced
+ *   by its default (the `envKnobs.ts` rule).
+ * - Result: frozen (lists and json values deeply). The returned object is a Proxy: reading a key
+ *   that was not declared throws, naming it — at runtime as at compile time, where the type is
+ *   inferred from the declaration (required -> value, optional without default -> `| undefined`,
+ *   enum -> union of its literals) and an undeclared key does not compile. Declared divergence:
+ *   symbol keys and `then` read through as `undefined`, so the object can be returned from an
+ *   async function; the serialisation keys of `PROTOCOL_KEYS` read through too (below); no other
+ *   undeclared string key does.
+ * - Serialisation: `JSON.stringify`, `String()`, template literals and `util.inspect` (hence
+ *   `console.log`) never throw and render every declared key, a `secret: true` one as the fixed
+ *   `SECRET_MASK` (never the value, never its length). A declared key named like a protocol key
+ *   wins over it; a secret stays masked or hidden either way.
+ * - Enumeration: a `secret: true` value is NON-enumerable, so `{ ...config }`, `Object.entries`,
+ *   `Object.keys`, `Object.assign` and `for…in` never copy it. A secret is read by name only
+ *   (`config.readKey`); an operator who wants the value asks for it explicitly. Declared
+ *   divergence: an explicit reflective read (`Object.getOwnPropertyDescriptor`, or `util.inspect`
+ *   with `customInspect: false` and `showHidden: true`) is asking by name, and shows it.
+ * - Declaration: `defineVariables` refuses, when it is called, a duplicate env name, an unknown
+ *   type, an unknown property (a typo such as `requried` would otherwise be silently ignored), a
+ *   default that does not itself validate, a default on a required variable (`required` defaults
+ *   to true: a default needs `required: false`), and any field it cannot read. Its errors
+ *   (`VariableDeclarationError`, English: they are programmer errors, raised while the code is
+ *   written) name the key and the env name, never a default value.
+ * - `describeVariables` lists the contract (`--help`, docs) with no value and no default.
+ *
+ * DECLARED DIVERGENCE, NOT DONE HERE: the boilerplate's own readers — `OAUTH_ENV` and
+ * `readAuthorizeSettings` (`src/oauth/settings.ts`), the knobs read through `src/envKnobs.ts`, and
+ * `clientCredentialsFromEnv` (`src/upstream/clientCredentials.ts`) — are candidates to migrate
+ * onto this registry. They are left untouched in this delivery; the https-or-loopback URL rule is
+ * therefore held in three places until that migration.
+ */
+import { flagKnob, integerKnob, originListKnob, rawKnob } from "./envKnobs.js";
+import { t } from "./i18n.js";
+/** Every type a variable can declare. Derived from `envKnobs.ts` readers + url, enum, json. */
+export const VARIABLE_TYPES = [
+    "string",
+    "integer",
+    "boolean",
+    "url",
+    "originList",
+    "enum",
+    "json",
+];
+/** A broken declaration, raised by `defineVariables`. Names the key and env, never a default. */
+export class VariableDeclarationError extends Error {
+    constructor(message) {
+        super(`declared variables: ${message}`);
+        this.name = "VariableDeclarationError";
+    }
+}
+/**
+ * The environment does not satisfy the declaration. `problems` lists every one of them; the
+ * message (built by `loadVariables`) names each variable and its expected form. No value, ever.
+ */
+export class ConfigurationError extends Error {
+    problems;
+    constructor(message, problems) {
+        super(message);
+        this.name = "ConfigurationError";
+        this.problems = Object.freeze(problems.map((p) => Object.freeze({ ...p })));
+    }
+}
+/** Declarations that passed `defineVariables`, with their normalized entries. */
+const REGISTRIES = new WeakMap();
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const COMMON_PROPERTIES = ["env", "type", "required", "secret", "description", "default"];
+const TYPE_PROPERTIES = {
+    string: [],
+    integer: ["min", "max"],
+    boolean: [],
+    url: [],
+    originList: [],
+    enum: ["values"],
+    json: [],
+};
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** Stands for a `secret: true` value in every rendering. Fixed: never the value, nor its length. */
+const SECRET_MASK = "[secret]";
+/** Node's `util.inspect.custom`: a registered symbol, so `node:util` need not be imported. */
+const INSPECT_CUSTOM = Symbol.for("nodejs.util.inspect.custom");
+/**
+ * The undeclared keys the language and Node read on their own to serialise an object, allowed
+ * through the undeclared-read trap and answered with the masked form. Where each comes from:
+ * - `toJSON`: read by `JSON.stringify` (SerializeJSONProperty).
+ * - `Symbol.toPrimitive`: read first by `String(config)`, template literals and `"" + config`
+ *   (ToPrimitive). Since it is defined, ToPrimitive never falls back to `toString` / `valueOf`.
+ * - `toString`: an explicit `config.toString()` call.
+ * - `nodejs.util.inspect.custom`: read by `util.inspect`, hence `console.log`. Node reads it on the
+ *   proxy TARGET, not through the trap, so it lives on the target's prototype like the others.
+ */
+const PROTOCOL_KEYS = new Set([
+    "toJSON",
+    Symbol.toPrimitive,
+    "toString",
+    INSPECT_CUSTOM,
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isVariableType(value) {
+    return typeof value === "string" && VARIABLE_TYPES.includes(value);
+}
+/**
+ * https, or http on a loopback host. Same rule as `src/oauth/settings.ts` (`originOf`). Exported
+ * for the package's own modules (src/lake/convex.ts), not from the package root.
+ */
+export function isSecureUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (url.protocol === "https:")
+            return true;
+        return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function isJsonContainer(value) {
+    return typeof value === "object" && value !== null;
+}
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/**
+ * Parses one SET (non-empty) raw value. Returns `{ ok: false }` when it is invalid; the envKnobs
+ * readers signal invalid by throwing, and their message is dropped here (the problem list carries
+ * the name and the expected type; a reader message is never forwarded).
+ */
+function parse(entry, raw) {
+    const env = { [entry.env]: raw };
+    try {
+        switch (entry.type) {
+            case "string":
+                return { ok: true, value: raw };
+            case "integer":
+                return { ok: true, value: integerKnob(env, entry.env, entry.min, entry.max) };
+            case "boolean":
+                return { ok: true, value: flagKnob(env, entry.env) };
+            case "url":
+                return isSecureUrl(raw) ? { ok: true, value: raw } : { ok: false };
+            case "originList":
+                return { ok: true, value: Object.freeze(originListKnob(env, entry.env)) };
+            case "enum":
+                return entry.values.includes(raw) ? { ok: true, value: raw } : { ok: false };
+            case "json": {
+                const value = JSON.parse(raw);
+                return isJsonContainer(value) ? { ok: true, value: deepFreeze(value) } : { ok: false };
+            }
+        }
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** Validates a declared default against the same rules as a value read from the environment. */
+function defaultIsValid(entry, value) {
+    switch (entry.type) {
+        case "string":
+        case "url":
+        case "enum":
+            return typeof value === "string" && value !== "" && parse(entry, value).ok;
+        case "integer":
+            return typeof value === "number" && parse(entry, String(value)).ok;
+        case "boolean":
+            return typeof value === "boolean";
+        case "originList": {
+            if (!Array.isArray(value) || !value.every((o) => typeof o === "string"))
+                return false;
+            if (value.length === 0)
+                return true;
+            const read = parse(entry, value.join(","));
+            return (read.ok &&
+                Array.isArray(read.value) &&
+                read.value.length === value.length &&
+                read.value.every((o, i) => o === value[i]));
+        }
+        case "json":
+            return isJsonContainer(value);
+    }
+}
+function normalize(key, raw) {
+    if (!isRecord(raw))
+        throw new VariableDeclarationError(`"${key}" is not an object`);
+    const { env } = raw;
+    if (typeof env !== "string" || !ENV_NAME.test(env)) {
+        throw new VariableDeclarationError(`"${key}": env must be an environment variable name ([A-Za-z_][A-Za-z0-9_]*)`);
+    }
+    const where = `"${key}" (${env})`;
+    const { type } = raw;
+    if (!isVariableType(type)) {
+        throw new VariableDeclarationError(`${where}: unknown type; expected one of ${VARIABLE_TYPES.join(", ")}`);
+    }
+    const allowed = new Set([...COMMON_PROPERTIES, ...TYPE_PROPERTIES[type]]);
+    for (const property of Object.keys(raw)) {
+        if (!allowed.has(property)) {
+            throw new VariableDeclarationError(`${where}: unknown property "${property}" for type ${type}`);
+        }
+    }
+    if (raw.required !== undefined && typeof raw.required !== "boolean") {
+        throw new VariableDeclarationError(`${where}: required must be a boolean`);
+    }
+    if (raw.secret !== undefined && typeof raw.secret !== "boolean") {
+        throw new VariableDeclarationError(`${where}: secret must be a boolean`);
+    }
+    const en = isRecord(raw.description) ? raw.description.en : undefined;
+    const fr = isRecord(raw.description) ? raw.description.fr : undefined;
+    if (typeof en !== "string" || en === "" || typeof fr !== "string" || fr === "") {
+        throw new VariableDeclarationError(`${where}: description must carry non-empty "en" and "fr" strings`);
+    }
+    let min = 0;
+    let max = Number.MAX_SAFE_INTEGER;
+    if (type === "integer") {
+        if (raw.min !== undefined) {
+            if (!Number.isSafeInteger(raw.min) || raw.min < 0) {
+                throw new VariableDeclarationError(`${where}: min must be a non-negative integer`);
+            }
+            min = raw.min;
+        }
+        if (raw.max !== undefined) {
+            if (!Number.isSafeInteger(raw.max) || raw.max < 0) {
+                throw new VariableDeclarationError(`${where}: max must be a non-negative integer`);
+            }
+            max = raw.max;
+        }
+        if (min > max)
+            throw new VariableDeclarationError(`${where}: min is greater than max`);
+    }
+    let values = [];
+    if (type === "enum") {
+        const declared = raw.values;
+        if (!Array.isArray(declared) ||
+            declared.length === 0 ||
+            !declared.every((v) => typeof v === "string" && v !== "") ||
+            new Set(declared).size !== declared.length) {
+            throw new VariableDeclarationError(`${where}: values must be a non-empty list of distinct non-empty strings`);
+        }
+        values = Object.freeze([...declared]);
+    }
+    const required = raw.required ?? true;
+    const hasDefault = raw.default !== undefined;
+    const entry = {
+        key,
+        env,
+        type,
+        required: required,
+        secret: (raw.secret ?? false),
+        hasDefault,
+        default: undefined,
+        min,
+        max,
+        values,
+        description: Object.freeze({ en, fr }),
+    };
+    if (hasDefault && entry.required) {
+        throw new VariableDeclarationError(`${where}: a default is declared on a required variable; set required: false (required defaults to true)`);
+    }
+    if (hasDefault && !defaultIsValid(entry, raw.default)) {
+        throw new VariableDeclarationError(`${where}: the default does not validate as ${type} (value not shown)`);
+    }
+    return Object.freeze({
+        ...entry,
+        default: hasDefault ? deepFreeze(structuredClone(raw.default)) : undefined,
+    });
+}
+/**
+ * Validates a declaration and returns it, typed. Throws `VariableDeclarationError` on anything it
+ * cannot read: a broken declaration fails here, not silently when the environment is read.
+ */
+export function defineVariables(spec) {
+    if (!isRecord(spec))
+        throw new VariableDeclarationError("the declaration is not an object");
+    const entries = [];
+    const byKey = new Map();
+    const keyByEnv = new Map();
+    for (const [key, raw] of Object.entries(spec)) {
+        const entry = normalize(key, raw);
+        const previous = keyByEnv.get(entry.env);
+        if (previous !== undefined) {
+            throw new VariableDeclarationError(`${entry.env} is declared twice, by "${previous}" and by "${key}"`);
+        }
+        keyByEnv.set(entry.env, key);
+        entries.push(entry);
+        byKey.set(key, entry);
+    }
+    const declared = Object.freeze({ spec });
+    REGISTRIES.set(declared, { entries: Object.freeze(entries), byKey });
+    return declared;
+}
+function registryOf(declared) {
+    const registry = typeof declared === "object" && declared !== null ? REGISTRIES.get(declared) : undefined;
+    if (!registry) {
+        throw new VariableDeclarationError("not a declaration produced by defineVariables (refused: it was never validated)");
+    }
+    return registry;
+}
+/**
+ * Reads every declared variable from `env`. Returns the frozen, typed configuration, or throws ONE
+ * `ConfigurationError` listing every missing or invalid variable — names and expected types only.
+ */
+export function loadVariables(declared, env = process.env) {
+    const registry = registryOf(declared);
+    const problems = [];
+    const values = {};
+    for (const entry of registry.entries) {
+        const raw = rawKnob(env, entry.env);
+        if (raw === undefined) {
+            if (entry.required) {
+                problems.push({ key: entry.key, env: entry.env, reason: "missing", expected: entry.type });
+            }
+            else {
+                values[entry.key] = entry.default;
+            }
+            continue;
+        }
+        const read = parse(entry, raw);
+        if (read.ok) {
+            values[entry.key] = read.value;
+        }
+        else {
+            problems.push({ key: entry.key, env: entry.env, reason: "invalid", expected: entry.type });
+        }
+    }
+    if (problems.length > 0) {
+        throw new ConfigurationError(refusalMessage(problems, registry.byKey), problems);
+    }
+    // The masked view: every declared key, a secret replaced by SECRET_MASK. A fresh plain object.
+    const masked = () => {
+        const view = {};
+        for (const entry of registry.entries) {
+            view[entry.key] = entry.secret ? SECRET_MASK : values[entry.key];
+        }
+        return view;
+    };
+    const rendered = () => JSON.stringify(masked());
+    // Non-enumerable, read-only: `for…in` and spread never see them.
+    const protocol = Object.freeze(Object.create(Object.prototype, {
+        toJSON: { value: masked },
+        [Symbol.toPrimitive]: { value: rendered },
+        toString: { value: rendered },
+        [INSPECT_CUSTOM]: { value: masked },
+    }));
+    // A secret is non-enumerable: readable by name, never copied by spread or Object.entries.
+    const frozen = Object.create(protocol);
+    for (const entry of registry.entries) {
+        Object.defineProperty(frozen, entry.key, {
+            value: values[entry.key],
+            enumerable: !entry.secret,
+            writable: false,
+            configurable: false,
+        });
+    }
+    return new Proxy(Object.freeze(frozen), {
+        get(target, property, receiver) {
+            if (PROTOCOL_KEYS.has(property) ||
+                typeof property === "symbol" ||
+                property === "then" ||
+                registry.byKey.has(property)) {
+                return Reflect.get(target, property, receiver);
+            }
+            throw new TypeError(`configuration: "${property}" is not a declared variable (declared: ${[...registry.byKey.keys()].join(", ")})`);
+        },
+    });
+}
+/** The configuration contract, for `--help` or documentation. Carries no value and no default. */
+export function describeVariables(declared) {
+    return Object.freeze(registryOf(declared).entries.map((entry) => Object.freeze({
+        key: entry.key,
+        env: entry.env,
+        type: entry.type,
+        required: entry.required,
+        secret: entry.secret,
+        hasDefault: entry.hasDefault,
+        description: entry.description,
+    })));
+}
+/** `{name}` placeholders filled literally (a function replacer: no `$` pattern is interpreted). */
+function fill(text, params) {
+    return Object.entries(params).reduce((out, [name, value]) => out.replaceAll(`{${name}}`, () => value), text);
+}
+/** The expected form of a variable, in one language. Declaration content only, never a value. */
+function expectedText(locale, entry) {
+    switch (entry.type) {
+        case "integer":
+            return entry.max === Number.MAX_SAFE_INTEGER
+                ? fill(t(locale, "config.expect.integerAtLeast"), { min: String(entry.min) })
+                : fill(t(locale, "config.expect.integer"), {
+                    min: String(entry.min),
+                    max: String(entry.max),
+                });
+        case "enum":
+            return fill(t(locale, "config.expect.enum"), { values: entry.values.join(", ") });
+        default:
+            return t(locale, `config.expect.${entry.type}`);
+    }
+}
+/**
+ * The refusal, English / French in one string as `tBoth` renders it (a start-time failure has no
+ * caller locale). Built from names and declaration content only: `problems` carries no value.
+ */
+function refusalMessage(problems, byKey) {
+    const render = (locale) => fill(t(locale, "config.refused"), {
+        problems: problems
+            .map((p) => fill(t(locale, `config.${p.reason}`), {
+            env: p.env,
+            expected: expectedText(locale, byKey.get(p.key)),
+        }))
+            .join("; "),
+    });
+    return `${render("en")} / ${render("fr")}`;
+}

package/dist/exampleItems.d.ts

@@ -3,6 +3,8 @@
  * stored `orgId` of the organisation that owns it — the row is selected by comparing that
  * stored id with the caller's verified organisation (tenancy.ts `isRowInTenant`), never by
  * a creator name. `createdBy` / `namespace` stay as display fields only.
+ *
+ * The collection is keyed by `id` and kept sorted by it (the `list_items` range reads rely on it).
  */
 export interface ExampleItem {
     id: string;
@@ -12,3 +14,16 @@ export interface ExampleItem {
     namespace: string;
 }
 export declare const EXAMPLE_ITEMS: ExampleItem[];
+/**
+ * The rows strictly after `afterKey` (all rows when it is undefined), at most `limit` of them,
+ * from a collection SORTED by `id`: a binary search for the first key above `afterKey`, then a
+ * slice of the page. That is the `indexed-range` mechanism the list tools declare
+ * (src/toolRecord.ts): the cost follows the page, not the collection. It requires sorted input;
+ * `EXAMPLE_ITEMS` is sorted above and scoping by tenant (a filter) preserves the order.
+ *
+ * In this in-memory seed the tenant scoping that precedes it is a filter over the rows. A fork
+ * backed by a store reads the same range from a compound (orgId, id) index instead.
+ */
+export declare function rangeAfter<T extends {
+    id: string;
+}>(sortedRows: readonly T[], afterKey: string | undefined, limit?: number): T[];