@mccaskie-labs/workbench-config 0.0.0-stage → 0.1.1

package/dist/capability-schema.d.ts

@@ -0,0 +1,193 @@
+import { z } from "zod";
+export declare const COMPONENTS: readonly ["gateway", "ai", "images", "image-search", "config", "email", "email-inbound", "email-sending", "database", "workers", "domains", "dns", "analytics", "access", "r2", "kv", "github"];
+export type Component = (typeof COMPONENTS)[number];
+export declare const allowedSchemas: {
+    gateway: z.ZodObject<{
+        scopes: z.ZodArray<z.ZodEnum<{
+            ai: "ai";
+            email: "email";
+            images: "images";
+            search: "search";
+        }>>;
+        key_environments: z.ZodArray<z.ZodObject<{
+            environment: z.ZodEnum<{
+                development: "development";
+                production: "production";
+                staging: "staging";
+            }>;
+            prefix: z.ZodString;
+        }, z.core.$strict>>;
+        request_headers: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            required: z.ZodBoolean;
+            pattern: z.ZodOptional<z.ZodString>;
+            description: z.ZodString;
+        }, z.core.$strict>>;
+        response_headers: z.ZodArray<z.ZodString>;
+        server_timing_metrics: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    ai: z.ZodObject<{
+        aliases: z.ZodArray<z.ZodObject<{
+            alias: z.ZodString;
+            provider: z.ZodEnum<{
+                anthropic: "anthropic";
+                google: "google";
+                openai: "openai";
+            }>;
+            default_model: z.ZodString;
+        }, z.core.$strict>>;
+        explicit_models: z.ZodArray<z.ZodString>;
+        server_tools: z.ZodArray<z.ZodString>;
+        required_headers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    config: z.ZodObject<{
+        environments: z.ZodArray<z.ZodEnum<{
+            development: "development";
+            production: "production";
+            staging: "staging";
+        }>>;
+    }, z.core.$strict>;
+};
+/** One file in `capabilities/`. Parsing checks shape only; cross-references are checked by `checkManifests`. */
+export declare const capabilitySchema: z.ZodObject<{
+    $schema: z.ZodLiteral<"./schema.json">;
+    format: z.ZodLiteral<1>;
+    component: z.ZodEnum<{
+        access: "access";
+        ai: "ai";
+        analytics: "analytics";
+        config: "config";
+        database: "database";
+        dns: "dns";
+        domains: "domains";
+        email: "email";
+        "email-inbound": "email-inbound";
+        "email-sending": "email-sending";
+        gateway: "gateway";
+        github: "github";
+        "image-search": "image-search";
+        images: "images";
+        kv: "kv";
+        r2: "r2";
+        workers: "workers";
+    }>;
+    title: z.ZodString;
+    summary: z.ZodString;
+    status: z.ZodEnum<{
+        built: "built";
+        deprecated: "deprecated";
+        planned: "planned";
+    }>;
+    surfaces: z.ZodObject<{
+        gateway: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        package: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    config: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        required: z.ZodBoolean;
+        secret: z.ZodBoolean;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        environments: z.ZodArray<z.ZodEnum<{
+            development: "development";
+            production: "production";
+            staging: "staging";
+        }>>;
+        description: z.ZodString;
+    }, z.core.$strict>>>;
+    allowed: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    limits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        unit: z.ZodString;
+        per: z.ZodString;
+        enforced_by: z.ZodEnum<{
+            control: "control";
+            database: "database";
+            gateway: "gateway";
+            types: "types";
+        }>;
+        refusal: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        gate: z.ZodEnum<{
+            free: "free";
+            two_step: "two_step";
+            two_step_on_production: "two_step_on_production";
+            two_step_when: "two_step_when";
+        }>;
+        when: z.ZodOptional<z.ZodString>;
+        ships: z.ZodEnum<{
+            3: "3";
+            4: "4";
+            later: "later";
+        }>;
+    }, z.core.$strict>>>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        http: z.ZodNumber;
+        retryable: z.ZodBoolean;
+        meaning: z.ZodString;
+    }, z.core.$strict>>>;
+    rules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            must: "must";
+            must_not: "must_not";
+        }>;
+        text: z.ZodString;
+        enforced_by: z.ZodEnum<{
+            control: "control";
+            database: "database";
+            gateway: "gateway";
+            review: "review";
+            types: "types";
+        }>;
+        probe: z.ZodString;
+    }, z.core.$strict>>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        lang: z.ZodEnum<{
+            js: "js";
+            json: "json";
+            ps1: "ps1";
+            sh: "sh";
+            sql: "sql";
+            ts: "ts";
+        }>;
+        code: z.ZodString;
+        probe: z.ZodString;
+    }, z.core.$strict>>>;
+    probes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        half: z.ZodEnum<{
+            drill: "drill";
+            runtime: "runtime";
+        }>;
+        expect: z.ZodEnum<{
+            pass: "pass";
+            refused_as_expected: "refused_as_expected";
+        }>;
+        refusal: z.ZodOptional<z.ZodString>;
+        smoke: z.ZodOptional<z.ZodBoolean>;
+        cost_hint_usd: z.ZodOptional<z.ZodNumber>;
+        two_step: z.ZodOptional<z.ZodBoolean>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Capability = z.infer<typeof capabilitySchema>;
+export interface ManifestProblem {
+    file: string;
+    check: "schema" | "proof" | "ids" | "surfaces" | "errors" | "generated";
+    message: string;
+}
+/**
+ * The checks that need only the manifests themselves (§5: schema, proof, ids).
+ * `files` maps a file name (e.g. `ai.json`) to its parsed JSON.
+ */
+export declare function checkManifests(files: Record<string, unknown>): {
+    manifests: Capability[];
+    problems: ManifestProblem[];
+};

package/dist/capability-schema.js

@@ -0,0 +1,217 @@
+// The capabilities manifest schema (docs/capabilities-manifest.md §3). One
+// parser shared by the packages, the Gateway, Control and the checks.
+// capabilities/schema.json is generated from it by `npm run capabilities:build`.
+import { z } from "zod";
+export const COMPONENTS = [
+    "gateway",
+    "ai",
+    "images",
+    "image-search",
+    "config",
+    "email",
+    "email-inbound",
+    "email-sending",
+    "database",
+    "workers",
+    "domains",
+    "dns",
+    "analytics",
+    "access",
+    "r2",
+    "kv",
+    "github",
+];
+const id = z.string().regex(/^[a-z0-9][a-z0-9.-]*$/, "lower case, digits, dots and hyphens");
+const code = z.string().regex(/^[a-z][a-z0-9_]*$/, "a snake_case error code");
+const envName = z.enum(["development", "staging", "production"]);
+const enforcedBy = z.enum(["types", "gateway", "control", "database", "review"]);
+const configVariable = z.strictObject({
+    name: z.string().regex(/^[A-Z][A-Z0-9_]*$/, "an UPPER_SNAKE variable name"),
+    required: z.boolean(),
+    secret: z.boolean(),
+    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+    environments: z.array(envName).min(1),
+    description: z.string().min(1),
+});
+const limit = z.strictObject({
+    id,
+    value: z.union([z.string(), z.number()]),
+    unit: z.string().min(1),
+    per: z.string().min(1),
+    enforced_by: enforcedBy.exclude(["review"]),
+    refusal: code.optional(),
+});
+const action = z.strictObject({
+    tool: z.string().regex(/^[a-z]+_[a-z0-9_]+$/),
+    gate: z.enum(["free", "two_step", "two_step_on_production", "two_step_when"]),
+    when: z.string().min(1).optional(),
+    ships: z.enum(["3", "4", "later"]),
+});
+const errorEntry = z.strictObject({
+    code,
+    http: z.number().int().min(400).max(599),
+    retryable: z.boolean(),
+    meaning: z.string().min(1),
+});
+const rule = z.strictObject({
+    id,
+    kind: z.enum(["must", "must_not"]),
+    text: z.string().min(1),
+    enforced_by: enforcedBy,
+    probe: id,
+});
+const example = z.strictObject({
+    id,
+    title: z.string().min(1),
+    lang: z.enum(["ts", "js", "sh", "ps1", "json", "sql"]),
+    code: z.string().min(1),
+    probe: id,
+});
+const probe = z.strictObject({
+    id,
+    half: z.enum(["runtime", "drill"]),
+    expect: z.enum(["pass", "refused_as_expected"]),
+    refusal: code.optional(),
+    smoke: z.boolean().optional(),
+    cost_hint_usd: z.number().min(0).optional(),
+    two_step: z.boolean().optional(),
+    note: z.string().min(1).optional(),
+});
+// `allowed` is typed per component (§3, §4). A component with no schema here
+// can't carry an `allowed` section until one is added.
+const aliasEntry = z.strictObject({
+    alias: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    provider: z.enum(["anthropic", "google", "openai"]),
+    default_model: z.string().min(1),
+});
+export const allowedSchemas = {
+    gateway: z.strictObject({
+        scopes: z.array(z.enum(["ai", "images", "search", "email"])).min(1),
+        key_environments: z.array(z.strictObject({ environment: envName, prefix: z.string().regex(/^wbk_[a-z]{3}_$/) })).min(1),
+        request_headers: z
+            .array(z.strictObject({ name: z.string().min(1), required: z.boolean(), pattern: z.string().optional(), description: z.string().min(1) }))
+            .min(1),
+        response_headers: z.array(z.string().min(1)).min(1),
+        server_timing_metrics: z.array(z.string().regex(/^[a-z_]+$/)).min(1),
+    }),
+    ai: z.strictObject({
+        aliases: z.array(aliasEntry).min(1),
+        explicit_models: z.array(z.string().min(1)),
+        server_tools: z.array(z.string().min(1)),
+        required_headers: z.array(z.string().min(1)),
+    }),
+    config: z.strictObject({
+        environments: z.array(envName).min(1),
+    }),
+};
+const baseShape = {
+    $schema: z.literal("./schema.json"),
+    format: z.literal(1),
+    component: z.enum(COMPONENTS),
+    title: z.string().min(1),
+    summary: z.string().min(1),
+    status: z.enum(["planned", "built", "deprecated"]),
+    surfaces: z
+        .strictObject({
+        gateway: z.array(z.string().regex(/^(GET|POST|PUT|PATCH|DELETE) \/\S*$/)).min(1).optional(),
+        tools: z.array(z.string().regex(/^[a-z]+_[a-z0-9_]+$/)).min(1).optional(),
+        package: z.array(z.string().min(1)).min(1).optional(),
+    })
+        .refine((s) => s.gateway || s.tools || s.package, "name at least one surface"),
+    config: z.array(configVariable).min(1).optional(),
+    allowed: z.record(z.string(), z.unknown()).optional(),
+    limits: z.array(limit).min(1).optional(),
+    actions: z.array(action).min(1).optional(),
+    errors: z.array(errorEntry).min(1).optional(),
+    rules: z.array(rule).min(1),
+    examples: z.array(example).min(1).optional(),
+    probes: z.array(probe).min(1),
+};
+/** One file in `capabilities/`. Parsing checks shape only; cross-references are checked by `checkManifests`. */
+export const capabilitySchema = z.strictObject(baseShape).superRefine((m, ctx) => {
+    if (m.allowed === undefined)
+        return;
+    const schema = allowedSchemas[m.component];
+    if (!schema) {
+        ctx.addIssue({ code: "custom", path: ["allowed"], message: `component ${m.component} has no allowed schema yet` });
+        return;
+    }
+    const result = schema.safeParse(m.allowed);
+    if (!result.success) {
+        for (const issue of result.error.issues) {
+            ctx.addIssue({ code: "custom", path: ["allowed", ...issue.path.map((p) => (typeof p === "symbol" ? String(p) : p))], message: issue.message });
+        }
+    }
+});
+/**
+ * The checks that need only the manifests themselves (§5: schema, proof, ids).
+ * `files` maps a file name (e.g. `ai.json`) to its parsed JSON.
+ */
+export function checkManifests(files) {
+    const problems = [];
+    const manifests = [];
+    const globalIds = new Map();
+    for (const [file, json] of Object.entries(files)) {
+        const parsed = capabilitySchema.safeParse(json);
+        if (!parsed.success) {
+            for (const issue of parsed.error.issues) {
+                problems.push({ file, check: "schema", message: `${issue.path.join(".") || "(root)"}: ${issue.message}` });
+            }
+            continue;
+        }
+        const m = parsed.data;
+        manifests.push(m);
+        if (file !== `${m.component}.json`) {
+            problems.push({ file, check: "schema", message: `file name must be ${m.component}.json` });
+        }
+        const probeIds = new Set();
+        const seen = (kind, value) => {
+            const prior = globalIds.get(value);
+            if (prior)
+                problems.push({ file, check: "ids", message: `${kind} id ${value} is already used (${prior})` });
+            else
+                globalIds.set(value, `${kind} in ${file}`);
+        };
+        for (const p of m.probes) {
+            seen("probe", p.id);
+            probeIds.add(p.id);
+            if (!p.id.startsWith(`${m.component}.`)) {
+                problems.push({ file, check: "ids", message: `probe ${p.id} must start with ${m.component}.` });
+            }
+            if (p.expect === "refused_as_expected" && !p.refusal) {
+                problems.push({ file, check: "proof", message: `probe ${p.id} expects a refusal but names no refusal code` });
+            }
+        }
+        for (const r of m.rules)
+            seen("rule", r.id);
+        for (const l of m.limits ?? [])
+            seen("limit", l.id);
+        for (const e of m.examples ?? [])
+            seen("example", e.id);
+        for (const r of m.rules) {
+            if (!probeIds.has(r.probe))
+                problems.push({ file, check: "proof", message: `rule ${r.id} names probe ${r.probe}, which isn't in this file` });
+        }
+        for (const e of m.examples ?? []) {
+            if (!probeIds.has(e.probe))
+                problems.push({ file, check: "proof", message: `example ${e.id} names probe ${e.probe}, which isn't in this file` });
+        }
+        const errorCodes = new Set();
+        for (const e of m.errors ?? []) {
+            if (errorCodes.has(e.code))
+                problems.push({ file, check: "ids", message: `error code ${e.code} is listed twice` });
+            errorCodes.add(e.code);
+        }
+        const names = new Set();
+        for (const v of m.config ?? []) {
+            if (names.has(v.name))
+                problems.push({ file, check: "ids", message: `config variable ${v.name} is listed twice` });
+            names.add(v.name);
+        }
+        for (const a of m.actions ?? []) {
+            if (a.gate === "two_step_when" && !a.when)
+                problems.push({ file, check: "schema", message: `action ${a.tool} is two_step_when but has no when` });
+        }
+    }
+    return { manifests, problems };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// `npx workbench-config check [dir]`: compares the variable names in
+// <dir>/.dev.vars with <dir>/.dev.vars.example. Prints names only.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { compareDevVars } from "./dev-vars.js";
+function main(argv) {
+    const [command, dir = "."] = argv;
+    if (command !== "check") {
+        console.error("Usage: workbench-config check [dir]");
+        return 2;
+    }
+    const examplePath = join(dir, ".dev.vars.example");
+    const devVarsPath = join(dir, ".dev.vars");
+    if (!existsSync(examplePath)) {
+        console.error(`No .dev.vars.example in ${dir}`);
+        return 1;
+    }
+    if (!existsSync(devVarsPath)) {
+        console.error(`No .dev.vars in ${dir}. Copy .dev.vars.example to .dev.vars and fill it in.`);
+        return 1;
+    }
+    const result = compareDevVars(readFileSync(devVarsPath, "utf8"), readFileSync(examplePath, "utf8"));
+    if (result.ok) {
+        console.log(".dev.vars has every variable in .dev.vars.example, and no others.");
+        return 0;
+    }
+    if (result.missing.length)
+        console.error(`Missing from .dev.vars: ${result.missing.join(", ")}`);
+    if (result.extra.length)
+        console.error(`In .dev.vars but not in .dev.vars.example: ${result.extra.join(", ")}`);
+    return 1;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/define-config.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export interface Config<S extends z.ZodRawShape> {
+    /** The variable names this config reads. */
+    readonly variables: readonly (keyof S & string)[];
+    /**
+     * Validates the variables named in the shape and returns them typed.
+     * Throws `WorkbenchConfigError` naming every bad variable at once. The
+     * message never includes a value, and zod's own messages (which can) are
+     * not used.
+     */
+    parse(env: Record<string, unknown>): z.infer<z.ZodObject<S>>;
+}
+/**
+ * Declares the variables an app needs, as a zod shape:
+ *
+ *   const config = defineConfig({ WORKBENCH_GATEWAY_KEY: z.string(), SITE_NAME: z.string().default('Probe') })
+ *   const { WORKBENCH_GATEWAY_KEY } = config.parse(env)
+ *
+ * An empty string counts as missing, so a blank `.dev.vars` line fails by name.
+ */
+export declare function defineConfig<S extends z.ZodRawShape>(shape: S): Config<S>;

package/dist/define-config.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { WorkbenchConfigError } from "./errors.js";
+/**
+ * Declares the variables an app needs, as a zod shape:
+ *
+ *   const config = defineConfig({ WORKBENCH_GATEWAY_KEY: z.string(), SITE_NAME: z.string().default('Probe') })
+ *   const { WORKBENCH_GATEWAY_KEY } = config.parse(env)
+ *
+ * An empty string counts as missing, so a blank `.dev.vars` line fails by name.
+ */
+export function defineConfig(shape) {
+    const schema = z.object(shape);
+    const variables = Object.keys(shape);
+    return {
+        variables,
+        parse(env) {
+            const input = {};
+            for (const name of variables) {
+                const value = env[name];
+                if (value !== undefined && value !== null && value !== "")
+                    input[name] = value;
+            }
+            const result = schema.safeParse(input);
+            if (result.success)
+                return result.data;
+            const problems = new Map();
+            for (const issue of result.error.issues) {
+                const variable = String(issue.path[0] ?? "(config)");
+                if (problems.has(variable))
+                    continue;
+                const absent = !(variable in input);
+                problems.set(variable, absent ? { variable, problem: "missing" } : { variable, problem: "invalid", detail: detailFor(issue) });
+            }
+            const list = [...problems.values()];
+            const code = list.every((p) => p.problem === "missing") ? "missing_variable" : "invalid_variable";
+            throw new WorkbenchConfigError(code, list);
+        },
+    };
+}
+// A description of the issue built only from its kind and the schema's
+// expectations, never from the input.
+function detailFor(issue) {
+    switch (issue.code) {
+        case "invalid_type":
+            return `expected ${issue.expected}`;
+        case "invalid_value":
+            return "not an allowed value";
+        case "invalid_format":
+            return `expected format ${issue.format}`;
+        case "too_small":
+            return "too short or too small";
+        case "too_big":
+            return "too long or too large";
+        default:
+            return issue.code.replace(/_/g, " ");
+    }
+}

package/dist/dev-vars.d.ts

@@ -0,0 +1,10 @@
+/** The variable names in a dotenv-style file, in order, without values. */
+export declare function parseDevVarNames(text: string): string[];
+export interface DevVarsComparison {
+    /** In the example but not in `.dev.vars`. */
+    missing: string[];
+    /** In `.dev.vars` but not in the example (undocumented). */
+    extra: string[];
+    ok: boolean;
+}
+export declare function compareDevVars(devVars: string, example: string): DevVarsComparison;

package/dist/dev-vars.js

@@ -0,0 +1,23 @@
+// Compares the variable names in `.dev.vars` with `.dev.vars.example`
+// (audit F6). Works on text so it runs anywhere; the CLI reads the files.
+// Only names are ever returned or printed, never values.
+/** The variable names in a dotenv-style file, in order, without values. */
+export function parseDevVarNames(text) {
+    const names = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+        if (match?.[1] && !names.includes(match[1]))
+            names.push(match[1]);
+    }
+    return names;
+}
+export function compareDevVars(devVars, example) {
+    const have = new Set(parseDevVarNames(devVars));
+    const want = new Set(parseDevVarNames(example));
+    const missing = [...want].filter((n) => !have.has(n));
+    const extra = [...have].filter((n) => !want.has(n));
+    return { missing, extra, ok: missing.length === 0 && extra.length === 0 };
+}

package/dist/env.d.ts

@@ -0,0 +1,8 @@
+export declare const WORKBENCH_ENVS: readonly ["development", "staging", "production"];
+export type WorkbenchEnv = (typeof WORKBENCH_ENVS)[number];
+export declare const DEFAULT_GATEWAY_URL = "https://gateway.mccaskielabs.dev";
+/**
+ * Reads `WORKBENCH_ENV`. Throws if it is missing or not one of the three
+ * environments. Never falls back to `NODE_ENV` or a default (audit F9, F18).
+ */
+export declare function workbenchEnv(env: Record<string, unknown>): WorkbenchEnv;

package/dist/env.js

@@ -0,0 +1,16 @@
+import { invalid, missing } from "./errors.js";
+export const WORKBENCH_ENVS = ["development", "staging", "production"];
+export const DEFAULT_GATEWAY_URL = "https://gateway.mccaskielabs.dev";
+/**
+ * Reads `WORKBENCH_ENV`. Throws if it is missing or not one of the three
+ * environments. Never falls back to `NODE_ENV` or a default (audit F9, F18).
+ */
+export function workbenchEnv(env) {
+    const value = env["WORKBENCH_ENV"];
+    if (value === undefined || value === null || value === "")
+        throw missing("WORKBENCH_ENV");
+    if (typeof value !== "string" || !WORKBENCH_ENVS.includes(value)) {
+        throw invalid("WORKBENCH_ENV", `expected one of ${WORKBENCH_ENVS.join(", ")}`);
+    }
+    return value;
+}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+export type ConfigErrorCode = "missing_variable" | "invalid_variable" | "invalid_config";
+export interface ConfigProblem {
+    /** The variable's name, e.g. `WORKBENCH_GATEWAY_KEY`. */
+    variable: string;
+    problem: "missing" | "invalid";
+    /** What was wrong, in words that never include the value (e.g. "expected one of development, staging, production"). */
+    detail?: string;
+}
+export declare class WorkbenchConfigError extends Error {
+    readonly code: ConfigErrorCode;
+    readonly problems: readonly ConfigProblem[];
+    constructor(code: ConfigErrorCode, problems: readonly ConfigProblem[]);
+    /** The names of every variable that was missing or invalid. */
+    get variables(): string[];
+}
+export declare function missing(variable: string, detail?: string): WorkbenchConfigError;
+export declare function invalid(variable: string, detail?: string): WorkbenchConfigError;

package/dist/errors.js

@@ -0,0 +1,26 @@
+// Errors from workbench-config name the variable and the problem, never the value
+// (docs/spec.md §3, audit F6). Nothing here keeps the input as a cause.
+export class WorkbenchConfigError extends Error {
+    code;
+    problems;
+    constructor(code, problems) {
+        super(describe(problems));
+        this.name = "WorkbenchConfigError";
+        this.code = code;
+        this.problems = problems;
+    }
+    /** The names of every variable that was missing or invalid. */
+    get variables() {
+        return this.problems.map((p) => p.variable);
+    }
+}
+function describe(problems) {
+    const parts = problems.map((p) => `${p.variable} is ${p.problem}${p.detail ? ` (${p.detail})` : ""}`);
+    return `Workbench config: ${parts.join("; ")}`;
+}
+export function missing(variable, detail) {
+    return new WorkbenchConfigError("missing_variable", [{ variable, problem: "missing", ...(detail ? { detail } : {}) }]);
+}
+export function invalid(variable, detail) {
+    return new WorkbenchConfigError("invalid_variable", [{ variable, problem: "invalid", ...(detail ? { detail } : {}) }]);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { WORKBENCH_ENVS, DEFAULT_GATEWAY_URL, workbenchEnv, type WorkbenchEnv } from "./env.ts";
+export { defineConfig, type Config } from "./define-config.ts";
+export { sharedSecret, workerSecret, redact, redactAll, type SecretsStoreSecretLike } from "./secrets.ts";
+export { WorkbenchConfigError, type ConfigErrorCode, type ConfigProblem } from "./errors.ts";
+export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, type Capability, type Component, type ManifestProblem, } from "./capability-schema.ts";
+export { capabilities, MANIFEST_VERSION, type Alias, type GatewayScope } from "./capabilities.gen.ts";
+export { compareDevVars, parseDevVarNames } from "./dev-vars.ts";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { WORKBENCH_ENVS, DEFAULT_GATEWAY_URL, workbenchEnv } from "./env.js";
+export { defineConfig } from "./define-config.js";
+export { sharedSecret, workerSecret, redact, redactAll } from "./secrets.js";
+export { WorkbenchConfigError } from "./errors.js";
+export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, } from "./capability-schema.js";
+export { capabilities, MANIFEST_VERSION } from "./capabilities.gen.js";
+export { compareDevVars, parseDevVarNames } from "./dev-vars.js";

package/dist/secrets.d.ts

@@ -0,0 +1,19 @@
+/** The part of a Secrets Store binding that this package uses. */
+export interface SecretsStoreSecretLike {
+    get(): Promise<string>;
+}
+/**
+ * Reads a Secrets Store binding (a secret shared between Workers). Throws if
+ * the value is empty. `name` is only used to name the binding in the error.
+ */
+export declare function sharedSecret(binding: SecretsStoreSecretLike, name?: string): Promise<string>;
+/** Reads a Worker secret or variable by name. Throws, naming it, if it is missing or empty. */
+export declare function workerSecret(env: Record<string, unknown>, name: string): string;
+/**
+ * Replaces a secret for logs. Always `[redacted]`, whatever the value: no
+ * prefix, suffix or length is kept, so a log line can never carry part of it.
+ * `redactAll` does the same for every occurrence inside a longer string.
+ */
+export declare function redact(_value: string): string;
+/** Replaces every occurrence of each secret in `text` with `[redacted]`. Empty secrets are ignored. */
+export declare function redactAll(text: string, secrets: readonly string[]): string;