@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/telemetry/langfuse-model-sync.mjs

@@ -1,270 +0,0 @@
-/**
- * lib/telemetry/langfuse-model-sync.mjs — Sync live model pricing into Langfuse.
- *
- * Fetches OpenRouter's public model list for live pricing, merges with a static
- * Anthropic table (no machine-readable public pricing API), and upserts all
- * entries into Langfuse's custom model registry so that traces show real costs.
- *
- * Designed to be called once at plugin init; subsequent calls within the same
- * process are skipped via a module-level guard to avoid hammering the APIs.
- */
-
-const OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
-
-// Static Anthropic pricing (USD per token, as of 2026-04).
-// No machine-readable public pricing endpoint — update on model price changes.
-const ANTHROPIC_MODELS = [
-  {
-    modelName: "claude-opus-4-7",
-    matchPattern: "(?i)^(anthropic/)?claude-opus-4-7$",
-    inputPrice: 15 / 1_000_000,
-    outputPrice: 75 / 1_000_000,
-  },
-  {
-    modelName: "claude-opus-4-5",
-    matchPattern: "(?i)^(anthropic/)?claude-opus-4-5$",
-    inputPrice: 15 / 1_000_000,
-    outputPrice: 75 / 1_000_000,
-  },
-  {
-    modelName: "claude-sonnet-4-6",
-    matchPattern: "(?i)^(anthropic/)?claude-sonnet-4-6$",
-    inputPrice: 3 / 1_000_000,
-    outputPrice: 15 / 1_000_000,
-  },
-  {
-    modelName: "claude-sonnet-4-5",
-    matchPattern: "(?i)^(anthropic/)?claude-sonnet-4-5$",
-    inputPrice: 3 / 1_000_000,
-    outputPrice: 15 / 1_000_000,
-  },
-  {
-    modelName: "claude-haiku-4-5",
-    matchPattern: "(?i)^(anthropic/)?claude-haiku-4-5(-\\d+)?$",
-    inputPrice: 0.8 / 1_000_000,
-    outputPrice: 4 / 1_000_000,
-  },
-];
-
-// GitHub Copilot uses a per-request billing model, not per-token.
-// Register at $0 so Langfuse records usage without phantom costs.
-const GITHUB_COPILOT_MODELS = [
-  { modelName: "github-copilot/gpt-5.4", matchPattern: "(?i)^(github-copilot/)?gpt-5\\.4$" },
-  { modelName: "github-copilot/gpt-4.1", matchPattern: "(?i)^(github-copilot/)?gpt-4\\.1$" },
-  { modelName: "github-copilot/claude-sonnet-4-5", matchPattern: "(?i)^github-copilot/claude-sonnet" },
-  { modelName: "github-copilot/gemini-2.5-pro", matchPattern: "(?i)^github-copilot/gemini" },
-  { modelName: "github-copilot/o4-mini", matchPattern: "(?i)^github-copilot/o4" },
-].map((m) => ({ ...m, inputPrice: 0, outputPrice: 0 }));
-
-let syncDone = false;
-let cachedPricingCatalog = buildPricingCatalog();
-
-function normalizeModelKey(modelName = "") {
-  return String(modelName ?? "").trim().toLowerCase();
-}
-
-function indexPricingEntry(map, model) {
-  if (!model?.modelName) return;
-  const key = normalizeModelKey(model.modelName);
-  const entry = {
-    modelName: model.modelName,
-    inputPrice: Number(model.inputPrice) || 0,
-    outputPrice: Number(model.outputPrice) || 0,
-    source: model.source || "catalog",
-  };
-  map.set(key, entry);
-  if (key.startsWith("anthropic/")) map.set(key.replace(/^anthropic\//, ""), entry);
-  if (key.startsWith("github-copilot/")) map.set(key.replace(/^github-copilot\//, ""), entry);
-  if (key.startsWith("openrouter/")) map.set(key.replace(/^openrouter\//, ""), entry);
-}
-
-export function buildPricingCatalog(openRouterModels = []) {
-  const map = new Map();
-  for (const model of [...ANTHROPIC_MODELS, ...GITHUB_COPILOT_MODELS]) {
-    indexPricingEntry(map, { ...model, source: "static" });
-  }
-  for (const model of openRouterModels) {
-    indexPricingEntry(map, { ...model, source: "openrouter" });
-  }
-  return map;
-}
-
-export function resolveModelPricing(modelName, catalog = cachedPricingCatalog) {
-  const key = normalizeModelKey(modelName);
-  if (!key) return null;
-  return catalog.get(key) || null;
-}
-
-export function estimateUsageCost(modelName, usage = {}, catalog = cachedPricingCatalog) {
-  const pricing = resolveModelPricing(modelName, catalog);
-  if (!pricing) return { costUsd: 0, costSource: "unavailable", modelName: modelName || null };
-
-  const inputTokens = Number(usage.inputTokens ?? 0);
-  const outputTokens = Number(usage.outputTokens ?? 0);
-  const reasoningTokens = Number(usage.reasoningTokens ?? 0);
-  const billableOutputTokens = outputTokens + reasoningTokens;
-  const inputCost = inputTokens * pricing.inputPrice;
-  const outputCost = billableOutputTokens * pricing.outputPrice;
-  const costUsd = inputCost + outputCost;
-
-  return {
-    costUsd,
-    costSource: `estimated:${pricing.source}`,
-    modelName: pricing.modelName,
-    pricing,
-    breakdown: {
-      inputCostUsd: inputCost,
-      outputCostUsd: outputCost,
-      billableInputTokens: inputTokens,
-      billableOutputTokens,
-    },
-  };
-}
-
-function buildAuthHeader(publicKey, secretKey) {
-  return `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString("base64")}`;
-}
-
-async function fetchOpenRouterModels(fetchImpl = globalThis.fetch) {
-  try {
-    const res = await fetchImpl(OPENROUTER_MODELS_URL, {
-      headers: { "User-Agent": "construct-telemetry/1.0" },
-      signal: AbortSignal.timeout(10_000),
-    });
-    if (!res.ok) return [];
-    const { data } = await res.json();
-    if (!Array.isArray(data)) return [];
-    return data
-      .filter((m) => m?.id && m?.pricing)
-      .map((m) => {
-        const inputPrice = parseFloat(m.pricing.prompt) || 0;
-        const outputPrice = parseFloat(m.pricing.completion) || 0;
-        // Escape dots and slashes in match pattern
-        const escaped = m.id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        return {
-          modelName: m.id,
-          matchPattern: `(?i)^${escaped}$`,
-          inputPrice,
-          outputPrice,
-        };
-      });
-  } catch {
-    return [];
-  }
-}
-
-async function listLangfuseModels(baseUrl, authHeader, fetchImpl) {
-  const all = [];
-  let page = 1;
-  try {
-    while (true) {
-      const res = await fetchImpl(`${baseUrl}/api/public/models?limit=100&page=${page}`, {
-        headers: { Authorization: authHeader },
-        signal: AbortSignal.timeout(8_000),
-      });
-      if (!res.ok) break;
-      const body = await res.json();
-      const items = Array.isArray(body?.data) ? body.data : [];
-      all.push(...items);
-      if (items.length < 100) break;
-      page++;
-    }
-  } catch { /* return what we have */ }
-  return all;
-}
-
-async function deleteLangfuseModel(baseUrl, authHeader, id, fetchImpl) {
-  try {
-    await fetchImpl(`${baseUrl}/api/public/models/${id}`, {
-      method: "DELETE",
-      headers: { Authorization: authHeader },
-      signal: AbortSignal.timeout(5_000),
-    });
-  } catch { /* best effort */ }
-}
-
-async function upsertLangfuseModel(baseUrl, authHeader, model, existing, fetchImpl) {
-  const match = existing.find((e) => e.modelName === model.modelName);
-  if (match) {
-    // Langfuse has no PATCH; delete then recreate if pricing changed.
-    const priceChanged =
-      Math.abs((match.inputPrice ?? 0) - model.inputPrice) > 1e-12 ||
-      Math.abs((match.outputPrice ?? 0) - model.outputPrice) > 1e-12;
-    if (!priceChanged) return "unchanged";
-    await deleteLangfuseModel(baseUrl, authHeader, match.id, fetchImpl);
-  }
-  const body = JSON.stringify({
-    modelName: model.modelName,
-    matchPattern: model.matchPattern,
-    unit: "TOKENS",
-    inputPrice: model.inputPrice,
-    outputPrice: model.outputPrice,
-    tokenizerId: model.modelName.includes("claude") ? "claude" : null,
-  });
-  try {
-    const res = await fetchImpl(`${baseUrl}/api/public/models`, {
-      method: "POST",
-      headers: { Authorization: authHeader, "Content-Type": "application/json" },
-      body,
-      signal: AbortSignal.timeout(5_000),
-    });
-    return res.ok ? "created" : "error";
-  } catch {
-    return "error";
-  }
-}
-
-/**
- * Syncs model pricing into Langfuse. Safe to call multiple times — only runs once per process.
- *
- * @param {object} opts
- * @param {string} opts.baseUrl — Langfuse base URL
- * @param {string} opts.publicKey
- * @param {string} opts.secretKey
- * @param {Function} [opts.fetchImpl] — injectable fetch for tests
- * @param {boolean} [opts.force] — bypass the once-per-process guard
- * @returns {Promise<{synced: number, unchanged: number, errors: number}>}
- */
-export async function syncModelPricing({
-  baseUrl = (process.env.LANGFUSE_BASEURL ?? "https://cloud.langfuse.com").replace(/\/$/, ""),
-  publicKey = process.env.LANGFUSE_PUBLIC_KEY,
-  secretKey = process.env.LANGFUSE_SECRET_KEY,
-  fetchImpl = globalThis.fetch,
-  force = false,
-} = {}) {
-  if (!force && syncDone) return { synced: 0, unchanged: 0, errors: 0 };
-  if (!publicKey || !secretKey || !fetchImpl) return { synced: 0, unchanged: 0, errors: 0 };
-
-  syncDone = true;
-
-  const authHeader = buildAuthHeader(publicKey, secretKey);
-
-  const [openRouterModels, existing] = await Promise.all([
-    fetchOpenRouterModels(fetchImpl),
-    listLangfuseModels(baseUrl, authHeader, fetchImpl),
-  ]);
-
-  const allModels = [...ANTHROPIC_MODELS, ...GITHUB_COPILOT_MODELS, ...openRouterModels];
-  cachedPricingCatalog = buildPricingCatalog(openRouterModels);
-
-  let synced = 0;
-  let unchanged = 0;
-  let errors = 0;
-
-  for (const model of allModels) {
-    const result = await upsertLangfuseModel(baseUrl, authHeader, model, existing, fetchImpl);
-    if (result === "created") synced++;
-    else if (result === "unchanged") unchanged++;
-    else errors++;
-  }
-
-  return { synced, unchanged, errors };
-}
-
-export function resetSyncGuard() {
-  syncDone = false;
-}
-
-export function resetPricingCatalog() {
-  cachedPricingCatalog = buildPricingCatalog();
-}

package/rules/common/hooks.md

@@ -1,35 +0,0 @@
-<!--
-rules/common/hooks.md — <one-line purpose>
-
-<2–6 line summary.>
--->
-# Hooks System
-
-## Hook Types
-
-- **PreToolUse**: Before tool execution (validation, parameter modification)
-- **PostToolUse**: After tool execution (auto-format, checks)
-- **Stop**: When session ends (final verification)
-
-## Auto-Accept Permissions
-
-Use with caution:
-- Enable for trusted, well-defined plans
-- Disable for exploratory work
-- Never use dangerously-skip-permissions flag
-- Configure `allowedTools` in `~/.claude.json` instead
-
-## TodoWrite Best Practices
-
-Use TodoWrite tool to:
-- Track progress on multi-step tasks
-- Verify understanding of instructions
-- Enable real-time steering
-- Show granular implementation steps
-
-Todo list reveals:
-- Out of order steps
-- Missing items
-- Extra unnecessary items
-- Wrong granularity
-- Misinterpreted requirements

package/rules/zh/README.md

@@ -1,113 +0,0 @@
-<!--
-rules/zh/README.md — <one-line purpose>
-
-<2–6 line summary.>
--->
-# 规则
-
-## 结构
-
-规则按**通用**层和**语言特定**目录组织：
-
-```
-rules/
-├── common/          # 语言无关的原则（始终安装）
-│   ├── coding-style.md
-│   ├── git-workflow.md
-│   ├── testing.md
-│   ├── performance.md
-│   ├── patterns.md
-│   ├── hooks.md
-│   ├── agents.md
-│   ├── security.md
-│   ├── code-review.md
-│   └── development-workflow.md
-├── zh/              # 中文翻译版本
-│   ├── coding-style.md
-│   ├── git-workflow.md
-│   ├── testing.md
-│   ├── performance.md
-│   ├── patterns.md
-│   ├── hooks.md
-│   ├── agents.md
-│   ├── security.md
-│   ├── code-review.md
-│   └── development-workflow.md
-├── typescript/      # TypeScript/JavaScript 特定
-├── python/          # Python 特定
-├── golang/          # Go 特定
-├── swift/           # Swift 特定
-└── php/             # PHP 特定
-```
-
-- **common/** 包含通用原则 — 无语言特定的代码示例。
-- **zh/** 包含 common 目录的中文翻译版本。
-- **语言目录** 扩展通用规则，包含框架特定的模式、工具和代码示例。每个文件引用其对应的通用版本。
-
-## 安装
-
-### 选项 1：安装脚本（推荐）
-
-```bash
-# 安装通用 + 一个或多个语言特定的规则集
-./install.sh typescript
-./install.sh python
-./install.sh golang
-./install.sh swift
-./install.sh php
-
-# 同时安装多种语言
-./install.sh typescript python
-```
-
-### 选项 2：手动安装
-
-> **重要提示：** 复制整个目录 — 不要使用 `/*` 展开。
-> 通用和语言特定目录包含同名文件。
-> 将它们展开到一个目录会导致语言特定文件覆盖通用规则，
-> 并破坏语言特定文件使用的 `../common/` 相对引用。
-
-```bash
-# 创建目标目录
-mkdir -p ~/.claude/rules
-
-# 安装通用规则（所有项目必需）
-cp -r rules/common ~/.claude/rules/common
-
-# 安装中文翻译版本（可选）
-cp -r rules/zh ~/.claude/rules/zh
-
-# 根据项目技术栈安装语言特定规则
-cp -r rules/typescript ~/.claude/rules/typescript
-cp -r rules/python ~/.claude/rules/python
-cp -r rules/golang ~/.claude/rules/golang
-cp -r rules/swift ~/.claude/rules/swift
-cp -r rules/php ~/.claude/rules/php
-```
-
-## 规则 vs 技能
-
-- **规则** 定义广泛适用的标准、约定和检查清单（如"80% 测试覆盖率"、"禁止硬编码密钥"）。
-- **技能**（`skills/` 目录）为特定任务提供深入、可操作的参考材料（如 `python-patterns`、`golang-testing`）。
-
-语言特定的规则文件在适当的地方引用相关技能。规则告诉你*做什么*；技能告诉你*怎么做*。
-
-## 规则优先级
-
-当语言特定规则与通用规则冲突时，**语言特定规则优先**（特定覆盖通用）。这遵循标准的分层配置模式（类似于 CSS 特异性或 `.gitignore` 优先级）。
-
-- `rules/common/` 定义适用于所有项目的通用默认值。
-- `rules/golang/`、`rules/python/`、`rules/swift/`、`rules/php/`、`rules/typescript/` 等在语言习惯不同时覆盖这些默认值。
-- `rules/zh/` 是通用规则的中文翻译，与英文版本内容一致。
-
-### 示例
-
-`common/coding-style.md` 推荐不可变性作为默认原则。语言特定的 `golang/coding-style.md` 可以覆盖这一点：
-
-> 惯用的 Go 使用指针接收器进行结构体变更 — 参见 [common/coding-style.md](../common/coding-style.md) 了解通用原则，但这里首选符合 Go 习惯的变更方式。
-
-### 带覆盖说明的通用规则
-
-`rules/common/` 中可能被语言特定文件覆盖的规则会被标记：
-
-> **语言说明**：此规则可能会被语言特定规则覆盖；对于某些语言，该模式可能并不符合惯用写法。

package/rules/zh/agents.md

@@ -1,55 +0,0 @@
-<!--
-rules/zh/agents.md — <one-line purpose>
-
-<2–6 line summary.>
--->
-# 代理编排
-
-## 可用代理
-
-位于 `~/.claude/agents/`：
-
-| 代理 | 用途 | 何时使用 |
-|-------|---------|------------|
-| planner | 实现规划 | 复杂功能、重构 |
-| architect | 系统设计 | 架构决策 |
-| tdd-guide | 测试驱动开发 | 新功能、bug 修复 |
-| code-reviewer | 代码审查 | 编写代码后 |
-| security-reviewer | 安全分析 | 提交前 |
-| build-error-resolver | 修复构建错误 | 构建失败时 |
-| e2e-runner | E2E 测试 | 关键用户流程 |
-| refactor-cleaner | 死代码清理 | 代码维护 |
-| doc-updater | 文档 | 更新文档 |
-| rust-reviewer | Rust 代码审查 | Rust 项目 |
-
-## 立即使用代理
-
-无需用户提示：
-1. 复杂功能请求 - 使用 **planner** 代理
-2. 刚编写/修改的代码 - 使用 **code-reviewer** 代理
-3. Bug 修复或新功能 - 使用 **tdd-guide** 代理
-4. 架构决策 - 使用 **architect** 代理
-
-## 并行任务执行
-
-对独立操作始终使用并行 Task 执行：
-
-```markdown
-# 好：并行执行
-同时启动 3 个代理：
-1. 代理 1：认证模块安全分析
-2. 代理 2：缓存系统性能审查
-3. 代理 3：工具类型检查
-
-# 坏：不必要的顺序
-先代理 1，然后代理 2，然后代理 3
-```
-
-## 多视角分析
-
-对于复杂问题，使用分角色子代理：
-- 事实审查者
-- 高级工程师
-- 安全专家
-- 一致性审查者
-- 冗余检查者

package/rules/zh/code-review.md

@@ -1,129 +0,0 @@
-<!--
-rules/zh/code-review.md — <one-line purpose>
-
-<2–6 line summary.>
--->
-# 代码审查标准
-
-## 目的
-
-代码审查确保代码合并前的质量、安全性和可维护性。此规则定义何时以及如何进行代码审查。
-
-## 何时审查
-
-**强制审查触发条件：**
-
-- 编写或修改代码后
-- 提交到共享分支之前
-- 更改安全敏感代码时（认证、支付、用户数据）
-- 进行架构更改时
-- 合并 pull request 之前
-
-**审查前要求：**
-
-在请求审查之前，确保：
-
-- 所有自动化检查（CI/CD）已通过
-- 合并冲突已解决
-- 分支已与目标分支同步
-
-## 审查检查清单
-
-在标记代码完成之前：
-
-- [ ] 代码可读且命名良好
-- [ ] 函数聚焦（<50 行）
-- [ ] 文件内聚（<800 行）
-- [ ] 无深层嵌套（>4 层）
-- [ ] 错误显式处理
-- [ ] 无硬编码密钥或凭据
-- [ ] 无 console.log 或调试语句
-- [ ] 新功能有测试
-- [ ] 测试覆盖率满足 80% 最低要求
-
-## 安全审查触发条件
-
-**停止并使用 security-reviewer 代理当：**
-
-- 认证或授权代码
-- 用户输入处理
-- 数据库查询
-- 文件系统操作
-- 外部 API 调用
-- 加密操作
-- 支付或金融代码
-
-## 审查严重级别
-
-| 级别 | 含义 | 行动 |
-|-------|---------|--------|
-| CRITICAL（关键） | 安全漏洞或数据丢失风险 | **阻止** - 合并前必须修复 |
-| HIGH（高） | Bug 或重大质量问题 | **警告** - 合并前应修复 |
-| MEDIUM（中） | 可维护性问题 | **信息** - 考虑修复 |
-| LOW（低） | 风格或次要建议 | **注意** - 可选 |
-
-## 代理使用
-
-使用这些代理进行代码审查：
-
-| 代理 | 用途 |
-|-------|--------|
-| **code-reviewer** | 通用代码质量、模式、最佳实践 |
-| **security-reviewer** | 安全漏洞、OWASP Top 10 |
-| **typescript-reviewer** | TypeScript/JavaScript 特定问题 |
-| **python-reviewer** | Python 特定问题 |
-| **go-reviewer** | Go 特定问题 |
-| **rust-reviewer** | Rust 特定问题 |
-
-## 审查工作流
-
-```
-1. 运行 git diff 了解更改
-2. 先检查安全检查清单
-3. 审查代码质量检查清单
-4. 运行相关测试
-5. 验证覆盖率 >= 80%
-6. 使用适当的代理进行详细审查
-```
-
-## 常见问题捕获
-
-### 安全
-
-- 硬编码凭据（API 密钥、密码、令牌）
-- SQL 注入（查询中的字符串拼接）
-- XSS 漏洞（未转义的用户输入）
-- 路径遍历（未净化的文件路径）
-- CSRF 保护缺失
-- 认证绕过
-
-### 代码质量
-
-- 大函数（>50 行）- 拆分为更小的
-- 大文件（>800 行）- 提取模块
-- 深层嵌套（>4 层）- 使用提前返回
-- 缺少错误处理 - 显式处理
-- 变更模式 - 优先使用不可变操作
-- 缺少测试 - 添加测试覆盖
-
-### 性能
-
-- N+1 查询 - 使用 JOIN 或批处理
-- 缺少分页 - 给查询添加 LIMIT
-- 无界查询 - 添加约束
-- 缺少缓存 - 缓存昂贵操作
-
-## 批准标准
-
-- **批准**：无关键或高优先级问题
-- **警告**：仅有高优先级问题（谨慎合并）
-- **阻止**：发现关键问题
-
-## 与其他规则的集成
-
-此规则与以下规则配合：
-
-- [testing.md](testing.md) - 测试覆盖率要求
-- [security.md](security.md) - 安全检查清单
-- [git-workflow.md](git-workflow.md) - 提交标准
-- [agents.md](agents.md) - 代理委托

package/rules/zh/coding-style.md

@@ -1,53 +0,0 @@
-<!--
-rules/zh/coding-style.md — <one-line purpose>
-
-<2–6 line summary.>
--->
-# 编码风格
-
-## 不可变性（关键）
-
-始终创建新对象，永远不要修改现有对象：
-
-```
-// 伪代码
-错误:  modify(original, field, value) → 就地修改 original
-正确: update(original, field, value) → 返回带有更改的新副本
-```
-
-原理：不可变数据防止隐藏的副作用，使调试更容易，并启用安全的并发。
-
-## 文件组织
-
-多个小文件 > 少量大文件：
-- 高内聚，低耦合
-- 典型 200-400 行，最多 800 行
-- 从大模块中提取工具函数
-- 按功能/领域组织，而非按类型
-
-## 错误处理
-
-始终全面处理错误：
-- 在每一层显式处理错误
-- 在面向 UI 的代码中提供用户友好的错误消息
-- 在服务器端记录详细的错误上下文
-- 永远不要静默吞掉错误
-
-## 输入验证
-
-始终在系统边界验证：
-- 处理前验证所有用户输入
-- 在可用的情况下使用基于模式的验证
-- 快速失败并给出清晰的错误消息
-- 永远不要信任外部数据（API 响应、用户输入、文件内容）
-
-## 代码质量检查清单
-
-在标记工作完成前：
-- [ ] 代码可读且命名良好
-- [ ] 函数很小（<50 行）
-- [ ] 文件聚焦（<800 行）
-- [ ] 没有深层嵌套（>4 层）
-- [ ] 正确的错误处理
-- [ ] 没有硬编码值（使用常量或配置）
-- [ ] 没有变更（使用不可变模式）