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

package/dist/capabilities.gen.d.ts

@@ -0,0 +1,403 @@
+export declare const MANIFEST_VERSION: "8c09d0a71651";
+export declare const capabilities: {
+    readonly ai: {
+        readonly $schema: "./schema.json";
+        readonly format: 1;
+        readonly component: "ai";
+        readonly title: "Claude through the Gateway";
+        readonly summary: "Text, structured output and streaming from Claude, metered against the project's budget. Apps never hold an Anthropic key.";
+        readonly status: "planned";
+        readonly surfaces: {
+            readonly gateway: readonly ["POST /anthropic/v1/messages", "POST /anthropic/v1/messages/count_tokens"];
+            readonly package: readonly ["createAi", "Ai.text", "Ai.structured", "Ai.stream", "Ai.budget", "createFakeAi"];
+        };
+        readonly config: readonly [{
+            readonly name: "WORKBENCH_GATEWAY_KEY";
+            readonly required: true;
+            readonly secret: true;
+            readonly environments: readonly ["staging", "production"];
+            readonly description: "Project key with the ai scope, delivered as a Worker secret by gw_key_issue";
+        }, {
+            readonly name: "WORKBENCH_ENV";
+            readonly required: true;
+            readonly secret: false;
+            readonly environments: readonly ["development", "staging", "production"];
+            readonly description: "Drives key checks; never NODE_ENV";
+        }];
+        readonly allowed: {
+            readonly aliases: readonly [{
+                readonly alias: "claude-default";
+                readonly provider: "anthropic";
+                readonly default_model: "claude-sonnet-5-5";
+            }, {
+                readonly alias: "claude-best";
+                readonly provider: "anthropic";
+                readonly default_model: "claude-opus-5-5";
+            }, {
+                readonly alias: "claude-fast";
+                readonly provider: "anthropic";
+                readonly default_model: "claude-haiku-5-5";
+            }];
+            readonly explicit_models: readonly ["claude-sonnet-5", "claude-opus-5"];
+            readonly server_tools: readonly ["web_search", "web_fetch", "code_execution"];
+            readonly required_headers: readonly ["X-Workbench-Job"];
+        };
+        readonly limits: readonly [{
+            readonly id: "ai.retry-attempts";
+            readonly value: 3;
+            readonly unit: "attempts";
+            readonly per: "request";
+            readonly enforced_by: "gateway";
+        }];
+        readonly errors: readonly [{
+            readonly code: "model_not_allowed";
+            readonly http: 400;
+            readonly retryable: false;
+            readonly meaning: "Not an alias or an allowlisted model id";
+        }, {
+            readonly code: "budget_exceeded";
+            readonly http: 402;
+            readonly retryable: false;
+            readonly meaning: "Enforced monthly budget reached";
+        }];
+        readonly rules: readonly [{
+            readonly id: "ai.no-partial-success";
+            readonly kind: "must_not";
+            readonly text: "Treat a refusal or a max_tokens truncation as a successful result.";
+            readonly enforced_by: "types";
+            readonly probe: "ai.text.truncation-throws";
+        }, {
+            readonly id: "ai.store-resolved-model";
+            readonly kind: "must";
+            readonly text: "Store the resolved model and request id with any output kept.";
+            readonly enforced_by: "review";
+            readonly probe: "ai.text.claude-default";
+        }, {
+            readonly id: "ai.aliases-only";
+            readonly kind: "must";
+            readonly text: "Ask for a Workbench alias (or an allowlisted explicit id), never an arbitrary model id.";
+            readonly enforced_by: "gateway";
+            readonly probe: "ai.model-not-allowed";
+        }];
+        readonly examples: readonly [{
+            readonly id: "ai.example.text";
+            readonly title: "One-shot text";
+            readonly lang: "ts";
+            readonly code: "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst r = await ai.text({ model: 'claude-default', job: 'article.write', prompt })\nawait save({ text: r.text, model: r.model, requestId: r.requestId })";
+            readonly probe: "ai.text.claude-default";
+        }];
+        readonly probes: readonly [{
+            readonly id: "ai.text.claude-default";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0.002;
+        }, {
+            readonly id: "ai.text.claude-best";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.004;
+        }, {
+            readonly id: "ai.text.claude-fast";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.001;
+        }, {
+            readonly id: "ai.stream";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.002;
+        }, {
+            readonly id: "ai.structured";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.003;
+        }, {
+            readonly id: "ai.text.truncation-throws";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.001;
+        }, {
+            readonly id: "ai.model-not-allowed";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "model_not_allowed";
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "ai.count-tokens";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0;
+        }];
+    };
+    readonly config: {
+        readonly $schema: "./schema.json";
+        readonly format: 1;
+        readonly component: "config";
+        readonly title: "App configuration with workbench-config";
+        readonly summary: "Reads WORKBENCH_ENV and the app's own variables and secrets. A missing or invalid variable fails at startup, by name, and no value is ever printed.";
+        readonly status: "built";
+        readonly surfaces: {
+            readonly package: readonly ["workbenchEnv", "defineConfig", "sharedSecret", "workerSecret", "redact", "redactAll", "WorkbenchConfigError", "capabilitySchema", "capabilities", "MANIFEST_VERSION", "compareDevVars"];
+        };
+        readonly config: readonly [{
+            readonly name: "WORKBENCH_ENV";
+            readonly required: true;
+            readonly secret: false;
+            readonly environments: readonly ["development", "staging", "production"];
+            readonly description: "development, staging or production. Drives key checks and the email transport; never NODE_ENV (audit F9)";
+        }];
+        readonly allowed: {
+            readonly environments: readonly ["development", "staging", "production"];
+        };
+        readonly rules: readonly [{
+            readonly id: "config.fail-by-name";
+            readonly kind: "must";
+            readonly text: "Fail at startup when a required variable is missing or invalid, naming every bad variable in one error.";
+            readonly enforced_by: "types";
+            readonly probe: "config.missing-variable-named";
+        }, {
+            readonly id: "config.never-print-values";
+            readonly kind: "must_not";
+            readonly text: "Print, log or include in an error the value of any variable, valid or not.";
+            readonly enforced_by: "types";
+            readonly probe: "config.value-never-printed";
+        }, {
+            readonly id: "config.no-node-env";
+            readonly kind: "must_not";
+            readonly text: "Decide the environment from NODE_ENV or a default. WORKBENCH_ENV is required and has no fallback.";
+            readonly enforced_by: "types";
+            readonly probe: "config.env-required";
+        }, {
+            readonly id: "config.dev-vars-example";
+            readonly kind: "must";
+            readonly text: "Keep .dev.vars.example listing every variable .dev.vars has, with no values; check with npx workbench-config check.";
+            readonly enforced_by: "review";
+            readonly probe: "config.dev-vars-check";
+        }];
+        readonly examples: readonly [{
+            readonly id: "config.example.define";
+            readonly title: "Declare and read the app's variables";
+            readonly lang: "ts";
+            readonly code: "import { z } from 'zod'\nimport { defineConfig, workbenchEnv } from '@mccaskie-labs/workbench-config'\n\nconst config = defineConfig({\n  WORKBENCH_GATEWAY_KEY: z.string().startsWith('wbk_'),\n  SITE_NAME: z.string().default('wb-probe'),\n})\n\nexport default {\n  async fetch(request: Request, env: Env) {\n    const stage = workbenchEnv(env)\n    const { WORKBENCH_GATEWAY_KEY, SITE_NAME } = config.parse(env)\n    return new Response(`${SITE_NAME} on ${stage}`)\n  },\n}";
+            readonly probe: "config.missing-variable-named";
+        }];
+        readonly probes: readonly [{
+            readonly id: "config.missing-variable-named";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "config.value-never-printed";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "config.env-required";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "config.dev-vars-check";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+            readonly note: "Manual: run npx workbench-config check in the project";
+        }];
+    };
+    readonly gateway: {
+        readonly $schema: "./schema.json";
+        readonly format: 1;
+        readonly component: "gateway";
+        readonly title: "Workbench Gateway: keys, headers, budgets and errors";
+        readonly summary: "What every Gateway endpoint shares: project keys by environment and scope, the request and response headers, the monthly budget check and the error codes. Apps hold one Workbench key and never a vendor key.";
+        readonly status: "planned";
+        readonly surfaces: {
+            readonly gateway: readonly ["GET /v1/health", "GET /v1/usage", "GET /v1/capabilities"];
+            readonly package: readonly ["DEFAULT_GATEWAY_URL"];
+        };
+        readonly config: readonly [{
+            readonly name: "WORKBENCH_GATEWAY_KEY";
+            readonly required: true;
+            readonly secret: true;
+            readonly environments: readonly ["staging", "production"];
+            readonly description: "The project's Gateway key for this environment, delivered as a Worker secret by gw_key_issue. Never in code, .dev.vars.example or logs";
+        }, {
+            readonly name: "WORKBENCH_GATEWAY_URL";
+            readonly required: false;
+            readonly secret: false;
+            readonly default: "https://gateway.mccaskielabs.dev";
+            readonly environments: readonly ["development", "staging", "production"];
+            readonly description: "Gateway base URL. Leave unset outside tests";
+        }];
+        readonly allowed: {
+            readonly scopes: readonly ["ai", "images", "search", "email"];
+            readonly key_environments: readonly [{
+                readonly environment: "development";
+                readonly prefix: "wbk_dev_";
+            }, {
+                readonly environment: "staging";
+                readonly prefix: "wbk_stg_";
+            }, {
+                readonly environment: "production";
+                readonly prefix: "wbk_prd_";
+            }];
+            readonly request_headers: readonly [{
+                readonly name: "Authorization";
+                readonly required: true;
+                readonly description: "Bearer <key>. On /anthropic/* the key goes in x-api-key instead, so the official SDK works unchanged";
+            }, {
+                readonly name: "X-Workbench-Job";
+                readonly required: true;
+                readonly pattern: "^[a-z0-9._-]{1,64}$";
+                readonly description: "What the call is for, e.g. article.write. Recorded with usage";
+            }, {
+                readonly name: "X-Workbench-Prompt-Version";
+                readonly required: false;
+                readonly description: "The app's prompt version, recorded with usage (audit F17)";
+            }, {
+                readonly name: "X-Workbench-Subject";
+                readonly required: false;
+                readonly pattern: "^[a-z0-9_-]+:[^\\s]{1,128}$";
+                readonly description: "type:id of the thing the call is about";
+            }, {
+                readonly name: "Idempotency-Key";
+                readonly required: false;
+                readonly description: "Email only: a repeat within 24 hours returns the stored result";
+            }];
+            readonly response_headers: readonly ["X-Workbench-Request-Id", "Server-Timing"];
+            readonly server_timing_metrics: readonly ["gw", "vendor_fb", "vendor", "total"];
+        };
+        readonly limits: readonly [{
+            readonly id: "gateway.key-cache";
+            readonly value: 60;
+            readonly unit: "seconds";
+            readonly per: "isolate";
+            readonly enforced_by: "gateway";
+        }, {
+            readonly id: "gateway.budget-cache";
+            readonly value: 60;
+            readonly unit: "seconds";
+            readonly per: "isolate";
+            readonly enforced_by: "gateway";
+        }, {
+            readonly id: "gateway.job-format";
+            readonly value: "[a-z0-9._-]{1,64}";
+            readonly unit: "pattern";
+            readonly per: "request";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }];
+        readonly errors: readonly [{
+            readonly code: "unauthorised";
+            readonly http: 401;
+            readonly retryable: false;
+            readonly meaning: "No key, a malformed or unknown key, a revoked key, or a key from the wrong environment";
+        }, {
+            readonly code: "forbidden_scope";
+            readonly http: 403;
+            readonly retryable: false;
+            readonly meaning: "The key doesn't carry the scope this endpoint needs";
+        }, {
+            readonly code: "invalid_request";
+            readonly http: 400;
+            readonly retryable: false;
+            readonly meaning: "The body or a required header is missing or malformed";
+        }, {
+            readonly code: "budget_exceeded";
+            readonly http: 402;
+            readonly retryable: false;
+            readonly meaning: "The environment's enforced monthly budget, or the global ceiling, is reached";
+        }, {
+            readonly code: "rate_limited";
+            readonly http: 429;
+            readonly retryable: true;
+            readonly meaning: "Per-key rate limit; it stops runaway loops, budgets limit spend";
+        }, {
+            readonly code: "not_available";
+            readonly http: 501;
+            readonly retryable: false;
+            readonly meaning: "Not built yet, e.g. bulk email";
+        }, {
+            readonly code: "upstream_error";
+            readonly http: 502;
+            readonly retryable: true;
+            readonly meaning: "The vendor failed after the Gateway's retries";
+        }, {
+            readonly code: "upstream_timeout";
+            readonly http: 504;
+            readonly retryable: true;
+            readonly meaning: "The vendor didn't answer in time";
+        }];
+        readonly rules: readonly [{
+            readonly id: "gateway.no-vendor-keys";
+            readonly kind: "must_not";
+            readonly text: "Hold a vendor key (Anthropic, Google, OpenAI, Serper, email) in an app. The Gateway key is the only Workbench credential an app has.";
+            readonly enforced_by: "review";
+            readonly probe: "gateway.no-vendor-keys.scan";
+        }, {
+            readonly id: "gateway.key-per-environment";
+            readonly kind: "must";
+            readonly text: "Use the key issued for the Worker's own environment. A staging key is refused by production and the other way round.";
+            readonly enforced_by: "gateway";
+            readonly probe: "gateway.wrong-environment";
+        }, {
+            readonly id: "gateway.request-id-kept";
+            readonly kind: "must";
+            readonly text: "Keep X-Workbench-Request-Id with any output stored or any error logged, so it can be matched to a usage row.";
+            readonly enforced_by: "review";
+            readonly probe: "gateway.health";
+        }];
+        readonly probes: readonly [{
+            readonly id: "gateway.health";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "gateway.bad-key";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "unauthorised";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "gateway.wrong-scope";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "forbidden_scope";
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "gateway.wrong-environment";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "unauthorised";
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "gateway.revoked-key";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "unauthorised";
+            readonly cost_hint_usd: 0;
+            readonly note: "Stops within 60 seconds of revocation";
+        }, {
+            readonly id: "gateway.budget-enforced";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "budget_exceeded";
+            readonly cost_hint_usd: 0.01;
+            readonly note: "Uses the development key's US$0.01 enforce budget (docs/phase-4-plan.md §3 Q10)";
+        }, {
+            readonly id: "gateway.no-vendor-keys.scan";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+            readonly note: "Manual: grep of the repo and cf_worker_secret_list show only WORKBENCH_GATEWAY_* secrets";
+        }];
+    };
+};
+export type Alias = (typeof capabilities)["ai"]["allowed"]["aliases"][number]["alias"];
+export type GatewayScope = (typeof capabilities)["gateway"]["allowed"]["scopes"][number];