@mcptoolshop/ai-loadout 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.0.1 — 2026-03-06
+
+- Add `hint` field to `ValidationIssue` (Tier 1 error shape compliance)
+- Add hints to key validation issues (MISSING_ID, MISSING_PATH, EMPTY_KEYWORDS)
+- Add SECURITY.md with threat model
+- Expand README security section with threat model table
+- Add logo
+- Include SECURITY.md and logo.png in npm package
+
 ## 1.0.0 — 2026-03-06
 
 Initial release.

package/README.es.md

@@ -0,0 +1,196 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a> | <a href="README.ja.md">日本語</a>
+</p>
+
+<p align="center">
+  <img src="logo.png" width="400" alt="ai-loadout">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/ai-loadout/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/ai-loadout/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/ai-loadout"><img src="https://img.shields.io/npm/v/@mcptoolshop/ai-loadout" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="Licencia MIT"></a>
+</p>
+
+Enrutador de conocimiento contextual para agentes de IA.
+
+`ai-loadout` es el formato de tabla de despacho y motor de coincidencia que permite a los agentes de IA cargar el conocimiento adecuado para la tarea en cuestión. En lugar de volcar todo en el contexto, mantienes un índice pequeño y cargas los contenidos bajo demanda.
+
+Piensa en ello como un equipamiento de videojuego — equipas al agente con exactamente el conocimiento que necesita antes de cada misión.
+
+## Instalación
+
+```bash
+npm install @mcptoolshop/ai-loadout
+```
+
+## Conceptos Fundamentales
+
+### La Tabla de Despacho
+
+Un `LoadoutIndex` es un índice estructurado de contenidos de conocimiento:
+
+```json
+{
+  "version": "1.0.0",
+  "generated": "2026-03-06T12:00:00Z",
+  "entries": [
+    {
+      "id": "github-actions",
+      "path": ".rules/github-actions.md",
+      "keywords": ["ci", "workflow", "runner"],
+      "patterns": ["ci_pipeline"],
+      "priority": "domain",
+      "summary": "CI triggers, path gating, runner cost control",
+      "triggers": { "task": true, "plan": true, "edit": false },
+      "tokens_est": 680,
+      "lines": 56
+    }
+  ],
+  "budget": {
+    "always_loaded_est": 320,
+    "on_demand_total_est": 8100,
+    "avg_task_load_est": 520,
+    "avg_task_load_observed": null
+  }
+}
+```
+
+### Niveles de Prioridad
+
+| Nivel | Comportamiento | Ejemplo |
+|-------|---------------|---------|
+| `core` | Siempre cargado | "nunca omitas tests para que CI pase" |
+| `domain` | Cargado cuando las palabras clave de la tarea coinciden | Reglas de CI al editar workflows |
+| `manual` | Nunca se carga automáticamente, solo búsqueda explícita | Problemas oscuros de plataforma |
+
+### Frontmatter del Contenido
+
+Cada archivo de contenido lleva sus propios metadatos de enrutamiento:
+
+```markdown
+---
+id: github-actions
+keywords: [ci, workflow, runner, dependabot]
+patterns: [ci_pipeline]
+priority: domain
+triggers:
+  task: true
+  plan: true
+  edit: false
+---
+
+# GitHub Actions Rules
+CI minutes are finite...
+```
+
+El frontmatter es la fuente de verdad. El índice se deriva de él.
+
+## API
+
+### `matchLoadout(task, index)`
+
+Compara una descripción de tarea contra un índice de loadout. Devuelve las entradas que deben cargarse, ordenadas por fuerza de coincidencia.
+
+```typescript
+import { matchLoadout } from "@mcptoolshop/ai-loadout";
+
+const results = matchLoadout("fix the CI workflow", index);
+// [{ entry: { id: "github-actions", ... }, score: 0.67, matchedKeywords: ["ci", "workflow"] }]
+```
+
+- Las entradas core siempre se incluyen (puntuación 1.0)
+- Las entradas manual nunca se incluyen automáticamente
+- Las entradas domain se puntúan por coincidencia de palabras clave + bonificación de patrón
+- Los resultados se ordenan por puntuación descendente
+
+### `lookupEntry(id, index)`
+
+Busca una entrada específica por ID. Para entradas manuales o acceso explícito.
+
+```typescript
+import { lookupEntry } from "@mcptoolshop/ai-loadout";
+
+const entry = lookupEntry("github-actions", index);
+```
+
+### `parseFrontmatter(content)`
+
+Analiza el frontmatter tipo YAML de un archivo de contenido.
+
+```typescript
+import { parseFrontmatter } from "@mcptoolshop/ai-loadout";
+
+const { frontmatter, body } = parseFrontmatter(fileContent);
+if (frontmatter) {
+  console.log(frontmatter.id, frontmatter.keywords);
+}
+```
+
+### `serializeFrontmatter(fm)`
+
+Serializa un objeto `Frontmatter` de vuelta a cadena de texto.
+
+### `validateIndex(index)`
+
+Valida la integridad estructural de un `LoadoutIndex`. Devuelve un arreglo de problemas.
+
+```typescript
+import { validateIndex } from "@mcptoolshop/ai-loadout";
+
+const issues = validateIndex(index);
+const errors = issues.filter(i => i.severity === "error");
+if (errors.length > 0) {
+  console.error("Index has errors:", errors);
+}
+```
+
+Verifica: campos requeridos, IDs únicos, formato kebab-case, límites de resumen, presencia de palabras clave para entradas domain, prioridades válidas, presupuestos no negativos.
+
+### `estimateTokens(text)`
+
+Estima el conteo de tokens de un texto. Usa la heurística de caracteres/4.
+
+```typescript
+import { estimateTokens } from "@mcptoolshop/ai-loadout";
+
+const tokens = estimateTokens(fileContent); // ~250
+```
+
+## Tipos
+
+```typescript
+import type {
+  LoadoutEntry,
+  LoadoutIndex,
+  Frontmatter,
+  MatchResult,
+  ValidationIssue,
+  Priority,       // "core" | "domain" | "manual"
+  Triggers,       // { task, plan, edit }
+  Budget,
+} from "@mcptoolshop/ai-loadout";
+```
+
+## Consumidores
+
+- **[@mcptoolshop/claude-rules](https://github.com/mcp-tool-shop-org/claude-rules)** — Optimizador de CLAUDE.md para Claude Code. Usa ai-loadout para la tabla de despacho y el motor de coincidencia.
+
+## Seguridad
+
+Este paquete es una biblioteca de datos pura. No accede al sistema de archivos, no realiza solicitudes de red ni recopila telemetría. Todo el I/O es responsabilidad del consumidor.
+
+### Modelo de Amenazas
+
+| Amenaza | Mitigación |
+|---------|------------|
+| Entrada de frontmatter malformado | `parseFrontmatter()` devuelve `null` ante entrada inválida — sin excepciones, sin eval |
+| Contaminación de prototipo | El parser manual usa literales de objeto planos, sin `JSON.parse` de estructuras anidadas no confiables |
+| Índice con datos incorrectos | `validateIndex()` detecta problemas estructurales antes de que se propaguen |
+| DoS por Regex | Sin regex proporcionado por el usuario — los patrones se comparan como búsquedas de texto plano |
+
+Consulta [SECURITY.md](SECURITY.md) para la política de seguridad completa.
+
+---
+
+Creado por [MCP Tool Shop](https://mcp-tool-shop.github.io/)

package/README.fr.md

@@ -0,0 +1,196 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a> | <a href="README.ja.md">日本語</a>
+</p>
+
+<p align="center">
+  <img src="logo.png" width="400" alt="ai-loadout">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/ai-loadout/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/ai-loadout/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/ai-loadout"><img src="https://img.shields.io/npm/v/@mcptoolshop/ai-loadout" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="Licence MIT"></a>
+</p>
+
+Routeur de connaissances contextuel pour agents IA.
+
+`ai-loadout` est le format de table de dispatch et le moteur de correspondance qui permet aux agents IA de charger les bonnes connaissances pour la tache en cours. Au lieu de tout charger dans le contexte, vous gardez un petit index et chargez les contenus a la demande.
+
+Pensez-y comme un equipement de jeu video — vous equipez l'agent avec exactement les connaissances dont il a besoin avant chaque mission.
+
+## Installation
+
+```bash
+npm install @mcptoolshop/ai-loadout
+```
+
+## Concepts Fondamentaux
+
+### La Table de Dispatch
+
+Un `LoadoutIndex` est un index structure de contenus de connaissances :
+
+```json
+{
+  "version": "1.0.0",
+  "generated": "2026-03-06T12:00:00Z",
+  "entries": [
+    {
+      "id": "github-actions",
+      "path": ".rules/github-actions.md",
+      "keywords": ["ci", "workflow", "runner"],
+      "patterns": ["ci_pipeline"],
+      "priority": "domain",
+      "summary": "CI triggers, path gating, runner cost control",
+      "triggers": { "task": true, "plan": true, "edit": false },
+      "tokens_est": 680,
+      "lines": 56
+    }
+  ],
+  "budget": {
+    "always_loaded_est": 320,
+    "on_demand_total_est": 8100,
+    "avg_task_load_est": 520,
+    "avg_task_load_observed": null
+  }
+}
+```
+
+### Niveaux de Priorite
+
+| Niveau | Comportement | Exemple |
+|--------|-------------|---------|
+| `core` | Toujours charge | "ne jamais ignorer les tests pour faire passer la CI" |
+| `domain` | Charge quand les mots-cles de la tache correspondent | Regles CI lors de l'edition de workflows |
+| `manual` | Jamais charge automatiquement, consultation explicite uniquement | Problemes obscurs de plateforme |
+
+### Frontmatter du Contenu
+
+Chaque fichier de contenu porte ses propres metadonnees de routage :
+
+```markdown
+---
+id: github-actions
+keywords: [ci, workflow, runner, dependabot]
+patterns: [ci_pipeline]
+priority: domain
+triggers:
+  task: true
+  plan: true
+  edit: false
+---
+
+# GitHub Actions Rules
+CI minutes are finite...
+```
+
+Le frontmatter est la source de verite. L'index en est derive.
+
+## API
+
+### `matchLoadout(task, index)`
+
+Compare une description de tache avec un index de loadout. Retourne les entrees qui doivent etre chargees, classees par force de correspondance.
+
+```typescript
+import { matchLoadout } from "@mcptoolshop/ai-loadout";
+
+const results = matchLoadout("fix the CI workflow", index);
+// [{ entry: { id: "github-actions", ... }, score: 0.67, matchedKeywords: ["ci", "workflow"] }]
+```
+
+- Les entrees core sont toujours incluses (score 1.0)
+- Les entrees manual ne sont jamais incluses automatiquement
+- Les entrees domain sont notees par chevauchement de mots-cles + bonus de patron
+- Les resultats sont tries par score decroissant
+
+### `lookupEntry(id, index)`
+
+Recherche une entree specifique par ID. Pour les entrees manuelles ou l'acces explicite.
+
+```typescript
+import { lookupEntry } from "@mcptoolshop/ai-loadout";
+
+const entry = lookupEntry("github-actions", index);
+```
+
+### `parseFrontmatter(content)`
+
+Analyse le frontmatter de type YAML d'un fichier de contenu.
+
+```typescript
+import { parseFrontmatter } from "@mcptoolshop/ai-loadout";
+
+const { frontmatter, body } = parseFrontmatter(fileContent);
+if (frontmatter) {
+  console.log(frontmatter.id, frontmatter.keywords);
+}
+```
+
+### `serializeFrontmatter(fm)`
+
+Serialise un objet `Frontmatter` en chaine de caracteres.
+
+### `validateIndex(index)`
+
+Valide l'integrite structurelle d'un `LoadoutIndex`. Retourne un tableau de problemes.
+
+```typescript
+import { validateIndex } from "@mcptoolshop/ai-loadout";
+
+const issues = validateIndex(index);
+const errors = issues.filter(i => i.severity === "error");
+if (errors.length > 0) {
+  console.error("Index has errors:", errors);
+}
+```
+
+Verifie : champs requis, IDs uniques, format kebab-case, limites de resume, presence de mots-cles pour les entrees domain, priorites valides, budgets non negatifs.
+
+### `estimateTokens(text)`
+
+Estime le nombre de tokens d'un texte. Utilise l'heuristique caracteres/4.
+
+```typescript
+import { estimateTokens } from "@mcptoolshop/ai-loadout";
+
+const tokens = estimateTokens(fileContent); // ~250
+```
+
+## Types
+
+```typescript
+import type {
+  LoadoutEntry,
+  LoadoutIndex,
+  Frontmatter,
+  MatchResult,
+  ValidationIssue,
+  Priority,       // "core" | "domain" | "manual"
+  Triggers,       // { task, plan, edit }
+  Budget,
+} from "@mcptoolshop/ai-loadout";
+```
+
+## Consommateurs
+
+- **[@mcptoolshop/claude-rules](https://github.com/mcp-tool-shop-org/claude-rules)** — Optimiseur de CLAUDE.md pour Claude Code. Utilise ai-loadout pour la table de dispatch et la correspondance.
+
+## Securite
+
+Ce paquet est une bibliotheque de donnees pure. Il n'accede pas au systeme de fichiers, ne fait pas de requetes reseau et ne collecte pas de telemetrie. Toutes les operations d'E/S sont de la responsabilite du consommateur.
+
+### Modele de Menaces
+
+| Menace | Attenuation |
+|--------|-------------|
+| Entree de frontmatter malformee | `parseFrontmatter()` retourne `null` sur une entree invalide — pas d'exceptions, pas d'eval |
+| Pollution de prototype | Le parser manuel utilise des litteraux d'objet simples, pas de `JSON.parse` de structures imbriquees non fiables |
+| Index avec des donnees incorrectes | `validateIndex()` detecte les problemes structurels avant qu'ils ne se propagent |
+| DoS par Regex | Pas de regex fournie par l'utilisateur — les patrons sont compares comme des recherches de texte brut |
+
+Consultez [SECURITY.md](SECURITY.md) pour la politique de securite complete.
+
+---
+
+Cree par [MCP Tool Shop](https://mcp-tool-shop.github.io/)

package/README.hi.md

@@ -0,0 +1,196 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a> | <a href="README.ja.md">日本語</a>
+</p>
+
+<p align="center">
+  <img src="logo.png" width="400" alt="ai-loadout">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/ai-loadout/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/ai-loadout/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/ai-loadout"><img src="https://img.shields.io/npm/v/@mcptoolshop/ai-loadout" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT लाइसेंस"></a>
+</p>
+
+AI एजेंटों के लिए संदर्भ-जागरूक ज्ञान राउटर।
+
+`ai-loadout` एक डिस्पैच टेबल फॉर्मैट और मैचिंग इंजन है जो AI एजेंटों को कार्य के अनुसार सही ज्ञान लोड करने देता है। सब कुछ संदर्भ में डालने के बजाय, आप एक छोटा इंडेक्स रखते हैं और आवश्यकतानुसार पेलोड लोड करते हैं।
+
+इसे एक वीडियो गेम लोडआउट की तरह समझें — आप हर मिशन से पहले एजेंट को ठीक उतना ज्ञान देते हैं जितना उसे चाहिए।
+
+## इंस्टॉलेशन
+
+```bash
+npm install @mcptoolshop/ai-loadout
+```
+
+## मूल अवधारणाएं
+
+### डिस्पैच टेबल
+
+एक `LoadoutIndex` ज्ञान पेलोड का एक संरचित इंडेक्स है:
+
+```json
+{
+  "version": "1.0.0",
+  "generated": "2026-03-06T12:00:00Z",
+  "entries": [
+    {
+      "id": "github-actions",
+      "path": ".rules/github-actions.md",
+      "keywords": ["ci", "workflow", "runner"],
+      "patterns": ["ci_pipeline"],
+      "priority": "domain",
+      "summary": "CI triggers, path gating, runner cost control",
+      "triggers": { "task": true, "plan": true, "edit": false },
+      "tokens_est": 680,
+      "lines": 56
+    }
+  ],
+  "budget": {
+    "always_loaded_est": 320,
+    "on_demand_total_est": 8100,
+    "avg_task_load_est": 520,
+    "avg_task_load_observed": null
+  }
+}
+```
+
+### प्राथमिकता स्तर
+
+| स्तर | व्यवहार | उदाहरण |
+|------|---------|--------|
+| `core` | हमेशा लोड | "CI पास करने के लिए कभी टेस्ट न छोड़ें" |
+| `domain` | कार्य के कीवर्ड मैच होने पर लोड | workflows संपादित करते समय CI नियम |
+| `manual` | कभी स्वचालित लोड नहीं, केवल स्पष्ट लुकअप | अस्पष्ट प्लेटफॉर्म समस्याएं |
+
+### पेलोड Frontmatter
+
+प्रत्येक पेलोड फ़ाइल अपने स्वयं के राउटिंग मेटाडेटा रखती है:
+
+```markdown
+---
+id: github-actions
+keywords: [ci, workflow, runner, dependabot]
+patterns: [ci_pipeline]
+priority: domain
+triggers:
+  task: true
+  plan: true
+  edit: false
+---
+
+# GitHub Actions Rules
+CI minutes are finite...
+```
+
+Frontmatter सत्य का स्रोत है। इंडेक्स इससे व्युत्पन्न होता है।
+
+## API
+
+### `matchLoadout(task, index)`
+
+एक कार्य विवरण को loadout इंडेक्स से मिलाता है। वे प्रविष्टियां लौटाता है जो लोड होनी चाहिए, मैच शक्ति के अनुसार क्रमबद्ध।
+
+```typescript
+import { matchLoadout } from "@mcptoolshop/ai-loadout";
+
+const results = matchLoadout("fix the CI workflow", index);
+// [{ entry: { id: "github-actions", ... }, score: 0.67, matchedKeywords: ["ci", "workflow"] }]
+```
+
+- Core प्रविष्टियां हमेशा शामिल (स्कोर 1.0)
+- Manual प्रविष्टियां कभी स्वचालित रूप से शामिल नहीं
+- Domain प्रविष्टियां कीवर्ड ओवरलैप + पैटर्न बोनस द्वारा स्कोर
+- परिणाम स्कोर के अनुसार अवरोही क्रम में
+
+### `lookupEntry(id, index)`
+
+ID द्वारा एक विशिष्ट प्रविष्टि खोजता है। मैनुअल प्रविष्टियों या स्पष्ट पहुंच के लिए।
+
+```typescript
+import { lookupEntry } from "@mcptoolshop/ai-loadout";
+
+const entry = lookupEntry("github-actions", index);
+```
+
+### `parseFrontmatter(content)`
+
+एक पेलोड फ़ाइल से YAML-जैसा frontmatter पार्स करता है।
+
+```typescript
+import { parseFrontmatter } from "@mcptoolshop/ai-loadout";
+
+const { frontmatter, body } = parseFrontmatter(fileContent);
+if (frontmatter) {
+  console.log(frontmatter.id, frontmatter.keywords);
+}
+```
+
+### `serializeFrontmatter(fm)`
+
+एक `Frontmatter` ऑब्जेक्ट को वापस स्ट्रिंग में सीरियलाइज़ करता है।
+
+### `validateIndex(index)`
+
+एक `LoadoutIndex` की संरचनात्मक अखंडता की जांच करता है। समस्याओं की एक सूची लौटाता है।
+
+```typescript
+import { validateIndex } from "@mcptoolshop/ai-loadout";
+
+const issues = validateIndex(index);
+const errors = issues.filter(i => i.severity === "error");
+if (errors.length > 0) {
+  console.error("Index has errors:", errors);
+}
+```
+
+जांचता है: आवश्यक फ़ील्ड, अद्वितीय ID, kebab-case प्रारूप, सारांश सीमाएं, domain प्रविष्टियों के लिए कीवर्ड उपस्थिति, मान्य प्राथमिकताएं, गैर-नकारात्मक बजट।
+
+### `estimateTokens(text)`
+
+टेक्स्ट से टोकन गणना का अनुमान लगाता है। अक्षर/4 ह्यूरिस्टिक का उपयोग करता है।
+
+```typescript
+import { estimateTokens } from "@mcptoolshop/ai-loadout";
+
+const tokens = estimateTokens(fileContent); // ~250
+```
+
+## टाइप्स
+
+```typescript
+import type {
+  LoadoutEntry,
+  LoadoutIndex,
+  Frontmatter,
+  MatchResult,
+  ValidationIssue,
+  Priority,       // "core" | "domain" | "manual"
+  Triggers,       // { task, plan, edit }
+  Budget,
+} from "@mcptoolshop/ai-loadout";
+```
+
+## उपभोक्ता
+
+- **[@mcptoolshop/claude-rules](https://github.com/mcp-tool-shop-org/claude-rules)** — Claude Code के लिए CLAUDE.md ऑप्टिमाइज़र। डिस्पैच टेबल और मैचिंग के लिए ai-loadout का उपयोग करता है।
+
+## सुरक्षा
+
+यह पैकेज एक शुद्ध डेटा लाइब्रेरी है। यह फ़ाइल सिस्टम तक नहीं पहुंचता, नेटवर्क अनुरोध नहीं करता और टेलीमेट्री एकत्र नहीं करता। सभी I/O उपभोक्ता की जिम्मेदारी है।
+
+### खतरा मॉडल
+
+| खतरा | शमन |
+|------|------|
+| विकृत frontmatter इनपुट | `parseFrontmatter()` अमान्य इनपुट पर `null` लौटाता है — कोई अपवाद नहीं, कोई eval नहीं |
+| प्रोटोटाइप प्रदूषण | मैनुअल पार्सर सादे ऑब्जेक्ट लिटरल का उपयोग करता है, अविश्वसनीय नेस्टेड संरचनाओं का `JSON.parse` नहीं |
+| खराब डेटा वाला इंडेक्स | `validateIndex()` संरचनात्मक समस्याओं को फैलने से पहले पकड़ता है |
+| Regex DoS | कोई उपयोगकर्ता-प्रदत्त regex नहीं — पैटर्न सादे स्ट्रिंग लुकअप के रूप में मिलाए जाते हैं |
+
+पूर्ण सुरक्षा नीति के लिए [SECURITY.md](SECURITY.md) देखें।
+
+---
+
+[MCP Tool Shop](https://mcp-tool-shop.github.io/) द्वारा निर्मित