@sriinnu/kosha-discovery 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Srinivas Pendela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+<p align="center">
+  <img src="logo.svg" alt="Kosha — AI Model Discovery" width="140" />
+</p>
+
+<h1 align="center">kosha-discovery — कोश</h1>
+
+<p align="center"><strong>AI Model & Provider Discovery Registry</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@sriinnu/kosha-discovery"><img src="https://img.shields.io/npm/v/%40sriinnu%2Fkosha-discovery?color=7C3AED&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@sriinnu/kosha-discovery"><img src="https://img.shields.io/npm/dm/%40sriinnu%2Fkosha-discovery?color=0EA5E9&label=downloads" alt="npm downloads" /></a>
+  <a href="https://github.com/sriinnu/kosha-discovery/blob/main/LICENSE"><img src="https://img.shields.io/github/license/sriinnu/kosha-discovery?color=F59E0B" alt="license" /></a>
+  <a href="https://www.npmjs.com/package/@sriinnu/kosha-discovery"><img src="https://img.shields.io/node/v/%40sriinnu%2Fkosha-discovery?color=5B21B6" alt="node version" /></a>
+  <a href="https://github.com/sriinnu/kosha-discovery/actions/workflows/release-npm.yml"><img src="https://img.shields.io/github/actions/workflow/status/sriinnu/kosha-discovery/release-npm.yml?label=release%20workflow" alt="release workflow status" /></a>
+  <a href="https://github.com/sriinnu/kosha-discovery/actions/workflows/update-kosha-snapshot.yml"><img src="https://img.shields.io/github/actions/workflow/status/sriinnu/kosha-discovery/update-kosha-snapshot.yml?label=snapshot%20workflow" alt="snapshot workflow status" /></a>
+  <a href="https://github.com/sriinnu/kosha-discovery/actions/workflows/provider-smoke.yml"><img src="https://img.shields.io/github/actions/workflow/status/sriinnu/kosha-discovery/provider-smoke.yml?label=provider%20smoke" alt="provider smoke status" /></a>
+  <a href="https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json"><img src="https://img.shields.io/badge/pricing%20source-LiteLLM-2563EB" alt="LiteLLM pricing source" /></a>
+</p>
+
+Kosha (कोश — treasury/repository) automatically discovers AI models across providers, resolves credentials from CLI tools and environment variables, enriches models with pricing data, and exposes the catalog via library, CLI, and HTTP API.
+
+## Why
+
+AI applications hardcode model IDs, pricing, and provider configs. When providers add models or change pricing, every app breaks. Kosha solves this:
+
+- **Dynamic discovery** — fetches real model lists from provider APIs
+- **Smart credentials** — finds API keys from env vars, CLI tools (Claude, Copilot, Gemini CLI), and config files
+- **Pricing enrichment** — fills in costs and context windows from litellm's community-maintained dataset
+- **Model aliases** — `sonnet` → `claude-sonnet-4-20250514`, updated as models evolve
+- **Role matrix** — query provider -> model -> roles (`chat`, `embedding`, `image_generation`, etc.)
+- **Cheapest routing** — rank cheapest eligible models for tasks like embeddings or image generation
+- **Local LLM scanning** — detects Ollama models alongside cloud providers
+- **Three access patterns** — use as a library, CLI tool, or HTTP API
+
+## Install
+
+```bash
+pnpm add kosha-discovery
+```
+
+## Development (pnpm)
+
+```bash
+pnpm install
+pnpm run build
+pnpm run test
+```
+
+## Quick Start
+
+### Library
+
+```typescript
+import { createKosha } from "kosha-discovery";
+
+const kosha = await createKosha();
+
+const models = kosha.models();                           // all models
+const embeddings = kosha.models({ mode: "embedding" });  // filter by mode
+const model = kosha.model("sonnet");                     // resolve alias
+const cheapest = kosha.cheapestModels({ role: "image", limit: 3 });
+
+console.log(model.pricing); // { inputPerMillion: 3, outputPerMillion: 15, ... }
+```
+
+### CLI
+
+```bash
+kosha discover                          # discover all providers
+kosha list                              # list models
+kosha list --provider anthropic         # filter by provider
+kosha search gemini                     # fuzzy search
+kosha model sonnet                      # model details
+kosha cheapest --role embeddings        # cheapest for a task
+kosha routes gpt-4o                     # all provider routes
+kosha providers                         # provider status
+kosha latest                            # force-fetch latest provider/model details
+kosha latest --provider openai          # latest for one provider
+kosha serve --port 3000                 # start HTTP API
+```
+
+### Auto-Fetch JSON Snapshot
+
+```bash
+# one-shot latest snapshot
+pnpm run autofetch:once
+
+# custom output/provider
+pnpm run autofetch:once -- --provider openai --output ./data/openai-latest.json
+
+# continuous loop (default 3600s)
+pnpm run autofetch -- --interval-seconds 900
+```
+
+By default this writes JSON to `./data/kosha-latest.json`.
+
+### CI / Smoke Checks
+
+Workflow files:
+
+- `.github/workflows/update-kosha-snapshot.yml`
+- `.github/workflows/provider-smoke.yml`
+
+Snapshot workflow:
+
+- Scheduled: weekly (Monday 06:00 UTC)
+- Manual: GitHub UI -> Actions -> `Update Kosha Snapshot` -> `Run workflow`
+- Optional manual inputs:
+  - `provider` (empty = all providers)
+  - `output` (default `data/kosha-latest.json`)
+- Disable scheduled runs without removing the workflow by setting `KOSHA_SNAPSHOT_SCHEDULE_ENABLED=false`
+- Manual `Run workflow` still works even when schedule is disabled
+
+Provider smoke workflow:
+
+- Scheduled: nightly (03:00 UTC)
+- Manual: GitHub UI -> Actions -> `Provider Smoke Checks` -> `Run workflow`
+- Runs only when repository variable `KOSHA_PROVIDER_SMOKE_ENABLED=true`
+- Manual dispatch can override that gate with `force=true`
+- Installs with pnpm, builds, then runs a node inline smoke script against real provider endpoints
+- Providers without the required secrets are skipped instead of failing the job
+- Always uploads `artifacts/provider-smoke-report.json`
+
+Provider smoke secrets:
+
+- OpenAI: `OPENAI_API_KEY`
+- Google/Gemini: `GOOGLE_API_KEY` or `GEMINI_API_KEY`
+- Mistral: `MISTRAL_API_KEY`
+- DeepSeek: `DEEPSEEK_API_KEY`
+- Moonshot: `MOONSHOT_API_KEY` or `KIMI_API_KEY`
+- GLM: `GLM_API_KEY` or `ZHIPUAI_API_KEY`
+- Z.AI: `ZAI_API_KEY`
+- MiniMax: `MINIMAX_API_KEY`
+- OpenRouter: optional `OPENROUTER_API_KEY`
+- Bedrock: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`
+- Vertex AI: `GOOGLE_APPLICATION_CREDENTIALS_JSON`, `GOOGLE_CLOUD_PROJECT`
+
+Security controls in these workflows:
+
+- Snapshot workflow commits only the configured snapshot file path plus its checksum file, never broad `git add -A`
+- Snapshot workflow validates the generated snapshot against a local JSON schema before commit
+- Snapshot workflow runs a high-signal secret-pattern scan on snapshot output before commit
+- Snapshot workflow writes `data/kosha-latest.sha256` alongside the snapshot
+- Snapshot workflow uploads an always-on artifact with run metadata, provider summaries, and failure details
+- Provider smoke workflow never echoes secret values and records a machine-readable JSON report
+
+### Branch Protection Audit
+
+Workflow file: `.github/workflows/branch-protection-check.yml`
+
+- Runs on `main` and via `workflow_dispatch`
+- Reads the `main` branch protection rule through the GitHub API
+- Expects the required status checks list to include `Branch Protection Check / audit`
+- Uploads a warning artifact instead of failing when the token cannot read branch protection settings
+
+Keep that check name stable when you rename the workflow or job, and update the protection rule whenever you add more required checks.
+
+### Where Data Is Stored
+
+- Git repo: model/provider discovery data is **not** committed by default.
+- Runtime cache: `~/.kosha/cache/*.json` (machine-local, TTL-based).
+- Exported snapshot: only if you run `autofetch`/`autofetch:once` with an output file and commit it yourself.
+
+### HTTP API
+
+```bash
+kosha serve --port 3000
+```
+
+```
+GET /api/models                    — All models (filterable)
+GET /api/models/cheapest           — Cheapest ranked models
+GET /api/models/:idOrAlias         — Single model
+GET /api/models/:idOrAlias/routes  — All provider routes
+GET /api/roles                     — Provider → model → roles matrix
+GET /api/providers                 — All providers
+POST /api/refresh                  — Re-discover
+GET /health                        — Health check
+```
+
+## Supported Providers
+
+| Provider | Discovery | Credential Sources |
+|----------|-----------|-------------------|
+| Anthropic | API (`/v1/models`) | `ANTHROPIC_API_KEY`, Claude CLI, Codex CLI |
+| OpenAI | API (`/v1/models`) | `OPENAI_API_KEY`, GitHub Copilot tokens |
+| Google | API (`/v1beta/models`) | `GOOGLE_API_KEY`, `GEMINI_API_KEY`, Gemini CLI, gcloud |
+| AWS Bedrock | SDK → CLI → static | `AWS_ACCESS_KEY_ID`, `~/.aws/credentials`, SSO, IAM |
+| Vertex AI | API + gcloud | `GOOGLE_APPLICATION_CREDENTIALS`, gcloud ADC |
+| Ollama | Local API | None needed (local) |
+| OpenRouter | API | `OPENROUTER_API_KEY` (optional) |
+| NVIDIA | API | `NVIDIA_API_KEY` |
+| Together AI | API | `TOGETHER_API_KEY` |
+| Fireworks AI | API | `FIREWORKS_API_KEY` |
+| Groq | API | `GROQ_API_KEY` |
+| Mistral AI | API | `MISTRAL_API_KEY` |
+| DeepInfra | API | `DEEPINFRA_API_KEY` |
+| Cohere | API | `CO_API_KEY` |
+| Cerebras | API | `CEREBRAS_API_KEY` |
+| Perplexity | API | `PERPLEXITY_API_KEY` |
+| DeepSeek | API | `DEEPSEEK_API_KEY` |
+| Moonshot (Kimi) | API | `MOONSHOT_API_KEY` / `KIMI_API_KEY` |
+| GLM (Zhipu) | API | `GLM_API_KEY` / `ZHIPUAI_API_KEY` |
+| Z.AI | API | `ZAI_API_KEY` |
+| MiniMax | API | `MINIMAX_API_KEY` |
+
+## Security
+
+All external data (API responses, CLI output, cache reads) is scanned for 9 threat types before use: credential leaks, base64 payloads, script/shell injection, data URIs, null bytes, prototype pollution, hex blobs, and oversized strings. A pre-commit hook blocks secrets at commit time.
+
+See [docs/security.md](docs/security.md) for the full threat catalogue and architecture.
+
+## Architecture
+
+<p align="center">
+  <img src="architecture.svg" alt="Kosha Architecture" width="720" />
+</p>
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  Your Application                    │
+│        import { createKosha } from "kosha"          │
+└───────────────────────┬─────────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────────┐
+│                  ModelRegistry                        │
+│  models() · providerRoles() · cheapestModels()       │
+└──┬──────────┬──────────────┬───────────────┬────────┘
+   │          │              │               │
+┌──▼───┐ ┌───▼────────┐ ┌───▼──────────┐ ┌──▼─────────┐
+│Alias │ │ Discovery   │ │ Enrichment   │ │ Resilience  │
+│System│ │ Layer       │ │ Layer        │ │ Layer       │
+└──────┘ └───┬────────┘ └──────┬───────┘ └────────────┘
+             │                 │          CircuitBreaker
+    ┌────────┼────────┐        │          HealthTracker
+    ▼        ▼        ▼        ▼          StaleCachePolicy
+ Direct   OpenAI-   Cloud      litellm
+  API    Compatible  Proxies    JSON
+```
+
+## Documentation
+
+| Doc | What's in it |
+|-----|-------------|
+| [Credentials](docs/credentials.md) | Setup for all 21 providers (env vars, CLI tools, config files) |
+| [CLI Reference](docs/cli.md) | All commands, flags, and example output |
+| [HTTP API](docs/api.md) | All endpoints, parameters, and response schemas |
+| [Configuration](docs/configuration.md) | Aliases, routing, pricing enrichment, programmatic config |
+| [Architecture](docs/architecture.md) | Discovery flow, module map, data pipeline, adding providers |
+| [Resilience](docs/resilience.md) | Circuit breakers, stale cache fallback, health monitoring |
+| [Security](docs/security.md) | Threat catalogue, runtime scanning, pre-commit hook |
+| [Discovery Plane v1](docs/discovery-plane-v1.md) | Stable daemon contract (deltas, SSE watch, binding hints) |
+
+## Release & Tagging
+
+Package: `@sriinnu/kosha-discovery`
+
+This repo uses a human-in-the-loop release flow:
+
+1. Update version in `package.json` and lockfiles locally.
+2. Create a signed tag and push it:
+   ```bash
+   git tag -s v0.6.0 -m "v0.6.0"
+   git push origin v0.6.0
+   ```
+3. In GitHub Actions, run `Manual Release (Tag + npm)` and provide `tag=v0.6.0`.
+4. Workflow verifies tag/version match, builds/tests, then publishes to npm (if enabled) and creates a GitHub Release.
+
+Required secret for publish:
+- `NPM_TOKEN` (publish rights for `@sriinnu` scope)
+
+## Credits
+
+- **[litellm](https://github.com/BerriAI/litellm)** -- Community-maintained model pricing database
+- **[openrouter](https://openrouter.ai)** -- Model aggregation API
+- **[ollama](https://ollama.ai)** -- Local LLM runtime
+- **[chitragupta](https://github.com/sriinnu/chitragupta)** -- Autonomous AI Agent Platform whose registry patterns inspired kosha
+- **[takumi](https://github.com/sriinnu/takumi)** -- AI coding agent TUI whose routing needs drove kosha's creation
+
+## What "Kosha" Means
+
+`Kosha` comes from Sanskrit -- a container, treasury, or layered sheath of knowledge. A standalone model-discovery utility for any AI system.
+
+## License
+
+MIT

package/dist/aliases.d.ts

@@ -0,0 +1,51 @@
+/**
+ * kosha-discovery — Model alias resolution system.
+ *
+ * Provides short, memorable names that resolve to canonical model IDs.
+ * Built-in aliases are kept in sync with the latest model releases.
+ * @module
+ */
+/**
+ * Curated default aliases mapping short names to canonical model IDs.
+ *
+ * These are production-ready and cover the most commonly referenced
+ * models across major providers. Updated February 2026.
+ */
+export declare const DEFAULT_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Resolves short alias names to canonical model IDs.
+ *
+ * Built-in aliases from {@link DEFAULT_ALIASES} are merged with optional
+ * user-provided overrides, where user overrides take precedence.
+ */
+export declare class AliasResolver {
+    /** Internal map holding the merged alias -> canonical ID mappings. */
+    private aliases;
+    /**
+     * @param customAliases - Optional user overrides; these are merged on top
+     *                        of the built-in {@link DEFAULT_ALIASES} map.
+     */
+    constructor(customAliases?: Record<string, string>);
+    /**
+     * Resolve an alias to its canonical model ID.
+     * Returns the input unchanged if no matching alias is found.
+     */
+    resolve(nameOrAlias: string): string;
+    /**
+     * Find all aliases that point to the given canonical model ID.
+     */
+    reverseAliases(modelId: string): string[];
+    /**
+     * Add or overwrite an alias mapping.
+     */
+    addAlias(alias: string, modelId: string): void;
+    /**
+     * Remove an alias mapping.
+     */
+    removeAlias(alias: string): void;
+    /**
+     * Return a snapshot of the full alias map (defaults + custom).
+     */
+    all(): Record<string, string>;
+}
+//# sourceMappingURL=aliases.d.ts.map

package/dist/aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgD5D,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,aAAa;IACzB,sEAAsE;IACtE,OAAO,CAAC,OAAO,CAAsB;IAErC;;;OAGG;gBACS,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAUlD;;;OAGG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAIpC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAUzC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAI9C;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhC;;OAEG;IACH,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAG7B"}

package/dist/aliases.js

@@ -0,0 +1,115 @@
+/**
+ * kosha-discovery — Model alias resolution system.
+ *
+ * Provides short, memorable names that resolve to canonical model IDs.
+ * Built-in aliases are kept in sync with the latest model releases.
+ * @module
+ */
+/**
+ * Curated default aliases mapping short names to canonical model IDs.
+ *
+ * These are production-ready and cover the most commonly referenced
+ * models across major providers. Updated February 2026.
+ */
+export const DEFAULT_ALIASES = {
+    // ── Anthropic — Claude 4.6 family (latest as of Feb 2026) ──
+    "opus": "claude-opus-4-6",
+    "opus-4": "claude-opus-4-6",
+    "sonnet": "claude-sonnet-4-6",
+    "sonnet-4": "claude-sonnet-4-6",
+    "haiku": "claude-haiku-4-5-20251001",
+    "haiku-4.5": "claude-haiku-4-5-20251001",
+    // ── OpenAI — latest reasoning and chat models ──
+    "gpt4o": "gpt-4o",
+    "gpt4o-mini": "gpt-4o-mini",
+    "o1": "o1",
+    "o3": "o3",
+    "o3-mini": "o3-mini",
+    "o4-mini": "o4-mini",
+    // ── Google — Gemini 2.5 series ──
+    "gemini-pro": "gemini-2.5-pro-preview-05-06",
+    "gemini-flash": "gemini-2.5-flash-preview-04-17",
+    "gemini-flash-lite": "gemini-2.0-flash-lite",
+    // ── Local — latest popular open-weight models for Ollama ──
+    "qwen": "qwen3:8b",
+    "llama": "llama3.3:latest",
+    "codestral": "codestral:latest",
+    "deepseek": "deepseek-r1:latest",
+    // ── NVIDIA — Nemotron family via build.nvidia.com ──
+    "nemotron-ultra": "nvidia/llama-3.1-nemotron-ultra-253b-v1",
+    "nemotron-super": "nvidia/llama-3.1-nemotron-super-49b-v1",
+    "nemotron-nano": "nvidia/llama-3.1-nemotron-nano-8b-v1",
+    // ── Mistral AI — latest models ──
+    "mistral-large": "mistral-large-latest",
+    "mistral-small": "mistral-small-latest",
+    "mistral-codestral": "codestral-latest",
+    "pixtral": "pixtral-large-latest",
+    // ── Groq — fast inference ──
+    "groq-llama": "llama-3.3-70b-versatile",
+    "groq-mixtral": "mixtral-8x7b-32768",
+    // ── Embeddings — OpenAI, Nomic, and Google embedding models ──
+    "embed-small": "text-embedding-3-small",
+    "embed-large": "text-embedding-3-large",
+    "nomic": "nomic-embed-text",
+    "gemini-embed": "gemini-embedding-001",
+};
+/**
+ * Resolves short alias names to canonical model IDs.
+ *
+ * Built-in aliases from {@link DEFAULT_ALIASES} are merged with optional
+ * user-provided overrides, where user overrides take precedence.
+ */
+export class AliasResolver {
+    /** Internal map holding the merged alias -> canonical ID mappings. */
+    aliases;
+    /**
+     * @param customAliases - Optional user overrides; these are merged on top
+     *                        of the built-in {@link DEFAULT_ALIASES} map.
+     */
+    constructor(customAliases) {
+        this.aliases = new Map(Object.entries(DEFAULT_ALIASES));
+        if (customAliases) {
+            for (const [alias, modelId] of Object.entries(customAliases)) {
+                this.aliases.set(alias, modelId);
+            }
+        }
+    }
+    /**
+     * Resolve an alias to its canonical model ID.
+     * Returns the input unchanged if no matching alias is found.
+     */
+    resolve(nameOrAlias) {
+        return this.aliases.get(nameOrAlias) ?? nameOrAlias;
+    }
+    /**
+     * Find all aliases that point to the given canonical model ID.
+     */
+    reverseAliases(modelId) {
+        const result = [];
+        for (const [alias, target] of this.aliases) {
+            if (target === modelId) {
+                result.push(alias);
+            }
+        }
+        return result;
+    }
+    /**
+     * Add or overwrite an alias mapping.
+     */
+    addAlias(alias, modelId) {
+        this.aliases.set(alias, modelId);
+    }
+    /**
+     * Remove an alias mapping.
+     */
+    removeAlias(alias) {
+        this.aliases.delete(alias);
+    }
+    /**
+     * Return a snapshot of the full alias map (defaults + custom).
+     */
+    all() {
+        return Object.fromEntries(this.aliases);
+    }
+}
+//# sourceMappingURL=aliases.js.map

package/dist/aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases.js","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqC;IAChE,8DAA8D;IAC9D,MAAM,EAAE,iBAAiB;IACzB,QAAQ,EAAE,iBAAiB;IAC3B,QAAQ,EAAE,mBAAmB;IAC7B,UAAU,EAAE,mBAAmB;IAC/B,OAAO,EAAE,2BAA2B;IACpC,WAAW,EAAE,2BAA2B;IAExC,kDAAkD;IAClD,OAAO,EAAE,QAAQ;IACjB,YAAY,EAAE,aAAa;IAC3B,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;IACV,SAAS,EAAE,SAAS;IACpB,SAAS,EAAE,SAAS;IAEpB,mCAAmC;IACnC,YAAY,EAAE,8BAA8B;IAC5C,cAAc,EAAE,gCAAgC;IAChD,mBAAmB,EAAE,uBAAuB;IAE5C,6DAA6D;IAC7D,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,iBAAiB;IAC1B,WAAW,EAAE,kBAAkB;IAC/B,UAAU,EAAE,oBAAoB;IAEhC,sDAAsD;IACtD,gBAAgB,EAAE,yCAAyC;IAC3D,gBAAgB,EAAE,wCAAwC;IAC1D,eAAe,EAAE,sCAAsC;IAEvD,mCAAmC;IACnC,eAAe,EAAE,sBAAsB;IACvC,eAAe,EAAE,sBAAsB;IACvC,mBAAmB,EAAE,kBAAkB;IACvC,SAAS,EAAE,sBAAsB;IAEjC,8BAA8B;IAC9B,YAAY,EAAE,yBAAyB;IACvC,cAAc,EAAE,oBAAoB;IAEpC,gEAAgE;IAChE,aAAa,EAAE,wBAAwB;IACvC,aAAa,EAAE,wBAAwB;IACvC,OAAO,EAAE,kBAAkB;IAC3B,cAAc,EAAE,sBAAsB;CACtC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACzB,sEAAsE;IAC9D,OAAO,CAAsB;IAErC;;;OAGG;IACH,YAAY,aAAsC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;QAExD,IAAI,aAAa,EAAE,CAAC;YACnB,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC9D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAClC,CAAC;QACF,CAAC;IACF,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,WAAmB;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,OAAe;QAC7B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC5C,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;gBACxB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACF,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,KAAa,EAAE,OAAe;QACtC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,KAAa;QACxB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,GAAG;QACF,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;CACD"}

package/dist/cache.d.ts

@@ -0,0 +1,57 @@
+/**
+ * kosha-discovery — File-based JSON cache with TTL.
+ *
+ * Stores discovered provider data as individual JSON files on disk
+ * to avoid re-fetching from provider APIs on every startup.
+ * Each cache key maps to a `{key}.json` file inside the cache directory.
+ * @module
+ */
+interface CacheEntry<T> {
+    data: T;
+    timestamp: number;
+}
+/**
+ * Simple file-based JSON cache with TTL support.
+ * Stores discovered provider data to avoid re-fetching on every startup.
+ *
+ * Each cache key maps to a `{key}.json` file inside the cache directory.
+ */
+export declare class KoshaCache {
+    private readonly cacheDir;
+    constructor(cacheDir?: string);
+    /**
+     * Retrieve cached data by key.
+     * Returns null if the entry is missing or the file cannot be read.
+     */
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * Write data to the cache under the given key.
+     *
+     * Uses atomic write (temp file + rename) so a crash mid-write
+     * cannot leave a corrupted cache file behind.
+     */
+    set<T>(key: string, data: T): Promise<void>;
+    /**
+     * Remove a single cached entry by key.
+     */
+    invalidate(key: string): Promise<void>;
+    /**
+     * Remove all cache files from the cache directory.
+     */
+    clear(): Promise<void>;
+    /**
+     * Check whether a cached timestamp has exceeded the given TTL.
+     */
+    isExpired(timestamp: number, ttlMs: number): boolean;
+    /**
+     * Sanitize a cache key into a safe filename and return the full path.
+     * Replaces any character that is not alphanumeric, dash, or underscore with an underscore.
+     */
+    private keyToPath;
+    /**
+     * Ensure the cache directory exists, creating it recursively if needed.
+     */
+    private ensureDir;
+}
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,UAAU,UAAU,CAAC,CAAC;IACrB,IAAI,EAAE,CAAC,CAAC;IACR,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,CAAC,EAAE,MAAM;IAI7B;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmBxD;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBjD;;OAEG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAQpD;;;OAGG;IACH,OAAO,CAAC,SAAS;IAKjB;;OAEG;YACW,SAAS;CAGvB"}

package/dist/cache.js

@@ -0,0 +1,123 @@
+/**
+ * kosha-discovery — File-based JSON cache with TTL.
+ *
+ * Stores discovered provider data as individual JSON files on disk
+ * to avoid re-fetching from provider APIs on every startup.
+ * Each cache key maps to a `{key}.json` file inside the cache directory.
+ * @module
+ */
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "fs/promises";
+import { randomBytes } from "crypto";
+import { homedir } from "os";
+import { join } from "path";
+import { assertCleanPayload } from "./security.js";
+/**
+ * Simple file-based JSON cache with TTL support.
+ * Stores discovered provider data to avoid re-fetching on every startup.
+ *
+ * Each cache key maps to a `{key}.json` file inside the cache directory.
+ */
+export class KoshaCache {
+    cacheDir;
+    constructor(cacheDir) {
+        this.cacheDir = cacheDir ?? join(homedir(), ".kosha", "cache");
+    }
+    /**
+     * Retrieve cached data by key.
+     * Returns null if the entry is missing or the file cannot be read.
+     */
+    async get(key) {
+        try {
+            const filePath = this.keyToPath(key);
+            const raw = await readFile(filePath, "utf-8");
+            const entry = JSON.parse(raw);
+            assertCleanPayload(entry, `cache/${key}`);
+            return entry;
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.startsWith("Rejected")) {
+                // Security violation — poisoned cache file. Log loudly, invalidate, return miss.
+                console.error(`KoshaCache SECURITY: ${err.message}`);
+                await this.invalidate(key);
+            }
+            else if (err instanceof SyntaxError) {
+                console.warn(`KoshaCache: corrupted cache file for key "${key}"`);
+            }
+            return null;
+        }
+    }
+    /**
+     * Write data to the cache under the given key.
+     *
+     * Uses atomic write (temp file + rename) so a crash mid-write
+     * cannot leave a corrupted cache file behind.
+     */
+    async set(key, data) {
+        await this.ensureDir();
+        const entry = {
+            data,
+            timestamp: Date.now(),
+        };
+        const filePath = this.keyToPath(key);
+        const tmpPath = `${filePath}.${randomBytes(4).toString("hex")}.tmp`;
+        try {
+            await writeFile(tmpPath, JSON.stringify(entry, null, "\t"), "utf-8");
+            await rename(tmpPath, filePath);
+        }
+        catch (err) {
+            await unlink(tmpPath).catch(() => { });
+            throw err;
+        }
+    }
+    /**
+     * Remove a single cached entry by key.
+     */
+    async invalidate(key) {
+        try {
+            const filePath = this.keyToPath(key);
+            await unlink(filePath);
+        }
+        catch {
+            // Ignore if file doesn't exist
+        }
+    }
+    /**
+     * Remove all cache files from the cache directory.
+     */
+    async clear() {
+        try {
+            const files = await readdir(this.cacheDir);
+            const removals = files
+                .filter((f) => f.endsWith(".json"))
+                .map((f) => unlink(join(this.cacheDir, f)).catch(() => { }));
+            await Promise.all(removals);
+        }
+        catch {
+            // Directory may not exist yet
+        }
+    }
+    /**
+     * Check whether a cached timestamp has exceeded the given TTL.
+     */
+    isExpired(timestamp, ttlMs) {
+        return Date.now() - timestamp > ttlMs;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Sanitize a cache key into a safe filename and return the full path.
+     * Replaces any character that is not alphanumeric, dash, or underscore with an underscore.
+     */
+    keyToPath(key) {
+        const safeKey = key.replace(/[^a-zA-Z0-9\-_]/g, "_");
+        return join(this.cacheDir, `${safeKey}.json`);
+    }
+    /**
+     * Ensure the cache directory exists, creating it recursively if needed.
+     */
+    async ensureDir() {
+        await mkdir(this.cacheDir, { recursive: true });
+    }
+}
+//# sourceMappingURL=cache.js.map