@mcptoolshop/roll 1.0.0

package/README.pt-BR.md

@@ -0,0 +1,204 @@
+<p align="center">
+  <a href="README.ja.md">日本語</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.md">English</a>
+</p>
+
+<p align="center"><img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/roll/readme.png" width="400" alt="Roll"></p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/roll/actions"><img src="https://github.com/mcp-tool-shop-org/roll/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+  <a href="https://mcp-tool-shop-org.github.io/roll/"><img src="https://img.shields.io/badge/Landing_Page-online-brightgreen" alt="Landing Page"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/roll"><img src="https://img.shields.io/npm/v/@mcptoolshop/roll" alt="npm version"></a>
+</p>
+
+<p align="center">RPG dice engine with probability analysis, loot tables, and beautiful terminal output.</p>
+
+```
+npx @mcptoolshop/roll 4d6dl1 --analyze
+```
+
+```
+  Distribution
+
+   3    0.08%
+   4 █   0.31%
+   5 ███   0.77%
+   6 ███████   1.62%
+   7 █████████████   2.93%
+   8 ██████████████████████   4.78%
+   9 ████████████████████████████████   7.02%
+  10 ███████████████████████████████████████████   9.41%
+  11 ████████████████████████████████████████████████████  11.42%
+  12 ██████████████████████████████████████████████████████████  12.89%
+  13 ████████████████████████████████████████████████████████████  13.27%
+  14 ████████████████████████████████████████████████████████  12.35%
+  15 ██████████████████████████████████████████████  10.11%
+  16 █████████████████████████████████   7.25%
+  17 ███████████████████   4.17%
+  18 ███████   1.62%
+
+┌─ Statistics ─────────────────────────────────┐
+│ Mean:    12.24                                │
+│ Median:  12                                   │
+│ Mode:    13                                   │
+│ Std Dev: 2.85                                 │
+│ Range:   3–18                                 │
+│ Entropy: 3.53 bits                            │
+│                                               │
+│ Percentiles:                                  │
+│   p10:8  p25:10  p50:12  p75:14  p90:16  p95:17│
+└───────────────────────────────────────────────┘
+```
+
+## Instalação
+
+```bash
+npm install @mcptoolshop/roll
+```
+
+Requer Node.js >= 22.
+
+## Uso da Linha de Comando
+
+### Lançar dados
+
+```bash
+roll 2d6+3
+roll d20+5
+roll 4d6kh3
+roll 1d6!
+roll d%
+roll 4dF
+roll "(2d6+3)*2"
+```
+
+### Analisar probabilidade
+
+```bash
+roll 2d6 --analyze          # Full distribution + statistics
+roll d20+5 --at-least 15    # P(result >= 15)
+```
+
+### Comparar distribuições
+
+```bash
+roll --compare "4d6dl1" "3d6"
+```
+
+Estatísticas lado a lado (média, mediana, moda, desvio padrão, intervalo, entropia) com coluna de diferença, além de ambos os histogramas.
+
+### Tabelas de recompensas
+
+```bash
+roll --loot treasure.json
+```
+
+Formato JSON:
+
+```json
+{
+  "tables": [
+    {
+      "table": "Treasure",
+      "items": [
+        { "name": "Gold", "weight": 40, "roll": "2d6*10" },
+        { "name": "Potion of Healing", "weight": 30 },
+        { "name": "Scroll", "weight": 15, "quantity": "1d3" },
+        { "name": "Rare Item", "weight": 5, "table": "Rare Weapons" }
+      ]
+    },
+    {
+      "table": "Rare Weapons",
+      "items": [
+        { "name": "Vorpal Blade", "weight": 5 },
+        { "name": "Frost Brand", "weight": 25 }
+      ]
+    }
+  ]
+}
+```
+
+Características: seleção ponderada, referências de tabelas aninhadas, expressões de dados para quantidade e valor.
+
+### Outras opções
+
+```bash
+roll 2d6+3 --times 5       # Roll 5 times
+roll 2d6+3 --json           # Machine-readable output
+roll --help                 # Full usage
+roll --version              # Version
+```
+
+## Notação de Dados
+
+| Notação | Significado |
+|----------|---------|
+| `2d6` | Lançar 2 dados de seis lados |
+| `d20` | Lançar 1 dado de vinte lados |
+| `4d6kh3` | Lançar 4d6, manter os 3 maiores |
+| `4d6dl1` | Lançar 4d6, descartar o menor |
+| `1d6!` | Dado explosivo (relançar no máximo, adicionar) |
+| `1d6!>4` | Explodir em 4 ou mais |
+| `d%` | Dado de percentil (1-100) |
+| `4dF` | Dados Fate/Fudge (-1, 0, +1 cada) |
+| `(2d6+3)*2` | Aritmética com agrupamento |
+| `2d6+1d4+3` | Expressões encadeadas |
+
+## API da Biblioteca
+
+```typescript
+import { roll, analyze, parse, evaluate, computeDistribution } from '@mcptoolshop/roll';
+
+// Quick roll
+const result = roll('4d6kh3');
+console.log(result.total);        // 14
+console.log(result.groups[0].dice); // per-die breakdown
+
+// Full analysis
+const analysis = analyze('2d6+3');
+console.log(analysis.stats.mean);                  // 10
+console.log(analysis.stats.percentiles[95]);        // 14
+console.log(analysis.probabilityAtLeast(12));       // 0.2778
+
+// Low-level: parse → AST → evaluate
+import { seededRng } from '@mcptoolshop/roll';
+const ast = parse('4d6dl1');
+const r = evaluate(ast, seededRng(42));  // deterministic
+
+// Loot tables
+import { rollLootTable } from '@mcptoolshop/roll';
+const tables = [{ table: "Loot", items: [{ name: "Gold", weight: 50, roll: "2d6*10" }] }];
+const drops = rollLootTable(tables);
+```
+
+## Motor de Probabilidade
+
+- **Distribuições exatas** via convolução polinomial para NdM básicos
+- **Enumeração completa** para mecânicas de manter/descartar (4d6 = 1.296 estados)
+- **Recursão truncada** para dados explosivos (limitado a 10 explosões)
+- **Fallback de Monte Carlo** (100 mil amostras) quando o cálculo exato excede 10 milhões de estados
+
+## Sem Dependências
+
+Construído inteiramente com os recursos nativos do Node.js 22+:
+- `util.styleText` para cores no terminal
+- `util.parseArgs` para análise de argumentos da linha de comando
+- `crypto.randomInt` para geração de números aleatórios criptograficamente seguros
+
+## Segurança e Confiança
+
+O `@mcptoolshop/roll` processa apenas expressões de dados e nada mais. Não faz solicitações de rede, não escreve arquivos e não coleta dados. O único acesso ao sistema de arquivos é a flag `--loot`, que lê um único arquivo JSON especificado pelo usuário.
+
+Não há telemetria, análise ou rastreamento de qualquer tipo. Nenhum segredo, token ou credencial está envolvido em nenhuma operação.
+
+Todos os lançamentos de dados usam `crypto.randomInt` do módulo `crypto` do Node.js, fornecendo aleatoriedade criptograficamente segura, adequada para resultados justos.
+
+Consulte [SECURITY.md](./SECURITY.md) para a política de relatório de vulnerabilidades.
+
+## Licença
+
+MIT
+
+---
+
+Desenvolvido por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

package/README.zh.md

@@ -0,0 +1,204 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.md">English</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>
+</p>
+
+<p align="center"><img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/roll/readme.png" width="400" alt="Roll"></p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/roll/actions"><img src="https://github.com/mcp-tool-shop-org/roll/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+  <a href="https://mcp-tool-shop-org.github.io/roll/"><img src="https://img.shields.io/badge/Landing_Page-online-brightgreen" alt="Landing Page"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/roll"><img src="https://img.shields.io/npm/v/@mcptoolshop/roll" alt="npm version"></a>
+</p>
+
+<p align="center">RPG dice engine with probability analysis, loot tables, and beautiful terminal output.</p>
+
+```
+npx @mcptoolshop/roll 4d6dl1 --analyze
+```
+
+```
+  Distribution
+
+   3    0.08%
+   4 █   0.31%
+   5 ███   0.77%
+   6 ███████   1.62%
+   7 █████████████   2.93%
+   8 ██████████████████████   4.78%
+   9 ████████████████████████████████   7.02%
+  10 ███████████████████████████████████████████   9.41%
+  11 ████████████████████████████████████████████████████  11.42%
+  12 ██████████████████████████████████████████████████████████  12.89%
+  13 ████████████████████████████████████████████████████████████  13.27%
+  14 ████████████████████████████████████████████████████████  12.35%
+  15 ██████████████████████████████████████████████  10.11%
+  16 █████████████████████████████████   7.25%
+  17 ███████████████████   4.17%
+  18 ███████   1.62%
+
+┌─ Statistics ─────────────────────────────────┐
+│ Mean:    12.24                                │
+│ Median:  12                                   │
+│ Mode:    13                                   │
+│ Std Dev: 2.85                                 │
+│ Range:   3–18                                 │
+│ Entropy: 3.53 bits                            │
+│                                               │
+│ Percentiles:                                  │
+│   p10:8  p25:10  p50:12  p75:14  p90:16  p95:17│
+└───────────────────────────────────────────────┘
+```
+
+## 安装
+
+```bash
+npm install @mcptoolshop/roll
+```
+
+需要 Node.js >= 22。
+
+## 命令行用法
+
+### 投骰子
+
+```bash
+roll 2d6+3
+roll d20+5
+roll 4d6kh3
+roll 1d6!
+roll d%
+roll 4dF
+roll "(2d6+3)*2"
+```
+
+### 分析概率
+
+```bash
+roll 2d6 --analyze          # Full distribution + statistics
+roll d20+5 --at-least 15    # P(result >= 15)
+```
+
+### 比较分布
+
+```bash
+roll --compare "4d6dl1" "3d6"
+```
+
+并排显示统计数据（均值、中位数、众数、标准差、范围、熵），包含差异列，以及直方图。
+
+### 掉落表
+
+```bash
+roll --loot treasure.json
+```
+
+JSON 格式：
+
+```json
+{
+  "tables": [
+    {
+      "table": "Treasure",
+      "items": [
+        { "name": "Gold", "weight": 40, "roll": "2d6*10" },
+        { "name": "Potion of Healing", "weight": 30 },
+        { "name": "Scroll", "weight": 15, "quantity": "1d3" },
+        { "name": "Rare Item", "weight": 5, "table": "Rare Weapons" }
+      ]
+    },
+    {
+      "table": "Rare Weapons",
+      "items": [
+        { "name": "Vorpal Blade", "weight": 5 },
+        { "name": "Frost Brand", "weight": 25 }
+      ]
+    }
+  ]
+}
+```
+
+特性：加权选择、嵌套表引用、用于数量和值的骰子表达式。
+
+### 其他选项
+
+```bash
+roll 2d6+3 --times 5       # Roll 5 times
+roll 2d6+3 --json           # Machine-readable output
+roll --help                 # Full usage
+roll --version              # Version
+```
+
+## 骰子表示法
+
+| 表示法 | 含义 |
+|----------|---------|
+| `2d6` | 投掷 2 个六面骰子 |
+| `d20` | 投掷 1 个二十面骰子 |
+| `4d6kh3` | 投掷 4d6，保留最高的 3 个 |
+| `4d6dl1` | 投掷 4d6，舍弃最低的 1 个 |
+| `1d6!` | 爆炸骰子（最大值时重新投掷，并加总） |
+| `1d6!>4` | 当结果为 4 或更高时爆炸 |
+| `d%` | 百分位骰子（1-100） |
+| `4dF` | 命运/模糊骰子（-1、0、+1 各一个） |
+| `(2d6+3)*2` | 带有分组的算术运算 |
+| `2d6+1d4+3` | 链式表达式 |
+
+## 库 API
+
+```typescript
+import { roll, analyze, parse, evaluate, computeDistribution } from '@mcptoolshop/roll';
+
+// Quick roll
+const result = roll('4d6kh3');
+console.log(result.total);        // 14
+console.log(result.groups[0].dice); // per-die breakdown
+
+// Full analysis
+const analysis = analyze('2d6+3');
+console.log(analysis.stats.mean);                  // 10
+console.log(analysis.stats.percentiles[95]);        // 14
+console.log(analysis.probabilityAtLeast(12));       // 0.2778
+
+// Low-level: parse → AST → evaluate
+import { seededRng } from '@mcptoolshop/roll';
+const ast = parse('4d6dl1');
+const r = evaluate(ast, seededRng(42));  // deterministic
+
+// Loot tables
+import { rollLootTable } from '@mcptoolshop/roll';
+const tables = [{ table: "Loot", items: [{ name: "Gold", weight: 50, roll: "2d6*10" }] }];
+const drops = rollLootTable(tables);
+```
+
+## 概率引擎
+
+- **精确分布**：通过多项式卷积计算基本 NdM 概率。
+- **完整枚举**：用于保留/舍弃机制（4d6 = 1296 种状态）。
+- **截断递归**：用于爆炸骰子（最多 10 次爆炸）。
+- **蒙特卡洛方法**（10 万个样本）：当精确计算超过 1000 万种状态时使用。
+
+## 无外部依赖
+
+完全基于 Node.js 22+ 的内置模块：
+- `util.styleText` 用于终端颜色。
+- `util.parseArgs` 用于命令行参数解析。
+- `crypto.randomInt` 用于密码学安全的骰子投掷。
+
+## 安全与信任
+
+`@mcptoolshop/roll` 只处理骰子表达式，不做其他任何操作。它不进行任何网络请求，不写入任何文件，也不收集任何数据。唯一的系统文件访问是 `--loot` 选项，它读取单个用户指定的 JSON 文件。
+
+没有遥测数据，没有分析，也没有任何形式的跟踪。没有涉及任何秘密、令牌或凭据。
+
+所有骰子投掷都使用 Node.js `crypto` 模块中的 `crypto.randomInt`，提供密码学安全的随机数，适用于公平的结果。
+
+请参阅 [SECURITY.md](./SECURITY.md) 以获取漏洞报告政策。
+
+## 许可证
+
+MIT
+
+---
+
+由 <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> 构建。

package/dist/analyze/distribution.d.ts

@@ -0,0 +1,6 @@
+import type { ASTNode } from "../parser/ast.js";
+/** A probability distribution: value → probability (0..1) */
+export type Distribution = Map<number, number>;
+/** Compute the full probability distribution for an AST. Falls back to Monte Carlo for complex cases. */
+export declare function computeDistribution(ast: ASTNode): Distribution;
+//# sourceMappingURL=distribution.d.ts.map

package/dist/analyze/distribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distribution.d.ts","sourceRoot":"","sources":["../../src/analyze/distribution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAuB,MAAM,kBAAkB,CAAC;AAGrE,6DAA6D;AAC7D,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AA+L/C,yGAAyG;AACzG,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAI9D"}

package/dist/analyze/distribution.js

@@ -0,0 +1,252 @@
+import { monteCarloDistribution } from "./montecarlo.js";
+const MAX_EXACT_STATES = 10_000_000;
+function sideCount(sides) {
+    if (sides === "%")
+        return 100;
+    if (sides === "F")
+        return 3;
+    return sides;
+}
+/** Distribution for a single die roll. */
+function singleDieDistribution(sides) {
+    const dist = new Map();
+    if (sides === "F") {
+        dist.set(-1, 1 / 3);
+        dist.set(0, 1 / 3);
+        dist.set(1, 1 / 3);
+    }
+    else {
+        const n = sides === "%" ? 100 : sides;
+        const p = 1 / n;
+        for (let i = 1; i <= n; i++) {
+            dist.set(i, p);
+        }
+    }
+    return dist;
+}
+/** Convolve two distributions (sum of independent random variables). */
+function convolve(a, b) {
+    const result = new Map();
+    for (const [va, pa] of a) {
+        for (const [vb, pb] of b) {
+            const sum = va + vb;
+            result.set(sum, (result.get(sum) ?? 0) + pa * pb);
+        }
+    }
+    return result;
+}
+/** Distribution for NdM via iterative convolution. */
+function convolveDice(count, sides) {
+    const single = singleDieDistribution(sides);
+    let dist = new Map([[0, 1]]); // identity: always 0
+    for (let i = 0; i < count; i++) {
+        dist = convolve(dist, single);
+    }
+    return dist;
+}
+/** Distribution with keep/drop via full enumeration. */
+function enumerateKeepDrop(node) {
+    const s = sideCount(node.sides);
+    const totalStates = Math.pow(s, node.count);
+    if (totalStates > MAX_EXACT_STATES)
+        return null;
+    const isFate = node.sides === "F";
+    const dist = new Map();
+    const prob = 1 / totalStates;
+    // Enumerate all outcomes
+    const rolls = new Array(node.count);
+    function enumerate(depth) {
+        if (depth === node.count) {
+            // Apply keep/drop
+            const sorted = [...rolls].sort((a, b) => a - b);
+            let kept = sorted.slice(); // start with all
+            for (const mod of node.modifiers) {
+                if (mod.kind === "explode")
+                    continue;
+                const n = mod.value ?? 1;
+                switch (mod.kind) {
+                    case "kh":
+                        kept = kept.slice(kept.length - n);
+                        break;
+                    case "kl":
+                        kept = kept.slice(0, n);
+                        break;
+                    case "dh":
+                        kept = kept.slice(0, kept.length - n);
+                        break;
+                    case "dl":
+                        kept = kept.slice(n);
+                        break;
+                }
+            }
+            const total = kept.reduce((a, b) => a + b, 0);
+            dist.set(total, (dist.get(total) ?? 0) + prob);
+            return;
+        }
+        if (isFate) {
+            for (let v = -1; v <= 1; v++) {
+                rolls[depth] = v;
+                enumerate(depth + 1);
+            }
+        }
+        else {
+            const max = sideCount(node.sides);
+            for (let v = 1; v <= max; v++) {
+                rolls[depth] = v;
+                enumerate(depth + 1);
+            }
+        }
+    }
+    enumerate(0);
+    return dist;
+}
+/** Distribution for exploding dice via iterative depth expansion. */
+function explodingDistribution(node) {
+    if (node.sides === "F")
+        return null;
+    const s = sideCount(node.sides);
+    const explodeMod = node.modifiers.find((m) => m.kind === "explode");
+    if (!explodeMod)
+        return null;
+    const threshold = explodeMod.value ?? s;
+    const maxExplosions = 10;
+    function singleExploding() {
+        const dist = new Map();
+        const pFace = 1 / s;
+        // Build depth-by-depth: accumulated tracks (sum → probability) for chains
+        // that haven't terminated yet
+        let accumulated = new Map([[0, 1]]);
+        for (let depth = 0; depth <= maxExplosions; depth++) {
+            const nextAccumulated = new Map();
+            for (const [accSum, accProb] of accumulated) {
+                for (let face = 1; face <= s; face++) {
+                    const total = accSum + face;
+                    const p = accProb * pFace;
+                    if (face < threshold || depth === maxExplosions) {
+                        // Terminating roll (or forced cap)
+                        dist.set(total, (dist.get(total) ?? 0) + p);
+                    }
+                    else {
+                        // Exploding — carry forward
+                        nextAccumulated.set(total, (nextAccumulated.get(total) ?? 0) + p);
+                    }
+                }
+            }
+            accumulated = nextAccumulated;
+            if (accumulated.size === 0)
+                break;
+        }
+        return dist;
+    }
+    const single = singleExploding();
+    let dist = new Map([[0, 1]]);
+    for (let i = 0; i < node.count; i++) {
+        dist = convolve(dist, single);
+    }
+    return dist;
+}
+/** Shift distribution by constant. */
+function shiftDistribution(dist, offset) {
+    const result = new Map();
+    for (const [v, p] of dist) {
+        result.set(v + offset, (result.get(v + offset) ?? 0) + p);
+    }
+    return result;
+}
+/** Scale distribution by constant. */
+function scaleDistribution(dist, factor) {
+    const result = new Map();
+    for (const [v, p] of dist) {
+        const scaled = factor >= 0 ? v * factor : v * factor;
+        result.set(scaled, (result.get(scaled) ?? 0) + p);
+    }
+    return result;
+}
+/** Floor-divide distribution by constant. */
+function divideDistribution(dist, divisor) {
+    if (divisor === 0)
+        return new Map([[0, 1]]);
+    const result = new Map();
+    for (const [v, p] of dist) {
+        const divided = Math.floor(v / divisor);
+        result.set(divided, (result.get(divided) ?? 0) + p);
+    }
+    return result;
+}
+/** Compute the full probability distribution for an AST. Falls back to Monte Carlo for complex cases. */
+export function computeDistribution(ast) {
+    const result = tryExact(ast);
+    if (result)
+        return result;
+    return monteCarloDistribution(ast);
+}
+function tryExact(node) {
+    switch (node.type) {
+        case "number":
+            return new Map([[node.value, 1]]);
+        case "dice": {
+            const hasKeepDrop = node.modifiers.some((m) => m.kind === "kh" || m.kind === "kl" || m.kind === "dh" || m.kind === "dl");
+            const hasExplode = node.modifiers.some((m) => m.kind === "explode");
+            if (hasExplode && !hasKeepDrop) {
+                return explodingDistribution(node);
+            }
+            if (hasKeepDrop) {
+                return enumerateKeepDrop(node);
+            }
+            // Plain NdM — use convolution
+            return convolveDice(node.count, node.sides);
+        }
+        case "binary": {
+            const left = tryExact(node.left);
+            const right = tryExact(node.right);
+            if (!left || !right)
+                return null;
+            // Optimize: if one side is a constant
+            if (right.size === 1) {
+                const [rv] = [...right.keys()];
+                switch (node.op) {
+                    case "+":
+                        return shiftDistribution(left, rv);
+                    case "-":
+                        return shiftDistribution(left, -rv);
+                    case "*":
+                        return scaleDistribution(left, rv);
+                    case "/":
+                        return divideDistribution(left, rv);
+                }
+            }
+            if (left.size === 1) {
+                const [lv] = [...left.keys()];
+                switch (node.op) {
+                    case "+":
+                        return shiftDistribution(right, lv);
+                    case "-": {
+                        // lv - right → negate right, shift by lv
+                        const negated = scaleDistribution(right, -1);
+                        return shiftDistribution(negated, lv);
+                    }
+                    case "*":
+                        return scaleDistribution(right, lv);
+                    case "/":
+                        return null; // constant / distribution is unusual, use MC
+                }
+            }
+            // Both sides are distributions — convolve for +/-, fall back for */÷
+            if (node.op === "+")
+                return convolve(left, right);
+            if (node.op === "-") {
+                const negated = scaleDistribution(right, -1);
+                return convolve(left, negated);
+            }
+            // Multiplication/division of two distributions — Monte Carlo
+            return null;
+        }
+        case "unary_minus": {
+            const inner = tryExact(node.operand);
+            if (!inner)
+                return null;
+            return scaleDistribution(inner, -1);
+        }
+    }
+}
+//# sourceMappingURL=distribution.js.map