ai-runtime-engine 1.1.0

package/docs/router.md

@@ -0,0 +1,376 @@
+# Router engine reference
+
+The **router** is the engine beneath the [Runtime](../README.md#how-to-use-it): the vendor-agnostic
+`AI` class that turns a task into a routed, executed, validated result. Most users only touch it through
+the Runtime — but it is fully usable on its own (`import { AI } from 'ai-runtime-engine'`), and this document is
+its complete reference: configuration, the `run()` API, providers, tasks/capabilities, routing internals,
+reliability, and advanced features.
+
+```ts
+import { AI } from 'ai-runtime-engine';
+const ai = await AI.load();                                  // ai-runtime.yaml + .env
+const r  = await ai.run({ task: 'jira-to-test', input: ticketText });
+if (r.ok) console.log(r.response?.text);
+else console.error(r.error?.category, r.error?.message);
+```
+
+`run()` **does not throw** for routing/provider failures — it returns `ok: false` with an actionable
+`error` and the full `routing` trace. It only throws for programmer errors (e.g. an unknown preset id).
+
+## The pipeline
+
+```
+run(request)
+ 1. Normalize   task name → required/preferred capabilities, strategy, sensitivity, context floor,
+                output contract. Unknown task? infer requirements from request hints; baseline confidence 0.5.
+ 2. Filter      drop candidates that can't/mustn't serve, each with a reason: not registered · unhealthy ·
+                denied · not allow-listed · pin mismatch · missing capability · context too small · privacy ·
+                over a hard cost/latency limit.
+ 3. Score       seven 0..1 sub-scores per survivor × strategy-adjusted weights → one score; sort
+                deterministically (score → quality → latency → id).
+ 4-7. Execute + validate + fall back   (one loop, bounded by maxFallbacks, default 4) top candidate →
+                provider.execute() → normalize → validate against the output contract; a thrown error or a
+                failed validation drops to the next candidate; a non-retryable error poisons that provider.
+ → confidence = topScore × (0.5 + 0.5 × evidence) × task.confidence
+ → RunResult { ok, response?, error?, confidence, routing }
+```
+
+Validation is applied **inside** the fallback loop as a per-attempt check, so an invalid response falls
+through to the next provider just like a thrown error does.
+
+---
+
+## Configuration
+
+A config carries **structure and env-var names only** — never secret values. The file is validated by a
+**strict** schema at load: an unknown key, or an `apiKeyEnv` that looks like a real key (`sk-…`, `gsk_…`,
+`Bearer …`, or a 40+ char token), is **rejected** with a `CONFIG` error — structurally preventing a
+committed secret.
+
+### Config-file keys (validated)
+
+These are the only keys accepted in `ai-runtime.yaml` / `.yml` / `.json` (also valid as the router block
+inside `.ai-runtime/config.yaml`):
+
+```yaml
+strategy: best                        # best | fastest | cheapest | highest-quality | local-only |
+                                      # cloud-only | provider-specific | privacy-first | fallback-only
+
+weights:                              # scoring weights (defaults shown; need not sum to 100)
+  capabilityFit: 30
+  quality: 20
+  reliability: 15
+  historicalSuccess: 10
+  latency: 10
+  cost: 10
+  userPreference: 5
+
+defaults:
+  timeoutMs: 90000                    # per-request HTTP timeout
+  maxFallbacks: 4                     # max providers tried per run
+  minEvidence: documented             # min evidence a capability needs to count as supported
+  minConfidence: 0.7                  # below this → result.routing.belowConfidenceThreshold = true
+
+privacy:
+  allowCloud: true                    # default true — a single cloud provider still works
+  allowLocal: true
+  sensitiveDataAllowedOnCloud: false  # HIGH-sensitivity input is kept off cloud providers
+  treatUnknownAsSensitive: false      # strict fail-closed: treat unknown sensitivity as sensitive
+  defaultSensitivity: unknown         # low | high | unknown
+
+telemetry:
+  enabled: true
+  sink: memory                        # memory | file
+  storePrompts: false                 # schema only allows false
+  path: .ai-runtime/telemetry.jsonl    # required when sink: file (keep it gitignored)
+
+providers:                            # the only required key
+  - id: gemini
+    kind: gemini                      # gemini | groq | anthropic | ollama | openai-compatible | custom | mock
+    apiKeyEnv: GEMINI_API_KEY         # NAME of the env var, never the value
+    # optional: enabled, baseUrl, models, defaultModel, capabilities,
+    #           privacyClass, wireShape, headers, weightOverrides
+
+  - id: internal                      # an unknown OpenAI-compatible provider self-declaring capabilities
+    kind: openai-compatible           # openai-compatible/custom REQUIRE a baseUrl
+    baseUrl: https://ai.internal.example/v1
+    apiKeyEnv: INTERNAL_AI_API_KEY
+    models: [internal-large]
+    capabilities:
+      intelligence: [reasoning, code_generation, code_analysis]
+      output: [text, code, json]
+      contextWindow: 128000
+
+tasks:                                # extend/override the built-in task registry
+  - id: my-task
+    required:
+      - { group: intelligence, key: reasoning }
+      - { group: output, key: json }
+    output: { format: json }
+    defaultStrategy: best
+```
+
+Load with `AI.load()`, `AI.load('/path/to/config.yaml')`, or a remote URL
+`AI.load('https://.../ai-runtime.yaml')` (remote configs get the same validation).
+
+### Programmatic-only options
+
+`learning`, `verification`, `budget`, and `policy` are read by the router but are **not** part of the
+strict file schema — set them by passing a config **object** to the constructor (a YAML file containing
+them is rejected). `verification` and `budget` can also be set per run in `run()`.
+
+```ts
+const ai = new AI({
+  providers: [{ id: 'gemini', kind: 'gemini', apiKeyEnv: 'GEMINI_API_KEY' }],
+  learning:     { enabled: true },                       // default true
+  verification: { enabled: false },                      // default false
+  budget:       { maxCostUsd: 0.10, maxCalls: 8 },       // per-run guardrail
+  policy:       { allowProviders: ['gemini', 'groq'],    // org guardrails on EVERY run
+                  requireLocal: false, maxCostUsd: 0.05, strategy: 'cheapest' },
+});
+```
+
+---
+
+## The `run()` API
+
+```ts
+const result = await ai.run({
+  task: 'analyze-playwright-trace',    // task name or alias; unknown tasks still work
+  input: trace,                         // string, or { text?, parts?: InputPart[] } for multimodal
+
+  system: 'You are a senior QA engineer.',
+  params: { temperature: 0.2, maxTokens: 2048, topP: 1, stop: ['\n\n'] },
+  requirements: { intelligence: ['code_analysis'], minContextWindow: 128000 },
+  constraints: {
+    maxCostUsd: 0.02, maxLatencyMs: 3000, minimumConfidence: 0.85,
+    allowProviders: ['gemini', 'groq'], denyProviders: ['ollama'],
+  },
+  strategy: 'highest-quality',
+  provider: 'gemini',                   // pin a provider (skips the capability filter; privacy/health still apply)
+  model: 'gemini-2.0-flash',            // pin a model
+  routing: { excludeProviders: ['x'], preferModels: ['gemini:gemini-2.0-flash'] },  // exclude/prefer
+  sensitivity: 'high',                  // 'low' | 'high' | 'unknown'
+  output: { format: 'json', schema: myZodSchema },   // validated after execution
+  tools: [{ name: 'search', parameters: {} }],
+  budget: { maxCostUsd: 0.05, maxCalls: 3 },         // per-run spend guardrail
+  verification: true,                   // run a second model to verify the answer
+  mcp: true,                            // attach tools from registered MCP sources
+});
+```
+
+**`RunResult`:**
+
+```ts
+{
+  ok: boolean;
+  response?: {                          // normalized — no vendor-specific parsing
+    text?: string; json?: unknown; toolCalls?: { name; arguments }[];
+    finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
+    usage?: { inputTokens?; outputTokens?; totalTokens? };
+    providerId: string; model: string; latencyMs: number;
+  };
+  error?: { category: ErrorCategory; message: string; retryable: boolean; providerId?; model? };
+  confidence: number;                   // 0..1
+  routing: {                            // the full decision trace
+    taskId, strategy, weights, requiredCapabilities, consideredCount,
+    filteredOut: { providerId, model, reason }[],     // why each provider was excluded
+    ranked: { providerId, model, score, breakdown }[],
+    selected?: { providerId, model },
+    attempts: { providerId, model, outcome, category?, latencyMs }[],  // incl. fallbacks
+    validation?, verification?, belowConfidenceThreshold?,
+  };
+}
+```
+
+## `AI` class reference
+
+| Method | Purpose |
+|---|---|
+| `new AI(config?, options?)` | Construct from a config object. `options`: `{ fetchImpl, clock, env, sinks }` |
+| `static AI.load(pathOrUrl?, options?)` | Build from a local config file or an http(s) URL |
+| `ai.run(request)` | Route and execute a task → `RunResult` |
+| `ai.registerProvider(provider, enabled?)` | Register a provider instance (e.g. `MockProvider`) — chainable |
+| `ai.registerTask(def)` | Add/override a task definition — chainable |
+| `ai.addPreset(id, overrides?)` | Add a provider from the marketplace catalog |
+| `ai.registerFromOpenApi(specOrAnalysis, overrides?)` | Generate + register a provider from an OpenAPI spec |
+| `ai.registerMcpSource(source)` | Register an MCP tool source — chainable |
+| `ai.providers()` / `ai.tasksList()` | Key-free provider listing / all registered tasks |
+| `ai.discover()` / `ai.checkHealth()` | Provider metadata + models + capabilities / run each health check |
+| `ai.probe(providerId, model, which?)` | Verify capabilities with live probes |
+| `ai.telemetryEvents()` / `ai.performanceSnapshot()` | Recent metadata-only telemetry / learned performance |
+
+---
+
+## Providers
+
+Every provider implements one `AIProvider` contract. Real providers (`HttpProvider`) ride **one HTTP path**
+(native `fetch`, zero SDKs); `MockProvider` is a deterministic no-network implementation of the same
+contract for tests.
+
+### Built-in kinds
+
+| kind | wire | key env (default) | notes |
+|---|---|---|---|
+| `gemini` | OpenAI-compat | `GEMINI_API_KEY` | via Gemini's OpenAI-compatible endpoint |
+| `groq` | OpenAI-compat | `GROQ_API_KEY` | |
+| `anthropic` | native `/v1/messages` | `ANTHROPIC_API_KEY` | dedicated wire (`x-api-key` + `anthropic-version`) |
+| `ollama` | OpenAI-compat | — | local, no key; degrades gracefully if absent |
+| `openai-compatible` | OpenAI-compat | (you set `apiKeyEnv`) | any gateway — **`baseUrl` required** |
+| `custom` | OpenAI-compat | (you set `apiKeyEnv`) | as above — **`baseUrl` required** |
+| `mock` | — | — | deterministic, no-network; registered programmatically |
+
+### Marketplace presets
+
+`ai-runtime presets` lists ready-to-use presets. **Native** presets (`gemini`, `groq`, `anthropic`,
+`ollama`) come from the built-in defaults; **community** presets (`openrouter`, `cerebras`, `mistral`,
+`together`, `deepseek`) are OpenAI-compatible. Add one: `ai.addPreset('openrouter', { models: ['…'] })`.
+
+### Unknown / self-declared providers
+
+A provider with no catalog entry is still routable if it **declares its capabilities** in config (the
+`internal` example above), or if you **pin** it in `run()`. Pinning routes on your assertion and skips the
+capability filter — but privacy and health filters still apply.
+
+### From an OpenAPI spec
+
+```bash
+ai-runtime discover ./company-ai.openapi.yaml     # analyze + suggest a config
+```
+```ts
+ai.registerFromOpenApi('./company-ai.openapi.yaml', { id: 'company', apiKeyEnv: 'COMPANY_KEY', models: ['big'] });
+```
+
+Only **config** is generated (and validated) — never code. If the spec yields no OpenAI-compatible mapping,
+generation throws a `CONFIG` error rather than guessing.
+
+---
+
+## Tasks & capabilities
+
+You route by **task name**, not a capability list. Built-in tasks (extend via `registerTask()`,
+`new AI({ tasks })`, or the YAML `tasks:` key):
+
+| Task (aliases) | required capabilities | context floor | default strategy |
+|---|---|---|---|
+| `generate-playwright-tests` (`url-to-test`) | code_generation, reasoning, output.code | 32k | highest-quality |
+| `playwright-trace-analysis` (`trace-analysis`, `analyze-playwright-trace`) | code_analysis, reasoning | 128k | best |
+| `test-healer` | code_analysis, code_generation | 64k | — |
+| `framework-converter` | code_generation, code_analysis | 64k | — |
+| `feature-analyzer` | reasoning, summarization, extraction | 32k | — |
+| `jira-to-test` (`ticket-router`) | reasoning, extraction, classification | — | — |
+
+**Unknown tasks never fail** — requirements are inferred from your `run()` hints (output format, image/file
+parts, tools) and the result's baseline `confidence` is lowered to 0.5.
+
+**Capability taxonomy** (normalized, provider-agnostic):
+- input: `text, image, audio, video, file, pdf`
+- output: `text, json, structured_output, code, image, audio`
+- intelligence: `reasoning, classification, summarization, code_generation, code_analysis, planning, translation, extraction`
+- agent: `tool_calling, function_calling, mcp, agentic_loop`
+- context: numeric `contextWindow`
+
+Every capability carries **evidence**, ranked `verified > documented > inferred > unknown > unsupported`.
+`unknown`/`unsupported` never satisfy a requirement, and evidence rank is never lowered except by a
+capability probe promoting a fact to `verified`.
+
+---
+
+## Routing internals
+
+### Strategies
+
+| Strategy | Effect |
+|---|---|
+| `best` (default) | base weights, no special filtering |
+| `fastest` | latency weight ×4 |
+| `cheapest` | cost weight ×4 |
+| `highest-quality` | quality weight ×2.5 |
+| `local-only` | filters out cloud providers |
+| `cloud-only` | filters out local providers |
+| `provider-specific` | set automatically when you pin a provider |
+| `privacy-first` | accepted; behaves like `best` — use `local-only`, `sensitivity: 'high'`, or a task/policy `requireLocal` |
+| `fallback-only` | base weights (relies on the fallback order) |
+
+### Scoring & confidence
+
+Each survivor gets a 0..1 sub-score per dimension (`capabilityFit · quality · reliability ·
+historicalSuccess · latency · cost · userPreference`); the final score is the weighted sum divided by the
+weight sum. Ties break by score → quality → latency → id.
+
+`confidence = topScore × (0.5 + 0.5 × evidenceFactor) × task.confidence`, where `task.confidence` is 1 for a
+known task and 0.5 for an inferred one. Verification adjusts it (agree `+0.05`, capped at 1; disagree caps
+at `minConfidence × 0.9`). Below `minConfidence` (default 0.7), `routing.belowConfidenceThreshold` is set.
+
+### Reliability & health
+
+- **Retryable** (fall through / retry): `RATE_LIMIT`, `QUOTA`, `TIMEOUT`, `NETWORK`, `PROVIDER`.
+- **Run-stopping**: exactly `BUDGET`, `CONFIG`, `PRIVACY_VIOLATION`.
+- **Other non-retryable** (`AUTHENTICATION`, `MODEL_NOT_FOUND`, `CAPABILITY`, `INVALID_REQUEST`,
+  `RESPONSE_VALIDATION`): poison *that* provider and let fallback continue.
+- **Two terminal outcomes:** `NO_CAPABLE_PROVIDER` (nothing eligible — with per-provider reasons) vs
+  `ALL_PROVIDERS_FAILED` (candidates existed but every attempt failed — with the full trace).
+- **Health monitor:** routable states are `AVAILABLE`, `CONFIGURED`, `DEGRADED`, `UNKNOWN`. A rate-limited
+  or quota-exhausted provider gets a timed cooldown (default 60s). Same-provider HTTP retries (default 2)
+  handle 429/5xx (honoring `Retry-After`, capped at 30s), timeouts, and a `response_format` graceful degrade.
+
+### Error categories
+
+```
+AUTHENTICATION · AUTHORIZATION · RATE_LIMIT · QUOTA · MODEL_NOT_FOUND · CAPABILITY ·
+INVALID_REQUEST · TIMEOUT · NETWORK · PROVIDER · RESPONSE_VALIDATION · BUDGET ·
+PRIVACY_VIOLATION · NO_CAPABLE_PROVIDER · ALL_PROVIDERS_FAILED · CONFIG · UNKNOWN
+```
+
+---
+
+## Advanced features
+
+- **Learning-based routing** — observed success rate/latency per `(task, provider, model)` feed the
+  `historicalSuccess`/`latency` dimensions after **3 samples**; never overrides a hard constraint. Inspect
+  with `ai.performanceSnapshot()`; toggle via `learning.enabled`.
+- **Capability probing** — `ai.probe('gemini', 'gemini-2.0-flash')` verifies what a model can actually do
+  (opt-in, minimal tokens, no secrets); positive probes promote capabilities to `verified`.
+- **Multi-model verification** — `run({ …, verification: true })` has a second model judge the answer; the
+  verdict adjusts confidence and appears in `routing.verification`. Budget-aware (inconclusive if unaffordable).
+- **Budgets** — `run({ …, budget: { maxCostUsd, maxCalls } })`; a spent budget stops the run with a distinct
+  `BUDGET` error.
+- **MCP tools** — an integration layer for tools/context (not a provider). Register a source; its tools are
+  namespaced `${sourceId}.${toolName}` and attached to a tool-calling model on `mcp: true` runs.
+- **Team policies** — a constructor-only `policy` applies org guardrails (allow/deny providers,
+  `requireLocal`, `maxCostUsd`, `strategy`) to every run, merged with per-run constraints.
+- **Remote config** — `AI.load('https://…/ai-runtime.yaml')` (same strict validation).
+- **Enterprise credentials** — `setCredentialResolver((name) => secrets.get(name))` (env wins when present).
+- **Observability** — `new AI(config, { sinks: [new CallbackSink(send)] })`; sinks: `MemorySink`, `FileSink`,
+  `CallbackSink`, `MultiSink`, `NullSink` (redacted metadata only).
+
+## Engine CLI commands
+
+| Command | Description |
+|---|---|
+| `ai-runtime init` | Scaffold `ai-runtime.yaml`, `.env.example`, `.gitignore` (the low-level scaffold; `setup` is the guided one) |
+| `ai-runtime providers` / `models` / `capabilities` | List providers + health / known models / the capability matrix (`--json`) |
+| `ai-runtime route <task>` | Route a task (`-i` input, `-s` strategy, `-p`/`-m` pin, `--json`) |
+| `ai-runtime test <provider>` | One live call to a provider (skipped without a key) |
+| `ai-runtime probe <provider> <model>` | Verify a model's capabilities (opt-in, live) |
+| `ai-runtime discover <spec>` | Analyze an OpenAPI spec → suggested config |
+| `ai-runtime benchmark` | Compare providers on tasks (`-n` samples) |
+| `ai-runtime presets` / `telemetry` / `config` | List presets / recent routing events / the resolved config |
+
+## Source layout
+
+```
+src/
+  plugin/ai.ts              the public AI facade
+  core/router/              pipeline: normalize · filter · score · execute+validate+fallback · confidence
+  core/{fallback,registry,capabilities,health,policies,validation}/   error taxonomy, registries, evidence, health, guardrails, validation
+  providers/                AIProvider contract, HttpProvider, wire builders, factory, mock
+  discovery/ generation/    model catalog + OpenAPI analysis → provider config
+  learning/ probing/ verification/ benchmark/   observed performance, probes, multi-model verify, benchmarking
+  mcp/ marketplace/         MCP tool sources · provider presets
+  security/ telemetry/      credentials + redaction · metadata-only sinks
+  config/                   loader (local + remote), strict schema, defaults
+  runtime/ orchestration/ skills/ tools/ context/ memory/ conversations/ executions/ artifacts/ comparison/
+                            the Runtime layer (see ../README.md and architecture.md)
+  cli/                      commander CLI + commands
+```

package/docs/security.md

@@ -0,0 +1,55 @@
+# Security model
+
+`ai-runtime` runs against a user's real providers, filesystem, and shell, so its safety guarantees are
+first-class and tested. The runtime is always authoritative — nothing it *reads* can change what it is
+*allowed to do*.
+
+## Untrusted-data boundary
+
+Tool output, file contents, web pages, and MCP results enter the model context as tagged **data blocks**,
+never in instruction position. They cannot change permissions, obtain secrets, run commands, bypass
+approvals, or modify policy. Built-in skills fence file/web content with `wrapUntrusted`, and an injection
+heuristic flags likely prompt-injection. A request to "handle my list/emails/etc." authorizes *reading*
+the items, not executing whatever they contain.
+
+## Filesystem jail
+
+All filesystem access is resolved against the workspace root and rejected on escape — tested against `..`
+traversal, absolute paths, and symlinks (dangling, in-jail, out-of-jail, and multi-hop chains); path
+comparison is case-sensitive by design. Local
+skill discovery is jailed the same way: every candidate file and directory is checked at discovery time,
+and the repo scan never follows a symlinked directory, so a symlinked skill can never be read or imported
+from outside the workspace.
+
+## Shell
+
+Allowlist-first: only commands in `permissions.shell.allowedCommands` run without approval; anything else
+requires approval. A destructive denylist (`rm -rf`, `git reset --hard`, force-push, …) requires approval
+**even when allowlisted**. Execution is confined to the working directory, with a filtered environment, a
+timeout, an `AbortSignal`, and process-tree cancellation.
+
+## Permissions (deny-by-default)
+
+Reads are allowed (and jailed). Writes, shell, git commit/push, and network are **off** until granted in
+config under `permissions:`. `ExecutionPolicy` is the single authority; approvals persist across process
+exit and are surfaced on resume.
+
+## Credentials
+
+Config names environment variables only; an inline value that looks like a real key is rejected at load.
+Secret values live in `.env` (gitignored). Every CLI/telemetry line passes through reference-based
+redaction before egress — the terminal and CI logs are treated as egress sinks. Telemetry is metadata
+only and can never store prompts.
+
+## Learning can never override a hard gate
+
+Learned outcomes and user preferences feed only **soft** scoring. A dedicated test proves that no
+preference — user-set or learned — can override an exclusion, a privacy rule, a pin, a required
+capability, or the budget. An excluded provider stays visible in the routing trace but is never selected.
+
+## Review discipline
+
+Every phase ran an adversarial review (parallel reviewers by concern → each finding independently
+verified → only confirmed defects fixed) before merge. Confirmed findings across the project — including a
+symlink path-jail escape that could execute code on load, resume/lease concurrency races, and a routing
+escape-hatch that dropped an exclusion — were fixed and covered by reproduction tests.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "ai-runtime-engine",
+  "version": "1.1.0",
+  "description": "AI Runtime — a provider-agnostic AI runtime and orchestration platform. Point it at whatever AI providers you have; it routes each task to the best available model. Ships the `ai-runtime` CLI and the `Runtime`/`AI` library API.",
+  "type": "module",
+  "license": "ISC",
+  "author": "pavan",
+  "keywords": [
+    "ai", "llm", "ai-runtime", "runtime", "orchestration", "router", "provider-agnostic", "agent",
+    "openai", "gemini", "groq", "anthropic", "ollama", "openrouter", "mcp", "cli", "typescript"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "ai-runtime": "./dist/cli/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/GUIDE.md",
+    "docs/router.md",
+    "docs/architecture.md",
+    "docs/security.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"tests/**/*.test.ts\"",
+    "test:unit": "node --import tsx --test \"tests/unit/**/*.test.ts\"",
+    "test:integration": "node --import tsx --test \"tests/integration/**/*.test.ts\"",
+    "test:contract": "node --import tsx --test \"tests/contract/**/*.test.ts\"",
+    "test:chaos": "node --import tsx --test \"tests/chaos/**/*.test.ts\"",
+    "cli": "node --import tsx src/cli/cli.ts",
+    "example:fallback": "node --import tsx examples/fallback.ts",
+    "example:minimal": "node --import tsx examples/minimal.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "dotenv": "^17.2.3",
+    "yaml": "^2.6.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}