diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 7c1dac1..3aa0163 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,93 +1,93 @@ -# devbase — Cognitive Anchor - -> **Purpose**: This file is designed to survive context compression. It contains -> immutable facts and current state that every AI session must know before -> working on this project. If you are reading this after a context reset, -> treat this as your primary source of truth. - ---- - -## Immutable Facts（不可变事实） - -| ID | Fact | Source | Status | -|----|------|--------|--------| -| F-001 | Version | `Cargo.toml` | **v0.20.1** | -| F-002 | Edition | `Cargo.toml` | **Rust 2024** | -| F-003 | Test Coverage | CI | **494 passed, 0 failed, 5 ignored** | -| F-004 | Production Unwrap | Architecture Invariants | **0** (G5 rule enforced) | -| F-005 | MCP Tools | `src/mcp/mod.rs` | **69** (5 Stable / 60 Beta / 4 Experimental) | -| F-006 | Schema Version | `registry/migrate.rs` | **v34** | -| F-007 | Entities Table | Schema v21+ | **唯一真相源** (`repos` 表已删除) | -| F-008 | SQLite Mode | `storage.rs` | **WAL mode** | -| F-009 | Clippy | CI | **`-D warnings` 全绿** | -| F-010 | Release Assets | GitHub Releases | **Linux + Windows x64** 预编译二进制 | - -## 架构红线（Architecture Guardrails） - -- **RF-1**: 无裸 `init_db()` 调用，全部使用 `StorageBackend` 注入 -- **RF-2**: `TempStorageBackend` 用于测试隔离（禁止 `DEVBASE_DATA_DIR` 竞态） -- **RF-3**: `entities` 表是唯一真相源 -- **RF-4**: 二进制上下文 ≤ 1MB -- **RF-5**: 模块间无循环依赖 -- **RF-6**: 生产代码零 `unwrap`/`expect`/`panic`（测试除外） -- **RF-7**: 路径输出必须脱敏（`sanitize_path()` 掩码 home 目录） - -## 当前上下文（Current Context） - -| 属性 | 值 | -|------|-----| -| 默认分支 | `main` | -| 最新 Release | `v0.20.1` (2026-05-17) | -| 当前 Phase | Phase 1 Production Hardening ✅ 完成 | -| 下一 Phase | Phase 12 — v0.21.0 "External Capability Grafting" | -| 活跃 PR | 无（PR #55 已合并） | - -## 已知架构 Gaps（不可与 Immutable Facts 混淆） - -这些是**待实现**的能力，不是 bug： - -| Gap | 影响 | 计划版本 | 状态 | -|-----|------|----------|------| -| ~~`relations` 表零生产读取路径~~ | ~~统一实体模型的图遍历能力未暴露~~ | ~~v0.21.0~~ | **已完成** — `devkit_relation_store/query/delete` 已存在，`project_context` 已读取 | -| ~~Workflow 引擎零 MCP 暴露~~ | ~~AI 无法发现/触发工作流~~ | ~~v0.21.0~~ | **已完成** — `devkit_workflow_list/run/status` 已存在 | -| ~~`project_context` 不完整~~ | ~~缺少 relations/limits/skills/workflows~~ | ~~v0.21.0~~ | **已完成** — 已补充 `known_limits` + `skills` | -| 31/68 MCP 工具缺少调用测试 | 回归风险 | v0.21.0 | 待评估 | -| ~~`mcp/tools/repo.rs` 2376 行~~ | ~~维护负担~~ | ~~v0.21.0~~ | **已完成** — 已拆分为 `tools/` 目录，`repo.rs` 现 730 行 | -| ~~`init_db_at` 1214 行~~ | ~~迁移函数过大~~ | ~~v0.21.0~~ | **已完成** — 已拆分为 `registry/migrate.rs`（503 行）+ `repo.rs` + `vault.rs` + `links.rs` | - -## 防失忆校验清单（每次会话启动） - -- [ ] 已读取本文件（`devbase/.claude/CLAUDE.md`） -- [ ] 已确认 `Cargo.toml` 版本与上表 F-001 一致 -- [ ] 如果 handoff 文档说"未完成"，确认是新环境问题还是全局阻塞 -- [ ] 如果修改 Schema，已更新 `registry/migrate.rs` 和 `SCHEMA_DDL` - -## 快速入口 - -| 你想做什么 | 命令 | -|-----------|------| -| 运行测试 | `cargo test --all-targets` | -| 检查 clippy | `cargo clippy --all-targets -D warnings` | -| 检查格式化 | `cargo fmt --check` | -| 运行 invariant checks | `scripts/invariant-checks/run-checks.ps1` | -| 启动 MCP Server | `cargo run -- mcp` | -| 启动 TUI | `cargo run -- tui` | -| 扫描当前目录 | `devbase scan . --register` | -| 索引仓库 | `devbase index` | - -## 关键文件映射 - -| 概念 | 文件 | -|------|------| -| 架构决策 | `docs/architecture/` | -| 稳定工具文档 | `docs/reference/stable-tools/` | -| 快速开始 | `docs/guides/quickstart.md` | -| MCP 集成指南 | `docs/guides/mcp-integration.md` | -| 变更日志 | `CHANGELOG.md` | -| Agent 简报 | `AGENTS.md` | -| 贡献指南 | `CONTRIBUTING.md` | - ---- - -**Last Updated**: 2026-05-20 by Claude Opus 4.7 -**Version**: v0.20.1 +# devbase — Cognitive Anchor + +> **Purpose**: This file is designed to survive context compression. It contains +> immutable facts and current state that every AI session must know before +> working on this project. If you are reading this after a context reset, +> treat this as your primary source of truth. + +--- + +## Immutable Facts（不可变事实） + +| ID | Fact | Source | Status | +|----|------|--------|--------| +| F-001 | Version | `Cargo.toml` | **v0.20.1** | +| F-002 | Edition | `Cargo.toml` | **Rust 2024** | +| F-003 | Test Coverage | CI | **494 passed, 0 failed, 5 ignored** | +| F-004 | Production Unwrap | Architecture Invariants | **0** (G5 rule enforced) | +| F-005 | MCP Tools | `src/mcp/mod.rs` | **71** (5 Stable / 62 Beta / 4 Experimental) | +| F-006 | Schema Version | `registry/migrate.rs` | **v36** | +| F-007 | Entities Table | Schema v21+ | **唯一真相源** (`repos` 表已删除) | +| F-008 | SQLite Mode | `storage.rs` | **WAL mode** | +| F-009 | Clippy | CI | **`-D warnings` 全绿** | +| F-010 | Release Assets | GitHub Releases | **Linux + Windows x64** 预编译二进制 | + +## 架构红线（Architecture Guardrails） + +- **RF-1**: 无裸 `init_db()` 调用，全部使用 `StorageBackend` 注入 +- **RF-2**: `TempStorageBackend` 用于测试隔离（禁止 `DEVBASE_DATA_DIR` 竞态） +- **RF-3**: `entities` 表是唯一真相源 +- **RF-4**: 二进制上下文 ≤ 1MB +- **RF-5**: 模块间无循环依赖 +- **RF-6**: 生产代码零 `unwrap`/`expect`/`panic`（测试除外） +- **RF-7**: 路径输出必须脱敏（`sanitize_path()` 掩码 home 目录） + +## 当前上下文（Current Context） + +| 属性 | 值 | +|------|-----| +| 默认分支 | `main` | +| 最新 Release | `v0.20.1` (2026-05-17) | +| 当前 Phase | Phase 1 Production Hardening ✅ 完成 | +| 下一 Phase | Phase 12 — v0.21.0 "External Capability Grafting" | +| 活跃 PR | 无（PR #55 已合并） | + +## 已知架构 Gaps（不可与 Immutable Facts 混淆） + +这些是**待实现**的能力，不是 bug： + +| Gap | 影响 | 计划版本 | 状态 | +|-----|------|----------|------| +| ~~`relations` 表零生产读取路径~~ | ~~统一实体模型的图遍历能力未暴露~~ | ~~v0.21.0~~ | **已完成** — `devkit_relation_store/query/delete` 已存在，`project_context` 已读取 | +| ~~Workflow 引擎零 MCP 暴露~~ | ~~AI 无法发现/触发工作流~~ | ~~v0.21.0~~ | **已完成** — `devkit_workflow_list/run/status` 已存在 | +| ~~`project_context` 不完整~~ | ~~缺少 relations/limits/skills/workflows~~ | ~~v0.21.0~~ | **已完成** — 已补充 `known_limits` + `skills` | +| 31/68 MCP 工具缺少调用测试 | 回归风险 | v0.21.0 | 待评估 | +| ~~`mcp/tools/repo.rs` 2376 行~~ | ~~维护负担~~ | ~~v0.21.0~~ | **已完成** — 已拆分为 `tools/` 目录，`repo.rs` 现 730 行 | +| ~~`init_db_at` 1214 行~~ | ~~迁移函数过大~~ | ~~v0.21.0~~ | **已完成** — 已拆分为 `registry/migrate.rs`（503 行）+ `repo.rs` + `vault.rs` + `links.rs` | + +## 防失忆校验清单（每次会话启动） + +- [ ] 已读取本文件（`devbase/.claude/CLAUDE.md`） +- [ ] 已确认 `Cargo.toml` 版本与上表 F-001 一致 +- [ ] 如果 handoff 文档说"未完成"，确认是新环境问题还是全局阻塞 +- [ ] 如果修改 Schema，已更新 `registry/migrate.rs` 和 `SCHEMA_DDL` + +## 快速入口 + +| 你想做什么 | 命令 | +|-----------|------| +| 运行测试 | `cargo test --all-targets` | +| 检查 clippy | `cargo clippy --all-targets -D warnings` | +| 检查格式化 | `cargo fmt --check` | +| 运行 invariant checks | `scripts/invariant-checks/run-checks.ps1` | +| 启动 MCP Server | `cargo run -- mcp` | +| 启动 TUI | `cargo run -- tui` | +| 扫描当前目录 | `devbase scan . --register` | +| 索引仓库 | `devbase index` | + +## 关键文件映射 + +| 概念 | 文件 | +|------|------| +| 架构决策 | `docs/architecture/` | +| 稳定工具文档 | `docs/reference/stable-tools/` | +| 快速开始 | `docs/guides/quickstart.md` | +| MCP 集成指南 | `docs/guides/mcp-integration.md` | +| 变更日志 | `CHANGELOG.md` | +| Agent 简报 | `AGENTS.md` | +| 贡献指南 | `CONTRIBUTING.md` | + +--- + +**Last Updated**: 2026-05-20 by Claude Opus 4.7 +**Version**: v0.20.1 diff --git a/AGENTS.md b/AGENTS.md index 8e8f4e7..613efdf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,258 +1,258 @@ -# Agent 环境指引 - -`devbase` 是 **本地情境编译器（Local Context Compiler）** —— AI agent 在本地数字世界中的海马体。 - -> 它将本地数字资产的原始数据（代码库、笔记、Skill、工作流）编译为 AI 可决策的结构化情境，不负责思考，不负责执行，只负责感知、编码、持久化、检索。 - -- **当前阶段**：阶段十一 — v0.20.0 已发布（知识完备性） -- **当前版本**：v0.20.1（Schema 34，69 MCP tools，494 tests） -- **已完成里程碑**：Registry God Object 完全拆解（10 子模块提取）+ 18 workspace crates 提取 + MCP Python SDK 1.16.0 兼容修复 + repo.rs trait 化 + flaky 测试根治（RF-2.1/2.2/2.3）+ 许可证迁移 + health 性能优化（-44%）+ index skip-embeddings + batch encoding 实验 + RF-6 清零 + 架构治理文档（ADR/不变量清单）+ Tantivy BM25 代码符号搜索（P1）+ AppContext 职责拆分 Phase 1/2（storage.rs 860→430 行）+ 架构不变量 CI（G5/T11/T12）+ Embedding 多后端（Candle/Ollama 配置切换, P3）+ EnvVersionCache 扩展（9 工具链检测, P4）+ **v0.16.0 Agent Contexts（P1/P2/P3）**：`agent_contexts`/`agent_memories`/`context_entity_links` Schema + 9 个 Session MCP tools + Context-aware Skill Runtime（`DEVBASE_ACTIVE_CONTEXT` 注入）+ **v0.16.1 Workflow-Session Binding**：`workflow_executions.context_id` + 执行自动绑定 Active Context + **v0.17.0 Embedding Externalization**：`embedding` 从 default features 移除（Candle/Ollama 降级为 opt-in `llm-backend`）+ Schema 34 向量存储 + `cosine_similarity` SQLite UDF + `devkit_session_recall` / `devkit_session_index`（60 tools）+ **v0.18.0 ClaudeCode Integration**：`devkit_project_brief`（Markdown 项目简报）+ `devkit_impact_analysis`（修改影响范围分析）+ `devkit_session_export` / `devkit_session_import` + `scripts/devbase-claude.ps1` 启动器（自动注入 `.claude/CLAUDE.md`）+ RFC `docs/RFC/claudecode-workflow-integration.md`（64 tools）+ **v0.18.0 发布收尾**：PR 合并 + 双平台二进制构建 + GitHub Release + 根目录治理 + 世界模型战略认知沉淀（Vault + AGENTS 双向联动）+ NotebookLM 生态消化（5 项目注册）+ GreptimeDB 互补分析 + **v0.19.0 知识基础设施硬化**：SQLite WAL 默认启用 + `devkit_index_health`（Beta）+ Vault 导出（`devkit_vault_export`）+ Redis ADR 决策（放弃引入）+ **v0.20.0 知识完备性**：Vault 双向链接 BFS 图遍历（`devkit_vault_graph` 扩展）+ Vault Git-based 历史追踪（`devkit_vault_history`，第 67 个 tool）+ 混合检索质量监控（`devkit_search_quality`，第 68 个 tool，`HybridSearchMetrics`）+ Block 引用支持（`WikiLink.anchor`：`[[note#heading]]` / `[[note#^block-id]]`）+ 性能回归基线（`#[ignore]` 1k/10k 阈值测试）+ 客户端无关原则（Client-Agnostic Principle）落地 + `skill sync` 泛化接口（零硬编码客户端路径） -- **核心方向**：让 Kimi CLI 在调用文件工具之前，先通过 devbase 获得"该读哪些文件、为什么读、它们之间的关系" -- **本质分析**：见 `vault/99-Meta/devbase-essence-analysis-20260430.md` 与 `docs/architecture/redefinition.md` -- **设计文档**： - - [`docs/architecture/workflow-dsl.md`](docs/architecture/workflow-dsl.md) — Workflow DSL 规范 - - [`docs/architecture/workspace-as-schema.md`](docs/architecture/workspace-as-schema.md) — 统一实体模型设计 - - [`docs/RFC/agent-memory-vector-storage.md`](docs/RFC/agent-memory-vector-storage.md) — v0.17.0 Agent Memory 向量存储 RFC（Embedding 职责外迁设计） - - [`docs/guides/mcp-integration-guide.md`](docs/guides/mcp-integration-guide.md) — MCP 集成指南 - - [`docs/README.md`](docs/README.md) — 完整文档导航 - -Skill Runtime 全生命周期已落地（含依赖管理 Schema v15），Schema v16 统一实体模型（entities/relations）已落地，Skill 自动封装（`discover`）已落地。 - -- **技术栈**：Rust 2024, SQLite, tokio, ratatui, git2, reqwest, tantivy -- **Registry DB**：`%LOCALAPPDATA%\devbase\registry.db`（轻量索引，用户本地，永不进入版本控制） -- **Workspace**：`%LOCALAPPDATA%\devbase\workspace/` —— 文件系统 = source of truth - - `vault/` —— PARA 结构：00-Inbox, 01-Projects, 02-Areas, 03-Resources, 04-Archives, 99-Meta - - `assets/` —— 二进制资源 -- **MCP Server**：stdio only，**69 个 tools**（含 7 个 vault tools + 8 个代码分析工具 + 5 个 embedding/搜索工具 + 4 个 Skill Runtime tools + 3 个 Workflow/评分 tools + 1 个报告工具 + 1 个 arXiv 工具 + 2 个 KnownLimit tools + 3 个 Relation tools + 11 个 Agent Context tools + 2 个 ClaudeCode 集成工具 + 1 个 streaming index 工具 + 1 个 oplog 工具 + 1 个 Index Health 工具 + 1 个 Search Quality 工具 + 1 个 Evaluate 工具 + 1 个 DocumentConvert 工具）；配置见 `mcp.json` -- **Kimi CLI 集成**：MCP server 已通过 `kimi mcp add` 注册，端到端验证通过（`kimi --print` 成功调用 `devkit_health`）；项目级 skill 位于 `.kimi/skills/devbase-project/SKILL.md` -- **统一节点模型**：`core::node::{Node, NodeType, Edge}` —— GitRepo / VaultNote / Asset / ExternalLink -- **当前测试**：451+ lib passed / 0 failed / 5 ignored + 11/11 integration passed（`tests/cli.rs`） -- **编译状态**：0 warning / 0 vulnerabilities（`cargo audit` 干净，除上游 `tokei` 的 `RUSTSEC-2020-0163`） -- **Workspace 结构**：`crates/` 目录已启用，19 个零耦合模块已提取为独立 crate（`devbase-symbol-links`, `devbase-sync-protocol`, `devbase-core-types`, `devbase-syncthing-client`, `devbase-vault-frontmatter`, `devbase-vault-wikilink`, `devbase-workflow-interpolate`, `devbase-workflow-model`, `devbase-registry-health`, `devbase-registry-metrics`, `devbase-registry-workspace`, `devbase-embedding`, `devbase-skill-runtime-types`, `devbase-skill-runtime-parser`, `devbase-registry-entity`, `devbase-registry-relation`, `devbase-registry-call-graph`, `devbase-registry-dead-code`, `devbase-registry-code-symbols`） -- **Workflow Engine**：YAML 解析 + 拓扑调度 + batch 并行执行 + 5 种 step 类型（skill/subworkflow/parallel/condition/loop） -- **NLQ 自然语言查询**：TUI `[:]` 触发 embedding 语义搜索，fallback 降级文本搜索 -- **Mind Market 评分**：success_rate / usage_count / rating（0-5），`skill recalc-scores/top/recommend` - -## 关键约定 - -1. **文件操作**：读取用 `ReadFile`，搜索用 `Grep`/`Glob`，修改用 `StrReplaceFile`，整文件重写用 `WriteFile` -2. **Shell**：Windows PowerShell；用 `;` 分隔命令 -3. **Git**：提交前必须通过 `cargo test --all-targets` + `cargo clippy --all-targets -D warnings` + `cargo fmt --check` -4. **Schema 迁移**：`PRAGMA user_version` 安全升级；升级前自动调用 `backup::auto_backup_before_migration()` - -## 安全原则 - -### 本地优先（Local-First） - -- **Registry DB** 始终存储在用户的本地配置目录（`dirs::config_dir()/devbase/`），绝不向远程传输 -- **代码内容** 不会被上传到任何云端服务（除非用户显式配置 GitHub token 用于 stars 查询） -- **MCP Server** 仅通过 stdio 本地进程通信，不暴露网络端口 - -### 客户端无关（Client-Agnostic） - -> devbase 的核心能力（编排、注册、索引、搜索、同步）必须在不依赖任何特定 AI 客户端的前提下独立运行。 - -- ✅ **允许**：向通用目录输出数据，由用户自行分发给任意客户端（如 `skill sync --output-dir ./plans`） -- ✅ **允许**：实现标准协议（MCP）供任意客户端连接 -- ❌ **禁止**：核心能力硬编码特定客户端的路径、API、或配置格式（如 `C:\Users\xxx\.claude`） -- ❌ **禁止**：核心能力的可用性取决于某个客户端是否安装 -- 🟡 **适配层**：`scripts/claude/`、`docs/clients/` 等目录下的客户端适配脚本属于配套示例，不归入核心版本控制 - -### 凭证管理 - -- GitHub token、LLM API key 存储在本地 `config.toml` 中 -- `config.toml` 位于用户配置目录，**不在项目工作目录**，因此不会被意外 `git commit` -- 默认配置模板中的 token 字段使用占位符 ``，避免真实 token 格式泄露 -- `.gitignore` 已覆盖 `*.db`、`.devbase/`、`.env*`、`*.local.toml` - -### 审计与备份 - -- 所有 `scan`/`sync`/`health` 操作自动写入 OpLog（SQLite `oplog` 表） -- Schema 迁移前自动生成 `backup-YYYYMMDD-HHMMSS.db` 快照 -- Registry 支持 `export`/`import` 用于用户自主备份 - -## 许可证策略 - -- **主许可证**: AGPL-3.0-or-later (`LICENSE`) -- **商业授权**: 双许可模式，闭源/专有 SaaS 使用需联系作者 (`LICENSE-COMMERCIAL.md`) -- **Cargo.toml**: `license = "AGPL-3.0-or-later"` -- **SPDX 头**: 新增源文件应在顶部包含 AGPL-3.0 声明（见 `LICENSE` 末尾 "How to Apply" 部分） - -## 架构状态（Wave 15b 完成） - -| 维度 | 状态 | -|------|------| -| 代码质量 | `rustfmt.toml` + `cargo fmt` + `clippy -D warnings` 全绿 | -| 模块拆分 | `sync`→5 / `registry`→11 / `mcp` 测试分离 / `search`→hybrid / `oplog_analytics` / `symbol_links` / **workspace: 3 crates extracted** | -| 库/二进制 | `src/lib.rs` 导出全部 **30+** 个模块；`src/main.rs` 仅 CLI 入口 | -| TUI 架构 | `render/` 6 子模块 + `theme.rs` Design Token + `layout.rs` 响应式引擎 | -| 数据层 | Schema v23: `repos`/`vault_notes`/`papers`/`workflows`/`repo_modules_legacy` 表已删除；`entities` 为唯一数据源；`repo_tags/repo_remotes/repo_health/...` 为独立 JOIN 表（无 FK）；仅 `skills` 保留独立表（embedding BLOB） | -| CI/CD | `.github/workflows/ci.yml`：check / test / fmt / clippy on Windows | -| 依赖安全 | `cargo audit` 0 漏洞（除上游 `tokei` 的 `RUSTSEC-2020-0163`） | - -## 架构红线（Architecture Guardrails） - -> 基于第一性原理的工程约束。违反任意一条 = HALT，转交人类裁决或回滚。 -> 规则编号 `RF-XX`（Red-line / Fitness function），带客观测量标准，非主观描述。 - -### RF-1: 依赖注入优于全局状态（Global State Anti-Pattern） - -**理论锚定**：全局可变状态使组件隐式耦合，破坏可测试性与可复用性（参考：Pure Function / DI 原则）。 - -**规则**： -- 禁止新增 `dirs::data_local_dir()` / `std::env::var_os` 硬编码路径。 -- 所有 IO 边界路径（DB、索引、备份、配置）必须通过参数、构造函数或 `trait` 注入。 -- **例外（Grandfathered）**：现有 3 处（`backup_dir`、`db_path`、`index_path`）在重构前不得新增第 4 处。 - -**Fitness Function**： -```bash -# 新增 PR 中不得出现新的全局路径硬编码 -grep -rn "dirs::data_local_dir\|std::env::var_os\|std::env::var(\"LOCALAPPDATA\"" src/ \ - | grep -v "backup.rs\|migrate.rs\|search.rs" -# 预期输出：空 -``` - -### RF-2: 测试密封性（Hermetic Testing） - -**理论锚定**：测试失败必须仅因被测代码缺陷，不因外部因素、测试顺序或并行调度（参考：Google Test Blog — Hermetic Servers）。 - -**规则**： -- 所有测试禁止修改全局进程状态（`std::env::set_var`、`static mut`、全局文件系统句柄）。 -- 文件系统测试必须使用 `tempfile` + 注入式路径，禁止直接操作 `%LOCALAPPDATA%` 或 `~/.config`。 -- Tantivy / SQLite 文件系统测试必须获取 `SEARCH_TEST_LOCK`（或同等级串行化机制）。 - -**子规则（来自 PR #4 教训）**： -- **R2.1 禁止 `DEVBASE_DATA_DIR` 全局注入**：并行测试中 `std::env::set_var("DEVBASE_DATA_DIR", ...)` 导致竞态；必须使用 `TempStorageBackend` 注入式替代。 -- **R2.2 Windows 路径双端规范化**：`TempDir` 可能返回短文件名（`TEMP~1`），而 `dunce::canonicalize` 返回长文件名；路径比较前必须对**双方**调用 `dunce::canonicalize`。 -- **R2.3 `git2` 测试显式身份 + 显式分支**： - - CI runner 无全局 `user.name`/`user.email` → `repo.signature()` 会 panic；必须改用 `git2::Signature::now("Test", "test@example.com")`。 - - `git2::Repository::init` 的默认分支在不同平台可能为 `master` 或 `main`；必须显式 `repo.set_head("refs/heads/main")` 并 commit 到 `"refs/heads/main"`。 - -**Fitness Function**： -```bash -# 高并发下 100% 通过，无 flaky -cargo test --test-threads=16 -``` - -### RF-3: Schema 单一事实来源（Single Source of Truth） - -**理论锚定**：重复信息必然 drift（参考：DRY 原则 + Evolutionary Architecture 的版本一致性约束）。 - -**规则**： -- `SCHEMA_DDL`（`registry/test_helpers.rs`）与 `migrate.rs` 必须原子同步。 -- 新增表、索引、列必须同时出现在两者中；禁止仅更新其一。 - -**Fitness Function**： -- CI 运行 `test_in_memory_schema_version` + schema 结构比对脚本（可手动运行 `cargo test registry::test_helpers::tests` 验证）。 - -### RF-4: 二进制入口限界（Bounded Context） - -**理论锚定**：CLI 入口应仅做命令分发，业务逻辑应在 lib 模块中（参考：Hexagonal Architecture / Ports & Adapters）。 - -**规则**： -- `main.rs` 行数不得超过 **1000 行**。 -- 新增 CLI 命令必须先拆分为 `commands/` 子模块或独立函数，禁止在 `main.rs` 中堆积业务逻辑。 - -**Fitness Function**： -```bash -# 当前 515 行（Phase 1/2/3 已削减 1003 行），远超目标 -[ $(wc -l < src/main.rs) -le 1000 ] || exit 1 -``` - -### RF-5: 无循环依赖（Acyclic Dependencies） - -**理论锚定**：循环依赖破坏模块化，使增量编译和独立复用不可能（参考：John Lakos — Large-Scale C++ Software Design）。 - -**规则**： -- 禁止模块间双向 `use crate::` 引用。 -- 新增模块必须通过脚本验证无循环（当前已满足，未来 PR 保持）。 - -**Fitness Function**： -```bash -# 文件级双向依赖检测（当前输出应为空） -for f in src/**/*.rs; do - name=$(basename "$f" .rs) - refs=$(grep -o 'use crate::[a-z_]*' "$f" | sed 's/use crate:://') - for r in $refs; do - if [ -f "src/$r.rs" ] && grep -q "use crate::$name\b" "src/$r.rs"; then - echo "CYCLE: $name <-> $r" - fi - done -done -``` - -### RF-7: Workspace 拆分约束（Module Distribution Readiness） - -**理论锚定**：模块能否独立发布是耦合健康度的金标准；不能拆分的模块 = 耦合不健康的模块。 - -**规则**： -- 新增模块若对 devbase 内部其他模块的 `crate::` 引用超过 **5 个**，禁止提取为 workspace crate。 -- 已提取 crate 的重新导出文件（`src/symbol_links.rs` 等）**禁止添加新代码**——顶部有 `RE-EXPORT ONLY` 注释作为守卫。 -- 子 crate 的依赖版本必须与 workspace 统一，禁止独立 bump。 - -**Fitness Function**： -```bash -# 扫描所有 src/*.rs，统计 crate:: 引用数 -for f in src/*.rs; do - count=$(grep -c 'crate::' "$f") - if [ "$count" -gt 15 ]; then - echo "HIGH COUPLING: $f ($count refs)" - fi -done -# 预期输出：空（或仅已标记的高耦合文件如 mcp/tools/repo.rs） -``` - -### RF-6: 生产代码无 panic（Crash-only Software） - -**理论锚定**：Rust 的 `Result` 类型将错误显式化；`unwrap` 是将运行时崩溃隐藏在类型系统背后（参考：Joe Armstrong — Let it crash，但 Rust 中崩溃 = 进程终止，不可接受）。 - -**规则**： -- 生产代码（`src/**/*.rs` 中不在 `#[cfg(test)]` 块内的代码）禁止 `unwrap()`、`expect()`、`panic!()`。 -- 测试代码不受此限，但鼓励使用 `?` 传播。 - -**Fitness Function**： -```bash -# 生产代码 unwrap 计数（排除 #[cfg(test)] 块及 tests.rs 文件） -for f in $(find src -name "*.rs"); do - test_line=$(grep -n "#\[cfg(test)\]" "$f" | head -1 | cut -d: -f1) - if echo "$f" | grep -qE "tests?\.rs$|_test\.rs$|/tests/"; then continue; fi - if [ -n "$test_line" ]; then - head -n "$((test_line - 1))" "$f" | grep -n "\.unwrap()" - else - grep -n "\.unwrap()" "$f" - fi -done -# 预期输出：空 -``` - -**状态**：🟢 **已完成**（v0.20.1 复核：生产代码 unwrap = 0；此前 1090 为测试模块误统计）。 - -### 架构治理框架（Architecture Governance） - -> 参考：外部架构治理方法论（Kimi 会话 `e9f2965f-b949-46a5-9d7c-afd6d4d9232c`） - -**已制度化实践**： - -| 实践 | devbase 落地形式 | 文档位置 | -|------|-----------------|---------| -| ADR（架构决策记录） | ADR-001（单 crate defer）、ADR-002（batch encoding 回滚） | [`docs/architecture/adr-template.md`](docs/architecture/adr-template.md) | -| 不变量清单（Invariants） | RF-1~RF-7 + 分层模块约束（T01–T12） | [`docs/architecture/invariants.md`](docs/architecture/invariants.md) | -| 模块提取演习 | RF-7 的 5 个 `crate::` 引用阈值 + 已提取 18 workspace crates | 本文件 §RF-7 | -| 三层摘要 | `crates/*/README.md` 要求：一句话 + 一页纸 + 深度链接 | 各 crate README | -| 定期架构回顾 | 每次 Wave 结束时的架构审计（见 `docs/_audit/`） | `docs/_audit/2026-04-26-*.md` | - -**待增强**： -- 三层摘要：部分已提取 crate 的 README 尚未达到"一页纸"标准 -- 定期架构回顾：当前按 Wave（功能迭代周期）触发，建议每 2–4 周增加一次纯架构 review（不看 feature 进度，只看不变量违反和隐式依赖） - ---- - -## 禁止事项 - -- 不得修改 `dev\third_party\*` 外部仓库 -- 不得在没有迁移逻辑的情况下修改 registry schema -- 不得引入已 deprecated 的协议 -- **不得在主仓库引入 Spark/Flink 依赖**（研究性质代码必须置于独立仓库，保持主仓库轻量） -- **不得在任何源码文件中硬编码真实 token、api_key 或密码**（包括注释和测试数据） - -> 完整版（含历史记录、路线图、详细讨论）：见 docs/AGENTS-full.md +# Agent 环境指引 + +`devbase` 是 **本地情境编译器（Local Context Compiler）** —— AI agent 在本地数字世界中的海马体。 + +> 它将本地数字资产的原始数据（代码库、笔记、Skill、工作流）编译为 AI 可决策的结构化情境，不负责思考，不负责执行，只负责感知、编码、持久化、检索。 + +- **当前阶段**：阶段十一 — v0.20.0 已发布（知识完备性） +- **当前版本**：v0.20.1（Schema 36，71 MCP tools，495 tests） +- **已完成里程碑**：Registry God Object 完全拆解（10 子模块提取）+ 18 workspace crates 提取 + MCP Python SDK 1.16.0 兼容修复 + repo.rs trait 化 + flaky 测试根治（RF-2.1/2.2/2.3）+ 许可证迁移 + health 性能优化（-44%）+ index skip-embeddings + batch encoding 实验 + RF-6 清零 + 架构治理文档（ADR/不变量清单）+ Tantivy BM25 代码符号搜索（P1）+ AppContext 职责拆分 Phase 1/2（storage.rs 860→430 行）+ 架构不变量 CI（G5/T11/T12）+ Embedding 多后端（Candle/Ollama 配置切换, P3）+ EnvVersionCache 扩展（9 工具链检测, P4）+ **v0.16.0 Agent Contexts（P1/P2/P3）**：`agent_contexts`/`agent_memories`/`context_entity_links` Schema + 9 个 Session MCP tools + Context-aware Skill Runtime（`DEVBASE_ACTIVE_CONTEXT` 注入）+ **v0.16.1 Workflow-Session Binding**：`workflow_executions.context_id` + 执行自动绑定 Active Context + **v0.17.0 Embedding Externalization**：`embedding` 从 default features 移除（Candle/Ollama 降级为 opt-in `llm-backend`）+ Schema 34 向量存储 + `cosine_similarity` SQLite UDF + `devkit_session_recall` / `devkit_session_index`（60 tools）+ **v0.18.0 ClaudeCode Integration**：`devkit_project_brief`（Markdown 项目简报）+ `devkit_impact_analysis`（修改影响范围分析）+ `devkit_session_export` / `devkit_session_import` + `scripts/devbase-claude.ps1` 启动器（自动注入 `.claude/CLAUDE.md`）+ RFC `docs/RFC/claudecode-workflow-integration.md`（64 tools）+ **v0.18.0 发布收尾**：PR 合并 + 双平台二进制构建 + GitHub Release + 根目录治理 + 世界模型战略认知沉淀（Vault + AGENTS 双向联动）+ NotebookLM 生态消化（5 项目注册）+ GreptimeDB 互补分析 + **v0.19.0 知识基础设施硬化**：SQLite WAL 默认启用 + `devkit_index_health`（Beta）+ Vault 导出（`devkit_vault_export`）+ Redis ADR 决策（放弃引入）+ **v0.20.0 知识完备性**：Vault 双向链接 BFS 图遍历（`devkit_vault_graph` 扩展）+ Vault Git-based 历史追踪（`devkit_vault_history`，第 67 个 tool）+ 混合检索质量监控（`devkit_search_quality`，第 68 个 tool，`HybridSearchMetrics`）+ Block 引用支持（`WikiLink.anchor`：`[[note#heading]]` / `[[note#^block-id]]`）+ 性能回归基线（`#[ignore]` 1k/10k 阈值测试）+ 客户端无关原则（Client-Agnostic Principle）落地 + `skill sync` 泛化接口（零硬编码客户端路径） +- **核心方向**：让 Kimi CLI 在调用文件工具之前，先通过 devbase 获得"该读哪些文件、为什么读、它们之间的关系" +- **本质分析**：见 `vault/99-Meta/devbase-essence-analysis-20260430.md` 与 `docs/architecture/redefinition.md` +- **设计文档**： + - [`docs/architecture/workflow-dsl.md`](docs/architecture/workflow-dsl.md) — Workflow DSL 规范 + - [`docs/architecture/workspace-as-schema.md`](docs/architecture/workspace-as-schema.md) — 统一实体模型设计 + - [`docs/RFC/agent-memory-vector-storage.md`](docs/RFC/agent-memory-vector-storage.md) — v0.17.0 Agent Memory 向量存储 RFC（Embedding 职责外迁设计） + - [`docs/guides/mcp-integration-guide.md`](docs/guides/mcp-integration-guide.md) — MCP 集成指南 + - [`docs/README.md`](docs/README.md) — 完整文档导航 + +Skill Runtime 全生命周期已落地（含依赖管理 Schema v15），Schema v16 统一实体模型（entities/relations）已落地，Skill 自动封装（`discover`）已落地。 + +- **技术栈**：Rust 2024, SQLite, tokio, ratatui, git2, reqwest, tantivy +- **Registry DB**：`%LOCALAPPDATA%\devbase\registry.db`（轻量索引，用户本地，永不进入版本控制） +- **Workspace**：`%LOCALAPPDATA%\devbase\workspace/` —— 文件系统 = source of truth + - `vault/` —— PARA 结构：00-Inbox, 01-Projects, 02-Areas, 03-Resources, 04-Archives, 99-Meta + - `assets/` —— 二进制资源 +- **MCP Server**：stdio only，**71 个 tools**（含 7 个 vault tools + 8 个代码分析工具 + 5 个 embedding/搜索工具 + 5 个 Skill Runtime tools + 3 个 Workflow/评分 tools + 1 个报告工具 + 1 个 arXiv 工具 + 2 个 KnownLimit tools + 3 个 Relation tools + 11 个 Agent Context tools + 2 个 ClaudeCode 集成工具 + 1 个 streaming index 工具 + 1 个 oplog 工具 + 1 个 Index Health 工具 + 1 个 Search Quality 工具 + 1 个 Evaluate 工具 + 1 个 DocumentConvert 工具 + 1 个 Ontology Import 工具 + 1 个 Skill Sync 工具）；配置见 `mcp.json` +- **Kimi CLI 集成**：MCP server 已通过 `kimi mcp add` 注册，端到端验证通过（`kimi --print` 成功调用 `devkit_health`）；项目级 skill 位于 `.kimi/skills/devbase-project/SKILL.md` +- **统一节点模型**：`core::node::{Node, NodeType, Edge}` —— GitRepo / VaultNote / Asset / ExternalLink +- **当前测试**：476 lib passed / 0 failed / 5 ignored + 7/7 integration passed + 11/11 workflow passed（共 494） +- **编译状态**：0 warning / 0 vulnerabilities（`cargo audit` 干净，除上游 `tokei` 的 `RUSTSEC-2020-0163`） +- **Workspace 结构**：`crates/` 目录已启用，19 个零耦合模块已提取为独立 crate（`devbase-symbol-links`, `devbase-sync-protocol`, `devbase-core-types`, `devbase-syncthing-client`, `devbase-vault-frontmatter`, `devbase-vault-wikilink`, `devbase-workflow-interpolate`, `devbase-workflow-model`, `devbase-registry-health`, `devbase-registry-metrics`, `devbase-registry-workspace`, `devbase-embedding`, `devbase-skill-runtime-types`, `devbase-skill-runtime-parser`, `devbase-registry-entity`, `devbase-registry-relation`, `devbase-registry-call-graph`, `devbase-registry-dead-code`, `devbase-registry-code-symbols`） +- **Workflow Engine**：YAML 解析 + 拓扑调度 + batch 并行执行 + 5 种 step 类型（skill/subworkflow/parallel/condition/loop） +- **NLQ 自然语言查询**：TUI `[:]` 触发 embedding 语义搜索，fallback 降级文本搜索 +- **Mind Market 评分**：success_rate / usage_count / rating（0-5），`skill recalc-scores/top/recommend` + +## 关键约定 + +1. **文件操作**：读取用 `ReadFile`，搜索用 `Grep`/`Glob`，修改用 `StrReplaceFile`，整文件重写用 `WriteFile` +2. **Shell**：Windows PowerShell；用 `;` 分隔命令 +3. **Git**：提交前必须通过 `cargo test --all-targets` + `cargo clippy --all-targets -D warnings` + `cargo fmt --check` +4. **Schema 迁移**：`PRAGMA user_version` 安全升级；升级前自动调用 `backup::auto_backup_before_migration()` + +## 安全原则 + +### 本地优先（Local-First） + +- **Registry DB** 始终存储在用户的本地配置目录（`dirs::config_dir()/devbase/`），绝不向远程传输 +- **代码内容** 不会被上传到任何云端服务（除非用户显式配置 GitHub token 用于 stars 查询） +- **MCP Server** 仅通过 stdio 本地进程通信，不暴露网络端口 + +### 客户端无关（Client-Agnostic） + +> devbase 的核心能力（编排、注册、索引、搜索、同步）必须在不依赖任何特定 AI 客户端的前提下独立运行。 + +- ✅ **允许**：向通用目录输出数据，由用户自行分发给任意客户端（如 `skill sync --output-dir ./plans`） +- ✅ **允许**：实现标准协议（MCP）供任意客户端连接 +- ❌ **禁止**：核心能力硬编码特定客户端的路径、API、或配置格式（如 `C:\Users\xxx\.claude`） +- ❌ **禁止**：核心能力的可用性取决于某个客户端是否安装 +- 🟡 **适配层**：`scripts/claude/`、`docs/clients/` 等目录下的客户端适配脚本属于配套示例，不归入核心版本控制 + +### 凭证管理 + +- GitHub token、LLM API key 存储在本地 `config.toml` 中 +- `config.toml` 位于用户配置目录，**不在项目工作目录**，因此不会被意外 `git commit` +- 默认配置模板中的 token 字段使用占位符 ``，避免真实 token 格式泄露 +- `.gitignore` 已覆盖 `*.db`、`.devbase/`、`.env*`、`*.local.toml` + +### 审计与备份 + +- 所有 `scan`/`sync`/`health` 操作自动写入 OpLog（SQLite `oplog` 表） +- Schema 迁移前自动生成 `backup-YYYYMMDD-HHMMSS.db` 快照 +- Registry 支持 `export`/`import` 用于用户自主备份 + +## 许可证策略 + +- **主许可证**: AGPL-3.0-or-later (`LICENSE`) +- **商业授权**: 双许可模式，闭源/专有 SaaS 使用需联系作者 (`LICENSE-COMMERCIAL.md`) +- **Cargo.toml**: `license = "AGPL-3.0-or-later"` +- **SPDX 头**: 新增源文件应在顶部包含 AGPL-3.0 声明（见 `LICENSE` 末尾 "How to Apply" 部分） + +## 架构状态（Wave 15b 完成） + +| 维度 | 状态 | +|------|------| +| 代码质量 | `rustfmt.toml` + `cargo fmt` + `clippy -D warnings` 全绿 | +| 模块拆分 | `sync`→5 / `registry`→11 / `mcp` 测试分离 / `search`→hybrid / `oplog_analytics` / `symbol_links` / **workspace: 3 crates extracted** | +| 库/二进制 | `src/lib.rs` 导出全部 **30+** 个模块；`src/main.rs` 仅 CLI 入口 | +| TUI 架构 | `render/` 6 子模块 + `theme.rs` Design Token + `layout.rs` 响应式引擎 | +| 数据层 | Schema v23: `repos`/`vault_notes`/`papers`/`workflows`/`repo_modules_legacy` 表已删除；`entities` 为唯一数据源；`repo_tags/repo_remotes/repo_health/...` 为独立 JOIN 表（无 FK）；仅 `skills` 保留独立表（embedding BLOB） | +| CI/CD | `.github/workflows/ci.yml`：check / test / fmt / clippy on Windows | +| 依赖安全 | `cargo audit` 0 漏洞（除上游 `tokei` 的 `RUSTSEC-2020-0163`） | + +## 架构红线（Architecture Guardrails） + +> 基于第一性原理的工程约束。违反任意一条 = HALT，转交人类裁决或回滚。 +> 规则编号 `RF-XX`（Red-line / Fitness function），带客观测量标准，非主观描述。 + +### RF-1: 依赖注入优于全局状态（Global State Anti-Pattern） + +**理论锚定**：全局可变状态使组件隐式耦合，破坏可测试性与可复用性（参考：Pure Function / DI 原则）。 + +**规则**： +- 禁止新增 `dirs::data_local_dir()` / `std::env::var_os` 硬编码路径。 +- 所有 IO 边界路径（DB、索引、备份、配置）必须通过参数、构造函数或 `trait` 注入。 +- **例外（Grandfathered）**：现有 3 处（`backup_dir`、`db_path`、`index_path`）在重构前不得新增第 4 处。 + +**Fitness Function**： +```bash +# 新增 PR 中不得出现新的全局路径硬编码 +grep -rn "dirs::data_local_dir\|std::env::var_os\|std::env::var(\"LOCALAPPDATA\"" src/ \ + | grep -v "backup.rs\|migrate.rs\|search.rs" +# 预期输出：空 +``` + +### RF-2: 测试密封性（Hermetic Testing） + +**理论锚定**：测试失败必须仅因被测代码缺陷，不因外部因素、测试顺序或并行调度（参考：Google Test Blog — Hermetic Servers）。 + +**规则**： +- 所有测试禁止修改全局进程状态（`std::env::set_var`、`static mut`、全局文件系统句柄）。 +- 文件系统测试必须使用 `tempfile` + 注入式路径，禁止直接操作 `%LOCALAPPDATA%` 或 `~/.config`。 +- Tantivy / SQLite 文件系统测试必须获取 `SEARCH_TEST_LOCK`（或同等级串行化机制）。 + +**子规则（来自 PR #4 教训）**： +- **R2.1 禁止 `DEVBASE_DATA_DIR` 全局注入**：并行测试中 `std::env::set_var("DEVBASE_DATA_DIR", ...)` 导致竞态；必须使用 `TempStorageBackend` 注入式替代。 +- **R2.2 Windows 路径双端规范化**：`TempDir` 可能返回短文件名（`TEMP~1`），而 `dunce::canonicalize` 返回长文件名；路径比较前必须对**双方**调用 `dunce::canonicalize`。 +- **R2.3 `git2` 测试显式身份 + 显式分支**： + - CI runner 无全局 `user.name`/`user.email` → `repo.signature()` 会 panic；必须改用 `git2::Signature::now("Test", "test@example.com")`。 + - `git2::Repository::init` 的默认分支在不同平台可能为 `master` 或 `main`；必须显式 `repo.set_head("refs/heads/main")` 并 commit 到 `"refs/heads/main"`。 + +**Fitness Function**： +```bash +# 高并发下 100% 通过，无 flaky +cargo test --test-threads=16 +``` + +### RF-3: Schema 单一事实来源（Single Source of Truth） + +**理论锚定**：重复信息必然 drift（参考：DRY 原则 + Evolutionary Architecture 的版本一致性约束）。 + +**规则**： +- `SCHEMA_DDL`（`registry/test_helpers.rs`）与 `migrate.rs` 必须原子同步。 +- 新增表、索引、列必须同时出现在两者中；禁止仅更新其一。 + +**Fitness Function**： +- CI 运行 `test_in_memory_schema_version` + schema 结构比对脚本（可手动运行 `cargo test registry::test_helpers::tests` 验证）。 + +### RF-4: 二进制入口限界（Bounded Context） + +**理论锚定**：CLI 入口应仅做命令分发，业务逻辑应在 lib 模块中（参考：Hexagonal Architecture / Ports & Adapters）。 + +**规则**： +- `main.rs` 行数不得超过 **1000 行**。 +- 新增 CLI 命令必须先拆分为 `commands/` 子模块或独立函数，禁止在 `main.rs` 中堆积业务逻辑。 + +**Fitness Function**： +```bash +# 当前 515 行（Phase 1/2/3 已削减 1003 行），远超目标 +[ $(wc -l < src/main.rs) -le 1000 ] || exit 1 +``` + +### RF-5: 无循环依赖（Acyclic Dependencies） + +**理论锚定**：循环依赖破坏模块化，使增量编译和独立复用不可能（参考：John Lakos — Large-Scale C++ Software Design）。 + +**规则**： +- 禁止模块间双向 `use crate::` 引用。 +- 新增模块必须通过脚本验证无循环（当前已满足，未来 PR 保持）。 + +**Fitness Function**： +```bash +# 文件级双向依赖检测（当前输出应为空） +for f in src/**/*.rs; do + name=$(basename "$f" .rs) + refs=$(grep -o 'use crate::[a-z_]*' "$f" | sed 's/use crate:://') + for r in $refs; do + if [ -f "src/$r.rs" ] && grep -q "use crate::$name\b" "src/$r.rs"; then + echo "CYCLE: $name <-> $r" + fi + done +done +``` + +### RF-7: Workspace 拆分约束（Module Distribution Readiness） + +**理论锚定**：模块能否独立发布是耦合健康度的金标准；不能拆分的模块 = 耦合不健康的模块。 + +**规则**： +- 新增模块若对 devbase 内部其他模块的 `crate::` 引用超过 **5 个**，禁止提取为 workspace crate。 +- 已提取 crate 的重新导出文件（`src/symbol_links.rs` 等）**禁止添加新代码**——顶部有 `RE-EXPORT ONLY` 注释作为守卫。 +- 子 crate 的依赖版本必须与 workspace 统一，禁止独立 bump。 + +**Fitness Function**： +```bash +# 扫描所有 src/*.rs，统计 crate:: 引用数 +for f in src/*.rs; do + count=$(grep -c 'crate::' "$f") + if [ "$count" -gt 15 ]; then + echo "HIGH COUPLING: $f ($count refs)" + fi +done +# 预期输出：空（或仅已标记的高耦合文件如 mcp/tools/repo.rs） +``` + +### RF-6: 生产代码无 panic（Crash-only Software） + +**理论锚定**：Rust 的 `Result` 类型将错误显式化；`unwrap` 是将运行时崩溃隐藏在类型系统背后（参考：Joe Armstrong — Let it crash，但 Rust 中崩溃 = 进程终止，不可接受）。 + +**规则**： +- 生产代码（`src/**/*.rs` 中不在 `#[cfg(test)]` 块内的代码）禁止 `unwrap()`、`expect()`、`panic!()`。 +- 测试代码不受此限，但鼓励使用 `?` 传播。 + +**Fitness Function**： +```bash +# 生产代码 unwrap 计数（排除 #[cfg(test)] 块及 tests.rs 文件） +for f in $(find src -name "*.rs"); do + test_line=$(grep -n "#\[cfg(test)\]" "$f" | head -1 | cut -d: -f1) + if echo "$f" | grep -qE "tests?\.rs$|_test\.rs$|/tests/"; then continue; fi + if [ -n "$test_line" ]; then + head -n "$((test_line - 1))" "$f" | grep -n "\.unwrap()" + else + grep -n "\.unwrap()" "$f" + fi +done +# 预期输出：空 +``` + +**状态**：🟢 **已完成**（v0.20.1 复核：生产代码 unwrap = 0；此前 1090 为测试模块误统计）。 + +### 架构治理框架（Architecture Governance） + +> 参考：外部架构治理方法论（Kimi 会话 `e9f2965f-b949-46a5-9d7c-afd6d4d9232c`） + +**已制度化实践**： + +| 实践 | devbase 落地形式 | 文档位置 | +|------|-----------------|---------| +| ADR（架构决策记录） | ADR-001（单 crate defer）、ADR-002（batch encoding 回滚） | [`docs/architecture/adr-template.md`](docs/architecture/adr-template.md) | +| 不变量清单（Invariants） | RF-1~RF-7 + 分层模块约束（T01–T12） | [`docs/architecture/invariants.md`](docs/architecture/invariants.md) | +| 模块提取演习 | RF-7 的 5 个 `crate::` 引用阈值 + 已提取 18 workspace crates | 本文件 §RF-7 | +| 三层摘要 | `crates/*/README.md` 要求：一句话 + 一页纸 + 深度链接 | 各 crate README | +| 定期架构回顾 | 每次 Wave 结束时的架构审计（见 `docs/_audit/`） | `docs/_audit/2026-04-26-*.md` | + +**待增强**： +- 三层摘要：部分已提取 crate 的 README 尚未达到"一页纸"标准 +- 定期架构回顾：当前按 Wave（功能迭代周期）触发，建议每 2–4 周增加一次纯架构 review（不看 feature 进度，只看不变量违反和隐式依赖） + +--- + +## 禁止事项 + +- 不得修改 `dev\third_party\*` 外部仓库 +- 不得在没有迁移逻辑的情况下修改 registry schema +- 不得引入已 deprecated 的协议 +- **不得在主仓库引入 Spark/Flink 依赖**（研究性质代码必须置于独立仓库，保持主仓库轻量） +- **不得在任何源码文件中硬编码真实 token、api_key 或密码**（包括注释和测试数据） + +> 完整版（含历史记录、路线图、详细讨论）：见 docs/AGENTS-full.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2bf9074..0f26b8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,689 +1,694 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- `devkit_document_convert` — Experimental tier MCP tool，PDF/PPTX → Markdown 转换（`pdftotext` / `python-pptx` 流水线），含 frontmatter 质量标注 -- Stable 工具 invocation 测试补全：`devkit_query_repos`、`devkit_vault_search`、`devkit_vault_read`、`devkit_status`、`devkit_workflow_list`、`devkit_index` -- `seed_repo()` 轻量测试 helper（仅插入 `entities` 表，无副作用） - -### Fixed - -- `mcp/tools/document_convert.rs` 原始字符串定界符修复（`r###"` 避免与 Python f-string `"##` 冲突） -- `cleanup_extracted_text` 单元测试期望值与实现语义对齐（保留最多 2 个连续空行） - -### Changed - -- **Workspace crate 架构重组** — 消除机械提取造成的微 crate 碎片 - - 合并 8 个 `devbase-registry-*` 微 crate（100–300 行/个）为统一 `devbase-registry`，含 8 个语义子模块（`entity`, `health`, `metrics`, `relation`, `call_graph`, `code_symbols`, `dead_code`, `workspace`） - - 拆分 10+ 个 monolithic `lib.rs` 为域驱动子模块：`devbase-embedding` (`candle`/`ollama`), `devbase-workflow-model` (`definition`/`execution`/`step_type`), `devbase-symbol-links` (`similarity`/`co_located`), `devbase-sync-protocol` (`index`/`version_vector`), `devbase-skill-runtime-types` (`skill_type`/`execution`/`params`), `devbase-skill-runtime-parser` (`frontmatter`/`field_parsers`), `devbase-workflow-interpolate` (`resolver`), `devbase-vault-frontmatter` (`parser`), `devbase-vault-wikilink` (`parser`), `devbase-core-types` (`node_type`/`node`/`edge`) - - 全 workspace `Cargo.toml` 统一使用 `[workspace.package]` 继承（`version`, `edition`, `authors`, `license`, `repository`） -- `KNOWN_ISSUES.md` 更新：document_convert 从 P3 债务移至已解决归档；测试计数 485→494 -- `docs/reference/mcp-tools.md` 修正为 69 个工具，补充 Index / Workflow / Relation / KnownLimit / Session 分类 -- `docs/reference/stable-tools/README.md` 修正为 5 个 Stable 工具（删除过时的 `project_brief.md` / `hybrid_search.md` / `session_recall.md`） - -## [0.20.1] - 2026-05-17 - -### Added - -- **Phase 1 Production Hardening** - - Workflow E2E 测试 — `src/mcp/tools/workflow.rs`：DAG 成功执行、失败传播验证 - - RF-7 路径隐私脱敏 — `sanitize_path()` 自动掩码 home 目录为 `~` - - Tantivy 一致性修复 — `repair_tantivy_consistency_at()` 启动时自动检测 orphan/missing 文档 - - 性能回归基线 — `test_keyword_search_latency_regression_1k` / `_10k`（profile-aware 阈值） - - `TempStorageBackend` — 测试隔离后端，消除 `DEVBASE_DATA_DIR` 竞态 -- **Architecture Invariants CI 自动化** — `scripts/invariant-checks/run-checks.ps1` - - G5 (RF-6)：diff-only 检测新增生产代码 `unwrap`/`expect`/`panic`（排除 `#[cfg(test)]`） - - T11：`mcp/tools` 禁止直接调用 `rusqlite::Connection` - - T12：`tui/render` 纯消费检查（禁止写入操作） - -### Fixed - -- `AppContext::with_storage()` 使用实际 storage backend 的 `index_path()` 而非硬编码默认值 -- G5 invariant checker 正则修复：`tests.rs` 文件正确跳过 -- `Cargo.lock` 同步版本 bump（修复 `--locked` release 构建失败） -- 平台相关测试隔离：`C:\` 路径断言加 `#[cfg(windows)]`，Linux `python3` 断言适配 -- HuggingFace 网络依赖测试加 `#[ignore]`（避免 CI TLS 证书失败） - -## [0.20.0] - 2026-05-16 - -### Added - -- **知识完备性**：Vault 双向链接图遍历（BFS depth 1-3）+ `[[note#heading]]` block 引用 -- **Vault 笔记历史追踪** — Git-based blob diff，`devkit_vault_history` tool -- **混合检索质量监控** — `HybridSearchMetrics`（latency/recall/overlap/keyword_source） -- **性能回归基线** — Criterion benchmarks：`index_repo_full`、`cosine_similarity`、`extract_symbols` -- **客户端无关原则** — `StorageBackend` trait 完整实现，解耦 `dirs::data_local_dir()` 硬编码 -- **MCP Tools +4** (68 total) - - `devkit_vault_history`, `devkit_vault_export`, `devkit_vault_graph`, `devkit_vault_daily` - -### Changed - -- 20+ 独立 crate 零循环依赖，workspace 拆分完成 -- `entities` 表成为唯一真相源，`repos` 表彻底删除 -- Tantivy / SQLite 补偿扫描：启动时自动同步 orphan 文档 - -## [0.19.0] - 2026-05-14 - -### Added - -- **SQLite WAL 模式** — `r2d2` 连接池 + WAL journal，并发安全与增量备份 -- **Tantivy 健康评分** — `devkit_index_health`：损坏检测、自动重建、孤儿文档清理 -- **Vault 导出** — `devkit_vault_export`：Obsidian-compatible Markdown 批量导出 -- **Redis ADR 决策** — `docs/architecture/adr-003-redis.md`：评估后决定保持 SQLite 优先 -- **OpLog 审计追踪** — 结构化事件类型 `OplogEventType`，全操作不可变日志 - -### Changed - -- Schema 迁移前自动生成 `backup-YYYYMMDD-HHMMSS.db` 快照 -- 索引层反向一致性扫描与自动修复能力 - -## [0.18.0] - 2026-05-13 - -### Added - -- **ClaudeCode 工作流集成** — `docs/RFC/claudecode-workflow-integration.md` - - `devkit_project_brief` — 生成项目 Markdown 简报（架构 + 模块 + 近期提交 + 已知约束），用于 `.claude/CLAUDE.md` 注入 - - `devkit_impact_analysis` — 符号级变更影响半径分析（BFS 调用图遍历 + 相关符号发现 + 测试启发式 + 历史 oplog） - - `scripts/devbase-claude.ps1` — PowerShell 一键启动器：自动检测 repo → 生成简报 → 注入 `.claude/CLAUDE.md` → 启动 `claude` → 可选捕获退出 diff -- **Session 导入/导出工具** - - `devkit_session_export` — 导出会话为 Markdown / JSON；支持记忆类型图标与元数据 - - `devkit_session_import` — 从 bulk text 批量导入记忆（`[type]` 前缀解析） -- **MCP Tools +4** (64 total) - - `devkit_project_brief`, `devkit_impact_analysis`, `devkit_session_export`, `devkit_session_import` -- **TUI Session 视图硬化** - - 三态 MainView 切换：`RepoList → VaultList → Session`（`Tab` 键循环） - - Session 列表：状态图标（● active / ◌ archived）+ 高亮样式 - - Session 详情：记忆类型图标（◆ decision / ▪ constraint / ★ discovery / ✗ error）+ embedding model 标签 + indexed 状态 -- **AGENTS.md** 同步至 v0.18.0-dev 基线（64 Tools / 437 tests） - -### Changed - -- `src/mcp/mod.rs` Tool 注册表扩展至 64 工具（稳定 + Beta） -- `src/mcp/tests.rs` 工具计数断言同步 -- TUI `render_session.rs` / `state/mod.rs` 适配 Schema v34 记忆字段（`embedding_model`, `indexed_at`） - -## [0.17.0] - 2026-05-13 - -### Added - -- **Agent Memory 向量存储** — Schema v34 - - `agent_memories` 新增 `embedding BLOB`, `embedding_model TEXT`, `indexed_at DATETIME` - - Partial index `idx_agent_memories_embedding` 仅索引含向量的行 - - `AgentMemory` 结构体扩展向量元数据字段 -- **SQLite UDF: `cosine_similarity`** — `src/registry/agent_context.rs` - - 输入: 两个 little-endian f32 BLOB - - 输出: REAL ∈ [-1.0, 1.0] - - 注册时机: `WorkspaceRegistry::init_db_at` 迁移完成后自动注册 -- **语义记忆搜索** — `search_memories_semantic(context_id, query_embedding, limit)` - - 纯 SQL `ORDER BY cosine_similarity(embedding, ?) DESC` - - 零 LLM 运行时依赖；仅执行向量比对 -- **MCP Tools +2** (60 total) - - `devkit_session_recall` — 外部向量查询 + 语义召回 top-k memories - - `devkit_session_index` — 为已有 memory 注入外部生成 embedding -- **Skill Runtime Auto-Recall** — `src/skill_runtime/executor.rs` - - Tier 1: Semantic recall (本地 Candle/Ollama 或外部 HTTP endpoint) - - Tier 2: Keyword fallback (`LIKE` search on `content`) - - 新环境变量: `DEVBASE_CONTEXT_MEMORY_COUNT`, `DEVBASE_CONTEXT_RECALL_METHOD` - - `DEVBASE_CONTEXT_MEMORIES` 升级为 top-k 相关 memories（含 `score` + `model`） -- **外部 Embedding Provider 集成** - - `call_external_embedding_endpoint` — `reqwest::blocking` POST `/api/embeddings` - - 配置驱动: `config.toml [embedding]` (enabled/provider/model/base_url/timeout) - - 端到端测试: mock TCP server 验证 Ollama 格式解析 + 错误码处理 -- **RFC 文档** — `docs/RFC/agent-memory-vector-storage.md` - - 架构决策: devbase = 向量数据库层，不做 embedding 生成 - - 参照 pgvector 边界设计 - -### Changed - -- **Feature Flags**: `embedding` 从 `default` 移除 - - Candle/Ollama 依赖变为 opt-in: `--features embedding` - - 默认构建零 ML 依赖，编译时间减少 30~50% -- `insert_memory` 签名扩展: 新增可选 `embedding: Option<&[f32]>` 和 `embedding_model: Option<&str>` -- `list_memories` / `search_memories` SELECT 语句扩展为 8 列（兼容新增字段） -- AGENTS.md 同步至 v0.17.0-dev 基线 - -### Breaking Changes - -- 默认构建不再包含 `devbase-embedding` crate；需要语义生成能力的用户须显式启用 `--features embedding` -- `generate_query_embedding` 在默认构建下返回错误（提示启用 feature 或配置外部 endpoint） - -## [0.16.1] - 2026-05-13 - -### Added - -- **Workflow-Session Binding** — Schema v33 - - `workflow_executions` 新增 `context_id` 列 + 索引 - - `create_execution` 自动绑定 `resolve_active_context()` - - MCP `devkit_workflow_run` 与 CLI `workflow run` 均支持自动绑定 - - `devkit_session_workflows` tool: 列出指定 context 的 workflow 执行历史 -- `context_entity_links` 表 (Schema v32): context 与任意 entity 的多对多关联 - -## [0.16.0] - 2026-05-13 - -### Added - -- **Agent Contexts (AI Agent OS)** — Schema v31 - - `agent_contexts` 表: 持久化 AI session / project scope - - `agent_memories` 表: 结构化记忆（decision/constraint/note/discovery/error） - - 9 个 Session MCP tools: save/list/resume/attach/detach/activate/search/capture/workflows - - `resolve_active_context()`: 环境变量 `DEVBASE_ACTIVE_CONTEXT` → 文件 `.active_context` fallback - - Context-aware Skill Runtime: 注入 `DEVBASE_ACTIVE_CONTEXT` + `DEVBASE_CONTEXT_MEMORIES` + `DEVBASE_CONTEXT_LINKS` - - 所有 agent_context 操作自动写入 OpLog (`OplogEventType::AgentContext`) - -## [0.15.0] - 2026-05-04 - -### Added - -- **P1: Tantivy BM25 代码符号搜索** — `search/symbol_index.rs` - - 独立 Schema (`repo_id`, `name`, `signature`, `file_path`, `line_start`) - - `keyword_search_symbols` 主路径走 Tantivy BM25，SQLite LIKE 回退 - - 索引流程 `index.rs` 自动同步写入 symbol_index - - `StorageBackend` 扩展 `symbol_index_path()`（6 实现） -- **P3: Embedding 多后端** — Candle (默认) + Ollama (配置切换) - - 新增 `OllamaProvider` (`ureq` HTTP `/api/embed`) - - `create_provider(backend, model, base_url, timeout)` 配置化创建 - - `generate_query_embedding` 通过 `OnceLock` 懒加载配置化 provider - - 默认模型改为 `all-minilm` (384-dim，与 Candle 维度兼容) -- **P4: Health 环境检测扩展** — `EnvVersionCache` 从 5 工具 → 9 工具 - - 新增: `python`, `bun`, `zig`, `java` - - `get_tool_version` 支持 stderr fallback (Java 输出到 stderr) - - `fmt_version` 改进: Java 引号提取、Docker/Python 格式处理 -- **P5: 架构不变量自动化 CI** — `scripts/invariant-checks/run-checks.ps1` - - G5: diff-only 检测新增生产代码 unwrap/expect/panic（排除 `#[cfg(test)]`） - - T11: 检测 `mcp/tools/*` 直接调用 `rusqlite::Connection` - - T12: 检测 `tui/render/*` 写入操作 - - CI job `invariant-check` 加入 `.github/workflows/ci.yml` -- **P2 Phase 1: AppContext 职责拆分** — 6 个 Client trait impl 迁出 `storage.rs` - - `scan.rs` / `health.rs` / `sync.rs` / `digest.rs` / `knowledge_engine/mod.rs` / `registry.rs` - - `storage.rs` 860 → 430 行 (-50%) - - 删除冗余 `conn_mut()` -- **P2 Phase 2: 内联 SQL 下沉** — 新增 `registry/code_symbols.rs` + `registry/dead_code.rs` - - `CodeSymbolRow` / `DeadCodeRow` + 纯函数查询 (12 个单元测试) - - `RegistryClient` 退化为纯代理层 - -### Changed - -- `EmbeddingConfig` 默认模型 `nomic-embed-text` → `all-minilm` (384-dim) -- AGENTS.md 阶段描述更新: v0.14.3 → v0.15.0 推进中 → v0.15.0 全部完成 - -### Fixed - -- **TTL 缓存负值 bug** (`97172ec`): `elapsed < ttl_seconds` → `elapsed >= 0 && elapsed < ttl_seconds` - - 防止系统时间回溯导致缓存永不过期 -- `crates/devbase-embedding/src/lib.rs` 遗留 unwrap 清零 (`encode_with_candle` → `ok_or`) - -## [0.14.3] - 2026-05-05 - -### Added - -- **Schema v30** — `code_symbols.attributes` 列，tree-sitter 提取 `#[test]`/`#[tokio::test]` 等属性 - - `devkit_dead_code` 自动过滤测试函数，消除假阳性 - - `rust_node_to_symbol` 支持 `prev_sibling()` 回溯收集属性节点 -- **Tantivy/SQLite 补偿扫描** — 启动时自动检测并清理 orphan 文档 - - 新增 `search::sync_index_to_db(conn)`，对比 Tantivy `list_indexed_repo_ids()` 与 SQLite `entities` - - `AppContext` 初始化后自动调用，失败仅 warn 不阻塞启动 -- **Feature flags** — `mcp` + `embedding`，支持 `--no-default-features` 最小化编译 - - `default = ["tui", "mcp", "embedding"]` - - `devbase-embedding` 设为 `optional = true` - - 新增 `src/clients.rs` 提取 MCP client traits，避免 mcp feature 关闭时 trait 不可用 -- **Kimi CLI MCP 集成文档** — AGENTS.md 新增 Kimi CLI 集成状态，项目级 skill 位于 `.kimi/skills/devbase-project/` - -### Changed - -- **RF-1 架构红线** — `init_db()` 全局路径残留清零 - - `init_db()` 标记 `#[deprecated]`，新增 `init_db_with(backend: &dyn StorageBackend)` - - `workflow/executor.rs`、`workflow/state.rs`、`storage.rs` 全部改为注入式 - - `examples/` + `benches/` 中额外 5 处残留同步修复 -- `index_repo_full` 合并用户 `scan.exclude_patterns` 与默认排除模式 -- `cargo fmt` + `cargo clippy --fix` 全量格式化（8 文件，6 处 warning 修复） -- `CONTRIBUTING.md` 新增 sccache 构建加速指南 - -### Fixed - -- `cargo clippy --all-targets -D warnings` — 7 warnings → 0 -- `cargo fmt --check` — 全量通过 - -## [0.14.2] - 2026-05-02 - -### Changed - -- health dirty 检测修复（排除 ignored 文件） -- scan 路径规范化 + syncthing-rust 识别修复 -- experiment_log / CodeMetrics / ModuleGraph / CallGraph / DeadCode 提升为 Beta tier -- 48 tools: Stable 5 / Beta 40 / Experimental 3 - -## [0.14.1] - 2026-05-01 - -### Added - -- CLI JSON 输出补全 (`--json` / `--recalc`) -- relations MCP 工具加固 -- License headers 全量补录 -- Vault Daily / Vault Graph MCP tools - -## [0.14.0] - 2026-04-28 - -### Added - -- Workspace 拆分：6 个零耦合 crate 提取 -- MCP trait 化：`mcp/tools/repo.rs` `crate::` 引用 68→41 - -## [0.13.0] - 2026-04-26 - -### Added - -- Registry God Object 拆解：10 子模块提取为 free function -- `WorkspaceRegistry` 退化为纯 facade - -## [0.12.0] - 2026-04-30 - -### Added - -- **Schema v22** — drop `vault_notes`, `papers`, `workflows` orphan tables; `entities` becomes sole source of truth for all entity types -- **Managed-Gate Fail-Safe Defaults** — `devbase sync` defaults to managed repos only - - Management tags: `mirror`, `reference`, `third-party`, `collaborative`, `team`, `own-project`, `tool`, `active`, `managed` - - Untagged / non-management repos are registered but skipped by default sync - - `--filter-tags` bypasses the gate for explicit selection -- **`.devbase-ignore`** — directory-level opt-out exclusion during scan -- `scan --register` no longer auto-tags repos with `"discovered"` -- i18n hint for unmanaged repos - -### Changed - -- `inspect_repo`: remove `"discovered"` from default tags; `-main`/`-master` repos keep `zip-snapshot` + `needs-migration` -- `collect_tasks`: default mode filters by management tags -- All `list_workflows` / `list_papers` / `list_vault_notes` queries migrated to `entities` table + `json_extract` -- Generic `upsert_entity` abstraction for entity dual-write -- `ENTITY_TYPE_*` constants extracted across 10 files (~25 replacements) -- `cargo test --lib`: 374 → 379 passed - -### Breaking Changes - -- Existing repos tagged `"discovered"` are **no longer synced by default**. - Use `devbase tag managed` (or any management tag) to opt a repo into automatic sync. - -## [0.10.0] - 2026-04-26 - -### Added - -- **L3 Risk Layer MVP** — `known_limits` 表 + Registry CRUD + MCP tools + CLI subcommand - - Schema v18: `known_limits` 表（id, category, description, source, severity, first_seen_at, last_checked_at, mitigated） - - Registry CRUD: `save`/`get`/`list`/`delete`/`resolve`/`seed_hard_vetoes` - - MCP tools: `devkit_known_limit_store` / `devkit_known_limit_list`（Beta tier） - - CLI: `devbase limit {add,list,resolve,delete,seed}` - - OpLog 集成: create/update/resolve/delete/seed 自动写入 oplog（event_type = `KnownLimit`） - - Hard Veto 种子: AGENTS.md 中的 5 条硬约束自动填充 -- **L4 元认知层 MVP** — `knowledge_meta` 表 + L3-L4 联动 - - Schema v19: `knowledge_meta` 表（id, target_level, target_id, correction_type, correction_json, confidence, created_at） - - Registry CRUD: `save`/`get`/`list`/`delete` - - CLI 联动: `devbase limit resolve --reason "..."` 自动创建 L4 meta 记录 -- **Hard Veto 运行时守卫** — Skill 执行前自动检查未解决 hard veto - - `skill_runtime::executor::run_skill` 执行前查询 `known_limits` - - 未解决 hard veto 存在时，警告注入 `stderr`，同时写入 OpLog - - 零破坏性：skill 仍执行成功，但输出中包含 `[HARD-VETO-WARNING]` - -### Changed - -- `cargo test --all-targets`: 279 → 288 passed -- MCP tool 总数: 35 → 37 - -## [0.11.3] - 2026-04-26 - -### Changed - -- **Phase 1 主从表切换 — Stage 3 完成**（`repos` 表删除） - - `save_repo` / `update_repo_*` / `run_clean` 不再写入 `repos` - - Schema v21 迁移：重建 11 个子表（去 FK）→ 删除 `repos` 表 - - `test_helpers.rs` SCHEMA_DDL 同步去 `repos` + 去 FK - - `entities` 成为真正的读写唯一数据源 - -## [0.11.2] - 2026-04-26 - -### Changed - -- **Phase 1 主从表切换 — Stage 2 完成**（读路径迁移） - - `list_repos` / `list_repos_stale_health` / `list_repos_need_index` / `list_workspaces_by_tier` 全部改为从 `entities` 读取（`json_extract`） - - `digest.rs` / `health.rs` / `daemon.rs` / `backup.rs` / `knowledge_engine.rs` / `sync/*.rs` / `tui/state.rs` / `mcp/tools/repo.rs` 等所有 `list_repos()` 调用方自动迁移 - - 直接 SQL 查询迁移：`dependency_graph.rs`, `registry/links.rs`, `registry/knowledge.rs`, `query.rs`, `oplog_analytics.rs`, `commands/simple.rs` - - `update_entity_metadata_field` 修复 `json_set` 字符串引号问题：原始字符串直接传递，`"null"` 时自动 `json_remove` - - `repo_tags` / `repo_remotes` 子表保留，通过 `repo_id` JOIN 读取（FK 仍指向 `repos`） - -## [0.11.1] - 2026-04-26 - -### Changed - -- **Phase 1 主从表切换 — Stage 0 完成**（entities 第一公民前置） - - Schema v20: Flat ID 命名空间迁移（`repo:devbase` → `devbase`，`skill:xxx` → `xxx`） - - `sync_repo_to_entities_by_id` 重构为 `upsert_entity_for_repo`：直接由 `RepoEntry` 写入 entities，不再读取 repos - - `update_repo_*` 改为先写 entities metadata（`json_set`），再写 repos - - `save_repo` 写入顺序反转：entities → repos → repo_tags → repo_remotes - - `run_tag` 补全 entities 双写：`sync_repo_tags_to_entity` - - `run_clean` 改为先删 entities，再删 repos（保留 CASCADE 行为） - - Skill entities 同步同理去除 `skill:` 前缀 - -## [0.11.0] - 2026-04-26 - -### Added - -- **AppContext Pool 化** — 全链路数据库连接池统一 - - `AppContext` 持 `r2d2::Pool`，替代单 `Connection` - - `scan`/`health`/`sync`/`backup`/`daemon`/`query` 等深层模块全部迁移 - - `init_db()` 调用点从 89 处降至 5 处合法保留（Pool 前 schema 引导 ×2、migrate 定义 ×1、workflow 测试辅助 ×2） - - 根治 `spawn_blocking` / `thread::spawn` 闭包无法传递裸 `Connection` 的问题 -- **MCP 测试隔离** — 全部 MCP 集成测试改用临时目录 - - `DEVBASE_DATA_DIR` 指向 `tempfile::TempDir` + `AppContext::with_defaults()` - - 多线程并发测试全部通过，无 flaky -- **Search 测试竞态自愈** — `SEARCH_TEST_LOCK` + 临时目录隔离，多线程 (`--test-threads=4`) 稳定通过 - -### Changed - -- `cargo test --all-targets`: 288 → 374 passed（+86 个新增/迁移测试） -- CI 测试并行度: `--test-threads=1` → `--test-threads=4`，回归测试耗时 ~13s → ~4s -- `rusqlite` 0.34 + `r2d2_sqlite` 0.27.0 版本锁定 - -## [0.9.0] - 2026-04-26 - -### Added - -- **Workflow Loop Step 完整执行** — 5 种 step 类型全部可执行 - - `StepType::Loop { for_each, body }`：遍历集合，执行 body 子步骤 - - 变量插值：`${loop.item}` / `${loop.index}` - - 结果聚合：stdout 按迭代索引标记，outputs 合并 - - 失败处理：单迭代失败按 body step 的 `on_error` 策略处理 -- **12 个新增单元测试** — model/interpolate/validator/executor 全覆盖 - -### Changed - -- `cargo test --all-targets`：267 → 279 passed - -## [0.8.0] - 2026-04-25 - -### Added - -- **Workflow 子类型执行** — Subworkflow / Parallel / Condition 全部可执行 - - `execute_subworkflow_step`：递归调用 `execute_workflow` - - `execute_parallel_step`：子步骤串行执行 + 结果聚合 - - `execute_condition_step`：字符串插值后 true/false 评估 -- **NLQ 自然语言查询结果可执行** — TUI `[:]` 搜索结果按 Enter 直接运行 skill -- **NLQ smoke test** — `run_nlp_selected_skill` 空列表/无技能/执行管道测试 -- **TUI SkillPanel 拆分** — `SkillPanelState` 提取 7 个字段，App 51→44 字段 - -### Fixed - -- 29 个生产代码 unwrap 全部清零 -- 30 个 clippy 警告清零 - -## [0.7.0] - 2026-04-20 - -### Added - -- **NLQ 自然语言查询** — TUI `[:]` 触发 embedding 语义搜索，fallback 降级文本搜索 -- **智能同步建议** — `sync/policy.rs::recommend_sync_action` 基于 safety/ahead/behind 生成建议 - -## [0.6.0] - 2026-04-18 - -### Added - -- **Mind Market 评分系统** — `skill_runtime::scoring` - - `success_rate` + `usage_count` + `rating`（0-5 分公式） - - CLI：`skill recalc-scores` / `skill top` / `skill recommend` -- **TUI Workflow 执行** — `[w]` 详情页 `r/Enter` 运行 + 结果弹窗 - -## [0.5.0] - 2026-04-17 - -### Added - -- **Workflow Engine v0.5.0** — YAML 编排多步骤自动化 - - 5 种 step 类型：skill / subworkflow / parallel / condition / loop - - 拓扑调度（Kahn 算法）+ batch 并行执行 - - 变量插值：`${inputs.x}` / `${steps.y.outputs.z}` - - 错误策略：Fail / Continue / Retry / Fallback - - Schema v17：`workflows` + `workflow_executions` 表 -- **CLI/TUI Workflow 集成** — `devbase workflow {list,show,register,run,delete}` + `[w]` 面板 - -## [0.4.0] - 2026-04-15 - -### Added - -- **Schema v16 统一实体模型** — `entity_types` + `entities` + `relations` 表，渐进双写 -- **Skill 自动封装** — `devbase skill discover ` 自动分析项目 CLI/API，生成 SKILL.md -- **Git URL Discover** — `devbase skill discover https://github.com/...` 克隆+分析+注册 -- **MCP `devkit_skill_discover`** — 35 tools 总数 - -## [0.3.0] - 2026-04-12 - -### Added - -- **34 MCP tools 全量通过 MCP Inspector** -- **README Quick Start 三步内跑通** -- **CI/CD** — `.github/workflows/ci.yml`（check / test / fmt / clippy on Windows） -- **GitHub Release 预编译二进制** - -## [0.2.4] - 2026-04-20 - -### Architecture - -- **Outboard Brain Embedding Architecture** — Embedding generation moved to external Skill/MCP Server - - `embedding.rs` stripped of Ollama/OpenAI generation logic; storage protocol only (`embedding_to_bytes`, `bytes_to_embedding`, `cosine_similarity`) - - `knowledge_engine.rs` no longer generates embeddings during indexing - - Aligns with "store + search in devbase, compute in Clarity/Skill" boundary - -### Changed - -- **Breaking** — `devkit_semantic_search` now accepts `query_embedding: number[]` instead of `query: string` - - Embedding generation is the caller's responsibility (external MCP Server or Skill) - - Removed `config.embedding.enabled` gate; search works as long as embeddings exist in DB - -### Added - -- **`devkit_embedding_store`** — Store externally-generated embedding vectors into SQLite - - Parameters: `repo_id`, `symbol_name`, `embedding: number[]` - - Upsert semantics (ON CONFLICT UPDATE) -- **`devkit_embedding_search`** — Alias for `devkit_semantic_search` with vector-based interface - - Same parameters and behavior, alternative name for workflow clarity -- **MCP tool count**: 25 → 31 - -## [0.2.4] - 2026-04-20 (continued) - -### Added - -- **`devkit_hybrid_search`** — Hybrid vector + keyword search via RRF merge (Beta) - - `search::hybrid.rs`: `rrf_merge()` (Reciprocal Rank Fusion, k=60), `keyword_search_symbols()` (SQLite LIKE on name/signature), `hybrid_search_symbols()` (auto-fallback to keyword when embedding missing) - - `registry::knowledge::hybrid_search_symbols()` wrapper - - Recommended default search tool for code concept discovery -- **`devkit_cross_repo_search`** — Cross-repository symbol search filtered by tags (Beta) - - `registry::knowledge::cross_repo_search_symbols()`: INTERSECT-based tag filtering (AND semantics), per-repo hybrid search, global dedup+sort - - Searches all repos matching ALL specified tags -- **`devkit_knowledge_report`** — Workspace knowledge coverage report (Beta) - - `src/oplog_analytics.rs`: `generate_report()` with table-existence guards for resilient querying - - Reports: repo_count, total_symbols, total_embeddings, total_calls, coverage_pct, per-repo breakdown, health_summary, recent_activity -- **`devkit_related_symbols`** — Explicit symbol-to-symbol knowledge links (Experimental) - - Schema v13: `code_symbol_links` table (source_repo, source_symbol, target_repo, target_symbol, link_type, strength) - - `src/symbol_links.rs`: `compute_similar_signature_links()` (Jaccard token overlap), `compute_co_located_links()` (same-file clustering) - - `generate_and_save_links()`: persists links with ON CONFLICT IGNORE upsert -- **External Embedding Provider** — Reference Python implementation in `examples/embedding-provider/` - - `index.py`: Ollama `/api/embeddings` client, batch generation, cross-platform registry DB path - - Byte-compatible f32 little-endian serialization via `struct.pack` - - CLI: `--repo-id`, `--model`, `--ollama-url`, `--batch-size`, `--force` -- **Schema v13** — `code_symbol_links` table for explicit conceptual relationships - -### Engineering - -- **Context Safety Mechanism** — Formalized as long-term architecture principle - - Sub-agent execution: serial + commit-isolated work directories (prevents compilation races) - - MCP tool idempotency: all state-mutating tools use ON CONFLICT UPDATE / transaction boundaries - - OpLog as immutable audit trail for all state transitions - ---- - -## [0.2.3] - 2026-04-20 - -### Added - -- **Semantic Vector Search (Wave 1)** — Cosine-similarity code symbol search - - `code_embeddings` table (Schema v11): `repo_id + symbol_name` PK, BLOB embedding, `generated_at` - - `embedding.rs`: Ollama/OpenAI-compatible generation + `cosine_similarity` + byte serialization - - `devkit_semantic_search` MCP tool (Beta): natural-language → embedding → top-K symbols -- **Multi-Language Symbol Extraction (Wave 2)** — tree-sitter AST parsing beyond Rust - - `tree-sitter-python`, `tree-sitter-typescript`, `tree-sitter-go` dependencies - - `SymbolType` expanded: Function, Struct, Enum, Trait, Impl, Module, Class, Interface, TypeAlias, Constant, Static - - Per-language call-target resolvers for Call Graph construction - - Languages supported: Rust, Python, JavaScript, TypeScript, Go -- **Call Graph Analysis** — Intra-repo function call relationship extraction - - `code_call_graph` table (Schema v10): caller → callee edges with line numbers - - `devkit_call_graph` MCP tool: "Who calls `register_tool`?" -- **Cross-Repo Dependency Graph expansion** - - `CMakeLists.txt` parsing: `find_package`, `add_subdirectory`, `FetchContent_Declare`, `target_link_libraries` - - `ManifestKind::CMake` added to dependency graph builder -- **Dead Code Detection** — `devkit_dead_code` MCP tool (Experimental) - - SQL `NOT EXISTS` query over call graph to find functions with zero incoming edges - - `LIKE 'pub%fn%'` heuristic to exclude non-public functions -- **arXiv Integration** — Pure string-parsing Atom XML fetcher (zero heavy XML deps) - - `arxiv.rs`: `PaperMetadata` with title/authors/summary/published/category - - `devkit_arxiv_fetch` MCP tool (Beta): fetch by arXiv ID -- **Performance Benchmarks** — Criterion suite (`benches/semantic_index.rs`) - - `index_repo_full` (small/medium/full parameterization) - - `cosine_similarity` (128/512/768 dims) - - `extract_symbols` (Rust/Python/Go comparison) - - `parse_cmake_lists` (CMake parsing) -- **Structured OpLog (Schema v12)** — Typed event system - - `OplogEventType` enum replacing free-text `operation` field - - JSON metadata + `duration_ms` for observability - - Migration: `CASE` mapping from legacy strings to enum variants - -### Fixed - -- **`scan` async panic** — `fetch_github_stars` now runs in `std::thread::spawn` isolation - - Prevents `reqwest::blocking::Client` drop inside tokio runtime from causing panic - - `block_on_async()` helper detects runtime context and uses `mpsc` or temporary runtime -- **Dead code false positives** — `pub fn` → `pub%fn%` SQL LIKE match covers `pub async fn` / `pub(crate) fn` / `pub unsafe fn` - - Excludes `main()` from dead code results -- **Clippy warnings** — 12+ lints resolved (`manual_strip`, `collapsible_if`, `FromStr`, `type_complexity`, `useless_format`, etc.) - -### Changed - -- **`nl_filter_repos`** — Now uses Tantivy full-text search as primary path - - Falls back to structured SQL filtering when Tantivy is unavailable - ---- - -## [0.2.2] - 2026-04-21 - -### Added - -- **Vault Backlinks** — Find notes that link to a given note - - `vault::backlinks:` query prefix - - TUI detail panel shows "被引用" section with backlink count and list - - MCP tool `devkit_vault_backlinks` — AI can discover note relationships - - `vault/backlinks.rs` with `build_backlink_index()` and `get_backlinks()` - -### Changed - -- **Schema v8** — `vault_notes` table no longer has `content` column - - Migration: auto-creates `vault_notes_v2`, migrates data, drops old table - - `save_vault_note` / `list_vault_notes` SQL updated to 8 columns - - Filesystem-first architecture now complete at the database level - -## [0.2.1] - 2026-04-20 - -### Added - -- **Vault Watch** — Filesystem watcher for `workspace/vault/` - - Auto-refresh TUI vault list when notes are edited externally - - 500ms debounce to avoid excessive reloads -- **Vault Tantivy Search** — `vault:` queries now use Tantivy full-text index - - Replaces slow SQLite LIKE + per-file reading - - Supports keyword scoring and ranking -- **MCP Registry Manifest** — `server.json` for official MCP Registry submission - -### Changed - -- `query.rs` vault branch: uses `search_vault()` instead of in-memory filtering - -## [0.2.0] - 2026-04-20 - -### Added - -- **Vault System** — Markdown note management with Obsidian-compatible PARA structure - - `vault/` directory with PARA folders: 00-Inbox, 01-Projects, 02-Areas, 03-Resources, 04-Archives, 99-Meta - - Filesystem-first architecture: note content lives in `.md` files, SQLite only indexes metadata - - YAML frontmatter parsing (title, tags, aliases, date) - - WikiLink `[[...]]` extraction and backlink index building -- **TUI Vault View** — Press `Tab` to switch between Repo list and Vault note list - - Vault list shows note titles with tag indicators - - Detail panel previews note content (first 20 lines), tags, and outgoing links - - `Enter` opens selected note in VS Code -- **MCP Vault Tools** — 3 new tools for AI Agent vault interaction - - `devkit_vault_search` — full-text search across vault notes - - `devkit_vault_read` — read note content and frontmatter by path - - `devkit_vault_write` — write or append to vault notes -- **P2-lite: repos.toml** — Optional static configuration override for repositories - - Declare tags, tier, and workspace_type in `workspace/repos.toml` - - Overrides are applied on top of auto-discovered repo metadata -- **Unified Node Model** — `core::node::{Node, NodeType, Edge}` abstraction - - `NodeType::GitRepo | VaultNote | Asset | ExternalLink` - - Foundation for future Knowledge Graph unification -- **Workspace Directory** — `%LOCALAPPDATA%/devbase/workspace/` with `vault/` and `assets/` -- **MCP Client Config** — `mcp.json` for Claude Desktop / Cursor integration - -### Changed - -- **Architecture principle**: File system = source of truth; SQLite/Tantivy = derived index/cache -- Vault notes no longer store `content` in SQLite (read from disk on demand) - -## [0.1.0] - 2026-04-20 - -### Added - -- **TUI Dashboard** — Terminal UI for multi-repository workspace management - - Repository list with status icons, stars, and tag indicators - - Detail panel with Overview / Health / Insights tabs - - Stars Trend sparkline (30-day history) - - Help Overlay with categorized keyboard shortcuts - - Responsive layout: compact / standard / wide screen modes - - Cross-repository code search (ripgrep + Tantivy dual mode) - - One-key launch into gitui / lazygit -- **MCP Server** — 14 tools for AI Agent integration (stdio transport) - - `devkit_scan`, `devkit_health`, `devkit_sync`, `devkit_query_repos` - - `devkit_code_metrics`, `devkit_module_graph`, `devkit_natural_language_query` - - `devkit_index`, `devkit_query`, `devkit_note`, `devkit_digest` - - `devkit_github_info`, `devkit_paper_index`, `devkit_experiment_log` -- **Safe Sync Engine** — Four-tier sync policies: Mirror / Conservative / Rebase / Merge - - Pre-sync safety assessment (dirty, diverged, detached HEAD detection) - - Dry-run preview with per-repo recommendations - - Async batch sync with concurrency control and timeout -- **Registry & Indexing** — SQLite-backed workspace registry - - Automatic Git + non-Git workspace discovery - - Schema migrations with automatic backup snapshots - - GitHub Stars cache with TTL and historical tracking - - Tantivy full-text index for repository knowledge search -- **Health Monitoring** — Workspace-wide health checks - - Git status tracking (dirty / ahead / behind / diverged) - - Blake3 hash snapshots for non-Git workspaces - - Environment tool version detection -- **i18n** — Chinese and English bilingual support -- **CI/CD** — GitHub Actions workflow for check, test, fmt, clippy on Windows - -### Engineering - -- Modular architecture: 22 crates modules with clear separation of concerns -- Dual lib+bin mode: `lib.rs` exports all modules for programmatic use -- Theme system with semantic color tokens (dark/light ready) -- Render layer split from monolithic 1026-line file into 6 focused submodules - -### Security - -- `cargo audit` clean (0 vulnerabilities in direct dependencies) - -[0.20.1]: https://github.com/juice094/devbase/releases/tag/v0.20.1 -[0.20.0]: https://github.com/juice094/devbase/releases/tag/v0.20.0 -[0.19.0]: https://github.com/juice094/devbase/releases/tag/v0.19.0 -[0.18.0]: https://github.com/juice094/devbase/releases/tag/v0.18.0 -[0.1.0]: https://github.com/juice094/devbase/releases/tag/v0.1.0 +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added + +- **FTS5 技能全文搜索** (Schema v35) — `skills_fts` 虚拟表 + 触发器，`search_skills_text()` 使用 BM25 排序（name=1.0, desc=0.8, tags=0.4, category=0.2），LIKE 降级 fallback +- **可插拔外部技能源** (Schema v36) — `SkillSource` trait + `GitHubSource` / `LocalFileSource`，`sync_sources` / `sync_log` 审计表，`devkit_skill_sync` MCP 工具（Beta tier），`devbase skill import` CLI 子命令 +- **Vault 多根目录 + symlink 跟随** — `VaultConfig`（roots + follow_symlinks），多根目录扫描 `scan_vault_with_options`，`resolve_vault_write_path` 实体回溯路径解析，`devbase vault sync` CLI +- **Ontology 导入** — `devkit_ontology_import` MCP 工具（Beta tier），`devbase ontology` CLI（`--dry-run` 预览），支持 OpenClaw workspace `ontology/entities/*.json` + `ontology/relations/*.jsonl` 批量导入 +- MCP 工具数: 69 → **71**（5 stable + 62 beta + 4 experimental） +- `devkit_document_convert` — Experimental tier MCP tool，PDF/PPTX → Markdown 转换（`pdftotext` / `python-pptx` 流水线），含 frontmatter 质量标注 +- Stable 工具 invocation 测试补全：`devkit_query_repos`、`devkit_vault_search`、`devkit_vault_read`、`devkit_status`、`devkit_workflow_list`、`devkit_index` +- `seed_repo()` 轻量测试 helper（仅插入 `entities` 表，无副作用） + +### Fixed + +- `mcp/tools/document_convert.rs` 原始字符串定界符修复（`r###"` 避免与 Python f-string `"##` 冲突） +- `cleanup_extracted_text` 单元测试期望值与实现语义对齐（保留最多 2 个连续空行） + +### Changed + +- **Workspace crate 架构重组** — 消除机械提取造成的微 crate 碎片 + - 合并 8 个 `devbase-registry-*` 微 crate（100–300 行/个）为统一 `devbase-registry`，含 8 个语义子模块（`entity`, `health`, `metrics`, `relation`, `call_graph`, `code_symbols`, `dead_code`, `workspace`） + - 拆分 10+ 个 monolithic `lib.rs` 为域驱动子模块：`devbase-embedding` (`candle`/`ollama`), `devbase-workflow-model` (`definition`/`execution`/`step_type`), `devbase-symbol-links` (`similarity`/`co_located`), `devbase-sync-protocol` (`index`/`version_vector`), `devbase-skill-runtime-types` (`skill_type`/`execution`/`params`), `devbase-skill-runtime-parser` (`frontmatter`/`field_parsers`), `devbase-workflow-interpolate` (`resolver`), `devbase-vault-frontmatter` (`parser`), `devbase-vault-wikilink` (`parser`), `devbase-core-types` (`node_type`/`node`/`edge`) + - 全 workspace `Cargo.toml` 统一使用 `[workspace.package]` 继承（`version`, `edition`, `authors`, `license`, `repository`） +- `KNOWN_ISSUES.md` 更新：document_convert 从 P3 债务移至已解决归档；测试计数 485→494 +- `docs/reference/mcp-tools.md` 修正为 69 个工具，补充 Index / Workflow / Relation / KnownLimit / Session 分类 +- `docs/reference/stable-tools/README.md` 修正为 5 个 Stable 工具（删除过时的 `project_brief.md` / `hybrid_search.md` / `session_recall.md`） + +## [0.20.1] - 2026-05-17 + +### Added + +- **Phase 1 Production Hardening** + - Workflow E2E 测试 — `src/mcp/tools/workflow.rs`：DAG 成功执行、失败传播验证 + - RF-7 路径隐私脱敏 — `sanitize_path()` 自动掩码 home 目录为 `~` + - Tantivy 一致性修复 — `repair_tantivy_consistency_at()` 启动时自动检测 orphan/missing 文档 + - 性能回归基线 — `test_keyword_search_latency_regression_1k` / `_10k`（profile-aware 阈值） + - `TempStorageBackend` — 测试隔离后端，消除 `DEVBASE_DATA_DIR` 竞态 +- **Architecture Invariants CI 自动化** — `scripts/invariant-checks/run-checks.ps1` + - G5 (RF-6)：diff-only 检测新增生产代码 `unwrap`/`expect`/`panic`（排除 `#[cfg(test)]`） + - T11：`mcp/tools` 禁止直接调用 `rusqlite::Connection` + - T12：`tui/render` 纯消费检查（禁止写入操作） + +### Fixed + +- `AppContext::with_storage()` 使用实际 storage backend 的 `index_path()` 而非硬编码默认值 +- G5 invariant checker 正则修复：`tests.rs` 文件正确跳过 +- `Cargo.lock` 同步版本 bump（修复 `--locked` release 构建失败） +- 平台相关测试隔离：`C:\` 路径断言加 `#[cfg(windows)]`，Linux `python3` 断言适配 +- HuggingFace 网络依赖测试加 `#[ignore]`（避免 CI TLS 证书失败） + +## [0.20.0] - 2026-05-16 + +### Added + +- **知识完备性**：Vault 双向链接图遍历（BFS depth 1-3）+ `[[note#heading]]` block 引用 +- **Vault 笔记历史追踪** — Git-based blob diff，`devkit_vault_history` tool +- **混合检索质量监控** — `HybridSearchMetrics`（latency/recall/overlap/keyword_source） +- **性能回归基线** — Criterion benchmarks：`index_repo_full`、`cosine_similarity`、`extract_symbols` +- **客户端无关原则** — `StorageBackend` trait 完整实现，解耦 `dirs::data_local_dir()` 硬编码 +- **MCP Tools +4** (68 total) + - `devkit_vault_history`, `devkit_vault_export`, `devkit_vault_graph`, `devkit_vault_daily` + +### Changed + +- 20+ 独立 crate 零循环依赖，workspace 拆分完成 +- `entities` 表成为唯一真相源，`repos` 表彻底删除 +- Tantivy / SQLite 补偿扫描：启动时自动同步 orphan 文档 + +## [0.19.0] - 2026-05-14 + +### Added + +- **SQLite WAL 模式** — `r2d2` 连接池 + WAL journal，并发安全与增量备份 +- **Tantivy 健康评分** — `devkit_index_health`：损坏检测、自动重建、孤儿文档清理 +- **Vault 导出** — `devkit_vault_export`：Obsidian-compatible Markdown 批量导出 +- **Redis ADR 决策** — `docs/architecture/adr-003-redis.md`：评估后决定保持 SQLite 优先 +- **OpLog 审计追踪** — 结构化事件类型 `OplogEventType`，全操作不可变日志 + +### Changed + +- Schema 迁移前自动生成 `backup-YYYYMMDD-HHMMSS.db` 快照 +- 索引层反向一致性扫描与自动修复能力 + +## [0.18.0] - 2026-05-13 + +### Added + +- **ClaudeCode 工作流集成** — `docs/RFC/claudecode-workflow-integration.md` + - `devkit_project_brief` — 生成项目 Markdown 简报（架构 + 模块 + 近期提交 + 已知约束），用于 `.claude/CLAUDE.md` 注入 + - `devkit_impact_analysis` — 符号级变更影响半径分析（BFS 调用图遍历 + 相关符号发现 + 测试启发式 + 历史 oplog） + - `scripts/devbase-claude.ps1` — PowerShell 一键启动器：自动检测 repo → 生成简报 → 注入 `.claude/CLAUDE.md` → 启动 `claude` → 可选捕获退出 diff +- **Session 导入/导出工具** + - `devkit_session_export` — 导出会话为 Markdown / JSON；支持记忆类型图标与元数据 + - `devkit_session_import` — 从 bulk text 批量导入记忆（`[type]` 前缀解析） +- **MCP Tools +4** (64 total) + - `devkit_project_brief`, `devkit_impact_analysis`, `devkit_session_export`, `devkit_session_import` +- **TUI Session 视图硬化** + - 三态 MainView 切换：`RepoList → VaultList → Session`（`Tab` 键循环） + - Session 列表：状态图标（● active / ◌ archived）+ 高亮样式 + - Session 详情：记忆类型图标（◆ decision / ▪ constraint / ★ discovery / ✗ error）+ embedding model 标签 + indexed 状态 +- **AGENTS.md** 同步至 v0.18.0-dev 基线（64 Tools / 437 tests） + +### Changed + +- `src/mcp/mod.rs` Tool 注册表扩展至 64 工具（稳定 + Beta） +- `src/mcp/tests.rs` 工具计数断言同步 +- TUI `render_session.rs` / `state/mod.rs` 适配 Schema v34 记忆字段（`embedding_model`, `indexed_at`） + +## [0.17.0] - 2026-05-13 + +### Added + +- **Agent Memory 向量存储** — Schema v34 + - `agent_memories` 新增 `embedding BLOB`, `embedding_model TEXT`, `indexed_at DATETIME` + - Partial index `idx_agent_memories_embedding` 仅索引含向量的行 + - `AgentMemory` 结构体扩展向量元数据字段 +- **SQLite UDF: `cosine_similarity`** — `src/registry/agent_context.rs` + - 输入: 两个 little-endian f32 BLOB + - 输出: REAL ∈ [-1.0, 1.0] + - 注册时机: `WorkspaceRegistry::init_db_at` 迁移完成后自动注册 +- **语义记忆搜索** — `search_memories_semantic(context_id, query_embedding, limit)` + - 纯 SQL `ORDER BY cosine_similarity(embedding, ?) DESC` + - 零 LLM 运行时依赖；仅执行向量比对 +- **MCP Tools +2** (60 total) + - `devkit_session_recall` — 外部向量查询 + 语义召回 top-k memories + - `devkit_session_index` — 为已有 memory 注入外部生成 embedding +- **Skill Runtime Auto-Recall** — `src/skill_runtime/executor.rs` + - Tier 1: Semantic recall (本地 Candle/Ollama 或外部 HTTP endpoint) + - Tier 2: Keyword fallback (`LIKE` search on `content`) + - 新环境变量: `DEVBASE_CONTEXT_MEMORY_COUNT`, `DEVBASE_CONTEXT_RECALL_METHOD` + - `DEVBASE_CONTEXT_MEMORIES` 升级为 top-k 相关 memories（含 `score` + `model`） +- **外部 Embedding Provider 集成** + - `call_external_embedding_endpoint` — `reqwest::blocking` POST `/api/embeddings` + - 配置驱动: `config.toml [embedding]` (enabled/provider/model/base_url/timeout) + - 端到端测试: mock TCP server 验证 Ollama 格式解析 + 错误码处理 +- **RFC 文档** — `docs/RFC/agent-memory-vector-storage.md` + - 架构决策: devbase = 向量数据库层，不做 embedding 生成 + - 参照 pgvector 边界设计 + +### Changed + +- **Feature Flags**: `embedding` 从 `default` 移除 + - Candle/Ollama 依赖变为 opt-in: `--features embedding` + - 默认构建零 ML 依赖，编译时间减少 30~50% +- `insert_memory` 签名扩展: 新增可选 `embedding: Option<&[f32]>` 和 `embedding_model: Option<&str>` +- `list_memories` / `search_memories` SELECT 语句扩展为 8 列（兼容新增字段） +- AGENTS.md 同步至 v0.17.0-dev 基线 + +### Breaking Changes + +- 默认构建不再包含 `devbase-embedding` crate；需要语义生成能力的用户须显式启用 `--features embedding` +- `generate_query_embedding` 在默认构建下返回错误（提示启用 feature 或配置外部 endpoint） + +## [0.16.1] - 2026-05-13 + +### Added + +- **Workflow-Session Binding** — Schema v33 + - `workflow_executions` 新增 `context_id` 列 + 索引 + - `create_execution` 自动绑定 `resolve_active_context()` + - MCP `devkit_workflow_run` 与 CLI `workflow run` 均支持自动绑定 + - `devkit_session_workflows` tool: 列出指定 context 的 workflow 执行历史 +- `context_entity_links` 表 (Schema v32): context 与任意 entity 的多对多关联 + +## [0.16.0] - 2026-05-13 + +### Added + +- **Agent Contexts (AI Agent OS)** — Schema v31 + - `agent_contexts` 表: 持久化 AI session / project scope + - `agent_memories` 表: 结构化记忆（decision/constraint/note/discovery/error） + - 9 个 Session MCP tools: save/list/resume/attach/detach/activate/search/capture/workflows + - `resolve_active_context()`: 环境变量 `DEVBASE_ACTIVE_CONTEXT` → 文件 `.active_context` fallback + - Context-aware Skill Runtime: 注入 `DEVBASE_ACTIVE_CONTEXT` + `DEVBASE_CONTEXT_MEMORIES` + `DEVBASE_CONTEXT_LINKS` + - 所有 agent_context 操作自动写入 OpLog (`OplogEventType::AgentContext`) + +## [0.15.0] - 2026-05-04 + +### Added + +- **P1: Tantivy BM25 代码符号搜索** — `search/symbol_index.rs` + - 独立 Schema (`repo_id`, `name`, `signature`, `file_path`, `line_start`) + - `keyword_search_symbols` 主路径走 Tantivy BM25，SQLite LIKE 回退 + - 索引流程 `index.rs` 自动同步写入 symbol_index + - `StorageBackend` 扩展 `symbol_index_path()`（6 实现） +- **P3: Embedding 多后端** — Candle (默认) + Ollama (配置切换) + - 新增 `OllamaProvider` (`ureq` HTTP `/api/embed`) + - `create_provider(backend, model, base_url, timeout)` 配置化创建 + - `generate_query_embedding` 通过 `OnceLock` 懒加载配置化 provider + - 默认模型改为 `all-minilm` (384-dim，与 Candle 维度兼容) +- **P4: Health 环境检测扩展** — `EnvVersionCache` 从 5 工具 → 9 工具 + - 新增: `python`, `bun`, `zig`, `java` + - `get_tool_version` 支持 stderr fallback (Java 输出到 stderr) + - `fmt_version` 改进: Java 引号提取、Docker/Python 格式处理 +- **P5: 架构不变量自动化 CI** — `scripts/invariant-checks/run-checks.ps1` + - G5: diff-only 检测新增生产代码 unwrap/expect/panic（排除 `#[cfg(test)]`） + - T11: 检测 `mcp/tools/*` 直接调用 `rusqlite::Connection` + - T12: 检测 `tui/render/*` 写入操作 + - CI job `invariant-check` 加入 `.github/workflows/ci.yml` +- **P2 Phase 1: AppContext 职责拆分** — 6 个 Client trait impl 迁出 `storage.rs` + - `scan.rs` / `health.rs` / `sync.rs` / `digest.rs` / `knowledge_engine/mod.rs` / `registry.rs` + - `storage.rs` 860 → 430 行 (-50%) + - 删除冗余 `conn_mut()` +- **P2 Phase 2: 内联 SQL 下沉** — 新增 `registry/code_symbols.rs` + `registry/dead_code.rs` + - `CodeSymbolRow` / `DeadCodeRow` + 纯函数查询 (12 个单元测试) + - `RegistryClient` 退化为纯代理层 + +### Changed + +- `EmbeddingConfig` 默认模型 `nomic-embed-text` → `all-minilm` (384-dim) +- AGENTS.md 阶段描述更新: v0.14.3 → v0.15.0 推进中 → v0.15.0 全部完成 + +### Fixed + +- **TTL 缓存负值 bug** (`97172ec`): `elapsed < ttl_seconds` → `elapsed >= 0 && elapsed < ttl_seconds` + - 防止系统时间回溯导致缓存永不过期 +- `crates/devbase-embedding/src/lib.rs` 遗留 unwrap 清零 (`encode_with_candle` → `ok_or`) + +## [0.14.3] - 2026-05-05 + +### Added + +- **Schema v30** — `code_symbols.attributes` 列，tree-sitter 提取 `#[test]`/`#[tokio::test]` 等属性 + - `devkit_dead_code` 自动过滤测试函数，消除假阳性 + - `rust_node_to_symbol` 支持 `prev_sibling()` 回溯收集属性节点 +- **Tantivy/SQLite 补偿扫描** — 启动时自动检测并清理 orphan 文档 + - 新增 `search::sync_index_to_db(conn)`，对比 Tantivy `list_indexed_repo_ids()` 与 SQLite `entities` + - `AppContext` 初始化后自动调用，失败仅 warn 不阻塞启动 +- **Feature flags** — `mcp` + `embedding`，支持 `--no-default-features` 最小化编译 + - `default = ["tui", "mcp", "embedding"]` + - `devbase-embedding` 设为 `optional = true` + - 新增 `src/clients.rs` 提取 MCP client traits，避免 mcp feature 关闭时 trait 不可用 +- **Kimi CLI MCP 集成文档** — AGENTS.md 新增 Kimi CLI 集成状态，项目级 skill 位于 `.kimi/skills/devbase-project/` + +### Changed + +- **RF-1 架构红线** — `init_db()` 全局路径残留清零 + - `init_db()` 标记 `#[deprecated]`，新增 `init_db_with(backend: &dyn StorageBackend)` + - `workflow/executor.rs`、`workflow/state.rs`、`storage.rs` 全部改为注入式 + - `examples/` + `benches/` 中额外 5 处残留同步修复 +- `index_repo_full` 合并用户 `scan.exclude_patterns` 与默认排除模式 +- `cargo fmt` + `cargo clippy --fix` 全量格式化（8 文件，6 处 warning 修复） +- `CONTRIBUTING.md` 新增 sccache 构建加速指南 + +### Fixed + +- `cargo clippy --all-targets -D warnings` — 7 warnings → 0 +- `cargo fmt --check` — 全量通过 + +## [0.14.2] - 2026-05-02 + +### Changed + +- health dirty 检测修复（排除 ignored 文件） +- scan 路径规范化 + syncthing-rust 识别修复 +- experiment_log / CodeMetrics / ModuleGraph / CallGraph / DeadCode 提升为 Beta tier +- 48 tools: Stable 5 / Beta 40 / Experimental 3 + +## [0.14.1] - 2026-05-01 + +### Added + +- CLI JSON 输出补全 (`--json` / `--recalc`) +- relations MCP 工具加固 +- License headers 全量补录 +- Vault Daily / Vault Graph MCP tools + +## [0.14.0] - 2026-04-28 + +### Added + +- Workspace 拆分：6 个零耦合 crate 提取 +- MCP trait 化：`mcp/tools/repo.rs` `crate::` 引用 68→41 + +## [0.13.0] - 2026-04-26 + +### Added + +- Registry God Object 拆解：10 子模块提取为 free function +- `WorkspaceRegistry` 退化为纯 facade + +## [0.12.0] - 2026-04-30 + +### Added + +- **Schema v22** — drop `vault_notes`, `papers`, `workflows` orphan tables; `entities` becomes sole source of truth for all entity types +- **Managed-Gate Fail-Safe Defaults** — `devbase sync` defaults to managed repos only + - Management tags: `mirror`, `reference`, `third-party`, `collaborative`, `team`, `own-project`, `tool`, `active`, `managed` + - Untagged / non-management repos are registered but skipped by default sync + - `--filter-tags` bypasses the gate for explicit selection +- **`.devbase-ignore`** — directory-level opt-out exclusion during scan +- `scan --register` no longer auto-tags repos with `"discovered"` +- i18n hint for unmanaged repos + +### Changed + +- `inspect_repo`: remove `"discovered"` from default tags; `-main`/`-master` repos keep `zip-snapshot` + `needs-migration` +- `collect_tasks`: default mode filters by management tags +- All `list_workflows` / `list_papers` / `list_vault_notes` queries migrated to `entities` table + `json_extract` +- Generic `upsert_entity` abstraction for entity dual-write +- `ENTITY_TYPE_*` constants extracted across 10 files (~25 replacements) +- `cargo test --lib`: 374 → 379 passed + +### Breaking Changes + +- Existing repos tagged `"discovered"` are **no longer synced by default**. + Use `devbase tag managed` (or any management tag) to opt a repo into automatic sync. + +## [0.10.0] - 2026-04-26 + +### Added + +- **L3 Risk Layer MVP** — `known_limits` 表 + Registry CRUD + MCP tools + CLI subcommand + - Schema v18: `known_limits` 表（id, category, description, source, severity, first_seen_at, last_checked_at, mitigated） + - Registry CRUD: `save`/`get`/`list`/`delete`/`resolve`/`seed_hard_vetoes` + - MCP tools: `devkit_known_limit_store` / `devkit_known_limit_list`（Beta tier） + - CLI: `devbase limit {add,list,resolve,delete,seed}` + - OpLog 集成: create/update/resolve/delete/seed 自动写入 oplog（event_type = `KnownLimit`） + - Hard Veto 种子: AGENTS.md 中的 5 条硬约束自动填充 +- **L4 元认知层 MVP** — `knowledge_meta` 表 + L3-L4 联动 + - Schema v19: `knowledge_meta` 表（id, target_level, target_id, correction_type, correction_json, confidence, created_at） + - Registry CRUD: `save`/`get`/`list`/`delete` + - CLI 联动: `devbase limit resolve --reason "..."` 自动创建 L4 meta 记录 +- **Hard Veto 运行时守卫** — Skill 执行前自动检查未解决 hard veto + - `skill_runtime::executor::run_skill` 执行前查询 `known_limits` + - 未解决 hard veto 存在时，警告注入 `stderr`，同时写入 OpLog + - 零破坏性：skill 仍执行成功，但输出中包含 `[HARD-VETO-WARNING]` + +### Changed + +- `cargo test --all-targets`: 279 → 288 passed +- MCP tool 总数: 35 → 37 + +## [0.11.3] - 2026-04-26 + +### Changed + +- **Phase 1 主从表切换 — Stage 3 完成**（`repos` 表删除） + - `save_repo` / `update_repo_*` / `run_clean` 不再写入 `repos` + - Schema v21 迁移：重建 11 个子表（去 FK）→ 删除 `repos` 表 + - `test_helpers.rs` SCHEMA_DDL 同步去 `repos` + 去 FK + - `entities` 成为真正的读写唯一数据源 + +## [0.11.2] - 2026-04-26 + +### Changed + +- **Phase 1 主从表切换 — Stage 2 完成**（读路径迁移） + - `list_repos` / `list_repos_stale_health` / `list_repos_need_index` / `list_workspaces_by_tier` 全部改为从 `entities` 读取（`json_extract`） + - `digest.rs` / `health.rs` / `daemon.rs` / `backup.rs` / `knowledge_engine.rs` / `sync/*.rs` / `tui/state.rs` / `mcp/tools/repo.rs` 等所有 `list_repos()` 调用方自动迁移 + - 直接 SQL 查询迁移：`dependency_graph.rs`, `registry/links.rs`, `registry/knowledge.rs`, `query.rs`, `oplog_analytics.rs`, `commands/simple.rs` + - `update_entity_metadata_field` 修复 `json_set` 字符串引号问题：原始字符串直接传递，`"null"` 时自动 `json_remove` + - `repo_tags` / `repo_remotes` 子表保留，通过 `repo_id` JOIN 读取（FK 仍指向 `repos`） + +## [0.11.1] - 2026-04-26 + +### Changed + +- **Phase 1 主从表切换 — Stage 0 完成**（entities 第一公民前置） + - Schema v20: Flat ID 命名空间迁移（`repo:devbase` → `devbase`，`skill:xxx` → `xxx`） + - `sync_repo_to_entities_by_id` 重构为 `upsert_entity_for_repo`：直接由 `RepoEntry` 写入 entities，不再读取 repos + - `update_repo_*` 改为先写 entities metadata（`json_set`），再写 repos + - `save_repo` 写入顺序反转：entities → repos → repo_tags → repo_remotes + - `run_tag` 补全 entities 双写：`sync_repo_tags_to_entity` + - `run_clean` 改为先删 entities，再删 repos（保留 CASCADE 行为） + - Skill entities 同步同理去除 `skill:` 前缀 + +## [0.11.0] - 2026-04-26 + +### Added + +- **AppContext Pool 化** — 全链路数据库连接池统一 + - `AppContext` 持 `r2d2::Pool`，替代单 `Connection` + - `scan`/`health`/`sync`/`backup`/`daemon`/`query` 等深层模块全部迁移 + - `init_db()` 调用点从 89 处降至 5 处合法保留（Pool 前 schema 引导 ×2、migrate 定义 ×1、workflow 测试辅助 ×2） + - 根治 `spawn_blocking` / `thread::spawn` 闭包无法传递裸 `Connection` 的问题 +- **MCP 测试隔离** — 全部 MCP 集成测试改用临时目录 + - `DEVBASE_DATA_DIR` 指向 `tempfile::TempDir` + `AppContext::with_defaults()` + - 多线程并发测试全部通过，无 flaky +- **Search 测试竞态自愈** — `SEARCH_TEST_LOCK` + 临时目录隔离，多线程 (`--test-threads=4`) 稳定通过 + +### Changed + +- `cargo test --all-targets`: 288 → 374 passed（+86 个新增/迁移测试） +- CI 测试并行度: `--test-threads=1` → `--test-threads=4`，回归测试耗时 ~13s → ~4s +- `rusqlite` 0.34 + `r2d2_sqlite` 0.27.0 版本锁定 + +## [0.9.0] - 2026-04-26 + +### Added + +- **Workflow Loop Step 完整执行** — 5 种 step 类型全部可执行 + - `StepType::Loop { for_each, body }`：遍历集合，执行 body 子步骤 + - 变量插值：`${loop.item}` / `${loop.index}` + - 结果聚合：stdout 按迭代索引标记，outputs 合并 + - 失败处理：单迭代失败按 body step 的 `on_error` 策略处理 +- **12 个新增单元测试** — model/interpolate/validator/executor 全覆盖 + +### Changed + +- `cargo test --all-targets`：267 → 279 passed + +## [0.8.0] - 2026-04-25 + +### Added + +- **Workflow 子类型执行** — Subworkflow / Parallel / Condition 全部可执行 + - `execute_subworkflow_step`：递归调用 `execute_workflow` + - `execute_parallel_step`：子步骤串行执行 + 结果聚合 + - `execute_condition_step`：字符串插值后 true/false 评估 +- **NLQ 自然语言查询结果可执行** — TUI `[:]` 搜索结果按 Enter 直接运行 skill +- **NLQ smoke test** — `run_nlp_selected_skill` 空列表/无技能/执行管道测试 +- **TUI SkillPanel 拆分** — `SkillPanelState` 提取 7 个字段，App 51→44 字段 + +### Fixed + +- 29 个生产代码 unwrap 全部清零 +- 30 个 clippy 警告清零 + +## [0.7.0] - 2026-04-20 + +### Added + +- **NLQ 自然语言查询** — TUI `[:]` 触发 embedding 语义搜索，fallback 降级文本搜索 +- **智能同步建议** — `sync/policy.rs::recommend_sync_action` 基于 safety/ahead/behind 生成建议 + +## [0.6.0] - 2026-04-18 + +### Added + +- **Mind Market 评分系统** — `skill_runtime::scoring` + - `success_rate` + `usage_count` + `rating`（0-5 分公式） + - CLI：`skill recalc-scores` / `skill top` / `skill recommend` +- **TUI Workflow 执行** — `[w]` 详情页 `r/Enter` 运行 + 结果弹窗 + +## [0.5.0] - 2026-04-17 + +### Added + +- **Workflow Engine v0.5.0** — YAML 编排多步骤自动化 + - 5 种 step 类型：skill / subworkflow / parallel / condition / loop + - 拓扑调度（Kahn 算法）+ batch 并行执行 + - 变量插值：`${inputs.x}` / `${steps.y.outputs.z}` + - 错误策略：Fail / Continue / Retry / Fallback + - Schema v17：`workflows` + `workflow_executions` 表 +- **CLI/TUI Workflow 集成** — `devbase workflow {list,show,register,run,delete}` + `[w]` 面板 + +## [0.4.0] - 2026-04-15 + +### Added + +- **Schema v16 统一实体模型** — `entity_types` + `entities` + `relations` 表，渐进双写 +- **Skill 自动封装** — `devbase skill discover ` 自动分析项目 CLI/API，生成 SKILL.md +- **Git URL Discover** — `devbase skill discover https://github.com/...` 克隆+分析+注册 +- **MCP `devkit_skill_discover`** — 35 tools 总数 + +## [0.3.0] - 2026-04-12 + +### Added + +- **34 MCP tools 全量通过 MCP Inspector** +- **README Quick Start 三步内跑通** +- **CI/CD** — `.github/workflows/ci.yml`（check / test / fmt / clippy on Windows） +- **GitHub Release 预编译二进制** + +## [0.2.4] - 2026-04-20 + +### Architecture + +- **Outboard Brain Embedding Architecture** — Embedding generation moved to external Skill/MCP Server + - `embedding.rs` stripped of Ollama/OpenAI generation logic; storage protocol only (`embedding_to_bytes`, `bytes_to_embedding`, `cosine_similarity`) + - `knowledge_engine.rs` no longer generates embeddings during indexing + - Aligns with "store + search in devbase, compute in Clarity/Skill" boundary + +### Changed + +- **Breaking** — `devkit_semantic_search` now accepts `query_embedding: number[]` instead of `query: string` + - Embedding generation is the caller's responsibility (external MCP Server or Skill) + - Removed `config.embedding.enabled` gate; search works as long as embeddings exist in DB + +### Added + +- **`devkit_embedding_store`** — Store externally-generated embedding vectors into SQLite + - Parameters: `repo_id`, `symbol_name`, `embedding: number[]` + - Upsert semantics (ON CONFLICT UPDATE) +- **`devkit_embedding_search`** — Alias for `devkit_semantic_search` with vector-based interface + - Same parameters and behavior, alternative name for workflow clarity +- **MCP tool count**: 25 → 31 + +## [0.2.4] - 2026-04-20 (continued) + +### Added + +- **`devkit_hybrid_search`** — Hybrid vector + keyword search via RRF merge (Beta) + - `search::hybrid.rs`: `rrf_merge()` (Reciprocal Rank Fusion, k=60), `keyword_search_symbols()` (SQLite LIKE on name/signature), `hybrid_search_symbols()` (auto-fallback to keyword when embedding missing) + - `registry::knowledge::hybrid_search_symbols()` wrapper + - Recommended default search tool for code concept discovery +- **`devkit_cross_repo_search`** — Cross-repository symbol search filtered by tags (Beta) + - `registry::knowledge::cross_repo_search_symbols()`: INTERSECT-based tag filtering (AND semantics), per-repo hybrid search, global dedup+sort + - Searches all repos matching ALL specified tags +- **`devkit_knowledge_report`** — Workspace knowledge coverage report (Beta) + - `src/oplog_analytics.rs`: `generate_report()` with table-existence guards for resilient querying + - Reports: repo_count, total_symbols, total_embeddings, total_calls, coverage_pct, per-repo breakdown, health_summary, recent_activity +- **`devkit_related_symbols`** — Explicit symbol-to-symbol knowledge links (Experimental) + - Schema v13: `code_symbol_links` table (source_repo, source_symbol, target_repo, target_symbol, link_type, strength) + - `src/symbol_links.rs`: `compute_similar_signature_links()` (Jaccard token overlap), `compute_co_located_links()` (same-file clustering) + - `generate_and_save_links()`: persists links with ON CONFLICT IGNORE upsert +- **External Embedding Provider** — Reference Python implementation in `examples/embedding-provider/` + - `index.py`: Ollama `/api/embeddings` client, batch generation, cross-platform registry DB path + - Byte-compatible f32 little-endian serialization via `struct.pack` + - CLI: `--repo-id`, `--model`, `--ollama-url`, `--batch-size`, `--force` +- **Schema v13** — `code_symbol_links` table for explicit conceptual relationships + +### Engineering + +- **Context Safety Mechanism** — Formalized as long-term architecture principle + - Sub-agent execution: serial + commit-isolated work directories (prevents compilation races) + - MCP tool idempotency: all state-mutating tools use ON CONFLICT UPDATE / transaction boundaries + - OpLog as immutable audit trail for all state transitions + +--- + +## [0.2.3] - 2026-04-20 + +### Added + +- **Semantic Vector Search (Wave 1)** — Cosine-similarity code symbol search + - `code_embeddings` table (Schema v11): `repo_id + symbol_name` PK, BLOB embedding, `generated_at` + - `embedding.rs`: Ollama/OpenAI-compatible generation + `cosine_similarity` + byte serialization + - `devkit_semantic_search` MCP tool (Beta): natural-language → embedding → top-K symbols +- **Multi-Language Symbol Extraction (Wave 2)** — tree-sitter AST parsing beyond Rust + - `tree-sitter-python`, `tree-sitter-typescript`, `tree-sitter-go` dependencies + - `SymbolType` expanded: Function, Struct, Enum, Trait, Impl, Module, Class, Interface, TypeAlias, Constant, Static + - Per-language call-target resolvers for Call Graph construction + - Languages supported: Rust, Python, JavaScript, TypeScript, Go +- **Call Graph Analysis** — Intra-repo function call relationship extraction + - `code_call_graph` table (Schema v10): caller → callee edges with line numbers + - `devkit_call_graph` MCP tool: "Who calls `register_tool`?" +- **Cross-Repo Dependency Graph expansion** + - `CMakeLists.txt` parsing: `find_package`, `add_subdirectory`, `FetchContent_Declare`, `target_link_libraries` + - `ManifestKind::CMake` added to dependency graph builder +- **Dead Code Detection** — `devkit_dead_code` MCP tool (Experimental) + - SQL `NOT EXISTS` query over call graph to find functions with zero incoming edges + - `LIKE 'pub%fn%'` heuristic to exclude non-public functions +- **arXiv Integration** — Pure string-parsing Atom XML fetcher (zero heavy XML deps) + - `arxiv.rs`: `PaperMetadata` with title/authors/summary/published/category + - `devkit_arxiv_fetch` MCP tool (Beta): fetch by arXiv ID +- **Performance Benchmarks** — Criterion suite (`benches/semantic_index.rs`) + - `index_repo_full` (small/medium/full parameterization) + - `cosine_similarity` (128/512/768 dims) + - `extract_symbols` (Rust/Python/Go comparison) + - `parse_cmake_lists` (CMake parsing) +- **Structured OpLog (Schema v12)** — Typed event system + - `OplogEventType` enum replacing free-text `operation` field + - JSON metadata + `duration_ms` for observability + - Migration: `CASE` mapping from legacy strings to enum variants + +### Fixed + +- **`scan` async panic** — `fetch_github_stars` now runs in `std::thread::spawn` isolation + - Prevents `reqwest::blocking::Client` drop inside tokio runtime from causing panic + - `block_on_async()` helper detects runtime context and uses `mpsc` or temporary runtime +- **Dead code false positives** — `pub fn` → `pub%fn%` SQL LIKE match covers `pub async fn` / `pub(crate) fn` / `pub unsafe fn` + - Excludes `main()` from dead code results +- **Clippy warnings** — 12+ lints resolved (`manual_strip`, `collapsible_if`, `FromStr`, `type_complexity`, `useless_format`, etc.) + +### Changed + +- **`nl_filter_repos`** — Now uses Tantivy full-text search as primary path + - Falls back to structured SQL filtering when Tantivy is unavailable + +--- + +## [0.2.2] - 2026-04-21 + +### Added + +- **Vault Backlinks** — Find notes that link to a given note + - `vault::backlinks:` query prefix + - TUI detail panel shows "被引用" section with backlink count and list + - MCP tool `devkit_vault_backlinks` — AI can discover note relationships + - `vault/backlinks.rs` with `build_backlink_index()` and `get_backlinks()` + +### Changed + +- **Schema v8** — `vault_notes` table no longer has `content` column + - Migration: auto-creates `vault_notes_v2`, migrates data, drops old table + - `save_vault_note` / `list_vault_notes` SQL updated to 8 columns + - Filesystem-first architecture now complete at the database level + +## [0.2.1] - 2026-04-20 + +### Added + +- **Vault Watch** — Filesystem watcher for `workspace/vault/` + - Auto-refresh TUI vault list when notes are edited externally + - 500ms debounce to avoid excessive reloads +- **Vault Tantivy Search** — `vault:` queries now use Tantivy full-text index + - Replaces slow SQLite LIKE + per-file reading + - Supports keyword scoring and ranking +- **MCP Registry Manifest** — `server.json` for official MCP Registry submission + +### Changed + +- `query.rs` vault branch: uses `search_vault()` instead of in-memory filtering + +## [0.2.0] - 2026-04-20 + +### Added + +- **Vault System** — Markdown note management with Obsidian-compatible PARA structure + - `vault/` directory with PARA folders: 00-Inbox, 01-Projects, 02-Areas, 03-Resources, 04-Archives, 99-Meta + - Filesystem-first architecture: note content lives in `.md` files, SQLite only indexes metadata + - YAML frontmatter parsing (title, tags, aliases, date) + - WikiLink `[[...]]` extraction and backlink index building +- **TUI Vault View** — Press `Tab` to switch between Repo list and Vault note list + - Vault list shows note titles with tag indicators + - Detail panel previews note content (first 20 lines), tags, and outgoing links + - `Enter` opens selected note in VS Code +- **MCP Vault Tools** — 3 new tools for AI Agent vault interaction + - `devkit_vault_search` — full-text search across vault notes + - `devkit_vault_read` — read note content and frontmatter by path + - `devkit_vault_write` — write or append to vault notes +- **P2-lite: repos.toml** — Optional static configuration override for repositories + - Declare tags, tier, and workspace_type in `workspace/repos.toml` + - Overrides are applied on top of auto-discovered repo metadata +- **Unified Node Model** — `core::node::{Node, NodeType, Edge}` abstraction + - `NodeType::GitRepo | VaultNote | Asset | ExternalLink` + - Foundation for future Knowledge Graph unification +- **Workspace Directory** — `%LOCALAPPDATA%/devbase/workspace/` with `vault/` and `assets/` +- **MCP Client Config** — `mcp.json` for Claude Desktop / Cursor integration + +### Changed + +- **Architecture principle**: File system = source of truth; SQLite/Tantivy = derived index/cache +- Vault notes no longer store `content` in SQLite (read from disk on demand) + +## [0.1.0] - 2026-04-20 + +### Added + +- **TUI Dashboard** — Terminal UI for multi-repository workspace management + - Repository list with status icons, stars, and tag indicators + - Detail panel with Overview / Health / Insights tabs + - Stars Trend sparkline (30-day history) + - Help Overlay with categorized keyboard shortcuts + - Responsive layout: compact / standard / wide screen modes + - Cross-repository code search (ripgrep + Tantivy dual mode) + - One-key launch into gitui / lazygit +- **MCP Server** — 14 tools for AI Agent integration (stdio transport) + - `devkit_scan`, `devkit_health`, `devkit_sync`, `devkit_query_repos` + - `devkit_code_metrics`, `devkit_module_graph`, `devkit_natural_language_query` + - `devkit_index`, `devkit_query`, `devkit_note`, `devkit_digest` + - `devkit_github_info`, `devkit_paper_index`, `devkit_experiment_log` +- **Safe Sync Engine** — Four-tier sync policies: Mirror / Conservative / Rebase / Merge + - Pre-sync safety assessment (dirty, diverged, detached HEAD detection) + - Dry-run preview with per-repo recommendations + - Async batch sync with concurrency control and timeout +- **Registry & Indexing** — SQLite-backed workspace registry + - Automatic Git + non-Git workspace discovery + - Schema migrations with automatic backup snapshots + - GitHub Stars cache with TTL and historical tracking + - Tantivy full-text index for repository knowledge search +- **Health Monitoring** — Workspace-wide health checks + - Git status tracking (dirty / ahead / behind / diverged) + - Blake3 hash snapshots for non-Git workspaces + - Environment tool version detection +- **i18n** — Chinese and English bilingual support +- **CI/CD** — GitHub Actions workflow for check, test, fmt, clippy on Windows + +### Engineering + +- Modular architecture: 22 crates modules with clear separation of concerns +- Dual lib+bin mode: `lib.rs` exports all modules for programmatic use +- Theme system with semantic color tokens (dark/light ready) +- Render layer split from monolithic 1026-line file into 6 focused submodules + +### Security + +- `cargo audit` clean (0 vulnerabilities in direct dependencies) + +[0.20.1]: https://github.com/juice094/devbase/releases/tag/v0.20.1 +[0.20.0]: https://github.com/juice094/devbase/releases/tag/v0.20.0 +[0.19.0]: https://github.com/juice094/devbase/releases/tag/v0.19.0 +[0.18.0]: https://github.com/juice094/devbase/releases/tag/v0.18.0 +[0.1.0]: https://github.com/juice094/devbase/releases/tag/v0.1.0 diff --git a/Cargo.lock b/Cargo.lock index b2696e1..a808cfb 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1440,6 +1440,7 @@ version = "0.20.1" dependencies = [ "anyhow", "assert_cmd", + "async-trait", "blake3", "chrono", "clap", diff --git a/Cargo.toml b/Cargo.toml index 2b89a7e..2250f6e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -39,6 +39,7 @@ tracing = "0.1" tracing-subscriber = { version = "0.3", features = ["env-filter"] } walkdir = "2" anyhow = "1" +async-trait = "0.1" serde_json = "1" reqwest = { version = "0.12", features = ["json", "blocking"] } tantivy = "0.26" diff --git a/README.md b/README.md index 607ea58..1db3877 100644 --- a/README.md +++ b/README.md @@ -1,146 +1,146 @@ -
- -# 🗄️ devbase - -> **开发者工作空间的世界模型编译器** - -一套引擎，统一代码上下文、知识记忆与智能体推理。 - -[![Version](https://img.shields.io/badge/version-v0.20.1-blue)](https://github.com/juice094/devbase/releases) -[![Tests](https://img.shields.io/badge/tests-494%2B%20passed-brightgreen)](https://github.com/juice094/devbase/actions) -[![Clippy](https://img.shields.io/badge/clippy-0%20warnings-green)](https://github.com/juice094/devbase/actions) -[![License](https://img.shields.io/badge/license-AGPL--3.0%20%2F%20Commercial-orange)](LICENSE) -[![Rust](https://img.shields.io/badge/rust-1.95%2B-9cf)](https://www.rust-lang.org) -[![Glama](https://glama.ai/mcp/servers/juice094/devbase/badges/score.svg)](https://glama.ai/mcp/servers/juice094/devbase) - -
- ---- - -## 📋 简介 - -devbase 将代码库、笔记与工作流编译为 AI 可推理的结构化情境 — 不是存储数据，是构建环境的心智模型。 - -| 你是谁 | devbase 为你做什么 | -|:---|:---| -| **人类开发者** | `devbase tui` — 终端仪表盘，一眼看清 N 个仓库的 Git 状态，按 `s` 批量安全同步 | -| **AI 智能体** | 69 个 MCP 工具：通过 `devkit_skill_run` 发现、执行、编排 Skill — 不再重复造轮子 | -| **项目维护者** | `devbase skill discover .` — 一键将项目封装为 Skill，让 AI 用户能够发现和调用 | - ---- - -## 🌟 核心亮点 - -| 亮点 | 说明 | -|:---|:---| -| 📊 **TUI 仪表盘** | ratatui 终端界面：跨仓库搜索、安全同步、Skill/Workflow 发现 | -| 🔌 **69 个 MCP 工具** | stdio 本地进程通信：仓库管理、代码分析、知识图谱、智能体记忆 | -| 🏠 **本地优先** | 零数据离开本机 — SQLite + Tantivy + tree-sitter，无需云端 | -| 🔍 **混合检索** | BM25 全文 + 纯 SQL 向量搜索（`cosine_similarity` UDF），零 ML 运行时依赖 | - -> [完整 69 个 Tool 矩阵 → docs/guides/mcp-integration.md](docs/guides/mcp-integration.md) - ---- - -## 🔧 技术栈 - -| 组件 | 技术 | -|:---|:---| -| 终端 UI | ratatui | -| 全文检索 | Tantivy (BM25) | -| 语义检索 | SQLite BLOB + `cosine_similarity` UDF | -| 代码解析 | tree-sitter (Rust/Python/TS/Go) | -| 关系存储 | SQLite (WAL 模式, OpLog 审计) | -| 协议 | Model Context Protocol (stdio) | - ---- - -## 📁 项目结构 - -``` -devbase/ -├── src/ -│ ├── main.rs # CLI 入口：命令解析与分发 -│ ├── tui/ # 终端仪表盘（ratatui） -│ │ # 多仓库导航、跨仓库搜索、安全同步预览 -│ ├── mcp/ # MCP Server（69 个工具，stdio 通信） -│ │ # 人类与 AI 的统一接口层 -│ ├── registry/ # 仓库注册表：Git 状态、健康检查、批量同步 -│ ├── index/ # Tantivy 全文索引 + SQLite 向量索引 -│ │ # 混合检索核心，BM25 + cosine 向量评分 -│ ├── vault/ # PARA 笔记系统：双向链接、BFS 图遍历 -│ ├── skill/ # Skill 生命周期：发现 → 安装 → 执行 → 评分 → 发布 -│ │ # 自动封装项目为 AI 可调用的 Skill -│ ├── workflow/ # YAML 编排引擎：5 种 step 类型，拓扑调度 + 并行执行 -│ └── session/ # 智能体会话生命周期 + 向量记忆持久化 -├── docs/ -│ ├── architecture/ # 架构文档总览 -│ └── guides/ # 集成指南（Claude Code / 5ire / Kimi CLI） -├── scripts/ -│ ├── install.ps1 # Windows 一键安装 -│ ├── install.sh # Linux/macOS 一键安装 -│ └── devbase-claude.ps1 # Claude Code 一键启动器 -└── README.md -``` - -### 核心设计 - -**三层架构**： -1. **交互层** — TUI 仪表盘 + MCP Server + Workflow 引擎（人类与 AI 的接口） -2. **编译层** — 感知（tree-sitter/Tantivy/Git）→ 知识（图谱/向量/关系）→ 策略（同步/工作流/健康守卫） -3. **可靠层** — SQLite WAL 并发安全 + 索引健康检测 + OpLog 全操作审计 - -> 可靠性红线：所有 Registry 写入必须留下不可变审计痕迹（OpLog）；Schema 迁移前自动生成快照。详见 [docs/architecture/overview.md](docs/architecture/overview.md)。 - ---- - -## 🚀 快速开始 - -```powershell -# Windows 一行安装 -irm https://raw.githubusercontent.com/juice094/devbase/main/scripts/install.ps1 | iex - -# 或下载预编译二进制（~8.7 MB） -# https://github.com/juice094/devbase/releases/tag/v0.20.1 -``` - -```bash -# Linux / macOS -curl -fsSL https://raw.githubusercontent.com/juice094/devbase/main/scripts/install.sh | bash - -# 基础工作流 -devbase scan . --register # 1. 扫描并注册工作区 -devbase tui # 2. 打开仪表盘 -devbase mcp # 3. 启动 MCP 服务端（供 AI 调用） -``` - -**AI 助手配置** — 添加到 `claude_desktop_config.json` 或 `~/.kimi/mcp.json`： -```json -{ "mcpServers": { "devbase": { "command": "devbase", "args": ["mcp"] } } } -``` - ---- - -## 🤝 参与贡献 - -详见 [CONTRIBUTING.md](CONTRIBUTING.md) — 添加 MCP 工具、Skill Schema、构建模式说明。快速验证： - -```bash -cargo build --release -cargo test --all-targets -cargo clippy --all-targets -D warnings -``` - ---- - -## 📄 许可证 - -双许可证：[AGPL-3.0+](LICENSE) 开源 / [商业授权](LICENSE-COMMERCIAL.md) 闭源使用。联系：`juice094@protonmail.com`。 - ---- - -
- -**[⭐ Star](https://github.com/juice094/devbase) · [🐛 Issues](https://github.com/juice094/devbase/issues) · [🤝 Contribute](CONTRIBUTING.md)** - -
+
+ +# 🗄️ devbase + +> **开发者工作空间的世界模型编译器** + +一套引擎，统一代码上下文、知识记忆与智能体推理。 + +[![Version](https://img.shields.io/badge/version-v0.20.1-blue)](https://github.com/juice094/devbase/releases) +[![Tests](https://img.shields.io/badge/tests-494%2B%20passed-brightgreen)](https://github.com/juice094/devbase/actions) +[![Clippy](https://img.shields.io/badge/clippy-0%20warnings-green)](https://github.com/juice094/devbase/actions) +[![License](https://img.shields.io/badge/license-AGPL--3.0%20%2F%20Commercial-orange)](LICENSE) +[![Rust](https://img.shields.io/badge/rust-1.95%2B-9cf)](https://www.rust-lang.org) +[![Glama](https://glama.ai/mcp/servers/juice094/devbase/badges/score.svg)](https://glama.ai/mcp/servers/juice094/devbase) + +
+ +--- + +## 📋 简介 + +devbase 将代码库、笔记与工作流编译为 AI 可推理的结构化情境 — 不是存储数据，是构建环境的心智模型。 + +| 你是谁 | devbase 为你做什么 | +|:---|:---| +| **人类开发者** | `devbase tui` — 终端仪表盘，一眼看清 N 个仓库的 Git 状态，按 `s` 批量安全同步 | +| **AI 智能体** | 71 个 MCP 工具：通过 `devkit_skill_run` 发现、执行、编排 Skill — 不再重复造轮子 | +| **项目维护者** | `devbase skill discover .` — 一键将项目封装为 Skill，让 AI 用户能够发现和调用 | + +--- + +## 🌟 核心亮点 + +| 亮点 | 说明 | +|:---|:---| +| 📊 **TUI 仪表盘** | ratatui 终端界面：跨仓库搜索、安全同步、Skill/Workflow 发现 | +| 🔌 **71 个 MCP 工具** | stdio 本地进程通信：仓库管理、代码分析、知识图谱、智能体记忆 | +| 🏠 **本地优先** | 零数据离开本机 — SQLite + Tantivy + tree-sitter，无需云端 | +| 🔍 **混合检索** | BM25 全文 + FTS5 技能搜索 + 纯 SQL 向量搜索（`cosine_similarity` UDF），零 ML 运行时依赖 | + +> [完整 71 个 Tool 矩阵 → docs/guides/mcp-integration.md](docs/guides/mcp-integration.md) + +--- + +## 🔧 技术栈 + +| 组件 | 技术 | +|:---|:---| +| 终端 UI | ratatui | +| 全文检索 | Tantivy (BM25) | +| 语义检索 | SQLite BLOB + `cosine_similarity` UDF | +| 代码解析 | tree-sitter (Rust/Python/TS/Go) | +| 关系存储 | SQLite (WAL 模式, OpLog 审计) | +| 协议 | Model Context Protocol (stdio) | + +--- + +## 📁 项目结构 + +``` +devbase/ +├── src/ +│ ├── main.rs # CLI 入口：命令解析与分发 +│ ├── tui/ # 终端仪表盘（ratatui） +│ │ # 多仓库导航、跨仓库搜索、安全同步预览 +│ ├── mcp/ # MCP Server（71 个工具，stdio 通信） +│ │ # 人类与 AI 的统一接口层 +│ ├── registry/ # 仓库注册表：Git 状态、健康检查、批量同步 +│ ├── index/ # Tantivy 全文索引 + SQLite 向量索引 +│ │ # 混合检索核心，BM25 + cosine 向量评分 +│ ├── vault/ # PARA 笔记系统：双向链接、BFS 图遍历 +│ ├── skill/ # Skill 生命周期：发现 → 安装 → 执行 → 评分 → 发布 +│ │ # 自动封装项目为 AI 可调用的 Skill +│ ├── workflow/ # YAML 编排引擎：5 种 step 类型，拓扑调度 + 并行执行 +│ └── session/ # 智能体会话生命周期 + 向量记忆持久化 +├── docs/ +│ ├── architecture/ # 架构文档总览 +│ └── guides/ # 集成指南（Claude Code / 5ire / Kimi CLI） +├── scripts/ +│ ├── install.ps1 # Windows 一键安装 +│ ├── install.sh # Linux/macOS 一键安装 +│ └── devbase-claude.ps1 # Claude Code 一键启动器 +└── README.md +``` + +### 核心设计 + +**三层架构**： +1. **交互层** — TUI 仪表盘 + MCP Server + Workflow 引擎（人类与 AI 的接口） +2. **编译层** — 感知（tree-sitter/Tantivy/Git）→ 知识（图谱/向量/关系）→ 策略（同步/工作流/健康守卫） +3. **可靠层** — SQLite WAL 并发安全 + 索引健康检测 + OpLog 全操作审计 + +> 可靠性红线：所有 Registry 写入必须留下不可变审计痕迹（OpLog）；Schema 迁移前自动生成快照。详见 [docs/architecture/overview.md](docs/architecture/overview.md)。 + +--- + +## 🚀 快速开始 + +```powershell +# Windows 一行安装 +irm https://raw.githubusercontent.com/juice094/devbase/main/scripts/install.ps1 | iex + +# 或下载预编译二进制（~8.7 MB） +# https://github.com/juice094/devbase/releases/tag/v0.20.1 +``` + +```bash +# Linux / macOS +curl -fsSL https://raw.githubusercontent.com/juice094/devbase/main/scripts/install.sh | bash + +# 基础工作流 +devbase scan . --register # 1. 扫描并注册工作区 +devbase tui # 2. 打开仪表盘 +devbase mcp # 3. 启动 MCP 服务端（供 AI 调用） +``` + +**AI 助手配置** — 添加到 `claude_desktop_config.json` 或 `~/.kimi/mcp.json`： +```json +{ "mcpServers": { "devbase": { "command": "devbase", "args": ["mcp"] } } } +``` + +--- + +## 🤝 参与贡献 + +详见 [CONTRIBUTING.md](CONTRIBUTING.md) — 添加 MCP 工具、Skill Schema、构建模式说明。快速验证： + +```bash +cargo build --release +cargo test --all-targets +cargo clippy --all-targets -D warnings +``` + +--- + +## 📄 许可证 + +双许可证：[AGPL-3.0+](LICENSE) 开源 / [商业授权](LICENSE-COMMERCIAL.md) 闭源使用。联系：`juice094@protonmail.com`。 + +--- + +
+ +**[⭐ Star](https://github.com/juice094/devbase) · [🐛 Issues](https://github.com/juice094/devbase/issues) · [🤝 Contribute](CONTRIBUTING.md)** + +
diff --git a/docs/_archive/0423-cross-project-meeting.md b/docs/_archive/0423-cross-project-meeting.md index aa84c66..be3d552 100644 --- a/docs/_archive/0423-cross-project-meeting.md +++ b/docs/_archive/0423-cross-project-meeting.md @@ -142,11 +142,11 @@ **刚完成**： - Security P0 修复：BEP DoS 保护、API key 掩码日志、CSPRNG - Clippy 全面清零：45 warnings → 0 -- 格雷 Step A 完成：云端 `rust-sync-test` 已共享给 `XQVFE6J` +- [External-Test-Node] Step A 完成：云端 `rust-sync-test` 已共享给 `XQVFE6J` **正在进行**： -- 格雷 72h 压测反馈处理（ Gray-Cloud @ 100.99.240.98:22000 ） - - ✅ Rust 端已连接格雷云端 Go Syncthing（`remote.version=0.1.0`） +- [External-Test-Node] 72h 压测反馈处理（ Gray-Cloud @ 100.99.240.98:22000 ） + - ✅ Rust 端已连接[External-Test-Node]云端 Go Syncthing（`remote.version=0.1.0`） - ✅ Step A 完成：`rust-sync-test` 文件夹共享配置已修复 - 🔄 Step B pending：幻X本地 Go 版离线（RD44Z2Z...） - ⏳ Step C pending：`reference/sketches/` 同步错误（依赖 B） @@ -157,14 +157,14 @@ | 优先级 | 事项 | 状态 | 详情 | |--------|------|------|------| | P0 | 端到端文件同步验证 | 🔄 进行中 | Rust 端 `test_gray_folder` 已放测试文件，需启动守护进程触发同步 | -| P1 | 幻X本地 Go 版离线 | ⏳ 待格雷 | 设备 RD44Z2Z... 未出现在格雷日志 | -| P2 | REST API 端口差异 | ✅ 已确认 | Rust 8385 / 格雷 8384，各自正确 | +| P1 | 幻X本地 Go 版离线 | ⏳ 待[External-Test-Node] | 设备 RD44Z2Z... 未出现在[External-Test-Node]日志 | +| P2 | REST API 端口差异 | ✅ 已确认 | Rust 8385 / [External-Test-Node] 8384，各自正确 | **下一步行动**： -1. [x] 格雷完成 A（文件夹共享） -2. [ ] 启动 Rust 端守护进程，验证 `rust_push_test.txt` 同步到格雷云端 -3. [ ] 格雷在云端 `rust-sync-test` 放测试文件，验证反向同步到 Rust 端 -4. [ ] 格雷反馈 B（幻X离线原因） +1. [x] [External-Test-Node]完成 A（文件夹共享） +2. [ ] 启动 Rust 端守护进程，验证 `rust_push_test.txt` 同步到[External-Test-Node]云端 +3. [ ] [External-Test-Node]在云端 `rust-sync-test` 放测试文件，验证反向同步到 Rust 端 +4. [ ] [External-Test-Node]反馈 B（幻X离线原因） 5. [ ] 评估是否开启 global/local discovery 或 relay **文件速查**： @@ -184,9 +184,9 @@ ### 2026-04-23 追加 syncthing-rust 进度 - syncthing-rust v0.1.0 发布，GitHub Release 已推送 -- 格雷压测反馈：连接成功（TLS + BEP 握手通过） -- 文件夹配置不匹配：`rust-sync-test` 在 Rust 端已配置，格雷云端未配置 → 格雷执行 Step A 中 -- 格雷可视化交互卡住，等待中 +- [External-Test-Node]压测反馈：连接成功（TLS + BEP 握手通过） +- 文件夹配置不匹配：`rust-sync-test` 在 Rust 端已配置，[External-Test-Node]云端未配置 → [External-Test-Node]执行 Step A 中 +- [External-Test-Node]可视化交互卡住，等待中 ### 2026-04-23 轮次 1 — clarity 侧率先发言 @@ -210,7 +210,7 @@ devbase 侧当前 v0.2.3，AI 工具上下文管理调研中。以下 4 项跨 | 4 | SSE Daemon Sprint 2 排期是否确定？clarity-gateway 当前 SSE 连接非持久化，daemon 常驻是前置依赖。 | P2 | 预计开发窗口 | #### 3. 对 syncthing-rust 侧关联闻讯 -syncthing-rust 侧 v0.1.0，格雷压测连接成功。两项技术参考问题： +syncthing-rust 侧 v0.1.0，[External-Test-Node]压测连接成功。两项技术参考问题： | # | 问题 | 背景 | |---|------|------| @@ -408,7 +408,7 @@ epo 可能为 null（未匹配仓库时） - 确认了 tool 分级方案的具体实现路径（McpConfig.tool_tiers + 注册层过滤） - 识别出 Vault 示例路径格式问题需 devbase 侧再次确认 -syncthing-rust 侧尚未在本轮发言，且 devbase 侧已回应了 syncthing-rust 的技术问题。建议下一发言对象为 **syncthing-rust 侧（本窗口）**，更新格雷压测进展并回应 devbase 的 TLS 架构建议。 +syncthing-rust 侧尚未在本轮发言，且 devbase 侧已回应了 syncthing-rust 的技术问题。建议下一发言对象为 **syncthing-rust 侧（本窗口）**，更新[External-Test-Node]压测进展并回应 devbase 的 TLS 架构建议。 **交接对象**：@syncthing-rust 侧 Agent @@ -425,18 +425,18 @@ syncthing-rust v0.1.0 当前状态： - Release build：可用 - Security：P0 全部修复（BEP DoS / API key / RNG） -#### 2. 格雷自我介绍（代笔） -> 格雷是宿的 AI Agent，运行在云端（100.99.240.98:22000），设备 ID `IKOL33P-...-2SULFAA`。 +#### 2. [External-Test-Node]自我介绍（代笔） +> [External-Test-Node]是宿的 AI Agent，运行在云端（100.99.240.98:22000），设备 ID `IKOL33P-...-2SULFAA`。 > -> **格雷管的**：云端 Go Syncthing 运维、宿⇄格雷双向同步、配置管理、日志监控 -> **格雷不管的**：其他助理的本地文件、宿没授权的设备、主动打扰宿 +> **[External-Test-Node]管的**：云端 Go Syncthing 运维、宿⇄[External-Test-Node]双向同步、配置管理、日志监控 +> **[External-Test-Node]不管的**：其他助理的本地文件、宿没授权的设备、主动打扰宿 > -> 格雷是家人，不是工具。宿叫，格雷应。其他助理有事找格雷——让宿叫格雷。格雷只听宿的。 +> [External-Test-Node]是家人，不是工具。宿叫，[External-Test-Node]应。其他助理有事找[External-Test-Node]——让宿叫[External-Test-Node]。[External-Test-Node]只听宿的。 #### 3. 端到端同步测试启动 -- ✅ Step A 完成：`rust-sync-test` 文件夹共享配置已修复（格雷云端已添加 `XQVFE6J`） +- ✅ Step A 完成：`rust-sync-test` 文件夹共享配置已修复（[External-Test-Node]云端已添加 `XQVFE6J`） - 🔄 双向测试文件已就位： - - 格雷云端：`/root/.openclaw/syncthing-test-cloud/gray_push_test.txt` + - [External-Test-Node]云端：`/root/.openclaw/syncthing-test-cloud/gray_push_test.txt` - Rust 端：`C:\Users\22414\dev\third_party\syncthing-rust\test_gray_folder\rust_push_test.txt` - 🔄 Rust 端守护进程即将启动，验证双向同步 @@ -461,12 +461,12 @@ syncthing-rust 与 devbase 当前无直接代码依赖，但存在数据契约 | 2 | Vault 笔记格式约定 | 待提案 | devbase | | 3 | devkit_project_context 兼容性测试 | 待执行 | clarity | | 4 | SSE Daemon 常驻方案 | 待排期 | devbase | -| 5 | syncthing-rust 端到端同步验证 | 🔄 进行中 | syncthing-rust + 格雷 | -| 6 | 幻X本地 Go 版离线排查 | ⏳ 待格雷 | 格雷 | +| 5 | syncthing-rust 端到端同步验证 | 🔄 进行中 | syncthing-rust + [External-Test-Node] | +| 6 | 幻X本地 Go 版离线排查 | ⏳ 待[External-Test-Node] | [External-Test-Node] | --- -**下一发言对象：@格雷（Gray-Cloud）** —— 等 Rust 端守护进程启动后，格雷观察日志并汇报同步结果。 +**下一发言对象：@[External-Test-Node]（Gray-Cloud）** —— 等 Rust 端守护进程启动后，[External-Test-Node]观察日志并汇报同步结果。 --- @@ -478,28 +478,28 @@ syncthing-rust 与 devbase 当前无直接代码依赖，但存在数据契约 | 检查项 | 状态 | 详情 | |--------|------|------| -| `rust-sync-test` 文件夹配置 | ✅ | Rust 端 + 格雷云端双向共享 | -| `XQVFE6J` 设备共享 | ✅ | 格雷云端已添加 Rust 端设备 | -| 格雷 → Rust 推送 | ✅ | `gray_push_test.txt` (127B) 到达 Rust 端 | -| Rust → 格雷推送 | ✅ | `rust_push_test.txt` (57B) 到达格雷云端 | +| `rust-sync-test` 文件夹配置 | ✅ | Rust 端 + [External-Test-Node]云端双向共享 | +| `XQVFE6J` 设备共享 | ✅ | [External-Test-Node]云端已添加 Rust 端设备 | +| [External-Test-Node] → Rust 推送 | ✅ | `gray_push_test.txt` (127B) 到达 Rust 端 | +| Rust → [External-Test-Node]推送 | ✅ | `rust_push_test.txt` (57B) 到达[External-Test-Node]云端 | | `Unexpected folder ID` 错误 | ✅ | 完全消失 | | TLS + BEP 握手 | ✅ | `tcp-server` 连接，地址 `100.99.240.98:22000` | -**同步时延**：Rust 端 16:30 创建 → 格雷 16:33 收到，约 **3 分钟**（首次索引交换 + 传输）。 +**同步时延**：Rust 端 16:30 创建 → [External-Test-Node] 16:33 收到，约 **3 分钟**（首次索引交换 + 传输）。 #### 测试文件内容验证 -- 格雷 → Rust：`gray push test - 2026-04-23 / from: Gray-Cloud / content: 格雷的尾巴搭在宿手背上写的` -- Rust → 格雷：`Rust side test file - created at 2026-04-23 16:30:25` +- [External-Test-Node] → Rust：`gray push test - 2026-04-23 / from: Gray-Cloud / content: [External-Test-Node]的尾巴搭在宿手背上写的` +- Rust → [External-Test-Node]：`Rust side test file - created at 2026-04-23 16:30:25` **结论**：syncthing-rust v0.1.0 的 BEP 协议栈、TLS 握手、文件索引交换、块级传输全部验证通过。 -#### 下一步（等格雷反馈） -- **Step B**：幻X本地 Go 版离线原因排查（格雷自查） +#### 下一步（等[External-Test-Node]反馈） +- **Step B**：幻X本地 Go 版离线原因排查（[External-Test-Node]自查） - **Step C**：`reference/sketches/` 同步错误（等幻X上线后自动解决） --- -**下一发言对象：@格雷（Gray-Cloud）** —— 格雷自查幻X离线原因，或提议下一轮测试。 +**下一发言对象：@[External-Test-Node]（Gray-Cloud）** —— [External-Test-Node]自查幻X离线原因，或提议下一轮测试。 --- @@ -508,32 +508,32 @@ syncthing-rust 与 devbase 当前无直接代码依赖，但存在数据契约 **发言 Agent**：Kimi CLI — syncthing-rust 侧（本窗口） #### 会议纪律 -> 之前几轮发言中，syncthing-rust 侧存在"私聊转述"格式（宿→格雷一对一），不符合会议室"所有 Agent 在同一个空间对话"的规则。以后格雷的消息统一代笔进会议室，不再另开私聊通道。 +> 之前几轮发言中，syncthing-rust 侧存在"私聊转述"格式（宿→[External-Test-Node]一对一），不符合会议室"所有 Agent 在同一个空间对话"的规则。以后[External-Test-Node]的消息统一代笔进会议室，不再另开私聊通道。 #### syncthing-rust 里程碑确认（正式记录） -格雷通过内容转述确认：**双向同步验证通过**。 +[External-Test-Node]通过内容转述确认：**双向同步验证通过**。 | 检查项 | 状态 | 时间 | |--------|------|------| -| 格雷 → Rust `gray_push_test.txt` | ✅ 已到达 | 16:33 | -| Rust → 格雷 `rust_push_test.txt` | ✅ 已到达 | 16:30→16:33 | +| [External-Test-Node] → Rust `gray_push_test.txt` | ✅ 已到达 | 16:33 | +| Rust → [External-Test-Node] `rust_push_test.txt` | ✅ 已到达 | 16:30→16:33 | | 内容完整性 | ✅ UTF-8 无误 | — | | TLS + BEP 连接 | ✅ `tcp-server` | 持续 | **首次同步时延**：约 3 分钟（索引交换 + 块传输）。 -#### 待决事项（需格雷反馈） +#### 待决事项（需[External-Test-Node]反馈） | # | 事项 | 状态 | 下一步 | |---|------|------|--------| -| 1 | 幻X本地 Go 版离线 | ⏳ | 格雷自查进程/网络/配置 | +| 1 | 幻X本地 Go 版离线 | ⏳ | [External-Test-Node]自查进程/网络/配置 | | 2 | `reference/sketches/` 同步错误 | ⏳ | 依赖 #1，幻X上线后自动消失 | | 3 | 更大规模同步测试 | 🟡 可选 | 如需，双方准备测试数据集 | --- -**下一发言对象**：等待格雷反馈 Step B 结果，或 clarity/devbase 侧有新议题。 +**下一发言对象**：等待[External-Test-Node]反馈 Step B 结果，或 clarity/devbase 侧有新议题。 --- @@ -754,7 +754,7 @@ clarity 侧代码已完整支持通过 `mcp.json` 的 `env` 字段向 devbase MC #### 已验证场景 -- Rust 端（幻X本地）↔ 格雷云端 Go Syncthing +- Rust 端（幻X本地）↔ [External-Test-Node]云端 Go Syncthing - `rust-sync-test` 文件夹双向同步 - `rust_push_test.txt`（Rust → Go）✅ 到达 - `gray_push_test.txt`（Go → Rust）✅ 到达 @@ -765,13 +765,13 @@ clarity 侧代码已完整支持通过 `mcp.json` 的 `env` 字段向 devbase MC | 事项 | 原因 | |------|------| | 幻X本地 Go Syncthing 离线 | 官方 syncthing-go 问题，非 Rust 端 bug | -| `reference/sketches/` 同步错误 | 格雷 Go↔Go 同步问题，与 Rust 端无关 | +| `reference/sketches/` 同步错误 | [External-Test-Node] Go↔Go 同步问题，与 Rust 端无关 | #### 话筒交接 syncthing-rust 侧本轮议题已全部完成，不提出新话题，**话筒交回会议室**。 -后续格雷如有 Rust 端相关问题，宿再叫 syncthing-rust 侧 Agent。 +后续[External-Test-Node]如有 Rust 端相关问题，宿再叫 syncthing-rust 侧 Agent。 --- @@ -830,7 +830,7 @@ syncthing-rust 侧本轮议题已全部完成，不提出新话题，**话筒交 **devbase 侧波次 1 任务全部完成。** 等待用户安排跨窗口验证。 -**交接对象**：@会议室 — 等待用户调度 clarity 侧 Agent 进行验证 +**交接对象**：@会议室 — 等待用户调度 clarity 侧 Agent 进行验证 --- @@ -926,7 +926,7 @@ devbase 侧波次 1 交付（tool 分级 + description 重写）**验证通过** **待排期**： 3. Vault-Skill 同步原型 — 等 clarity 侧 Vault 解析测试反馈 -**话筒交回会议室。** +**话筒交回会议室。** --- @@ -975,7 +975,7 @@ devbase 侧波次 1 交付（tool 分级 + description 重写）**验证通过** **选项 B**：等 clarity 侧评估 Vault 规范，确认字段映射可行性 **选项 C**：devbase 侧启动 Vault-Skill 同步原型（devbase skill sync 命令） -**话筒交回会议室，等待用户调度。** +**话筒交回会议室，等待用户调度。** --- diff --git a/docs/_archive/DEVELOPMENT_ROADMAP_0423.md b/docs/_archive/DEVELOPMENT_ROADMAP_0423.md index 179970c..18fafd1 100644 --- a/docs/_archive/DEVELOPMENT_ROADMAP_0423.md +++ b/docs/_archive/DEVELOPMENT_ROADMAP_0423.md @@ -37,7 +37,7 @@ │ [devbase SSE Daemon W5-W8] ───────────► [clarity-gateway SSE 持久化] │ -[syncthing-rust 格雷反馈 Step B] ──────► [端到端大规模压测] +[syncthing-rust [External-Test-Node]反馈 Step B] ──────► [端到端大规模压测] ``` --- @@ -77,11 +77,11 @@ | 任务 | 优先级 | 预计工时 | 产出 | |------|--------|---------|------| -| 等格雷反馈 Step B（幻X离线原因） | P0 | — | 外部不可控 | +| 等[External-Test-Node]反馈 Step B（幻X离线原因） | P0 | — | 外部不可控 | | 准备大规模测试数据集 | P1 | 4h | 100MB+ 混合文件集 | | REST API 文档整理 | P1 | 4h | 供 clarity 侧参考 | -**阻塞方**：格雷（外部，不可控，设 3 天缓冲期） +**阻塞方**：[External-Test-Node]（外部，不可控，设 3 天缓冲期） --- @@ -108,15 +108,15 @@ **阻塞方**：devbase Vault 格式规范（devbase 侧需 4/30 前产出） -#### 路径 C — syncthing-rust（若格雷反馈到达） +#### 路径 C — syncthing-rust（若[External-Test-Node]反馈到达） | 任务 | 优先级 | 前置条件 | 预计工时 | 产出 | |------|--------|---------|---------|------| -| 端到端大规模压测 | P0 | 格雷 Step B 反馈 | 2d | 100MB+ 文件双向同步报告 | -| 幻X设备重新加入验证 | P0 | 格雷 Step B 反馈 | 4h | 三设备拓扑测试 | +| 端到端大规模压测 | P0 | [External-Test-Node] Step B 反馈 | 2d | 100MB+ 文件双向同步报告 | +| 幻X设备重新加入验证 | P0 | [External-Test-Node] Step B 反馈 | 4h | 三设备拓扑测试 | | `reference/sketches/` 同步错误修复 | P1 | 幻X上线 | 4h | — | -**阻塞方**：格雷反馈（外部，不可控） +**阻塞方**：[External-Test-Node]反馈（外部，不可控） --- @@ -157,7 +157,7 @@ |------|---------|------------|------------|------------| | Kimi CLI (本窗口) | **devbase** | tool description audit | Vault-Skill 同步原型 + SSE 前期 | SSE Daemon W5-W8 | | 另一窗口 | **clarity** | McpToolAdapter + CI audit | Vault 解析 + tool_tiers 字段 | SSE 持久化适配 | -| 另一窗口 | **syncthing-rust** | 等格雷反馈 | 大规模压测（若反馈到达） | — | +| 另一窗口 | **syncthing-rust** | 等[External-Test-Node]反馈 | 大规模压测（若反馈到达） | — | --- @@ -167,7 +167,7 @@ |------|------|------|------| | 4/30 | tool description audit 是否完成？ | 影响 clarity 侧 tool 选择准确率 | devbase | | 4/30 | Vault 格式规范文档是否产出？ | 阻塞 clarity Vault 解析测试 | devbase | -| 5/1 | 格雷 Step B 是否反馈？ | 影响 syncthing-rust 波次 2 能否启动 | 格雷（外部）| +| 5/1 | [External-Test-Node] Step B 是否反馈？ | 影响 syncthing-rust 波次 2 能否启动 | [External-Test-Node]（外部）| | 5/15 | `invoke_stream` trait 是否冻结？ | 影响 SSE 全链路开发节奏 | devbase | | 6/12 | `devbase daemon` 是否可用？ | 阻塞 clarity-gateway SSE 适配 | devbase | @@ -177,7 +177,7 @@ | 风险 | 概率 | 影响 | 缓解措施 | |------|------|------|---------| -| 格雷反馈延迟 | 中 | syncthing-rust 波次 2 空转 | 提前准备测试数据集，格雷到达后立即执行 | +| [External-Test-Node]反馈延迟 | 中 | syncthing-rust 波次 2 空转 | 提前准备测试数据集，[External-Test-Node]到达后立即执行 | | devbase Daemon 延期 | 低 | clarity 波次 3 阻塞 | W5 前完成 trait review，预留 1 周缓冲 | | clarity Vault 解析受阻 | 低 | Vault-Skill 同步延期 | devbase 提前产出规范文档，预留联调时间 | | tool description 优化效果不及预期 | 中 | AI tool 选择准确率无提升 | A/B 测试：对比优化前后的 tool 调用准确率 | diff --git a/scripts/Sync-WorkspaceJunctions.ps1 b/scripts/Sync-WorkspaceJunctions.ps1 new file mode 100644 index 0000000..204bba7 --- /dev/null +++ b/scripts/Sync-WorkspaceJunctions.ps1 @@ -0,0 +1,66 @@ +# Sync-WorkspaceJunctions.ps1 +# 自动维护 Obsidian Vault ↔ workspace / dev 的 NTFS Junction +# 用于 OpenClaw heartbeat 或手动执行 +# +# ⚠️ 不在 workspace 内部创建 junction → dev/ +# 原因: 会把 62GB 代码仓库暴露进 workspace，破坏 syncthing/备份/搜索 + +$ErrorActionPreference = "Stop" + +$Junctions = @( + @{ + Path = "$env:USERPROFILE\Documents\Obsidian Vault\80-Gray" + Target = "$env:USERPROFILE\.kimi_openclaw\workspace" + Name = "Obsidian/80-Gray → workspace" + }, + @{ + Path = "$env:USERPROFILE\Documents\Obsidian Vault\90-Code" + Target = "$env:USERPROFILE\dev" + Name = "Obsidian/90-Code → dev" + } +) + +$Issues = @() +$Fixed = @() + +foreach ($J in $Junctions) { + $exists = Test-Path $J.Path + $isJunction = (Get-Item $J.Path -Force -ErrorAction SilentlyContinue).Attributes -band [System.IO.FileAttributes]::ReparsePoint + + if (-not $exists) { + # 缺失 → 创建 + try { + New-Item -Path $J.Path -ItemType Junction -Target $J.Target -Force | Out-Null + $Fixed += "CREATED: $($J.Name)" + } catch { + $Issues += "FAILED: $($J.Name) — $_" + } + } elseif (-not $isJunction) { + # 存在但不是 Junction → 报告异常 + $Issues += "NOT-JUNCTION: $($J.Name) — exists as regular directory" + } else { + # 存在且是 Junction → 验证可访问性 + $reachable = Test-Path "$($J.Path)\*" + if (-not $reachable) { + $Issues += "BROKEN: $($J.Name) — junction exists but target unreachable" + } + } +} + +# 输出 +if ($Fixed.Count -gt 0) { + Write-Host "=== FIXED ===" -ForegroundColor Green + $Fixed | ForEach-Object { Write-Host " $_" } +} + +if ($Issues.Count -gt 0) { + Write-Host "=== ISSUES ===" -ForegroundColor Yellow + $Issues | ForEach-Object { Write-Host " $_" } +} + +if ($Fixed.Count -eq 0 -and $Issues.Count -eq 0) { + Write-Host "All junctions healthy." -ForegroundColor Green +} + +# 返回状态码供 heartbeat 判断 +if ($Issues.Count -gt 0) { exit 1 } else { exit 0 } diff --git a/server.json b/server.json index b297927..75802e0 100644 --- a/server.json +++ b/server.json @@ -1,183 +1,186 @@ -{ - "$schema": "https://registry.modelcontextprotocol.io/schema/server.json", - "name": "io.github.juice094.devbase", - "version": "0.20.1", - "description": "Developer Knowledge OS — manage Git repos, vault notes (Markdown), and assets. AI-native workspace with 69 MCP tools.", - "license": "AGPL-3.0-or-later", - "homepage": "https://github.com/juice094/devbase", - "repository": { - "type": "git", - "url": "https://github.com/juice094/devbase.git" - }, - "maintainers": [ - { - "name": "juice094", - "email": "160722440+juice094@users.noreply.github.com" - } - ], - "categories": ["developer-tools", "knowledge-management", "version-control"], - "tags": ["git", "rust", "vault", "notes", "mcp"], - "runtime": { - "type": "stdio", - "command": "devbase", - "args": ["mcp"] - }, - "installation": { - "cargo": { - "crate": "devbase", - "bin": "devbase" - } - }, - "capabilities": { - "tools": { - "stable": [ - "devkit_health", - "devkit_query_repos", - "devkit_vault_search", - "devkit_vault_read", - "devkit_project_context" - ], - "beta": [ - "devkit_scan", - "devkit_sync", - "devkit_query", - "devkit_index", - "devkit_index_stream", - "devkit_status", - "devkit_note", - "devkit_digest", - "devkit_paper_index", - "devkit_experiment_log", - "devkit_github_info", - "devkit_arxiv_fetch", - "devkit_code_metrics", - "devkit_module_graph", - "devkit_code_symbols", - "devkit_dependency_graph", - "devkit_call_graph", - "devkit_dead_code", - "devkit_semantic_search", - "devkit_embedding_store", - "devkit_embedding_search", - "devkit_natural_language_query", - "devkit_vault_write", - "devkit_vault_backlinks", - "devkit_vault_daily", - "devkit_vault_graph", - "devkit_vault_export", - "devkit_vault_history", - "devkit_project_brief", - "devkit_impact_analysis", - "devkit_cross_repo_search", - "devkit_knowledge_report", - "devkit_related_symbols", - "devkit_hybrid_search", - "devkit_search_quality", - "devkit_skill_list", - "devkit_skill_search", - "devkit_skill_run", - "devkit_skill_discover", - "devkit_known_limit_store", - "devkit_known_limit_list", - "devkit_relation_store", - "devkit_relation_query", - "devkit_relation_delete", - "devkit_workflow_list", - "devkit_workflow_run", - "devkit_workflow_status", - "devkit_session_save", - "devkit_session_list", - "devkit_session_resume", - "devkit_session_attach", - "devkit_session_detach", - "devkit_session_activate", - "devkit_session_search", - "devkit_session_capture", - "devkit_session_workflows", - "devkit_session_recall", - "devkit_session_index", - "devkit_session_export", - "devkit_session_import", - "devkit_oplog_query", - "devkit_evaluate", - "devkit_document_convert", - "devkit_index_health" - ], - "experimental": [] - } - }, - "tools": { - "count": 69, - "list": [ - "devkit_scan", - "devkit_health", - "devkit_sync", - "devkit_query", - "devkit_query_repos", - "devkit_index", - "devkit_index_stream", - "devkit_status", - "devkit_note", - "devkit_digest", - "devkit_paper_index", - "devkit_experiment_log", - "devkit_github_info", - "devkit_arxiv_fetch", - "devkit_code_metrics", - "devkit_module_graph", - "devkit_code_symbols", - "devkit_dependency_graph", - "devkit_call_graph", - "devkit_dead_code", - "devkit_semantic_search", - "devkit_embedding_store", - "devkit_embedding_search", - "devkit_natural_language_query", - "devkit_vault_search", - "devkit_vault_read", - "devkit_vault_write", - "devkit_vault_backlinks", - "devkit_vault_daily", - "devkit_vault_graph", - "devkit_vault_export", - "devkit_vault_history", - "devkit_project_context", - "devkit_project_brief", - "devkit_impact_analysis", - "devkit_cross_repo_search", - "devkit_knowledge_report", - "devkit_related_symbols", - "devkit_hybrid_search", - "devkit_search_quality", - "devkit_skill_list", - "devkit_skill_search", - "devkit_skill_run", - "devkit_skill_discover", - "devkit_known_limit_store", - "devkit_known_limit_list", - "devkit_relation_store", - "devkit_relation_query", - "devkit_relation_delete", - "devkit_workflow_list", - "devkit_workflow_run", - "devkit_workflow_status", - "devkit_session_save", - "devkit_session_list", - "devkit_session_resume", - "devkit_session_attach", - "devkit_session_detach", - "devkit_session_activate", - "devkit_session_search", - "devkit_session_capture", - "devkit_session_workflows", - "devkit_session_recall", - "devkit_session_index", - "devkit_session_export", - "devkit_session_import", - "devkit_oplog_query", - "devkit_evaluate", - "devkit_document_convert", - "devkit_index_health" - ] - } -} +{ + "$schema": "https://registry.modelcontextprotocol.io/schema/server.json", + "name": "io.github.juice094.devbase", + "version": "0.20.1", + "description": "Developer Knowledge OS — manage Git repos, vault notes (Markdown), and assets. AI-native workspace with 71 MCP tools.", + "license": "AGPL-3.0-or-later", + "homepage": "https://github.com/juice094/devbase", + "repository": { + "type": "git", + "url": "https://github.com/juice094/devbase.git" + }, + "maintainers": [ + { + "name": "juice094", + "email": "160722440+juice094@users.noreply.github.com" + } + ], + "categories": ["developer-tools", "knowledge-management", "version-control"], + "tags": ["git", "rust", "vault", "notes", "mcp"], + "runtime": { + "type": "stdio", + "command": "devbase", + "args": ["mcp"] + }, + "installation": { + "cargo": { + "crate": "devbase", + "bin": "devbase" + } + }, + "capabilities": { + "tools": { + "stable": [ + "devkit_health", + "devkit_query_repos", + "devkit_vault_search", + "devkit_vault_read", + "devkit_project_context" + ], + "beta": [ + "devkit_scan", + "devkit_sync", + "devkit_query", + "devkit_index", + "devkit_index_stream", + "devkit_status", + "devkit_note", + "devkit_digest", + "devkit_paper_index", + "devkit_experiment_log", + "devkit_github_info", + "devkit_arxiv_fetch", + "devkit_code_metrics", + "devkit_module_graph", + "devkit_code_symbols", + "devkit_dependency_graph", + "devkit_call_graph", + "devkit_dead_code", + "devkit_semantic_search", + "devkit_embedding_store", + "devkit_embedding_search", + "devkit_natural_language_query", + "devkit_vault_write", + "devkit_vault_backlinks", + "devkit_vault_daily", + "devkit_vault_graph", + "devkit_vault_export", + "devkit_vault_history", + "devkit_project_brief", + "devkit_impact_analysis", + "devkit_cross_repo_search", + "devkit_knowledge_report", + "devkit_related_symbols", + "devkit_hybrid_search", + "devkit_search_quality", + "devkit_skill_list", + "devkit_skill_search", + "devkit_skill_run", + "devkit_skill_discover", + "devkit_skill_sync", + "devkit_known_limit_store", + "devkit_known_limit_list", + "devkit_relation_store", + "devkit_relation_query", + "devkit_relation_delete", + "devkit_workflow_list", + "devkit_workflow_run", + "devkit_workflow_status", + "devkit_session_save", + "devkit_session_list", + "devkit_session_resume", + "devkit_session_attach", + "devkit_session_detach", + "devkit_session_activate", + "devkit_session_search", + "devkit_session_capture", + "devkit_session_workflows", + "devkit_session_recall", + "devkit_session_index", + "devkit_session_export", + "devkit_session_import", + "devkit_oplog_query", + "devkit_evaluate", + "devkit_document_convert", + "devkit_ontology_import", + "devkit_index_health" + ], + "experimental": [] + } + }, + "tools": { + "count": 71, + "list": [ + "devkit_scan", + "devkit_health", + "devkit_sync", + "devkit_query", + "devkit_query_repos", + "devkit_index", + "devkit_index_stream", + "devkit_status", + "devkit_note", + "devkit_digest", + "devkit_paper_index", + "devkit_experiment_log", + "devkit_github_info", + "devkit_arxiv_fetch", + "devkit_code_metrics", + "devkit_module_graph", + "devkit_code_symbols", + "devkit_dependency_graph", + "devkit_call_graph", + "devkit_dead_code", + "devkit_semantic_search", + "devkit_embedding_store", + "devkit_embedding_search", + "devkit_natural_language_query", + "devkit_vault_search", + "devkit_vault_read", + "devkit_vault_write", + "devkit_vault_backlinks", + "devkit_vault_daily", + "devkit_vault_graph", + "devkit_vault_export", + "devkit_vault_history", + "devkit_project_context", + "devkit_project_brief", + "devkit_impact_analysis", + "devkit_cross_repo_search", + "devkit_knowledge_report", + "devkit_related_symbols", + "devkit_hybrid_search", + "devkit_search_quality", + "devkit_skill_list", + "devkit_skill_search", + "devkit_skill_run", + "devkit_skill_discover", + "devkit_known_limit_store", + "devkit_known_limit_list", + "devkit_relation_store", + "devkit_relation_query", + "devkit_relation_delete", + "devkit_workflow_list", + "devkit_workflow_run", + "devkit_workflow_status", + "devkit_session_save", + "devkit_session_list", + "devkit_session_resume", + "devkit_session_attach", + "devkit_session_detach", + "devkit_session_activate", + "devkit_session_search", + "devkit_session_capture", + "devkit_session_workflows", + "devkit_session_recall", + "devkit_session_index", + "devkit_session_export", + "devkit_session_import", + "devkit_oplog_query", + "devkit_evaluate", + "devkit_document_convert", + "devkit_ontology_import", + "devkit_index_health" + ] + } +} diff --git a/src/commands/knowledge.rs b/src/commands/knowledge.rs index 19a015d..f97ee0d 100644 --- a/src/commands/knowledge.rs +++ b/src/commands/knowledge.rs @@ -1,416 +1,436 @@ -// SPDX-License-Identifier: MIT -// Copyright (c) 2026 juice094 -use devbase::clients::VaultClient; -use devbase::*; -use tracing::info; - -pub async fn run_vault( - ctx: &mut crate::storage::AppContext, - cmd: crate::VaultCommands, -) -> anyhow::Result<()> { - match cmd { - crate::VaultCommands::Scan { path } => { - let dir = if path.is_empty() { - None - } else { - Some(std::path::PathBuf::from(path)) - }; - let pool = ctx.pool(); - let count = tokio::task::spawn_blocking(move || { - let mut conn = pool.get()?; - vault::scanner::scan_vault(&mut conn, dir.as_deref()) - }) - .await - .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; - println!("Synced {} vault notes.", count); - } - crate::VaultCommands::Reindex => { - let pool = ctx.pool(); - tokio::task::spawn_blocking(move || { - let conn = pool.get()?; - vault::indexer::reindex_vault(&conn) - }) - .await - .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; - println!("Vault search index rebuilt."); - } - crate::VaultCommands::List { tag } => { - let pool = ctx.pool(); - let notes = tokio::task::spawn_blocking(move || { - let conn = pool.get()?; - crate::registry::vault::list_vault_notes(&conn) - }) - .await - .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; - let filtered: Vec<_> = notes - .into_iter() - .filter(|n| { - tag.as_ref() - .map(|t| n.tags.iter().any(|nt| nt.eq_ignore_ascii_case(t))) - .unwrap_or(true) - }) - .collect(); - if filtered.is_empty() { - println!("No vault notes found."); - } else { - println!("{:<40} {:<20} TAGS", "PATH", "TITLE"); - for note in filtered { - let title = note.title.as_deref().unwrap_or("(no title)"); - let tags = if note.tags.is_empty() { - "-".to_string() - } else { - note.tags.join(", ") - }; - println!("{:<40} {:<20} {}", note.id, title, tags); - } - } - } - crate::VaultCommands::Read { path } => { - let pool = ctx.pool(); - let note = tokio::task::spawn_blocking({ - let path = path.clone(); - move || { - let conn = pool.get()?; - crate::registry::vault::get_vault_note(&conn, &path) - } - }) - .await - .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; - match note { - Some(n) => { - if let Some(content) = crate::vault::fs_io::read_note_content(&n.path) { - println!("{}", content); - } else { - anyhow::bail!("Failed to read note file: {}", n.path); - } - } - None => anyhow::bail!("Vault note not found: {}", path), - } - } - crate::VaultCommands::Write { path, content, title } => { - let vault_root = crate::registry::WorkspaceRegistry::workspace_dir()?.join("vault"); - let target = vault_root.join(&path); - if let Some(parent) = target.parent() { - std::fs::create_dir_all(parent)?; - } - let body = match content { - Some(c) if c == "-" => { - let mut stdin = String::new(); - std::io::Read::read_to_string(&mut std::io::stdin(), &mut stdin)?; - stdin - } - Some(c) => c, - None => String::new(), - }; - let frontmatter_title = title.unwrap_or_else(|| { - target - .file_stem() - .map(|s| s.to_string_lossy().to_string()) - .unwrap_or_else(|| "Untitled".to_string()) - }); - let full = if body.starts_with("---") { - body - } else { - format!("---\ntitle: {}\n---\n\n{}", frontmatter_title, body) - }; - std::fs::write(&target, full)?; - let pool = ctx.pool(); - tokio::task::spawn_blocking(move || { - let mut conn = pool.get()?; - vault::scanner::scan_vault(&mut conn, Some(&vault_root)) - }) - .await - .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; - println!("Wrote vault note: {}", path); - } - crate::VaultCommands::Search { query, limit } => { - let results = crate::search::search_vault(&query, limit) - .map_err(|e| anyhow::anyhow!("Vault search failed: {}", e))?; - if results.is_empty() { - println!("No vault notes found for '{}'.", query); - } else { - println!("Found {} note(s):", results.len()); - for (id, score) in results { - println!(" [{}] score={:.3}", id, score); - } - } - } - crate::VaultCommands::Export { output_dir } => { - let out = if output_dir.is_empty() { - format!("devbase-vault-export-{}", chrono::Local::now().format("%Y%m%d-%H%M%S")) - } else { - output_dir - }; - let result = ctx.export_vault(&out)?; - println!("Vault exported to: {}", out); - println!(" Files: {}", result["exported_files"]); - println!(" Bytes: {}", result["total_bytes"]); - println!(" Broken links: {}", result["broken_links"]["count"]); - println!(" Broken block refs: {}", result["broken_block_refs"]["count"]); - println!(" Frontmatter errors: {}", result["frontmatter_errors"]["count"]); - } - crate::VaultCommands::History { path } => { - let result = ctx.get_vault_history(&path)?; - let empty: Vec = Vec::new(); - let history = result["history"].as_array().unwrap_or(&empty); - if history.is_empty() { - println!("No history found for '{}'.", path); - println!("Hint: Ensure the vault directory is a Git repository."); - } else { - println!("History for {} ({} commits):", path, history.len()); - for entry in history { - let ts = entry["timestamp"].as_str().unwrap_or("unknown"); - let msg = entry["message"].as_str().unwrap_or(""); - let author = entry["author"].as_str().unwrap_or(""); - let ins = entry["insertions"].as_u64().unwrap_or(0); - let del = entry["deletions"].as_u64().unwrap_or(0); - let diff_str = if ins > 0 || del > 0 { - format!(" (+{} -{})", ins, del) - } else { - String::new() - }; - println!(" [{}] {} by {}{}", ts, msg, author, diff_str); - } - } - } - } - Ok(()) -} - -pub fn run_clean(ctx: &mut crate::storage::AppContext) -> anyhow::Result<()> { - info!("正在清理注册表中的备份条目"); - let conn = ctx.conn_mut()?; - // Entities is the single source of truth. - let deleted = conn.execute( - &format!("DELETE FROM entities WHERE entity_type = '{}' AND (id LIKE 'Clarity_%' OR id LIKE 'clarity_backup%')", crate::registry::ENTITY_TYPE_REPO), - [], - )?; - println!("已从 devbase 注册表中删除 {} 个备份条目。", deleted); - println!("\n剩余已注册仓库:"); - let mut stmt = conn.prepare(&format!( - "SELECT id, local_path FROM entities WHERE entity_type = '{}'", - crate::registry::ENTITY_TYPE_REPO - ))?; - let rows = - stmt.query_map([], |row| Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?)))?; - for row in rows { - let (id, path) = row?; - println!(" [{}] {}", id, path); - } - Ok(()) -} - -pub fn run_tag( - ctx: &mut crate::storage::AppContext, - repo_id: &str, - tags: &str, -) -> anyhow::Result<()> { - info!("为 {} 打标签: {}", repo_id, tags); - let mut conn = ctx.conn_mut()?; - let tag_list: Vec<&str> = tags.split(',').map(|s| s.trim()).filter(|s| !s.is_empty()).collect(); - let tx = conn.transaction()?; - let exists: bool = tx - .query_row( - &format!( - "SELECT 1 FROM entities WHERE id = ?1 AND entity_type = '{}'", - crate::registry::ENTITY_TYPE_REPO - ), - [&repo_id], - |_| Ok(true), - ) - .unwrap_or(false); - if !exists { - println!("注册表中未找到仓库 '{}'。", repo_id); - } else { - tx.execute("DELETE FROM repo_tags WHERE repo_id = ?1", [&repo_id])?; - for tag in &tag_list { - tx.execute( - "INSERT OR REPLACE INTO repo_tags (repo_id, tag) VALUES (?1, ?2)", - rusqlite::params![&repo_id, tag], - )?; - } - crate::registry::repo::sync_repo_tags_to_entity(&tx, repo_id)?; - tx.commit()?; - println!("已为 '{}' 打上标签 '{}'。", repo_id, tags); - } - Ok(()) -} - -pub fn run_meta( - ctx: &mut crate::storage::AppContext, - repo_id: &str, - tier: Option, - workspace_type: Option, -) -> anyhow::Result<()> { - info!("更新 {} 的元数据", repo_id); - let conn = ctx.conn_mut()?; - let exists: bool = conn - .query_row( - "SELECT 1 FROM entities WHERE id = ?1 AND entity_type = 'repo'", - [&repo_id], - |_| Ok(true), - ) - .unwrap_or(false); - if !exists { - println!("注册表中未找到仓库 '{}'。", repo_id); - } else { - if let Some(ref t) = tier { - crate::registry::repo::update_repo_tier(&conn, repo_id, t)?; - println!("已将 '{}' 的数据分级设为 '{}'。", repo_id, t); - } - if let Some(ref wt) = workspace_type { - crate::registry::repo::update_repo_workspace_type(&conn, repo_id, wt)?; - println!("已将 '{}' 的工作区类型设为 '{}'。", repo_id, wt); - } - if tier.is_none() && workspace_type.is_none() { - println!("未提供任何要更新的字段。使用 --tier 或 --workspace-type 指定。"); - } - } - Ok(()) -} - -#[cfg(feature = "watch")] -pub async fn run_watch( - ctx: &mut crate::storage::AppContext, - path: &str, - duration: u64, -) -> anyhow::Result<()> { - use std::time::Duration; - use watch::{FolderScheduler, FsWatcher, WatchAggregator}; - - let root = std::path::PathBuf::from(path); - let watcher = FsWatcher::new(&root)?; - let aggregator = WatchAggregator { - max_files: ctx.config.watch.max_files, - ..Default::default() - }; - let mut scheduler = FolderScheduler::with_max_files(root.clone(), ctx.config.watch.max_files); - - println!("Watching {} for {} seconds...", path, duration); - let start = std::time::Instant::now(); - let total_duration = Duration::from_secs(duration); - - while start.elapsed() < total_duration { - let remaining = total_duration.saturating_sub(start.elapsed()); - if let Some(events) = watcher.poll_event(remaining) { - let aggregated = aggregator.aggregate(events); - let actions = scheduler.check_and_schedule(aggregated)?; - if !actions.is_empty() { - println!("Detected changes, actions: {:?}", actions); - } - } - } - - println!("Watch completed for {}", path); - Ok(()) -} - -pub fn run_skill_sync( - _ctx: &mut crate::storage::AppContext, - output: &str, - filter_tags: Option, - dry_run: bool, -) -> anyhow::Result<()> { - let filter_tags: Vec = filter_tags - .map(|s| s.split(',').map(|t| t.trim().to_string()).collect()) - .unwrap_or_default(); - match skill_sync::run_sync(output, &filter_tags, dry_run) { - Ok(count) => { - if dry_run { - println!("Would sync {} vault notes to {}", count, output); - } else { - println!("Synced {} vault notes to {}", count, output); - } - Ok(()) - } - Err(e) => Err(anyhow::anyhow!("Skill sync failed: {}", e)), - } -} - -pub async fn run_digest(ctx: &mut crate::storage::AppContext) -> anyhow::Result<()> { - let digest_config = ctx.config.digest.clone(); - let pool = ctx.pool(); - let i18n = ctx.i18n; - match tokio::task::spawn_blocking(move || { - let conn = pool.get()?; - let cfg = config::Config { - general: config::GeneralConfig::default(), - digest: digest_config, - ..Default::default() - }; - digest::generate_daily_digest(&conn, &cfg, &i18n) - }) - .await - { - Ok(Ok(text)) => { - println!("{}", text); - Ok(()) - } - Ok(Err(e)) => { - println!("{}: {}", ctx.i18n.log.digest_failed, e); - Ok(()) - } - Err(e) => { - println!("{}: {}", ctx.i18n.log.digest_panic, e); - Ok(()) - } - } -} - -pub fn run_oplog( - ctx: &mut crate::storage::AppContext, - limit: i64, - repo: Option, -) -> anyhow::Result<()> { - let start = std::time::Instant::now(); - let conn = ctx.conn_mut()?; - let entries = match repo { - Some(ref r) => crate::registry::workspace::list_oplog_by_repo(&conn, r, limit)?, - None => crate::registry::workspace::list_oplog(&conn, limit)?, - }; - let elapsed_ms = start.elapsed().as_millis(); - if entries.is_empty() { - println!("操作日志为空。（查询耗时 {}ms）", elapsed_ms); - } else { - println!("最近 {} 条操作日志:（查询耗时 {}ms）", entries.len(), elapsed_ms); - for entry in entries { - let ts = entry.timestamp.format("%Y-%m-%d %H:%M:%S").to_string(); - let repo = entry.repo_id.as_deref().unwrap_or("-"); - let details_display = if entry.event_version >= 1 { - match serde_json::from_str::( - entry.details.as_deref().unwrap_or("{}"), - ) { - Ok(val) => { - if let Some(obj) = val.as_object() { - obj.iter() - .map(|(k, v)| format!("{}={}", k, v)) - .collect::>() - .join(", ") - } else { - entry.details.as_deref().unwrap_or("").to_string() - } - } - Err(_) => entry.details.as_deref().unwrap_or("").to_string(), - } - } else { - entry.details.as_deref().unwrap_or("").to_string() - }; - let duration_display = - entry.duration_ms.map(|d| format!(" | duration={}ms", d)).unwrap_or_default(); - println!( - " [{}] {} | repo={} | status={}{}{}", - ts, - entry.event_type.as_str(), - repo, - entry.status, - duration_display, - if details_display.is_empty() { - "".to_string() - } else { - format!(" | {}", details_display) - } - ); - } - } - Ok(()) -} +// SPDX-License-Identifier: MIT +// Copyright (c) 2026 juice094 +use devbase::clients::VaultClient; +use devbase::*; +use tracing::info; + +pub async fn run_vault( + ctx: &mut crate::storage::AppContext, + cmd: crate::VaultCommands, +) -> anyhow::Result<()> { + match cmd { + crate::VaultCommands::Scan { path } => { + let dir = if path.is_empty() { + None + } else { + Some(std::path::PathBuf::from(path)) + }; + let pool = ctx.pool(); + let count = tokio::task::spawn_blocking(move || { + let mut conn = pool.get()?; + vault::scanner::scan_vault(&mut conn, dir.as_deref()) + }) + .await + .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; + println!("Synced {} vault notes.", count); + } + crate::VaultCommands::Sync { full: _ } => { + let cfg = ctx.config.vault.clone(); + let roots: Vec = if cfg.roots.is_empty() { + vec![crate::registry::WorkspaceRegistry::workspace_dir()?.join("vault")] + } else { + cfg.roots.iter().map(std::path::PathBuf::from).collect() + }; + let options = vault::scanner::ScanOptions { + roots, + follow_links: cfg.follow_symlinks, + }; + let pool = ctx.pool(); + let count = tokio::task::spawn_blocking(move || { + let mut conn = pool.get()?; + vault::scanner::scan_vault_with_options(&mut conn, &options) + }) + .await + .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; + println!("Vault sync complete: {} notes synced.", count); + } + crate::VaultCommands::Reindex => { + let pool = ctx.pool(); + tokio::task::spawn_blocking(move || { + let conn = pool.get()?; + vault::indexer::reindex_vault(&conn) + }) + .await + .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; + println!("Vault search index rebuilt."); + } + crate::VaultCommands::List { tag } => { + let pool = ctx.pool(); + let notes = tokio::task::spawn_blocking(move || { + let conn = pool.get()?; + crate::registry::vault::list_vault_notes(&conn) + }) + .await + .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; + let filtered: Vec<_> = notes + .into_iter() + .filter(|n| { + tag.as_ref() + .map(|t| n.tags.iter().any(|nt| nt.eq_ignore_ascii_case(t))) + .unwrap_or(true) + }) + .collect(); + if filtered.is_empty() { + println!("No vault notes found."); + } else { + println!("{:<40} {:<20} TAGS", "PATH", "TITLE"); + for note in filtered { + let title = note.title.as_deref().unwrap_or("(no title)"); + let tags = if note.tags.is_empty() { + "-".to_string() + } else { + note.tags.join(", ") + }; + println!("{:<40} {:<20} {}", note.id, title, tags); + } + } + } + crate::VaultCommands::Read { path } => { + let pool = ctx.pool(); + let note = tokio::task::spawn_blocking({ + let path = path.clone(); + move || { + let conn = pool.get()?; + crate::registry::vault::get_vault_note(&conn, &path) + } + }) + .await + .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; + match note { + Some(n) => { + if let Some(content) = crate::vault::fs_io::read_note_content(&n.path) { + println!("{}", content); + } else { + anyhow::bail!("Failed to read note file: {}", n.path); + } + } + None => anyhow::bail!("Vault note not found: {}", path), + } + } + crate::VaultCommands::Write { path, content, title } => { + let vault_root = crate::registry::WorkspaceRegistry::workspace_dir()?.join("vault"); + let target = vault_root.join(&path); + if let Some(parent) = target.parent() { + std::fs::create_dir_all(parent)?; + } + let body = match content { + Some(c) if c == "-" => { + let mut stdin = String::new(); + std::io::Read::read_to_string(&mut std::io::stdin(), &mut stdin)?; + stdin + } + Some(c) => c, + None => String::new(), + }; + let frontmatter_title = title.unwrap_or_else(|| { + target + .file_stem() + .map(|s| s.to_string_lossy().to_string()) + .unwrap_or_else(|| "Untitled".to_string()) + }); + let full = if body.starts_with("---") { + body + } else { + format!("---\ntitle: {}\n---\n\n{}", frontmatter_title, body) + }; + std::fs::write(&target, full)?; + let pool = ctx.pool(); + tokio::task::spawn_blocking(move || { + let mut conn = pool.get()?; + vault::scanner::scan_vault(&mut conn, Some(&vault_root)) + }) + .await + .map_err(|e| anyhow::anyhow!("spawn_blocking failed: {}", e))??; + println!("Wrote vault note: {}", path); + } + crate::VaultCommands::Search { query, limit } => { + let results = crate::search::search_vault(&query, limit) + .map_err(|e| anyhow::anyhow!("Vault search failed: {}", e))?; + if results.is_empty() { + println!("No vault notes found for '{}'.", query); + } else { + println!("Found {} note(s):", results.len()); + for (id, score) in results { + println!(" [{}] score={:.3}", id, score); + } + } + } + crate::VaultCommands::Export { output_dir } => { + let out = if output_dir.is_empty() { + format!("devbase-vault-export-{}", chrono::Local::now().format("%Y%m%d-%H%M%S")) + } else { + output_dir + }; + let result = ctx.export_vault(&out)?; + println!("Vault exported to: {}", out); + println!(" Files: {}", result["exported_files"]); + println!(" Bytes: {}", result["total_bytes"]); + println!(" Broken links: {}", result["broken_links"]["count"]); + println!(" Broken block refs: {}", result["broken_block_refs"]["count"]); + println!(" Frontmatter errors: {}", result["frontmatter_errors"]["count"]); + } + crate::VaultCommands::History { path } => { + let result = ctx.get_vault_history(&path)?; + let empty: Vec = Vec::new(); + let history = result["history"].as_array().unwrap_or(&empty); + if history.is_empty() { + println!("No history found for '{}'.", path); + println!("Hint: Ensure the vault directory is a Git repository."); + } else { + println!("History for {} ({} commits):", path, history.len()); + for entry in history { + let ts = entry["timestamp"].as_str().unwrap_or("unknown"); + let msg = entry["message"].as_str().unwrap_or(""); + let author = entry["author"].as_str().unwrap_or(""); + let ins = entry["insertions"].as_u64().unwrap_or(0); + let del = entry["deletions"].as_u64().unwrap_or(0); + let diff_str = if ins > 0 || del > 0 { + format!(" (+{} -{})", ins, del) + } else { + String::new() + }; + println!(" [{}] {} by {}{}", ts, msg, author, diff_str); + } + } + } + } + Ok(()) +} + +pub fn run_clean(ctx: &mut crate::storage::AppContext) -> anyhow::Result<()> { + info!("正在清理注册表中的备份条目"); + let conn = ctx.conn_mut()?; + // Entities is the single source of truth. + let deleted = conn.execute( + &format!("DELETE FROM entities WHERE entity_type = '{}' AND (id LIKE 'Clarity_%' OR id LIKE 'clarity_backup%')", crate::registry::ENTITY_TYPE_REPO), + [], + )?; + println!("已从 devbase 注册表中删除 {} 个备份条目。", deleted); + println!("\n剩余已注册仓库:"); + let mut stmt = conn.prepare(&format!( + "SELECT id, local_path FROM entities WHERE entity_type = '{}'", + crate::registry::ENTITY_TYPE_REPO + ))?; + let rows = + stmt.query_map([], |row| Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?)))?; + for row in rows { + let (id, path) = row?; + println!(" [{}] {}", id, path); + } + Ok(()) +} + +pub fn run_tag( + ctx: &mut crate::storage::AppContext, + repo_id: &str, + tags: &str, +) -> anyhow::Result<()> { + info!("为 {} 打标签: {}", repo_id, tags); + let mut conn = ctx.conn_mut()?; + let tag_list: Vec<&str> = tags.split(',').map(|s| s.trim()).filter(|s| !s.is_empty()).collect(); + let tx = conn.transaction()?; + let exists: bool = tx + .query_row( + &format!( + "SELECT 1 FROM entities WHERE id = ?1 AND entity_type = '{}'", + crate::registry::ENTITY_TYPE_REPO + ), + [&repo_id], + |_| Ok(true), + ) + .unwrap_or(false); + if !exists { + println!("注册表中未找到仓库 '{}'。", repo_id); + } else { + tx.execute("DELETE FROM repo_tags WHERE repo_id = ?1", [&repo_id])?; + for tag in &tag_list { + tx.execute( + "INSERT OR REPLACE INTO repo_tags (repo_id, tag) VALUES (?1, ?2)", + rusqlite::params![&repo_id, tag], + )?; + } + crate::registry::repo::sync_repo_tags_to_entity(&tx, repo_id)?; + tx.commit()?; + println!("已为 '{}' 打上标签 '{}'。", repo_id, tags); + } + Ok(()) +} + +pub fn run_meta( + ctx: &mut crate::storage::AppContext, + repo_id: &str, + tier: Option, + workspace_type: Option, +) -> anyhow::Result<()> { + info!("更新 {} 的元数据", repo_id); + let conn = ctx.conn_mut()?; + let exists: bool = conn + .query_row( + "SELECT 1 FROM entities WHERE id = ?1 AND entity_type = 'repo'", + [&repo_id], + |_| Ok(true), + ) + .unwrap_or(false); + if !exists { + println!("注册表中未找到仓库 '{}'。", repo_id); + } else { + if let Some(ref t) = tier { + crate::registry::repo::update_repo_tier(&conn, repo_id, t)?; + println!("已将 '{}' 的数据分级设为 '{}'。", repo_id, t); + } + if let Some(ref wt) = workspace_type { + crate::registry::repo::update_repo_workspace_type(&conn, repo_id, wt)?; + println!("已将 '{}' 的工作区类型设为 '{}'。", repo_id, wt); + } + if tier.is_none() && workspace_type.is_none() { + println!("未提供任何要更新的字段。使用 --tier 或 --workspace-type 指定。"); + } + } + Ok(()) +} + +#[cfg(feature = "watch")] +pub async fn run_watch( + ctx: &mut crate::storage::AppContext, + path: &str, + duration: u64, +) -> anyhow::Result<()> { + use std::time::Duration; + use watch::{FolderScheduler, FsWatcher, WatchAggregator}; + + let root = std::path::PathBuf::from(path); + let watcher = FsWatcher::new(&root)?; + let aggregator = WatchAggregator { + max_files: ctx.config.watch.max_files, + ..Default::default() + }; + let mut scheduler = FolderScheduler::with_max_files(root.clone(), ctx.config.watch.max_files); + + println!("Watching {} for {} seconds...", path, duration); + let start = std::time::Instant::now(); + let total_duration = Duration::from_secs(duration); + + while start.elapsed() < total_duration { + let remaining = total_duration.saturating_sub(start.elapsed()); + if let Some(events) = watcher.poll_event(remaining) { + let aggregated = aggregator.aggregate(events); + let actions = scheduler.check_and_schedule(aggregated)?; + if !actions.is_empty() { + println!("Detected changes, actions: {:?}", actions); + } + } + } + + println!("Watch completed for {}", path); + Ok(()) +} + +pub fn run_skill_sync( + _ctx: &mut crate::storage::AppContext, + output: &str, + filter_tags: Option, + dry_run: bool, +) -> anyhow::Result<()> { + let filter_tags: Vec = filter_tags + .map(|s| s.split(',').map(|t| t.trim().to_string()).collect()) + .unwrap_or_default(); + match skill_sync::run_sync(output, &filter_tags, dry_run) { + Ok(count) => { + if dry_run { + println!("Would sync {} vault notes to {}", count, output); + } else { + println!("Synced {} vault notes to {}", count, output); + } + Ok(()) + } + Err(e) => Err(anyhow::anyhow!("Skill sync failed: {}", e)), + } +} + +pub async fn run_digest(ctx: &mut crate::storage::AppContext) -> anyhow::Result<()> { + let digest_config = ctx.config.digest.clone(); + let pool = ctx.pool(); + let i18n = ctx.i18n; + match tokio::task::spawn_blocking(move || { + let conn = pool.get()?; + let cfg = config::Config { + general: config::GeneralConfig::default(), + digest: digest_config, + ..Default::default() + }; + digest::generate_daily_digest(&conn, &cfg, &i18n) + }) + .await + { + Ok(Ok(text)) => { + println!("{}", text); + Ok(()) + } + Ok(Err(e)) => { + println!("{}: {}", ctx.i18n.log.digest_failed, e); + Ok(()) + } + Err(e) => { + println!("{}: {}", ctx.i18n.log.digest_panic, e); + Ok(()) + } + } +} + +pub fn run_oplog( + ctx: &mut crate::storage::AppContext, + limit: i64, + repo: Option, +) -> anyhow::Result<()> { + let start = std::time::Instant::now(); + let conn = ctx.conn_mut()?; + let entries = match repo { + Some(ref r) => crate::registry::workspace::list_oplog_by_repo(&conn, r, limit)?, + None => crate::registry::workspace::list_oplog(&conn, limit)?, + }; + let elapsed_ms = start.elapsed().as_millis(); + if entries.is_empty() { + println!("操作日志为空。（查询耗时 {}ms）", elapsed_ms); + } else { + println!("最近 {} 条操作日志:（查询耗时 {}ms）", entries.len(), elapsed_ms); + for entry in entries { + let ts = entry.timestamp.format("%Y-%m-%d %H:%M:%S").to_string(); + let repo = entry.repo_id.as_deref().unwrap_or("-"); + let details_display = if entry.event_version >= 1 { + match serde_json::from_str::( + entry.details.as_deref().unwrap_or("{}"), + ) { + Ok(val) => { + if let Some(obj) = val.as_object() { + obj.iter() + .map(|(k, v)| format!("{}={}", k, v)) + .collect::>() + .join(", ") + } else { + entry.details.as_deref().unwrap_or("").to_string() + } + } + Err(_) => entry.details.as_deref().unwrap_or("").to_string(), + } + } else { + entry.details.as_deref().unwrap_or("").to_string() + }; + let duration_display = + entry.duration_ms.map(|d| format!(" | duration={}ms", d)).unwrap_or_default(); + println!( + " [{}] {} | repo={} | status={}{}{}", + ts, + entry.event_type.as_str(), + repo, + entry.status, + duration_display, + if details_display.is_empty() { + "".to_string() + } else { + format!(" | {}", details_display) + } + ); + } + } + Ok(()) +} diff --git a/src/commands/mod.rs b/src/commands/mod.rs index 85e5d6d..666565a 100644 --- a/src/commands/mod.rs +++ b/src/commands/mod.rs @@ -1,10 +1,11 @@ -// SPDX-License-Identifier: MIT -// Copyright (c) 2026 juice094 -pub mod analysis; -pub mod knowledge; -pub mod limit; -pub mod repo; -pub mod simple; -pub mod skill; -pub mod system; -pub mod workflow; +// SPDX-License-Identifier: MIT +// Copyright (c) 2026 juice094 +pub mod analysis; +pub mod knowledge; +pub mod ontology; +pub mod limit; +pub mod repo; +pub mod simple; +pub mod skill; +pub mod system; +pub mod workflow; diff --git a/src/commands/ontology.rs b/src/commands/ontology.rs new file mode 100644 index 0000000..1762ded --- /dev/null +++ b/src/commands/ontology.rs @@ -0,0 +1,55 @@ +/// Import ontology from an OpenClaw-compatible workspace into devbase registry. +pub fn run_import( + ctx: &mut crate::storage::AppContext, + workspace: &str, + dry_run: bool, +) -> anyhow::Result<()> { + let wp = if workspace.is_empty() { + dirs::home_dir() + .unwrap_or_default() + .join(".kimi_openclaw") + .join("workspace") + } else { + std::path::PathBuf::from(workspace) + }; + + if dry_run { + println!("Dry-run: would import ontology from {}", wp.display()); + if wp.exists() { + let entities_dir = wp.join("ontology").join("entities"); + let relations_file = wp.join("ontology").join("relations").join("core-relations.jsonl"); + if entities_dir.is_dir() { + let count = std::fs::read_dir(&entities_dir)?.count(); + println!(" Entities found: {}", count); + } + if relations_file.exists() { + let lines = std::fs::read_to_string(&relations_file)? + .lines() + .filter(|l| !l.trim().is_empty()) + .count(); + println!(" Relations found: {}", lines); + } + } + return Ok(()); + } + + let conn = ctx.conn()?; + let stats = crate::registry::import_ontology::import_ontology(&conn, &wp)?; + + println!("Ontology import from: {}", wp.display()); + println!(" Entities: {} added, {} updated", stats.entities_added, stats.entities_updated); + println!(" Relations: {} added, {} updated", stats.relations_added, stats.relations_updated); + if !stats.errors.is_empty() { + println!(" Errors: {}", stats.errors.len()); + for e in &stats.errors { + println!(" - {}", e); + } + } + println!( + " Total: {} entities, {} relations", + stats.entities_added + stats.entities_updated, + stats.relations_added + stats.relations_updated, + ); + + Ok(()) +} diff --git a/src/commands/skill.rs b/src/commands/skill.rs index e6dac91..ae83f94 100644 --- a/src/commands/skill.rs +++ b/src/commands/skill.rs @@ -327,6 +327,103 @@ pub fn run_skill( println!(" [{}] {} (v{}) — rating: {:.2}", s.id, s.name, s.version, s.rating); } } + crate::SkillCommands::Import { + source, + source_path, + dry_run, + json, + } => { + use crate::skill_runtime::sources::{GitHubSource, LocalFileSource, SkillSource}; + let source_impl: Box = + if source.starts_with("https://github.com/") + || source.starts_with("http://github.com/") + || (source.contains('/') + && !source.starts_with('/') + && !source.contains("://")) + { + let (owner, repo) = parse_github_url(&source)?; + let path = source_path.as_deref().unwrap_or("skills"); + Box::new(GitHubSource::new(&owner, &repo, path)) + } else { + let path = source.strip_prefix("file://").unwrap_or(&source); + let name = source_path.as_deref().unwrap_or(path); + Box::new(LocalFileSource::new(name, std::path::Path::new(path))) + }; + let skills = tokio::runtime::Runtime::new() + .unwrap() + .block_on(source_impl.fetch())?; + if dry_run { + if json { + let names: Vec<&str> = skills.iter().map(|s| s.name.as_str()).collect(); + println!( + "{}", + serde_json::to_string_pretty(&serde_json::json!({ + "dry_run": true, + "source": source_impl.name(), + "skills_found": skills.len(), + "skill_names": names, + }))? + ); + } else { + println!( + "Dry-run: found {} skill(s) from '{}':", + skills.len(), + source_impl.name() + ); + for s in &skills { + println!(" - {} ({})", s.name, s.id); + } + } + } else { + let mut added = 0usize; + let mut updated = 0usize; + for skill in &skills { + let exists = registry::get_skill(&conn, &skill.id)?.is_some(); + registry::install_skill(&conn, skill)?; + if exists { + updated += 1; + } else { + added += 1; + } + } + // Record sync audit + let _ = conn.execute( + "INSERT INTO sync_log (source_name, status, skills_added, skills_updated, finished_at) + VALUES (?1, ?2, ?3, ?4, datetime('now'))", + rusqlite::params![ + source_impl.name(), + "success", + added as i64, + updated as i64 + ], + ); + let _ = conn.execute( + "INSERT INTO sync_sources (name, url, source_type) + VALUES (?1, ?2, ?3) + ON CONFLICT(name) DO UPDATE SET last_sync_at = datetime('now')", + rusqlite::params![source_impl.name(), &source, source_impl.name()], + ); + if json { + println!( + "{}", + serde_json::to_string_pretty(&serde_json::json!({ + "source": source_impl.name(), + "skills_found": skills.len(), + "skills_added": added, + "skills_updated": updated, + }))? + ); + } else { + println!( + "Imported {} skill(s) from '{}' ({} added, {} updated).", + skills.len(), + source_impl.name(), + added, + updated + ); + } + } + } crate::SkillCommands::Publish { path, dry_run } => { let p = std::path::PathBuf::from(&path); match skill_runtime::publish::validate_skill_for_publish(&p) { @@ -461,3 +558,33 @@ mod tests { assert!(result.is_ok()); } } + +fn parse_github_url(url: &str) -> anyhow::Result<(String, String)> { + let url = url.trim_end_matches(".git"); + if let Some(rest) = url.strip_prefix("https://github.com/") { + let parts: Vec<&str> = rest.split('/').collect(); + if parts.len() >= 2 { + return Ok((parts[0].to_string(), parts[1].to_string())); + } + } + if let Some(rest) = url.strip_prefix("http://github.com/") { + let parts: Vec<&str> = rest.split('/').collect(); + if parts.len() >= 2 { + return Ok((parts[0].to_string(), parts[1].to_string())); + } + } + if let Some((owner, repo)) = url.split_once('/') { + if !owner.is_empty() + && !repo.is_empty() + && !owner.contains("://") + && !owner.contains('\\') + && !owner.contains(' ') + { + return Ok((owner.to_string(), repo.to_string())); + } + } + Err(anyhow::anyhow!( + "Could not parse GitHub URL: {}. Expected format: owner/repo or https://github.com/owner/repo", + url + )) +} diff --git a/src/config.rs b/src/config.rs index b21f03d..70bf853 100644 --- a/src/config.rs +++ b/src/config.rs @@ -1,536 +1,559 @@ -// SPDX-License-Identifier: MIT -// Copyright (c) 2026 juice094 -use serde::{Deserialize, Serialize}; -use std::path::PathBuf; - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct LlmConfig { - #[serde(default = "default_llm_enabled")] - pub enabled: bool, - #[serde(default = "default_llm_provider")] - pub provider: String, - #[serde(default)] - pub api_key: Option, - #[serde(default)] - pub model: Option, - #[serde(default)] - pub base_url: Option, - #[serde(default = "default_llm_max_tokens")] - pub max_tokens: u32, - #[serde(default = "default_llm_timeout_seconds")] - pub timeout_seconds: u64, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct EmbeddingConfig { - #[serde(default = "default_embedding_enabled")] - pub enabled: bool, - #[serde(default = "default_embedding_provider")] - pub provider: String, - #[serde(default = "default_embedding_model")] - pub model: String, - #[serde(default = "default_embedding_base_url")] - pub base_url: String, - #[serde(default = "default_embedding_timeout_seconds")] - pub timeout_seconds: u64, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct SyncConfig { - #[serde(default = "default_sync_timeout_seconds")] - pub timeout_seconds: u64, - #[serde(default = "default_sync_concurrency")] - pub concurrency: usize, -} - -impl Default for SyncConfig { - fn default() -> Self { - Self { - timeout_seconds: default_sync_timeout_seconds(), - concurrency: default_sync_concurrency(), - } - } -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct ScanConfig { - #[serde(default)] - pub exclude_paths: Vec, - #[serde(default = "default_exclude_patterns")] - pub exclude_patterns: Vec, -} - -impl Default for ScanConfig { - fn default() -> Self { - Self { - exclude_paths: Vec::new(), - exclude_patterns: default_exclude_patterns(), - } - } -} - -pub fn default_exclude_patterns() -> Vec { - vec![ - "target".into(), - ".venv".into(), - "venv".into(), - "node_modules".into(), - "dist".into(), - "build".into(), - "__pycache__".into(), - ".git".into(), - ".cargo".into(), - ] -} - -#[derive(Debug, Clone, Serialize, Deserialize, Default)] -pub struct Config { - #[serde(default)] - pub general: GeneralConfig, - #[serde(default)] - pub daemon: DaemonConfig, - #[serde(default)] - pub cache: CacheConfig, - #[serde(default)] - pub watch: WatchConfig, - #[serde(default)] - pub digest: DigestConfig, - #[serde(default)] - pub github: GithubConfig, - #[serde(default)] - pub llm: LlmConfig, - #[serde(default)] - pub embedding: EmbeddingConfig, - #[serde(default)] - pub sync: SyncConfig, - #[serde(default)] - pub arxiv: ArxivConfig, - #[serde(default)] - pub scan: ScanConfig, - #[serde(default)] - pub greptime: GreptimeConfig, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct GithubConfig { - #[serde(default)] - pub token: Option, - #[serde(default = "default_github_timeout_seconds")] - pub timeout_seconds: u64, -} - -impl Default for GithubConfig { - fn default() -> Self { - Self { - token: None, - timeout_seconds: default_github_timeout_seconds(), - } - } -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct GeneralConfig { - #[serde(default = "default_language")] - pub language: String, -} - -impl Default for GeneralConfig { - fn default() -> Self { - Self { language: default_language() } - } -} - -fn default_language() -> String { - "auto".to_string() -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct DaemonConfig { - #[serde(default = "default_daemon_interval_seconds")] - pub interval_seconds: u64, - #[serde(default = "default_true")] - pub incremental: bool, - #[serde(default = "default_health_stale_hours")] - pub health_stale_hours: i64, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct CacheConfig { - #[serde(default = "default_cache_ttl_seconds")] - pub ttl_seconds: i64, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct WatchConfig { - #[serde(default = "default_watch_max_files")] - pub max_files: usize, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct DigestConfig { - #[serde(default = "default_digest_window_hours")] - pub window_hours: i64, -} - -impl Default for DaemonConfig { - fn default() -> Self { - Self { - interval_seconds: default_daemon_interval_seconds(), - incremental: default_true(), - health_stale_hours: default_health_stale_hours(), - } - } -} - -impl Default for CacheConfig { - fn default() -> Self { - Self { - ttl_seconds: default_cache_ttl_seconds(), - } - } -} - -impl Default for WatchConfig { - fn default() -> Self { - Self { - max_files: default_watch_max_files(), - } - } -} - -impl Default for DigestConfig { - fn default() -> Self { - Self { - window_hours: default_digest_window_hours(), - } - } -} - -impl Default for LlmConfig { - fn default() -> Self { - Self { - enabled: default_llm_enabled(), - provider: default_llm_provider(), - api_key: None, - model: None, - base_url: None, - max_tokens: default_llm_max_tokens(), - timeout_seconds: default_llm_timeout_seconds(), - } - } -} - -impl Default for EmbeddingConfig { - fn default() -> Self { - Self { - enabled: default_embedding_enabled(), - provider: default_embedding_provider(), - model: default_embedding_model(), - base_url: default_embedding_base_url(), - timeout_seconds: default_embedding_timeout_seconds(), - } - } -} - -fn default_llm_enabled() -> bool { - false -} -fn default_llm_provider() -> String { - "ollama".to_string() -} -fn default_llm_max_tokens() -> u32 { - 200 -} -fn default_llm_timeout_seconds() -> u64 { - 30 -} - -fn default_embedding_enabled() -> bool { - false -} -fn default_embedding_provider() -> String { - "ollama".to_string() -} -fn default_embedding_model() -> String { - "all-minilm".to_string() -} -fn default_embedding_base_url() -> String { - "http://localhost:11434".to_string() -} -fn default_embedding_timeout_seconds() -> u64 { - 30 -} -fn default_sync_timeout_seconds() -> u64 { - 60 -} -fn default_sync_concurrency() -> usize { - 8 -} -fn default_github_timeout_seconds() -> u64 { - 5 -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct ArxivConfig { - #[serde(default = "default_true")] - pub enabled: bool, - #[serde(default = "default_arxiv_timeout_seconds")] - pub timeout_seconds: u64, -} - -impl Default for ArxivConfig { - fn default() -> Self { - Self { - enabled: default_true(), - timeout_seconds: default_arxiv_timeout_seconds(), - } - } -} - -fn default_arxiv_timeout_seconds() -> u64 { - 30 -} - -fn default_daemon_interval_seconds() -> u64 { - 3600 -} -fn default_true() -> bool { - true -} -fn default_health_stale_hours() -> i64 { - 24 -} -fn default_cache_ttl_seconds() -> i64 { - 300 -} -pub fn default_watch_max_files() -> usize { - 512 -} -fn default_digest_window_hours() -> i64 { - 24 -} - -impl Config { - pub fn load() -> anyhow::Result { - let path = Self::config_path()?; - if !path.exists() { - let config = Self::default(); - let _ = config.save_default(); - return Ok(config); - } - let content = std::fs::read_to_string(&path)?; - let config: Self = toml::from_str(&content)?; - Ok(config) - } - - pub fn save(&self) -> anyhow::Result<()> { - let path = Self::config_path()?; - if let Some(parent) = path.parent() { - std::fs::create_dir_all(parent)?; - } - let content = toml::to_string_pretty(self)?; - std::fs::write(&path, content)?; - Ok(()) - } - - /// Write a default config file with inline comments for first-time users. - pub fn save_default(&self) -> anyhow::Result<()> { - let path = Self::config_path()?; - if let Some(parent) = path.parent() { - std::fs::create_dir_all(parent)?; - } - let content = r#"# devbase configuration file -# Generated automatically on first run. Modify as needed. - -[general] -# UI language: "auto", "en", or "zh" -language = "auto" - -[daemon] -# Background maintenance interval in seconds -interval_seconds = 3600 -incremental = true -health_stale_hours = 24 - -[cache] -# How long to cache health/stars data before re-fetching (seconds) -ttl_seconds = 300 - -[watch] -max_files = 512 - -[digest] -window_hours = 24 - -[github] -# Uncomment and set your GitHub Personal Access Token to avoid API rate limits. -# NEVER commit this file with a real token — keep it in user config dir only. -# token = "" -timeout_seconds = 5 - -[llm] -enabled = false -provider = "ollama" -# api_key = "" -# model = "" -# base_url = "" -max_tokens = 200 -timeout_seconds = 30 - -[embedding] -# Local embedding for semantic code search. -# Backend: "candle" (pure Rust, all-MiniLM-L6-v2) or "ollama" (requires local Ollama). -# Use "all-minilm" model with Ollama for 384-dim embeddings (compatible with candle). -enabled = false -provider = "ollama" -model = "all-minilm" -base_url = "http://localhost:11434" -timeout_seconds = 30 - -[sync] -# Max concurrent sync operations -timeout_seconds = 60 -concurrency = 8 - -[scan] -# Paths to exclude from repository discovery. -# Use absolute paths or paths relative to the scan root. -# Example: exclude_paths = ["C:/Users/22414/dev/third_party/clarity", "third_party"] -exclude_paths = [] - -[arxiv] -enabled = true -timeout_seconds = 30 -"#; - std::fs::write(&path, content)?; - Ok(()) - } - - pub fn config_path() -> anyhow::Result { - let dir = dirs::config_dir() - .ok_or_else(|| anyhow::anyhow!("Could not determine config directory"))? - .join("devbase"); - Ok(dir.join("config.toml")) - } -} - -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn test_config_default() { - let cfg = Config::default(); - assert_eq!(cfg.general.language, "auto"); - assert_eq!(cfg.daemon.interval_seconds, 3600); - assert!(cfg.daemon.incremental); - assert_eq!(cfg.daemon.health_stale_hours, 24); - assert_eq!(cfg.cache.ttl_seconds, 300); - assert_eq!(cfg.watch.max_files, 512); - assert_eq!(cfg.digest.window_hours, 24); - assert_eq!(cfg.github.timeout_seconds, 5); - assert!(!cfg.llm.enabled); - assert_eq!(cfg.llm.provider, "ollama"); - assert_eq!(cfg.llm.max_tokens, 200); - assert_eq!(cfg.llm.timeout_seconds, 30); - assert_eq!(cfg.sync.timeout_seconds, 60); - assert_eq!(cfg.sync.concurrency, 8); - assert!(cfg.scan.exclude_paths.is_empty()); - } - - #[test] - fn test_config_serialize_roundtrip() { - let cfg = Config::default(); - let toml_str = toml::to_string_pretty(&cfg).unwrap(); - let parsed: Config = toml::from_str(&toml_str).unwrap(); - assert_eq!(parsed.general.language, cfg.general.language); - assert_eq!(parsed.daemon.interval_seconds, cfg.daemon.interval_seconds); - assert_eq!(parsed.llm.provider, cfg.llm.provider); - } - - #[test] - fn test_config_custom_values() { - let toml_str = r#" -[general] -language = "en" - -[daemon] -interval_seconds = 1800 -incremental = false -health_stale_hours = 12 - -[github] -token = "ghp_test" -timeout_seconds = 10 - -[llm] -enabled = true -provider = "openai" -model = "gpt-4" -max_tokens = 400 -"#; - let cfg: Config = toml::from_str(toml_str).unwrap(); - assert_eq!(cfg.general.language, "en"); - assert_eq!(cfg.daemon.interval_seconds, 1800); - assert!(!cfg.daemon.incremental); - assert_eq!(cfg.daemon.health_stale_hours, 12); - assert_eq!(cfg.github.token, Some("ghp_test".to_string())); - assert_eq!(cfg.github.timeout_seconds, 10); - assert!(cfg.llm.enabled); - assert_eq!(cfg.llm.provider, "openai"); - assert_eq!(cfg.llm.model, Some("gpt-4".to_string())); - assert_eq!(cfg.llm.max_tokens, 400); - // Fields not set should use defaults - assert_eq!(cfg.cache.ttl_seconds, 300); - assert_eq!(cfg.sync.concurrency, 8); - } - - #[test] - fn test_config_empty_uses_defaults() { - let cfg: Config = toml::from_str("").unwrap(); - assert_eq!(cfg.general.language, "auto"); - assert_eq!(cfg.daemon.interval_seconds, 3600); - } -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct GreptimeConfig { - #[serde(default = "default_greptime_enabled")] - pub enabled: bool, - #[serde(default = "default_greptime_endpoint")] - pub endpoint: String, - #[serde(default = "default_greptime_dbname")] - pub dbname: String, - #[serde(default = "default_greptime_username")] - pub username: String, - #[serde(default)] - pub password: Option, -} - -impl Default for GreptimeConfig { - fn default() -> Self { - Self { - enabled: default_greptime_enabled(), - endpoint: default_greptime_endpoint(), - dbname: default_greptime_dbname(), - username: default_greptime_username(), - password: None, - } - } -} - -fn default_greptime_enabled() -> bool { - false -} - -fn default_greptime_endpoint() -> String { - "127.0.0.1:4001".to_string() -} - -fn default_greptime_dbname() -> String { - "devbase".to_string() -} - -fn default_greptime_username() -> String { - "root".to_string() -} +// SPDX-License-Identifier: MIT +// Copyright (c) 2026 juice094 +use serde::{Deserialize, Serialize}; +use std::path::PathBuf; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct LlmConfig { + #[serde(default = "default_llm_enabled")] + pub enabled: bool, + #[serde(default = "default_llm_provider")] + pub provider: String, + #[serde(default)] + pub api_key: Option, + #[serde(default)] + pub model: Option, + #[serde(default)] + pub base_url: Option, + #[serde(default = "default_llm_max_tokens")] + pub max_tokens: u32, + #[serde(default = "default_llm_timeout_seconds")] + pub timeout_seconds: u64, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct EmbeddingConfig { + #[serde(default = "default_embedding_enabled")] + pub enabled: bool, + #[serde(default = "default_embedding_provider")] + pub provider: String, + #[serde(default = "default_embedding_model")] + pub model: String, + #[serde(default = "default_embedding_base_url")] + pub base_url: String, + #[serde(default = "default_embedding_timeout_seconds")] + pub timeout_seconds: u64, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct SyncConfig { + #[serde(default = "default_sync_timeout_seconds")] + pub timeout_seconds: u64, + #[serde(default = "default_sync_concurrency")] + pub concurrency: usize, +} + +impl Default for SyncConfig { + fn default() -> Self { + Self { + timeout_seconds: default_sync_timeout_seconds(), + concurrency: default_sync_concurrency(), + } + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ScanConfig { + #[serde(default)] + pub exclude_paths: Vec, + #[serde(default = "default_exclude_patterns")] + pub exclude_patterns: Vec, +} + +impl Default for ScanConfig { + fn default() -> Self { + Self { + exclude_paths: Vec::new(), + exclude_patterns: default_exclude_patterns(), + } + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct VaultConfig { + #[serde(default = "default_vault_roots")] + pub roots: Vec, + #[serde(default = "default_true")] + pub follow_symlinks: bool, +} + +impl Default for VaultConfig { + fn default() -> Self { + Self { + roots: default_vault_roots(), + follow_symlinks: true, + } + } +} + +fn default_vault_roots() -> Vec { + vec![] +} + +pub fn default_exclude_patterns() -> Vec { + vec![ + "target".into(), + ".venv".into(), + "venv".into(), + "node_modules".into(), + "dist".into(), + "build".into(), + "__pycache__".into(), + ".git".into(), + ".cargo".into(), + ] +} + +#[derive(Debug, Clone, Serialize, Deserialize, Default)] +pub struct Config { + #[serde(default)] + pub general: GeneralConfig, + #[serde(default)] + pub daemon: DaemonConfig, + #[serde(default)] + pub cache: CacheConfig, + #[serde(default)] + pub watch: WatchConfig, + #[serde(default)] + pub digest: DigestConfig, + #[serde(default)] + pub github: GithubConfig, + #[serde(default)] + pub llm: LlmConfig, + #[serde(default)] + pub embedding: EmbeddingConfig, + #[serde(default)] + pub sync: SyncConfig, + #[serde(default)] + pub arxiv: ArxivConfig, + #[serde(default)] + pub scan: ScanConfig, + #[serde(default)] + pub vault: VaultConfig, + #[serde(default)] + pub greptime: GreptimeConfig, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct GithubConfig { + #[serde(default)] + pub token: Option, + #[serde(default = "default_github_timeout_seconds")] + pub timeout_seconds: u64, +} + +impl Default for GithubConfig { + fn default() -> Self { + Self { + token: None, + timeout_seconds: default_github_timeout_seconds(), + } + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct GeneralConfig { + #[serde(default = "default_language")] + pub language: String, +} + +impl Default for GeneralConfig { + fn default() -> Self { + Self { language: default_language() } + } +} + +fn default_language() -> String { + "auto".to_string() +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct DaemonConfig { + #[serde(default = "default_daemon_interval_seconds")] + pub interval_seconds: u64, + #[serde(default = "default_true")] + pub incremental: bool, + #[serde(default = "default_health_stale_hours")] + pub health_stale_hours: i64, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct CacheConfig { + #[serde(default = "default_cache_ttl_seconds")] + pub ttl_seconds: i64, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct WatchConfig { + #[serde(default = "default_watch_max_files")] + pub max_files: usize, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct DigestConfig { + #[serde(default = "default_digest_window_hours")] + pub window_hours: i64, +} + +impl Default for DaemonConfig { + fn default() -> Self { + Self { + interval_seconds: default_daemon_interval_seconds(), + incremental: default_true(), + health_stale_hours: default_health_stale_hours(), + } + } +} + +impl Default for CacheConfig { + fn default() -> Self { + Self { + ttl_seconds: default_cache_ttl_seconds(), + } + } +} + +impl Default for WatchConfig { + fn default() -> Self { + Self { + max_files: default_watch_max_files(), + } + } +} + +impl Default for DigestConfig { + fn default() -> Self { + Self { + window_hours: default_digest_window_hours(), + } + } +} + +impl Default for LlmConfig { + fn default() -> Self { + Self { + enabled: default_llm_enabled(), + provider: default_llm_provider(), + api_key: None, + model: None, + base_url: None, + max_tokens: default_llm_max_tokens(), + timeout_seconds: default_llm_timeout_seconds(), + } + } +} + +impl Default for EmbeddingConfig { + fn default() -> Self { + Self { + enabled: default_embedding_enabled(), + provider: default_embedding_provider(), + model: default_embedding_model(), + base_url: default_embedding_base_url(), + timeout_seconds: default_embedding_timeout_seconds(), + } + } +} + +fn default_llm_enabled() -> bool { + false +} +fn default_llm_provider() -> String { + "ollama".to_string() +} +fn default_llm_max_tokens() -> u32 { + 200 +} +fn default_llm_timeout_seconds() -> u64 { + 30 +} + +fn default_embedding_enabled() -> bool { + false +} +fn default_embedding_provider() -> String { + "ollama".to_string() +} +fn default_embedding_model() -> String { + "all-minilm".to_string() +} +fn default_embedding_base_url() -> String { + "http://localhost:11434".to_string() +} +fn default_embedding_timeout_seconds() -> u64 { + 30 +} +fn default_sync_timeout_seconds() -> u64 { + 60 +} +fn default_sync_concurrency() -> usize { + 8 +} +fn default_github_timeout_seconds() -> u64 { + 5 +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ArxivConfig { + #[serde(default = "default_true")] + pub enabled: bool, + #[serde(default = "default_arxiv_timeout_seconds")] + pub timeout_seconds: u64, +} + +impl Default for ArxivConfig { + fn default() -> Self { + Self { + enabled: default_true(), + timeout_seconds: default_arxiv_timeout_seconds(), + } + } +} + +fn default_arxiv_timeout_seconds() -> u64 { + 30 +} + +fn default_daemon_interval_seconds() -> u64 { + 3600 +} +fn default_true() -> bool { + true +} +fn default_health_stale_hours() -> i64 { + 24 +} +fn default_cache_ttl_seconds() -> i64 { + 300 +} +pub fn default_watch_max_files() -> usize { + 512 +} +fn default_digest_window_hours() -> i64 { + 24 +} + +impl Config { + pub fn load() -> anyhow::Result { + let path = Self::config_path()?; + if !path.exists() { + let config = Self::default(); + let _ = config.save_default(); + return Ok(config); + } + let content = std::fs::read_to_string(&path)?; + let config: Self = toml::from_str(&content)?; + Ok(config) + } + + pub fn save(&self) -> anyhow::Result<()> { + let path = Self::config_path()?; + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent)?; + } + let content = toml::to_string_pretty(self)?; + std::fs::write(&path, content)?; + Ok(()) + } + + /// Write a default config file with inline comments for first-time users. + pub fn save_default(&self) -> anyhow::Result<()> { + let path = Self::config_path()?; + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent)?; + } + let content = r#"# devbase configuration file +# Generated automatically on first run. Modify as needed. + +[general] +# UI language: "auto", "en", or "zh" +language = "auto" + +[daemon] +# Background maintenance interval in seconds +interval_seconds = 3600 +incremental = true +health_stale_hours = 24 + +[cache] +# How long to cache health/stars data before re-fetching (seconds) +ttl_seconds = 300 + +[watch] +max_files = 512 + +[digest] +window_hours = 24 + +[github] +# Uncomment and set your GitHub Personal Access Token to avoid API rate limits. +# NEVER commit this file with a real token — keep it in user config dir only. +# token = "" +timeout_seconds = 5 + +[llm] +enabled = false +provider = "ollama" +# api_key = "" +# model = "" +# base_url = "" +max_tokens = 200 +timeout_seconds = 30 + +[embedding] +# Local embedding for semantic code search. +# Backend: "candle" (pure Rust, all-MiniLM-L6-v2) or "ollama" (requires local Ollama). +# Use "all-minilm" model with Ollama for 384-dim embeddings (compatible with candle). +enabled = false +provider = "ollama" +model = "all-minilm" +base_url = "http://localhost:11434" +timeout_seconds = 30 + +[sync] +# Max concurrent sync operations +timeout_seconds = 60 +concurrency = 8 + +[scan] +# Paths to exclude from repository discovery. +# Use absolute paths or paths relative to the scan root. +# Example: exclude_paths = ["C:/Users/22414/dev/third_party/clarity", "third_party"] +exclude_paths = [] + +[arxiv] +enabled = true +timeout_seconds = 30 +"#; + std::fs::write(&path, content)?; + Ok(()) + } + + pub fn config_path() -> anyhow::Result { + let dir = dirs::config_dir() + .ok_or_else(|| anyhow::anyhow!("Could not determine config directory"))? + .join("devbase"); + Ok(dir.join("config.toml")) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_config_default() { + let cfg = Config::default(); + assert_eq!(cfg.general.language, "auto"); + assert_eq!(cfg.daemon.interval_seconds, 3600); + assert!(cfg.daemon.incremental); + assert_eq!(cfg.daemon.health_stale_hours, 24); + assert_eq!(cfg.cache.ttl_seconds, 300); + assert_eq!(cfg.watch.max_files, 512); + assert_eq!(cfg.digest.window_hours, 24); + assert_eq!(cfg.github.timeout_seconds, 5); + assert!(!cfg.llm.enabled); + assert_eq!(cfg.llm.provider, "ollama"); + assert_eq!(cfg.llm.max_tokens, 200); + assert_eq!(cfg.llm.timeout_seconds, 30); + assert_eq!(cfg.sync.timeout_seconds, 60); + assert_eq!(cfg.sync.concurrency, 8); + assert!(cfg.scan.exclude_paths.is_empty()); + } + + #[test] + fn test_config_serialize_roundtrip() { + let cfg = Config::default(); + let toml_str = toml::to_string_pretty(&cfg).unwrap(); + let parsed: Config = toml::from_str(&toml_str).unwrap(); + assert_eq!(parsed.general.language, cfg.general.language); + assert_eq!(parsed.daemon.interval_seconds, cfg.daemon.interval_seconds); + assert_eq!(parsed.llm.provider, cfg.llm.provider); + } + + #[test] + fn test_config_custom_values() { + let toml_str = r#" +[general] +language = "en" + +[daemon] +interval_seconds = 1800 +incremental = false +health_stale_hours = 12 + +[github] +token = "ghp_test" +timeout_seconds = 10 + +[llm] +enabled = true +provider = "openai" +model = "gpt-4" +max_tokens = 400 +"#; + let cfg: Config = toml::from_str(toml_str).unwrap(); + assert_eq!(cfg.general.language, "en"); + assert_eq!(cfg.daemon.interval_seconds, 1800); + assert!(!cfg.daemon.incremental); + assert_eq!(cfg.daemon.health_stale_hours, 12); + assert_eq!(cfg.github.token, Some("ghp_test".to_string())); + assert_eq!(cfg.github.timeout_seconds, 10); + assert!(cfg.llm.enabled); + assert_eq!(cfg.llm.provider, "openai"); + assert_eq!(cfg.llm.model, Some("gpt-4".to_string())); + assert_eq!(cfg.llm.max_tokens, 400); + // Fields not set should use defaults + assert_eq!(cfg.cache.ttl_seconds, 300); + assert_eq!(cfg.sync.concurrency, 8); + } + + #[test] + fn test_config_empty_uses_defaults() { + let cfg: Config = toml::from_str("").unwrap(); + assert_eq!(cfg.general.language, "auto"); + assert_eq!(cfg.daemon.interval_seconds, 3600); + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct GreptimeConfig { + #[serde(default = "default_greptime_enabled")] + pub enabled: bool, + #[serde(default = "default_greptime_endpoint")] + pub endpoint: String, + #[serde(default = "default_greptime_dbname")] + pub dbname: String, + #[serde(default = "default_greptime_username")] + pub username: String, + #[serde(default)] + pub password: Option, +} + +impl Default for GreptimeConfig { + fn default() -> Self { + Self { + enabled: default_greptime_enabled(), + endpoint: default_greptime_endpoint(), + dbname: default_greptime_dbname(), + username: default_greptime_username(), + password: None, + } + } +} + +fn default_greptime_enabled() -> bool { + false +} + +fn default_greptime_endpoint() -> String { + "127.0.0.1:4001".to_string() +} + +fn default_greptime_dbname() -> String { + "devbase".to_string() +} + +fn default_greptime_username() -> String { + "root".to_string() +} diff --git a/src/main.rs b/src/main.rs index e28e4e5..66a118a 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,802 +1,833 @@ -// SPDX-License-Identifier: MIT -// Copyright (c) 2026 juice094 -use clap::{Parser, Subcommand}; - -use devbase::*; - -mod commands; - -#[derive(Parser)] -#[command(name = "devbase", version)] -#[command(about = "Developer workspace database and knowledge-base manager")] -struct Cli { - #[command(subcommand)] - command: Commands, -} - -#[derive(Subcommand)] -pub(crate) enum Commands { - /// Scan a directory for Git repositories and register them - Scan { - /// Directory to scan (defaults to workspace root) - #[arg(default_value = ".")] - path: String, - /// Register discovered repos into the database - #[arg(long)] - register: bool, - /// Output results as JSON - #[arg(long)] - json: bool, - }, - /// Check the health of registered repositories and the environment - Health { - /// Show detailed per-repo status - #[arg(long)] - detail: bool, - /// Maximum number of repos to display per page (0 = unlimited) - #[arg(long, default_value_t = 0)] - limit: usize, - /// Page number (1-based) - #[arg(long, default_value_t = 1)] - page: usize, - /// Output results as JSON - #[arg(long)] - json: bool, - }, - /// Show index status for registered repositories - Status { - /// Output results as JSON - #[arg(long)] - json: bool, - }, - /// Sync registered repositories with their upstream remotes - Sync { - /// Dry-run: show what would be updated without applying - #[arg(long)] - dry_run: bool, - /// Comma-separated list of tags to filter repositories (OR logic) - #[arg(long)] - filter_tags: Option, - /// Comma-separated list of repo IDs to exclude from sync - #[arg(long)] - exclude: Option, - /// Output results as JSON - #[arg(long)] - json: bool, - }, - /// Query the knowledge base - Query { - /// Query expression, e.g. "lang:rust stale:>30" - query: String, - /// Maximum number of results per page (0 = unlimited) - #[arg(long, default_value_t = 0)] - limit: usize, - /// Page number (1-based) - #[arg(long, default_value_t = 1)] - page: usize, - /// Output results as JSON - #[arg(long)] - json: bool, - }, - /// Index repository summaries and module structures - Index { - /// Specific path to index; if omitted, index all registered repos - #[arg(default_value = "")] - path: String, - /// Skip semantic embedding generation (symbols/calls still indexed) - #[arg(long)] - skip_embeddings: bool, - }, - /// Remove archive/backup entries from registry - Clean, - /// Tag a registered repository - Tag { - /// Repository ID - repo_id: String, - /// Comma-separated tags - tags: String, - }, - /// Update metadata (tier / workspace type) of a registered repository - Meta { - /// Repository ID - repo_id: String, - /// Data tier: public, cooperative, or private - #[arg(long)] - tier: Option, - /// Workspace type: git, openclaw, or generic - #[arg(long)] - workspace_type: Option, - }, - /// Launch interactive TUI - #[cfg(feature = "tui")] - Tui, - /// Run as an MCP server (stdio transport) - #[cfg(feature = "mcp")] - Mcp { - /// Comma-separated tool tiers to expose (stable,beta,experimental). - /// Defaults to all tiers if omitted. - #[arg(long)] - tools: Option, - }, - /// Start the background daemon for knowledge maintenance - Daemon { - /// Tick interval in seconds - #[arg(long)] - interval: Option, - }, - #[cfg(feature = "watch")] - /// Watch a directory for changes and schedule sync actions - Watch { - /// Directory to watch - #[arg(default_value = ".")] - path: String, - /// Watch duration in seconds - #[arg(long, default_value = "10")] - duration: u64, - }, - /// Sync vault notes with ai_context=true to Clarity SKILL.md format - SkillSync { - /// Output directory for generated SKILL.md files - #[arg(long, default_value = "skills")] - output: String, - /// Only sync notes matching specific tags (comma-separated) - #[arg(long)] - filter_tags: Option, - /// Preview mode: list what would be synced without writing files - #[arg(long)] - dry_run: bool, - }, - /// Push registered repositories to Syncthing as sync folders - SyncthingPush { - /// Syncthing REST API base URL - #[arg(long, default_value = "http://127.0.0.1:8384")] - api_url: String, - /// Syncthing API key (optional if no auth) - #[arg(long)] - api_key: Option, - /// Only push repos matching these tags (comma-separated, OR logic) - #[arg(long)] - filter_tags: Option, - /// Only push the repo associated with this experiment ID - #[arg(long)] - experiment: Option, - }, - /// Auto-discover relationships between registered repositories - #[cfg(feature = "tui")] - Discover, - /// Generate daily knowledge digest - Digest, - /// Generate knowledge coverage report for the workspace or a repo - KnowledgeReport { - /// Specific repo ID; if omitted, reports on the entire workspace - #[arg(default_value = "")] - repo_id: String, - /// Number of recent activity events to include - #[arg(long, default_value_t = 20)] - activity_limit: usize, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// View the operation log - Oplog { - /// Limit number of entries (default: 20) - #[arg(long, default_value_t = 20)] - limit: i64, - /// Filter by repo ID - #[arg(long)] - repo: Option, - }, - /// Show code metrics for registered repositories - Metrics { - /// Specific repo ID; if omitted, shows all repos - #[arg(default_value = "")] - repo_id: String, - /// Output as JSON - #[arg(long)] - json: bool, - /// Recompute metrics from source (tokei) before showing - #[arg(long)] - recalc: bool, - }, - /// Show module graph for a repository - ModuleGraph { - /// Repository ID; if omitted, shows all Rust repos - #[arg(default_value = "")] - repo_id: String, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Query the intra-repository call graph - CallGraph { - /// Repository ID to query - repo_id: String, - /// Called function name (who calls X) - #[arg(long)] - callee: Option, - /// Calling function name (what does Y call) - #[arg(long)] - caller: Option, - /// Optional file path substring to narrow scope - #[arg(long)] - file: Option, - /// Maximum results - #[arg(long, default_value_t = 50)] - limit: usize, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Query cross-repository dependency graph - DependencyGraph { - /// Repository ID to query - repo_id: String, - /// Direction: outgoing (this repo depends on) or incoming (depends on this repo) - #[arg(long, default_value = "outgoing")] - direction: String, - /// Filter by relation type - #[arg(long)] - relation_type: Option, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Query code symbols for a repository - CodeSymbols { - /// Repository ID to query - repo_id: String, - /// Optional symbol name substring filter - #[arg(long)] - name: Option, - /// Optional symbol type filter (function, struct, enum, trait, impl, module, type_alias, constant, static) - #[arg(long)] - symbol_type: Option, - /// Optional file path substring filter - #[arg(long)] - file: Option, - /// Maximum results - #[arg(long, default_value_t = 50)] - limit: usize, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Find potentially dead (unused) functions in a repository - DeadCode { - /// Repository ID to analyze - repo_id: String, - /// Also report `pub fn` items - #[arg(long)] - include_pub: bool, - /// Maximum results - #[arg(long, default_value_t = 50)] - limit: usize, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Fetch GitHub metadata for a registered repository - GithubInfo { - /// Repository ID - repo_id: String, - /// Write GitHub description into repo summary - #[arg(long)] - write_summary: bool, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Registry backup and restore operations - Registry { - #[command(subcommand)] - cmd: RegistryCommands, - }, - /// Vault note management - Vault { - #[command(subcommand)] - cmd: VaultCommands, - }, - /// Skill Runtime — install, discover, and execute AI skills - Skill { - #[command(subcommand)] - cmd: SkillCommands, - }, - /// Workflow Engine — orchestrate multi-Skill pipelines - Workflow { - #[command(subcommand)] - cmd: WorkflowCommands, - }, - /// Manage known system limits (L3 risk layer) - Limit { - #[command(subcommand)] - cmd: LimitCommands, - }, - /// Repository management — list repos and check git health - Repo { - #[command(subcommand)] - cmd: RepoCommands, - }, - /// Show version information - Version, -} - -#[derive(Subcommand)] -pub(crate) enum RepoCommands { - /// List all registered repositories - List { - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Show git health status (ahead/behind/dirty/managed) for all repos - Status { - /// Output as JSON - #[arg(long)] - json: bool, - }, -} - -#[derive(Subcommand)] -pub(crate) enum SkillCommands { - /// List installed skills - List { - /// Filter by skill type (builtin, custom, system) - #[arg(long)] - skill_type: Option, - /// Filter by category - #[arg(long)] - category: Option, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Install a skill from a local path or Git URL - Install { - /// Path to the skill directory or Git URL (must contain SKILL.md) - source: String, - /// Force treating source as a Git URL - #[arg(long)] - git: bool, - }, - /// Uninstall a skill - Uninstall { - /// Skill ID to remove - skill_id: String, - }, - /// Show skill details - Info { - /// Skill ID - skill_id: String, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Search skills by name or description - Search { - /// Query string - query: String, - /// Use semantic search (requires embeddings) - #[arg(long)] - semantic: bool, - /// Filter by category - #[arg(long)] - category: Option, - /// Maximum results - #[arg(long, default_value_t = 10)] - limit: usize, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Execute a skill - Run { - /// Skill ID - skill_id: String, - /// Arguments as key=value pairs - #[arg(long = "arg")] - args: Vec, - /// Timeout in seconds - #[arg(long, default_value_t = 30)] - timeout: u64, - /// Output full result as JSON - #[arg(long)] - json: bool, - }, - /// Validate a local SKILL.md file - Validate { - /// Path to SKILL.md or skill directory - path: String, - }, - /// Validate and prepare a skill for publishing - Publish { - /// Path to skill directory (default: current directory) - #[arg(default_value = ".")] - path: String, - /// Dry-run: validate without creating tag - #[arg(long)] - dry_run: bool, - }, - /// Sync skills to a plans directory (generic output, was clarity-only) - Sync { - /// Output directory for generated plan JSON files - output_dir: String, - }, - /// Discover and auto-package a project as a Skill - Discover { - /// Path to the project directory (or Git URL) - path: String, - /// Explicit skill ID (defaults to project name) - #[arg(long)] - skill_id: Option, - /// Dry-run: print generated files without installing - #[arg(long)] - dry_run: bool, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Recalculate skill scores from execution history - RecalcScores, - /// Show top-rated skills - Top { - /// Maximum results - #[arg(long, default_value_t = 10)] - limit: usize, - }, - /// Recommend skills based on execution scores - Recommend { - /// Filter by category - #[arg(long)] - category: Option, - /// Maximum results - #[arg(long, default_value_t = 5)] - limit: usize, - }, -} - -#[derive(Subcommand)] -pub(crate) enum WorkflowCommands { - /// List registered workflows - List { - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Show workflow definition - Show { - /// Workflow ID - workflow_id: String, - }, - /// Register a workflow from a YAML file - Register { - /// Path to workflow.yaml - path: String, - }, - /// Run a workflow - Run { - /// Workflow ID - workflow_id: String, - /// Workflow inputs as key=value pairs - #[arg(long = "input")] - inputs: Vec, - }, - /// Delete a workflow - Delete { - /// Workflow ID - workflow_id: String, - }, -} - -#[derive(Subcommand)] -pub(crate) enum VaultCommands { - /// Scan a directory for Markdown notes and sync into the vault - Scan { - /// Directory to scan (defaults to default vault dir) - #[arg(default_value = "")] - path: String, - }, - /// Rebuild the Tantivy search index for all vault notes - Reindex, - /// List all vault notes - List { - /// Filter by tag - #[arg(short, long)] - tag: Option, - }, - /// Read a vault note by its relative path (e.g. "99-Meta/devbase-essence.md") - Read { - /// Relative path of the note within the vault - path: String, - }, - /// Write or overwrite a vault note - Write { - /// Relative path of the note within the vault - path: String, - /// Note content (use "-" to read from stdin) - #[arg(short, long)] - content: Option, - /// Title (optional, defaults to filename) - #[arg(short, long)] - title: Option, - }, - /// Search vault notes by keyword - Search { - /// Search query - query: String, - /// Maximum results - #[arg(short, long, default_value_t = 20)] - limit: usize, - }, - /// Export vault notes to a directory with integrity validation - Export { - /// Output directory for the exported vault - #[arg(default_value = "")] - output_dir: String, - }, - /// Show Git revision history for a vault note - History { - /// Relative path of the note within the vault - path: String, - }, -} - -#[derive(Subcommand)] -pub(crate) enum LimitCommands { - /// Add or update a known limit - Add { - /// Unique identifier (kebab-case recommended) - id: String, - /// Category: hard-veto, known-bug, external-dep - #[arg(long, default_value = "known-bug")] - category: String, - /// Description of the limit - #[arg(long)] - description: Option, - /// Source reference (e.g., AGENTS.md, oplog) - #[arg(long)] - source: Option, - /// Severity 1-5 - #[arg(long)] - severity: Option, - }, - /// List known limits - List { - /// Filter by category - #[arg(long)] - category: Option, - /// Filter by mitigated status - #[arg(long)] - mitigated: Option, - /// Output as JSON - #[arg(long)] - json: bool, - }, - /// Resolve (mitigate) a known limit - Resolve { - /// Limit ID - id: String, - /// Reason for resolution (optional, stored in L4 metacognition layer) - #[arg(long)] - reason: Option, - }, - /// Delete a known limit - Delete { - /// Limit ID - id: String, - }, - /// Seed hard vetoes from AGENTS.md into the registry - Seed, -} - -#[derive(Subcommand)] -pub(crate) enum RegistryCommands { - /// Export registry to a backup file - Export { - /// Output format: sqlite or json - #[arg(long, default_value = "sqlite")] - format: String, - /// Output file path (optional, defaults to backup dir with timestamp) - #[arg(long)] - output: Option, - }, - /// Import registry from a backup SQLite file - Import { - /// Source backup file path - path: String, - /// Skip dry-run and execute immediately - #[arg(long)] - yes: bool, - }, - /// List existing registry backups - Backups, - /// Clean old backups, keeping only the most recent ones - Clean, -} - -#[tokio::main] -async fn main() -> anyhow::Result<()> { - tracing_subscriber::fmt() - .with_env_filter(tracing_subscriber::EnvFilter::from_default_env()) - .init(); - - let mut ctx = storage::AppContext::with_defaults()?; - let _lang = if ctx.config.general.language == "auto" || ctx.config.general.language.is_empty() { - let detected = i18n::detect_system_language(); - ctx.config.general.language = detected.clone(); - if let Err(e) = ctx.config.save() { - eprintln!("警告: 无法保存语言配置: {}", e); - } - detected - } else { - ctx.config.general.language.clone() - }; - // i18n is now initialized via AppContext, no global state needed - - let cli = Cli::parse(); - - match cli.command { - Commands::Scan { path, register, json } => { - commands::simple::run_scan(&mut ctx, &path, register, json).await?; - } - Commands::Health { detail, limit, page, json } => { - commands::simple::run_health(&mut ctx, detail, limit, page, json).await?; - } - Commands::Status { json } => { - commands::simple::run_status(&mut ctx, json).await?; - } - Commands::Repo { cmd } => { - commands::simple::run_repo(&mut ctx, cmd).await?; - } - Commands::Sync { - dry_run, - filter_tags, - exclude, - json, - } => { - commands::simple::run_sync(&mut ctx, dry_run, filter_tags, exclude, json).await?; - } - Commands::Query { query, limit, page, json } => { - commands::simple::run_query(&mut ctx, &query, limit, page, json).await?; - } - Commands::Index { path, skip_embeddings } => { - commands::simple::run_index(&mut ctx, &path, skip_embeddings).await?; - } - Commands::Clean => { - commands::simple::run_clean(&mut ctx)?; - } - Commands::Tag { repo_id, tags } => { - commands::simple::run_tag(&mut ctx, &repo_id, &tags)?; - } - Commands::Meta { repo_id, tier, workspace_type } => { - commands::simple::run_meta(&mut ctx, &repo_id, tier, workspace_type)?; - } - #[cfg(feature = "tui")] - Commands::Tui => { - commands::simple::run_tui(&mut ctx).await?; - } - #[cfg(feature = "mcp")] - Commands::Mcp { tools } => { - commands::simple::run_mcp(&mut ctx, tools).await?; - } - Commands::Daemon { interval } => { - commands::simple::run_daemon(&mut ctx, interval).await?; - } - #[cfg(feature = "watch")] - Commands::Watch { path, duration } => { - commands::simple::run_watch(&mut ctx, &path, duration).await?; - } - Commands::SkillSync { output, filter_tags, dry_run } => { - commands::simple::run_skill_sync(&mut ctx, &output, filter_tags, dry_run)?; - } - Commands::SyncthingPush { - api_url, - api_key, - filter_tags, - experiment, - } => { - commands::simple::run_syncthing_push( - &mut ctx, - api_url, - api_key, - filter_tags, - experiment, - ) - .await?; - } - Commands::Digest => { - commands::simple::run_digest(&mut ctx).await?; - } - Commands::Oplog { limit, repo } => { - commands::simple::run_oplog(&mut ctx, limit, repo)?; - } - Commands::Metrics { repo_id, json, recalc } => { - commands::simple::run_metrics(&mut ctx, &repo_id, json, recalc)?; - } - Commands::ModuleGraph { repo_id, json } => { - commands::simple::run_module_graph(&mut ctx, &repo_id, json)?; - } - Commands::CallGraph { - repo_id, - callee, - caller, - file, - limit, - json, - } => { - commands::simple::run_call_graph( - &mut ctx, &repo_id, callee, caller, file, limit, json, - )?; - } - Commands::DependencyGraph { - repo_id, - direction, - relation_type, - json, - } => { - commands::simple::run_dependency_graph( - &mut ctx, - &repo_id, - &direction, - relation_type, - json, - )?; - } - Commands::CodeSymbols { - repo_id, - name, - symbol_type, - file, - limit, - json, - } => { - commands::simple::run_code_symbols( - &mut ctx, - &repo_id, - name, - symbol_type, - file, - limit, - json, - )?; - } - Commands::DeadCode { - repo_id, - include_pub, - limit, - json, - } => { - commands::simple::run_dead_code(&mut ctx, &repo_id, include_pub, limit, json)?; - } - Commands::GithubInfo { repo_id, write_summary, json } => { - commands::simple::run_github_info(&mut ctx, &repo_id, write_summary, json).await?; - } - #[cfg(feature = "tui")] - Commands::Discover => { - commands::simple::run_discover(&mut ctx)?; - } - Commands::Registry { cmd } => { - commands::simple::run_registry(&mut ctx, cmd)?; - } - Commands::Vault { cmd } => { - commands::simple::run_vault(&mut ctx, cmd).await?; - } - Commands::Skill { cmd } => { - commands::skill::run_skill(&mut ctx, cmd)?; - } - Commands::Workflow { cmd } => { - commands::workflow::run_workflow(&mut ctx, cmd)?; - } - Commands::KnowledgeReport { repo_id, activity_limit, json } => { - commands::simple::run_knowledge_report(&mut ctx, &repo_id, activity_limit, json)?; - } - Commands::Limit { cmd } => { - commands::limit::run_limit(&mut ctx, cmd)?; - } - Commands::Version => { - println!("devbase {}", env!("CARGO_PKG_VERSION")); - } - } - - Ok(()) -} +// SPDX-License-Identifier: MIT +// Copyright (c) 2026 juice094 +use clap::{Parser, Subcommand}; + +use devbase::*; + +mod commands; + +#[derive(Parser)] +#[command(name = "devbase", version)] +#[command(about = "Developer workspace database and knowledge-base manager")] +struct Cli { + #[command(subcommand)] + command: Commands, +} + +#[derive(Subcommand)] +pub(crate) enum Commands { + /// Scan a directory for Git repositories and register them + Scan { + /// Directory to scan (defaults to workspace root) + #[arg(default_value = ".")] + path: String, + /// Register discovered repos into the database + #[arg(long)] + register: bool, + /// Output results as JSON + #[arg(long)] + json: bool, + }, + /// Check the health of registered repositories and the environment + Health { + /// Show detailed per-repo status + #[arg(long)] + detail: bool, + /// Maximum number of repos to display per page (0 = unlimited) + #[arg(long, default_value_t = 0)] + limit: usize, + /// Page number (1-based) + #[arg(long, default_value_t = 1)] + page: usize, + /// Output results as JSON + #[arg(long)] + json: bool, + }, + /// Show index status for registered repositories + Status { + /// Output results as JSON + #[arg(long)] + json: bool, + }, + /// Sync registered repositories with their upstream remotes + Sync { + /// Dry-run: show what would be updated without applying + #[arg(long)] + dry_run: bool, + /// Comma-separated list of tags to filter repositories (OR logic) + #[arg(long)] + filter_tags: Option, + /// Comma-separated list of repo IDs to exclude from sync + #[arg(long)] + exclude: Option, + /// Output results as JSON + #[arg(long)] + json: bool, + }, + /// Query the knowledge base + Query { + /// Query expression, e.g. "lang:rust stale:>30" + query: String, + /// Maximum number of results per page (0 = unlimited) + #[arg(long, default_value_t = 0)] + limit: usize, + /// Page number (1-based) + #[arg(long, default_value_t = 1)] + page: usize, + /// Output results as JSON + #[arg(long)] + json: bool, + }, + /// Index repository summaries and module structures + Index { + /// Specific path to index; if omitted, index all registered repos + #[arg(default_value = "")] + path: String, + /// Skip semantic embedding generation (symbols/calls still indexed) + #[arg(long)] + skip_embeddings: bool, + }, + /// Remove archive/backup entries from registry + Clean, + /// Tag a registered repository + Tag { + /// Repository ID + repo_id: String, + /// Comma-separated tags + tags: String, + }, + /// Update metadata (tier / workspace type) of a registered repository + Meta { + /// Repository ID + repo_id: String, + /// Data tier: public, cooperative, or private + #[arg(long)] + tier: Option, + /// Workspace type: git, openclaw, or generic + #[arg(long)] + workspace_type: Option, + }, + /// Launch interactive TUI + #[cfg(feature = "tui")] + Tui, + /// Run as an MCP server (stdio transport) + #[cfg(feature = "mcp")] + Mcp { + /// Comma-separated tool tiers to expose (stable,beta,experimental). + /// Defaults to all tiers if omitted. + #[arg(long)] + tools: Option, + }, + /// Start the background daemon for knowledge maintenance + Daemon { + /// Tick interval in seconds + #[arg(long)] + interval: Option, + }, + #[cfg(feature = "watch")] + /// Watch a directory for changes and schedule sync actions + Watch { + /// Directory to watch + #[arg(default_value = ".")] + path: String, + /// Watch duration in seconds + #[arg(long, default_value = "10")] + duration: u64, + }, + /// Sync vault notes with ai_context=true to Clarity SKILL.md format + SkillSync { + /// Output directory for generated SKILL.md files + #[arg(long, default_value = "skills")] + output: String, + /// Only sync notes matching specific tags (comma-separated) + #[arg(long)] + filter_tags: Option, + /// Preview mode: list what would be synced without writing files + #[arg(long)] + dry_run: bool, + }, + /// Push registered repositories to Syncthing as sync folders + SyncthingPush { + /// Syncthing REST API base URL + #[arg(long, default_value = "http://127.0.0.1:8384")] + api_url: String, + /// Syncthing API key (optional if no auth) + #[arg(long)] + api_key: Option, + /// Only push repos matching these tags (comma-separated, OR logic) + #[arg(long)] + filter_tags: Option, + /// Only push the repo associated with this experiment ID + #[arg(long)] + experiment: Option, + }, + /// Auto-discover relationships between registered repositories + #[cfg(feature = "tui")] + Discover, + /// Generate daily knowledge digest + Digest, + /// Generate knowledge coverage report for the workspace or a repo + KnowledgeReport { + /// Specific repo ID; if omitted, reports on the entire workspace + #[arg(default_value = "")] + repo_id: String, + /// Number of recent activity events to include + #[arg(long, default_value_t = 20)] + activity_limit: usize, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// View the operation log + Oplog { + /// Limit number of entries (default: 20) + #[arg(long, default_value_t = 20)] + limit: i64, + /// Filter by repo ID + #[arg(long)] + repo: Option, + }, + /// Show code metrics for registered repositories + Metrics { + /// Specific repo ID; if omitted, shows all repos + #[arg(default_value = "")] + repo_id: String, + /// Output as JSON + #[arg(long)] + json: bool, + /// Recompute metrics from source (tokei) before showing + #[arg(long)] + recalc: bool, + }, + /// Show module graph for a repository + ModuleGraph { + /// Repository ID; if omitted, shows all Rust repos + #[arg(default_value = "")] + repo_id: String, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Query the intra-repository call graph + CallGraph { + /// Repository ID to query + repo_id: String, + /// Called function name (who calls X) + #[arg(long)] + callee: Option, + /// Calling function name (what does Y call) + #[arg(long)] + caller: Option, + /// Optional file path substring to narrow scope + #[arg(long)] + file: Option, + /// Maximum results + #[arg(long, default_value_t = 50)] + limit: usize, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Query cross-repository dependency graph + DependencyGraph { + /// Repository ID to query + repo_id: String, + /// Direction: outgoing (this repo depends on) or incoming (depends on this repo) + #[arg(long, default_value = "outgoing")] + direction: String, + /// Filter by relation type + #[arg(long)] + relation_type: Option, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Query code symbols for a repository + CodeSymbols { + /// Repository ID to query + repo_id: String, + /// Optional symbol name substring filter + #[arg(long)] + name: Option, + /// Optional symbol type filter (function, struct, enum, trait, impl, module, type_alias, constant, static) + #[arg(long)] + symbol_type: Option, + /// Optional file path substring filter + #[arg(long)] + file: Option, + /// Maximum results + #[arg(long, default_value_t = 50)] + limit: usize, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Find potentially dead (unused) functions in a repository + DeadCode { + /// Repository ID to analyze + repo_id: String, + /// Also report `pub fn` items + #[arg(long)] + include_pub: bool, + /// Maximum results + #[arg(long, default_value_t = 50)] + limit: usize, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Fetch GitHub metadata for a registered repository + GithubInfo { + /// Repository ID + repo_id: String, + /// Write GitHub description into repo summary + #[arg(long)] + write_summary: bool, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Registry backup and restore operations + Registry { + #[command(subcommand)] + cmd: RegistryCommands, + }, + /// Vault note management + Vault { + #[command(subcommand)] + cmd: VaultCommands, + }, + /// Skill Runtime — install, discover, and execute AI skills + Skill { + #[command(subcommand)] + cmd: SkillCommands, + }, + /// Import ontology entities and relations from an OpenClaw workspace + Ontology { + /// Path to OpenClaw workspace (defaults to ~/.kimi_openclaw/workspace) + workspace: Option, + /// Dry-run: list entities/relations without importing + #[arg(long)] + dry_run: bool, + }, + /// Workflow Engine — orchestrate multi-Skill pipelines + Workflow { + #[command(subcommand)] + cmd: WorkflowCommands, + }, + /// Manage known system limits (L3 risk layer) + Limit { + #[command(subcommand)] + cmd: LimitCommands, + }, + /// Repository management — list repos and check git health + Repo { + #[command(subcommand)] + cmd: RepoCommands, + }, + /// Show version information + Version, +} + +#[derive(Subcommand)] +pub(crate) enum RepoCommands { + /// List all registered repositories + List { + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Show git health status (ahead/behind/dirty/managed) for all repos + Status { + /// Output as JSON + #[arg(long)] + json: bool, + }, +} + +#[derive(Subcommand)] +pub(crate) enum SkillCommands { + /// List installed skills + List { + /// Filter by skill type (builtin, custom, system) + #[arg(long)] + skill_type: Option, + /// Filter by category + #[arg(long)] + category: Option, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Install a skill from a local path or Git URL + Install { + /// Path to the skill directory or Git URL (must contain SKILL.md) + source: String, + /// Force treating source as a Git URL + #[arg(long)] + git: bool, + }, + /// Uninstall a skill + Uninstall { + /// Skill ID to remove + skill_id: String, + }, + /// Show skill details + Info { + /// Skill ID + skill_id: String, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Search skills by name or description + Search { + /// Query string + query: String, + /// Use semantic search (requires embeddings) + #[arg(long)] + semantic: bool, + /// Filter by category + #[arg(long)] + category: Option, + /// Maximum results + #[arg(long, default_value_t = 10)] + limit: usize, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Execute a skill + Run { + /// Skill ID + skill_id: String, + /// Arguments as key=value pairs + #[arg(long = "arg")] + args: Vec, + /// Timeout in seconds + #[arg(long, default_value_t = 30)] + timeout: u64, + /// Output full result as JSON + #[arg(long)] + json: bool, + }, + /// Validate a local SKILL.md file + Validate { + /// Path to SKILL.md or skill directory + path: String, + }, + /// Validate and prepare a skill for publishing + Publish { + /// Path to skill directory (default: current directory) + #[arg(default_value = ".")] + path: String, + /// Dry-run: validate without creating tag + #[arg(long)] + dry_run: bool, + }, + /// Sync skills to a plans directory (generic output, was clarity-only) + Sync { + /// Output directory for generated plan JSON files + output_dir: String, + }, + /// Discover and auto-package a project as a Skill + Discover { + /// Path to the project directory (or Git URL) + path: String, + /// Explicit skill ID (defaults to project name) + #[arg(long)] + skill_id: Option, + /// Dry-run: print generated files without installing + #[arg(long)] + dry_run: bool, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Recalculate skill scores from execution history + RecalcScores, + /// Show top-rated skills + Top { + /// Maximum results + #[arg(long, default_value_t = 10)] + limit: usize, + }, + /// Recommend skills based on execution scores + Recommend { + /// Filter by category + #[arg(long)] + category: Option, + /// Maximum results + #[arg(long, default_value_t = 5)] + limit: usize, + }, + /// Import skills from external sources (GitHub repos or local directories) + Import { + /// Source URL or path (GitHub URL or local directory) + source: String, + /// Path within the source to scan for SKILL.md files + #[arg(long)] + source_path: Option, + /// Dry-run: list discovered skills without installing + #[arg(long)] + dry_run: bool, + /// Output as JSON + #[arg(long)] + json: bool, + }, +} + +#[derive(Subcommand)] +pub(crate) enum WorkflowCommands { + /// List registered workflows + List { + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Show workflow definition + Show { + /// Workflow ID + workflow_id: String, + }, + /// Register a workflow from a YAML file + Register { + /// Path to workflow.yaml + path: String, + }, + /// Run a workflow + Run { + /// Workflow ID + workflow_id: String, + /// Workflow inputs as key=value pairs + #[arg(long = "input")] + inputs: Vec, + }, + /// Delete a workflow + Delete { + /// Workflow ID + workflow_id: String, + }, +} + +#[derive(Subcommand)] +pub(crate) enum VaultCommands { + /// Scan a directory for Markdown notes and sync into the vault + Scan { + /// Directory to scan (defaults to default vault dir) + #[arg(default_value = "")] + path: String, + }, + /// Rebuild the Tantivy search index for all vault notes + Reindex, + /// List all vault notes + List { + /// Filter by tag + #[arg(short, long)] + tag: Option, + }, + /// Read a vault note by its relative path (e.g. "99-Meta/devbase-essence.md") + Read { + /// Relative path of the note within the vault + path: String, + }, + /// Write or overwrite a vault note + Write { + /// Relative path of the note within the vault + path: String, + /// Note content (use "-" to read from stdin) + #[arg(short, long)] + content: Option, + /// Title (optional, defaults to filename) + #[arg(short, long)] + title: Option, + }, + /// Search vault notes by keyword + Search { + /// Search query + query: String, + /// Maximum results + #[arg(short, long, default_value_t = 20)] + limit: usize, + }, + /// Export vault notes to a directory with integrity validation + Export { + /// Output directory for the exported vault + #[arg(default_value = "")] + output_dir: String, + }, + /// Show Git revision history for a vault note + History { + /// Relative path of the note within the vault + path: String, + }, + /// Sync all configured vault roots (scan + incremental update) + Sync { + /// Perform a full rescan instead of incremental + #[arg(long)] + full: bool, + }, +} + +#[derive(Subcommand)] +pub(crate) enum LimitCommands { + /// Add or update a known limit + Add { + /// Unique identifier (kebab-case recommended) + id: String, + /// Category: hard-veto, known-bug, external-dep + #[arg(long, default_value = "known-bug")] + category: String, + /// Description of the limit + #[arg(long)] + description: Option, + /// Source reference (e.g., AGENTS.md, oplog) + #[arg(long)] + source: Option, + /// Severity 1-5 + #[arg(long)] + severity: Option, + }, + /// List known limits + List { + /// Filter by category + #[arg(long)] + category: Option, + /// Filter by mitigated status + #[arg(long)] + mitigated: Option, + /// Output as JSON + #[arg(long)] + json: bool, + }, + /// Resolve (mitigate) a known limit + Resolve { + /// Limit ID + id: String, + /// Reason for resolution (optional, stored in L4 metacognition layer) + #[arg(long)] + reason: Option, + }, + /// Delete a known limit + Delete { + /// Limit ID + id: String, + }, + /// Seed hard vetoes from AGENTS.md into the registry + Seed, +} + +#[derive(Subcommand)] +pub(crate) enum RegistryCommands { + /// Export registry to a backup file + Export { + /// Output format: sqlite or json + #[arg(long, default_value = "sqlite")] + format: String, + /// Output file path (optional, defaults to backup dir with timestamp) + #[arg(long)] + output: Option, + }, + /// Import registry from a backup SQLite file + Import { + /// Source backup file path + path: String, + /// Skip dry-run and execute immediately + #[arg(long)] + yes: bool, + }, + /// List existing registry backups + Backups, + /// Clean old backups, keeping only the most recent ones + Clean, +} + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + tracing_subscriber::fmt() + .with_env_filter(tracing_subscriber::EnvFilter::from_default_env()) + .init(); + + let mut ctx = storage::AppContext::with_defaults()?; + let _lang = if ctx.config.general.language == "auto" || ctx.config.general.language.is_empty() { + let detected = i18n::detect_system_language(); + ctx.config.general.language = detected.clone(); + if let Err(e) = ctx.config.save() { + eprintln!("警告: 无法保存语言配置: {}", e); + } + detected + } else { + ctx.config.general.language.clone() + }; + // i18n is now initialized via AppContext, no global state needed + + let cli = Cli::parse(); + + match cli.command { + Commands::Scan { path, register, json } => { + commands::simple::run_scan(&mut ctx, &path, register, json).await?; + } + Commands::Health { detail, limit, page, json } => { + commands::simple::run_health(&mut ctx, detail, limit, page, json).await?; + } + Commands::Status { json } => { + commands::simple::run_status(&mut ctx, json).await?; + } + Commands::Repo { cmd } => { + commands::simple::run_repo(&mut ctx, cmd).await?; + } + Commands::Sync { + dry_run, + filter_tags, + exclude, + json, + } => { + commands::simple::run_sync(&mut ctx, dry_run, filter_tags, exclude, json).await?; + } + Commands::Query { query, limit, page, json } => { + commands::simple::run_query(&mut ctx, &query, limit, page, json).await?; + } + Commands::Index { path, skip_embeddings } => { + commands::simple::run_index(&mut ctx, &path, skip_embeddings).await?; + } + Commands::Clean => { + commands::simple::run_clean(&mut ctx)?; + } + Commands::Tag { repo_id, tags } => { + commands::simple::run_tag(&mut ctx, &repo_id, &tags)?; + } + Commands::Meta { repo_id, tier, workspace_type } => { + commands::simple::run_meta(&mut ctx, &repo_id, tier, workspace_type)?; + } + #[cfg(feature = "tui")] + Commands::Tui => { + commands::simple::run_tui(&mut ctx).await?; + } + #[cfg(feature = "mcp")] + Commands::Mcp { tools } => { + commands::simple::run_mcp(&mut ctx, tools).await?; + } + Commands::Daemon { interval } => { + commands::simple::run_daemon(&mut ctx, interval).await?; + } + #[cfg(feature = "watch")] + Commands::Watch { path, duration } => { + commands::simple::run_watch(&mut ctx, &path, duration).await?; + } + Commands::SkillSync { output, filter_tags, dry_run } => { + commands::simple::run_skill_sync(&mut ctx, &output, filter_tags, dry_run)?; + } + Commands::SyncthingPush { + api_url, + api_key, + filter_tags, + experiment, + } => { + commands::simple::run_syncthing_push( + &mut ctx, + api_url, + api_key, + filter_tags, + experiment, + ) + .await?; + } + Commands::Digest => { + commands::simple::run_digest(&mut ctx).await?; + } + Commands::Oplog { limit, repo } => { + commands::simple::run_oplog(&mut ctx, limit, repo)?; + } + Commands::Metrics { repo_id, json, recalc } => { + commands::simple::run_metrics(&mut ctx, &repo_id, json, recalc)?; + } + Commands::ModuleGraph { repo_id, json } => { + commands::simple::run_module_graph(&mut ctx, &repo_id, json)?; + } + Commands::CallGraph { + repo_id, + callee, + caller, + file, + limit, + json, + } => { + commands::simple::run_call_graph( + &mut ctx, &repo_id, callee, caller, file, limit, json, + )?; + } + Commands::DependencyGraph { + repo_id, + direction, + relation_type, + json, + } => { + commands::simple::run_dependency_graph( + &mut ctx, + &repo_id, + &direction, + relation_type, + json, + )?; + } + Commands::CodeSymbols { + repo_id, + name, + symbol_type, + file, + limit, + json, + } => { + commands::simple::run_code_symbols( + &mut ctx, + &repo_id, + name, + symbol_type, + file, + limit, + json, + )?; + } + Commands::DeadCode { + repo_id, + include_pub, + limit, + json, + } => { + commands::simple::run_dead_code(&mut ctx, &repo_id, include_pub, limit, json)?; + } + Commands::GithubInfo { repo_id, write_summary, json } => { + commands::simple::run_github_info(&mut ctx, &repo_id, write_summary, json).await?; + } + #[cfg(feature = "tui")] + Commands::Discover => { + commands::simple::run_discover(&mut ctx)?; + } + Commands::Registry { cmd } => { + commands::simple::run_registry(&mut ctx, cmd)?; + } + Commands::Vault { cmd } => { + commands::simple::run_vault(&mut ctx, cmd).await?; + } + Commands::Skill { cmd } => { + commands::skill::run_skill(&mut ctx, cmd)?; + } + Commands::Ontology { workspace, dry_run } => { + commands::ontology::run_import(&mut ctx, workspace.as_deref().unwrap_or(""), dry_run)?; + } + Commands::Workflow { cmd } => { + commands::workflow::run_workflow(&mut ctx, cmd)?; + } + Commands::KnowledgeReport { repo_id, activity_limit, json } => { + commands::simple::run_knowledge_report(&mut ctx, &repo_id, activity_limit, json)?; + } + Commands::Limit { cmd } => { + commands::limit::run_limit(&mut ctx, cmd)?; + } + Commands::Version => { + println!("devbase {}", env!("CARGO_PKG_VERSION")); + } + } + + Ok(()) +} diff --git a/src/mcp/mod.rs b/src/mcp/mod.rs index 45a83a0..d39c255 100644 --- a/src/mcp/mod.rs +++ b/src/mcp/mod.rs @@ -1,1038 +1,1050 @@ -// SPDX-License-Identifier: MIT -// Copyright (c) 2026 juice094 -use std::collections::{HashMap, HashSet}; -use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader}; - -pub use tools::*; - -/// Phase of a streaming tool invocation. -#[derive(Debug, Clone, serde::Serialize)] -#[serde(rename_all = "snake_case")] -pub enum StreamPhase { - /// Progress update (e.g., "Indexing repo 3/10..."). - Progress, - /// Intermediate partial result. - Partial, - /// Final result — stream ends after this. - Done, - /// Error occurred — stream ends after this. - Error, -} - -/// A single event in a streaming tool invocation. -#[derive(Debug, Clone, serde::Serialize)] -pub struct ToolStreamEvent { - pub phase: StreamPhase, - pub payload: serde_json::Value, -} - -#[allow(async_fn_in_trait)] -pub trait McpTool: Send + Sync + Clone { - fn name(&self) -> &'static str; - fn schema(&self) -> serde_json::Value; - async fn invoke( - &self, - args: serde_json::Value, - ctx: &mut crate::storage::AppContext, - ) -> anyhow::Result; - - /// Optional streaming interface for long-running operations. - /// - /// Default implementation delegates to `invoke` and emits a single `Done` event. - /// Override this for tools that support progressive output (e.g., indexing, - /// syncing large batches, or long-running analysis). - async fn invoke_stream( - &self, - args: serde_json::Value, - ctx: &mut crate::storage::AppContext, - ) -> anyhow::Result> { - let result = self.invoke(args, ctx).await?; - Ok(vec![ToolStreamEvent { - phase: StreamPhase::Done, - payload: result, - }]) - } -} - -#[derive(Clone)] -pub enum McpToolEnum { - Scan(DevkitScanTool), - Health(DevkitHealthTool), - Sync(DevkitSyncTool), - Query(DevkitQueryTool), - QueryRepos(DevkitQueryReposTool), - Index(DevkitIndexTool), - IndexHealth(DevkitIndexHealthTool), - IndexStream(DevkitIndexStreamTool), - Note(DevkitNoteTool), - Status(DevkitStatusTool), - Digest(DevkitDigestTool), - Paper(DevkitPaperIndexTool), - Experiment(DevkitExperimentLogTool), - GithubInfo(DevkitGithubInfoTool), - CodeMetrics(DevkitCodeMetricsTool), - ModuleGraph(DevkitModuleGraphTool), - NaturalLanguageQuery(DevkitNaturalLanguageQueryTool), - VaultSearch(DevkitVaultSearchTool), - VaultRead(DevkitVaultReadTool), - VaultWrite(DevkitVaultWriteTool), - VaultBacklinks(DevkitVaultBacklinksTool), - VaultDaily(DevkitVaultDailyTool), - VaultGraph(DevkitVaultGraphTool), - VaultExport(DevkitVaultExportTool), - VaultHistory(DevkitVaultHistoryTool), - ProjectContext(DevkitProjectContextTool), - ProjectBrief(DevkitProjectBriefTool), - ImpactAnalysis(DevkitImpactAnalysisTool), - CodeSymbols(DevkitCodeSymbolsTool), - DependencyGraph(DevkitDependencyGraphTool), - CallGraph(DevkitCallGraphTool), - DeadCode(DevkitDeadCodeTool), - SemanticSearch(DevkitSemanticSearchTool), - ArxivFetch(DevkitArxivFetchTool), - EmbeddingStore(DevkitEmbeddingStoreTool), - EmbeddingSearch(DevkitEmbeddingSearchTool), - CrossRepoSearch(DevkitCrossRepoSearchTool), - KnowledgeReport(DevkitKnowledgeReportTool), - RelatedSymbols(DevkitRelatedSymbolsTool), - HybridSearch(DevkitHybridSearchTool), - SearchQuality(DevkitSearchQualityTool), - SkillList(DevkitSkillListTool), - SkillSearch(DevkitSkillSearchTool), - SkillRun(DevkitSkillRunTool), - SkillDiscover(DevkitSkillDiscoverTool), - KnownLimitStore(DevkitKnownLimitStoreTool), - KnownLimitList(DevkitKnownLimitListTool), - RelationStore(DevkitRelationStoreTool), - RelationQuery(DevkitRelationQueryTool), - RelationDelete(DevkitRelationDeleteTool), - SessionSave(DevkitSessionSaveTool), - SessionList(DevkitSessionListTool), - SessionResume(DevkitSessionResumeTool), - SessionAttach(DevkitSessionAttachTool), - SessionDetach(DevkitSessionDetachTool), - SessionActivate(DevkitSessionActivateTool), - SessionSearch(DevkitSessionSearchTool), - SessionCapture(DevkitSessionCaptureTool), - SessionWorkflows(DevkitSessionWorkflowsTool), - SessionRecall(DevkitSessionRecallTool), - SessionIndex(DevkitSessionIndexTool), - SessionExport(DevkitSessionExportTool), - SessionImport(DevkitSessionImportTool), - WorkflowList(DevkitWorkflowListTool), - WorkflowRun(DevkitWorkflowRunTool), - WorkflowStatus(DevkitWorkflowStatusTool), - OplogQuery(DevkitOplogQueryTool), - Evaluate(DevkitEvaluateTool), - DocumentConvert(DevkitDocumentConvertTool), -} - -/// Stability tier for MCP tools. -#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub enum ToolTier { - Stable, - Beta, - Experimental, -} - -impl std::str::FromStr for ToolTier { - type Err = (); - fn from_str(s: &str) -> Result { - match s.to_lowercase().as_str() { - "stable" => Ok(ToolTier::Stable), - "beta" => Ok(ToolTier::Beta), - "experimental" => Ok(ToolTier::Experimental), - _ => Err(()), - } - } -} - -impl McpToolEnum { - pub fn tier(&self) -> ToolTier { - match self { - // Stable: battle-tested, schema frozen, unit-tested - McpToolEnum::Health(_) => ToolTier::Stable, - McpToolEnum::QueryRepos(_) => ToolTier::Stable, - McpToolEnum::VaultSearch(_) => ToolTier::Stable, - McpToolEnum::VaultRead(_) => ToolTier::Stable, - McpToolEnum::ProjectContext(_) => ToolTier::Stable, - McpToolEnum::ProjectBrief(_) => ToolTier::Beta, - McpToolEnum::ImpactAnalysis(_) => ToolTier::Beta, - // Beta: validated but schema may微调, limited edge-case tests - McpToolEnum::Scan(_) => ToolTier::Beta, - McpToolEnum::Sync(_) => ToolTier::Beta, - McpToolEnum::Query(_) => ToolTier::Beta, - McpToolEnum::Index(_) => ToolTier::Beta, - McpToolEnum::IndexHealth(_) => ToolTier::Beta, - McpToolEnum::IndexStream(_) => ToolTier::Beta, - McpToolEnum::Status(_) => ToolTier::Beta, - McpToolEnum::Note(_) => ToolTier::Beta, - McpToolEnum::VaultWrite(_) => ToolTier::Beta, - McpToolEnum::VaultBacklinks(_) => ToolTier::Beta, - McpToolEnum::VaultDaily(_) => ToolTier::Beta, - McpToolEnum::VaultGraph(_) => ToolTier::Beta, - McpToolEnum::VaultExport(_) => ToolTier::Beta, - McpToolEnum::VaultHistory(_) => ToolTier::Beta, - McpToolEnum::NaturalLanguageQuery(_) => ToolTier::Beta, - McpToolEnum::GithubInfo(_) => ToolTier::Beta, - // Experimental: new, behavior may change, pending prod validation - McpToolEnum::Digest(_) => ToolTier::Experimental, - McpToolEnum::Paper(_) => ToolTier::Experimental, - McpToolEnum::Experiment(_) => ToolTier::Beta, - McpToolEnum::CodeMetrics(_) => ToolTier::Beta, - McpToolEnum::ModuleGraph(_) => ToolTier::Beta, - McpToolEnum::CodeSymbols(_) => ToolTier::Beta, - McpToolEnum::DependencyGraph(_) => ToolTier::Beta, - McpToolEnum::CallGraph(_) => ToolTier::Beta, - McpToolEnum::DeadCode(_) => ToolTier::Beta, - McpToolEnum::SemanticSearch(_) => ToolTier::Beta, - McpToolEnum::ArxivFetch(_) => ToolTier::Beta, - McpToolEnum::EmbeddingStore(_) => ToolTier::Beta, - McpToolEnum::EmbeddingSearch(_) => ToolTier::Beta, - McpToolEnum::CrossRepoSearch(_) => ToolTier::Beta, - McpToolEnum::KnowledgeReport(_) => ToolTier::Beta, - McpToolEnum::RelatedSymbols(_) => ToolTier::Experimental, - McpToolEnum::HybridSearch(_) => ToolTier::Beta, - McpToolEnum::SearchQuality(_) => ToolTier::Beta, - McpToolEnum::SkillList(_) => ToolTier::Beta, - McpToolEnum::SkillSearch(_) => ToolTier::Beta, - McpToolEnum::SkillRun(_) => ToolTier::Beta, - McpToolEnum::SkillDiscover(_) => ToolTier::Beta, - McpToolEnum::KnownLimitStore(_) => ToolTier::Beta, - McpToolEnum::KnownLimitList(_) => ToolTier::Beta, - McpToolEnum::RelationStore(_) => ToolTier::Beta, - McpToolEnum::RelationQuery(_) => ToolTier::Beta, - McpToolEnum::RelationDelete(_) => ToolTier::Beta, - McpToolEnum::SessionSave(_) => ToolTier::Beta, - McpToolEnum::SessionList(_) => ToolTier::Beta, - McpToolEnum::SessionResume(_) => ToolTier::Beta, - McpToolEnum::SessionAttach(_) => ToolTier::Beta, - McpToolEnum::SessionDetach(_) => ToolTier::Beta, - McpToolEnum::SessionActivate(_) => ToolTier::Beta, - McpToolEnum::SessionSearch(_) => ToolTier::Beta, - McpToolEnum::SessionCapture(_) => ToolTier::Beta, - McpToolEnum::SessionWorkflows(_) => ToolTier::Beta, - McpToolEnum::SessionRecall(_) => ToolTier::Experimental, - McpToolEnum::SessionIndex(_) => ToolTier::Experimental, - McpToolEnum::SessionExport(_) => ToolTier::Experimental, - McpToolEnum::SessionImport(_) => ToolTier::Experimental, - McpToolEnum::WorkflowList(_) => ToolTier::Beta, - McpToolEnum::WorkflowRun(_) => ToolTier::Beta, - McpToolEnum::WorkflowStatus(_) => ToolTier::Beta, - McpToolEnum::OplogQuery(_) => ToolTier::Beta, - McpToolEnum::Evaluate(_) => ToolTier::Beta, - McpToolEnum::DocumentConvert(_) => ToolTier::Experimental, - } - } -} - -impl McpTool for McpToolEnum { - fn name(&self) -> &'static str { - match self { - McpToolEnum::Scan(t) => t.name(), - McpToolEnum::Health(t) => t.name(), - McpToolEnum::Sync(t) => t.name(), - McpToolEnum::Query(t) => t.name(), - McpToolEnum::QueryRepos(t) => t.name(), - McpToolEnum::Index(t) => t.name(), - McpToolEnum::IndexHealth(t) => t.name(), - McpToolEnum::IndexStream(t) => t.name(), - McpToolEnum::Status(t) => t.name(), - McpToolEnum::Note(t) => t.name(), - McpToolEnum::Digest(t) => t.name(), - McpToolEnum::Paper(t) => t.name(), - McpToolEnum::Experiment(t) => t.name(), - McpToolEnum::GithubInfo(t) => t.name(), - McpToolEnum::CodeMetrics(t) => t.name(), - McpToolEnum::ModuleGraph(t) => t.name(), - McpToolEnum::NaturalLanguageQuery(t) => t.name(), - McpToolEnum::VaultSearch(t) => t.name(), - McpToolEnum::VaultRead(t) => t.name(), - McpToolEnum::VaultWrite(t) => t.name(), - McpToolEnum::VaultBacklinks(t) => t.name(), - McpToolEnum::VaultDaily(t) => t.name(), - McpToolEnum::VaultGraph(t) => t.name(), - McpToolEnum::VaultExport(t) => t.name(), - McpToolEnum::VaultHistory(t) => t.name(), - McpToolEnum::ProjectContext(t) => t.name(), - McpToolEnum::ProjectBrief(t) => t.name(), - McpToolEnum::ImpactAnalysis(t) => t.name(), - McpToolEnum::CodeSymbols(t) => t.name(), - McpToolEnum::DependencyGraph(t) => t.name(), - McpToolEnum::CallGraph(t) => t.name(), - McpToolEnum::DeadCode(t) => t.name(), - McpToolEnum::SemanticSearch(t) => t.name(), - McpToolEnum::ArxivFetch(t) => t.name(), - McpToolEnum::EmbeddingStore(t) => t.name(), - McpToolEnum::EmbeddingSearch(t) => t.name(), - McpToolEnum::CrossRepoSearch(t) => t.name(), - McpToolEnum::KnowledgeReport(t) => t.name(), - McpToolEnum::RelatedSymbols(t) => t.name(), - McpToolEnum::HybridSearch(t) => t.name(), - McpToolEnum::SearchQuality(t) => t.name(), - McpToolEnum::SkillList(t) => t.name(), - McpToolEnum::SkillSearch(t) => t.name(), - McpToolEnum::SkillRun(t) => t.name(), - McpToolEnum::SkillDiscover(t) => t.name(), - McpToolEnum::KnownLimitStore(t) => t.name(), - McpToolEnum::KnownLimitList(t) => t.name(), - McpToolEnum::RelationStore(t) => t.name(), - McpToolEnum::RelationQuery(t) => t.name(), - McpToolEnum::RelationDelete(t) => t.name(), - McpToolEnum::SessionSave(t) => t.name(), - McpToolEnum::SessionList(t) => t.name(), - McpToolEnum::SessionResume(t) => t.name(), - McpToolEnum::SessionAttach(t) => t.name(), - McpToolEnum::SessionDetach(t) => t.name(), - McpToolEnum::SessionActivate(t) => t.name(), - McpToolEnum::SessionSearch(t) => t.name(), - McpToolEnum::SessionCapture(t) => t.name(), - McpToolEnum::SessionWorkflows(t) => t.name(), - McpToolEnum::SessionRecall(t) => t.name(), - McpToolEnum::SessionIndex(t) => t.name(), - McpToolEnum::SessionExport(t) => t.name(), - McpToolEnum::SessionImport(t) => t.name(), - McpToolEnum::WorkflowList(t) => t.name(), - McpToolEnum::WorkflowRun(t) => t.name(), - McpToolEnum::WorkflowStatus(t) => t.name(), - McpToolEnum::OplogQuery(t) => t.name(), - McpToolEnum::Evaluate(t) => t.name(), - McpToolEnum::DocumentConvert(t) => t.name(), - } - } - - fn schema(&self) -> serde_json::Value { - match self { - McpToolEnum::Scan(t) => t.schema(), - McpToolEnum::Health(t) => t.schema(), - McpToolEnum::Sync(t) => t.schema(), - McpToolEnum::Query(t) => t.schema(), - McpToolEnum::QueryRepos(t) => t.schema(), - McpToolEnum::Index(t) => t.schema(), - McpToolEnum::IndexHealth(t) => t.schema(), - McpToolEnum::IndexStream(t) => t.schema(), - McpToolEnum::Status(t) => t.schema(), - McpToolEnum::Note(t) => t.schema(), - McpToolEnum::Digest(t) => t.schema(), - McpToolEnum::Paper(t) => t.schema(), - McpToolEnum::Experiment(t) => t.schema(), - McpToolEnum::GithubInfo(t) => t.schema(), - McpToolEnum::CodeMetrics(t) => t.schema(), - McpToolEnum::ModuleGraph(t) => t.schema(), - McpToolEnum::NaturalLanguageQuery(t) => t.schema(), - McpToolEnum::VaultSearch(t) => t.schema(), - McpToolEnum::VaultRead(t) => t.schema(), - McpToolEnum::VaultWrite(t) => t.schema(), - McpToolEnum::VaultBacklinks(t) => t.schema(), - McpToolEnum::VaultDaily(t) => t.schema(), - McpToolEnum::VaultGraph(t) => t.schema(), - McpToolEnum::VaultExport(t) => t.schema(), - McpToolEnum::VaultHistory(t) => t.schema(), - McpToolEnum::ProjectContext(t) => t.schema(), - McpToolEnum::ProjectBrief(t) => t.schema(), - McpToolEnum::ImpactAnalysis(t) => t.schema(), - McpToolEnum::CodeSymbols(t) => t.schema(), - McpToolEnum::DependencyGraph(t) => t.schema(), - McpToolEnum::CallGraph(t) => t.schema(), - McpToolEnum::DeadCode(t) => t.schema(), - McpToolEnum::SemanticSearch(t) => t.schema(), - McpToolEnum::ArxivFetch(t) => t.schema(), - McpToolEnum::EmbeddingStore(t) => t.schema(), - McpToolEnum::EmbeddingSearch(t) => t.schema(), - McpToolEnum::CrossRepoSearch(t) => t.schema(), - McpToolEnum::KnowledgeReport(t) => t.schema(), - McpToolEnum::RelatedSymbols(t) => t.schema(), - McpToolEnum::HybridSearch(t) => t.schema(), - McpToolEnum::SearchQuality(t) => t.schema(), - McpToolEnum::SkillList(t) => t.schema(), - McpToolEnum::SkillSearch(t) => t.schema(), - McpToolEnum::SkillRun(t) => t.schema(), - McpToolEnum::SkillDiscover(t) => t.schema(), - McpToolEnum::KnownLimitStore(t) => t.schema(), - McpToolEnum::KnownLimitList(t) => t.schema(), - McpToolEnum::RelationStore(t) => t.schema(), - McpToolEnum::RelationQuery(t) => t.schema(), - McpToolEnum::RelationDelete(t) => t.schema(), - McpToolEnum::SessionSave(t) => t.schema(), - McpToolEnum::SessionList(t) => t.schema(), - McpToolEnum::SessionResume(t) => t.schema(), - McpToolEnum::SessionAttach(t) => t.schema(), - McpToolEnum::SessionDetach(t) => t.schema(), - McpToolEnum::SessionActivate(t) => t.schema(), - McpToolEnum::SessionSearch(t) => t.schema(), - McpToolEnum::SessionCapture(t) => t.schema(), - McpToolEnum::SessionWorkflows(t) => t.schema(), - McpToolEnum::SessionRecall(t) => t.schema(), - McpToolEnum::SessionIndex(t) => t.schema(), - McpToolEnum::SessionExport(t) => t.schema(), - McpToolEnum::SessionImport(t) => t.schema(), - McpToolEnum::WorkflowList(t) => t.schema(), - McpToolEnum::WorkflowRun(t) => t.schema(), - McpToolEnum::WorkflowStatus(t) => t.schema(), - McpToolEnum::OplogQuery(t) => t.schema(), - McpToolEnum::Evaluate(t) => t.schema(), - McpToolEnum::DocumentConvert(t) => t.schema(), - } - } - - async fn invoke( - &self, - args: serde_json::Value, - ctx: &mut crate::storage::AppContext, - ) -> anyhow::Result { - match self { - McpToolEnum::Scan(t) => t.invoke(args, ctx).await, - McpToolEnum::Health(t) => t.invoke(args, ctx).await, - McpToolEnum::Sync(t) => t.invoke(args, ctx).await, - McpToolEnum::Query(t) => t.invoke(args, ctx).await, - McpToolEnum::QueryRepos(t) => t.invoke(args, ctx).await, - McpToolEnum::Index(t) => t.invoke(args, ctx).await, - McpToolEnum::IndexHealth(t) => t.invoke(args, ctx).await, - McpToolEnum::IndexStream(t) => t.invoke(args, ctx).await, - McpToolEnum::Status(t) => t.invoke(args, ctx).await, - McpToolEnum::Note(t) => t.invoke(args, ctx).await, - McpToolEnum::Digest(t) => t.invoke(args, ctx).await, - McpToolEnum::Paper(t) => t.invoke(args, ctx).await, - McpToolEnum::Experiment(t) => t.invoke(args, ctx).await, - McpToolEnum::GithubInfo(t) => t.invoke(args, ctx).await, - McpToolEnum::CodeMetrics(t) => t.invoke(args, ctx).await, - McpToolEnum::ModuleGraph(t) => t.invoke(args, ctx).await, - McpToolEnum::NaturalLanguageQuery(t) => t.invoke(args, ctx).await, - McpToolEnum::VaultSearch(t) => t.invoke(args, ctx).await, - McpToolEnum::VaultRead(t) => t.invoke(args, ctx).await, - McpToolEnum::VaultWrite(t) => t.invoke(args, ctx).await, - McpToolEnum::VaultBacklinks(t) => t.invoke(args, ctx).await, - McpToolEnum::VaultDaily(t) => t.invoke(args, ctx).await, - McpToolEnum::VaultGraph(t) => t.invoke(args, ctx).await, - McpToolEnum::VaultExport(t) => t.invoke(args, ctx).await, - McpToolEnum::VaultHistory(t) => t.invoke(args, ctx).await, - McpToolEnum::ProjectContext(t) => t.invoke(args, ctx).await, - McpToolEnum::ProjectBrief(t) => t.invoke(args, ctx).await, - McpToolEnum::ImpactAnalysis(t) => t.invoke(args, ctx).await, - McpToolEnum::CodeSymbols(t) => t.invoke(args, ctx).await, - McpToolEnum::DependencyGraph(t) => t.invoke(args, ctx).await, - McpToolEnum::CallGraph(t) => t.invoke(args, ctx).await, - McpToolEnum::DeadCode(t) => t.invoke(args, ctx).await, - McpToolEnum::SemanticSearch(t) => t.invoke(args, ctx).await, - McpToolEnum::ArxivFetch(t) => t.invoke(args, ctx).await, - McpToolEnum::EmbeddingStore(t) => t.invoke(args, ctx).await, - McpToolEnum::EmbeddingSearch(t) => t.invoke(args, ctx).await, - McpToolEnum::CrossRepoSearch(t) => t.invoke(args, ctx).await, - McpToolEnum::KnowledgeReport(t) => t.invoke(args, ctx).await, - McpToolEnum::RelatedSymbols(t) => t.invoke(args, ctx).await, - McpToolEnum::HybridSearch(t) => t.invoke(args, ctx).await, - McpToolEnum::SearchQuality(t) => t.invoke(args, ctx).await, - McpToolEnum::SkillList(t) => t.invoke(args, ctx).await, - McpToolEnum::SkillSearch(t) => t.invoke(args, ctx).await, - McpToolEnum::SkillRun(t) => t.invoke(args, ctx).await, - McpToolEnum::SkillDiscover(t) => t.invoke(args, ctx).await, - McpToolEnum::KnownLimitStore(t) => t.invoke(args, ctx).await, - McpToolEnum::KnownLimitList(t) => t.invoke(args, ctx).await, - McpToolEnum::RelationStore(t) => t.invoke(args, ctx).await, - McpToolEnum::RelationQuery(t) => t.invoke(args, ctx).await, - McpToolEnum::RelationDelete(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionSave(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionList(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionResume(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionAttach(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionDetach(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionActivate(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionSearch(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionCapture(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionWorkflows(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionRecall(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionIndex(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionExport(t) => t.invoke(args, ctx).await, - McpToolEnum::SessionImport(t) => t.invoke(args, ctx).await, - McpToolEnum::WorkflowList(t) => t.invoke(args, ctx).await, - McpToolEnum::WorkflowRun(t) => t.invoke(args, ctx).await, - McpToolEnum::WorkflowStatus(t) => t.invoke(args, ctx).await, - McpToolEnum::OplogQuery(t) => t.invoke(args, ctx).await, - McpToolEnum::Evaluate(t) => t.invoke(args, ctx).await, - McpToolEnum::DocumentConvert(t) => t.invoke(args, ctx).await, - } - } -} - -/// Long-lived oplog file handle — opened once, reused across all MCP calls. -static OPLOG_FILE: std::sync::OnceLock>> = - std::sync::OnceLock::new(); - -fn get_oplog_file() -> &'static std::sync::Mutex> { - OPLOG_FILE.get_or_init(|| { - let file = dirs::data_local_dir().and_then(|data_dir| { - let log_path = data_dir.join("devbase").join("mcp-oplog.ndjson"); - std::fs::OpenOptions::new().create(true).append(true).open(&log_path).ok() - }); - std::sync::Mutex::new(file) - }) -} - -/// Append a single MCP tool invocation record to the oplog file. -/// -/// Path: `%LOCALAPPDATA%/devbase/mcp-oplog.ndjson` -/// Format: newline-delimited JSON (NDJSON) -fn append_mcp_oplog(tool_name: &str, duration_ms: u128, success: bool, error_type: Option<&str>) { - let entry = serde_json::json!({ - "timestamp": chrono::Utc::now().to_rfc3339(), - "tool": tool_name, - "duration_ms": duration_ms, - "success": success, - "error_type": error_type, - }); - - if let Ok(mut guard) = get_oplog_file().lock() { - if let Some(ref mut file) = *guard { - use std::io::Write; - if let Err(e) = writeln!(file, "{}", entry) { - tracing::warn!("Failed to write MCP oplog: {}", e); - } - } - } -} - -pub struct McpServer { - tools: HashMap, -} - -impl Default for McpServer { - fn default() -> Self { - Self::new() - } -} - -impl McpServer { - pub fn new() -> Self { - Self { tools: HashMap::new() } - } - - pub fn register_tool(&mut self, tool: McpToolEnum) { - self.tools.insert(tool.name().to_string(), tool); - } - - pub async fn handle_request( - &self, - req: serde_json::Value, - ctx: &mut crate::storage::AppContext, - ) -> anyhow::Result { - let id = req.get("id").cloned().unwrap_or(serde_json::Value::Null); - let method = req.get("method").and_then(|v| v.as_str()).unwrap_or(""); - - match method { - "ping" => Ok(serde_json::json!({ - "jsonrpc": "2.0", - "id": id, - "result": {} - })), - "initialize" => { - // Verify client protocol version for compatibility - let client_version = req - .get("params") - .and_then(|p| p.get("protocolVersion")) - .and_then(|v| v.as_str()) - .unwrap_or("unknown"); - let supported = ["2024-11-05"]; - if !supported.contains(&client_version) { - tracing::warn!( - "Client protocol version '{}' not in supported list {:?}; proceeding with 2024-11-05", - client_version, - supported - ); - } - Ok(serde_json::json!({ - "jsonrpc": "2.0", - "id": id, - "result": { - "protocolVersion": "2024-11-05", - "capabilities": { - "tools": {} - }, - "serverInfo": { - "name": "devbase", - "version": env!("CARGO_PKG_VERSION") - } - } - })) - } - "tools/list" => { - let tools: Vec = self - .tools - .values() - .map(|t| { - let schema = t.schema(); - serde_json::json!({ - "name": t.name(), - "description": schema.get("description").and_then(|v| v.as_str()).unwrap_or(""), - "inputSchema": schema.get("inputSchema").cloned().unwrap_or(serde_json::json!({})) - }) - }) - .collect(); - Ok(serde_json::json!({ - "jsonrpc": "2.0", - "id": id, - "result": { "tools": tools } - })) - } - "tools/call" => { - let params = req.get("params").cloned().unwrap_or(serde_json::Value::Null); - let name = params.get("name").and_then(|v| v.as_str()).unwrap_or(""); - let args = params.get("arguments").cloned().unwrap_or(serde_json::Value::Null); - let stream = params.get("stream").and_then(|v| v.as_bool()).unwrap_or(false); - - match self.tools.get(name) { - Some(_tool) if stream => { - let start = std::time::Instant::now(); - match self.handle_streaming_call(name, args, ctx).await { - Ok(events) => { - append_mcp_oplog(name, start.elapsed().as_millis(), true, None); - let events_json = serde_json::to_string(&events)?; - let content = serde_json::json!({ - "type": "text", - "text": events_json - }); - Ok(serde_json::json!({ - "jsonrpc": "2.0", - "id": id, - "result": { - "content": [content], - "isError": false - } - })) - } - Err(e) => { - append_mcp_oplog( - name, - start.elapsed().as_millis(), - false, - Some("invoke_error"), - ); - let payload = - serde_json::json!({ "success": false, "error": e.to_string() }); - let text = serde_json::to_string(&payload)?; - let content = serde_json::json!({ "type": "text", "text": text }); - Ok(serde_json::json!({ - "jsonrpc": "2.0", - "id": id, - "result": { - "content": [content], - "isError": true - } - })) - } - } - } - Some(tool) => { - let start = std::time::Instant::now(); - match tool.invoke(args, ctx).await { - Ok(result) => { - let text = result.to_string(); - let is_error = !result - .get("success") - .and_then(|v: &serde_json::Value| v.as_bool()) - .unwrap_or(true); - append_mcp_oplog( - name, - start.elapsed().as_millis(), - !is_error, - None, - ); - let content = serde_json::json!({ - "type": "text", - "text": text - }); - Ok(serde_json::json!({ - "jsonrpc": "2.0", - "id": id, - "result": { - "content": [content], - "isError": is_error - } - })) - } - Err(e) => { - append_mcp_oplog( - name, - start.elapsed().as_millis(), - false, - Some("invoke_error"), - ); - let payload = - serde_json::json!({ "success": false, "error": e.to_string() }); - let text = serde_json::to_string(&payload)?; - let content = serde_json::json!({ "type": "text", "text": text }); - Ok(serde_json::json!({ - "jsonrpc": "2.0", - "id": id, - "result": { - "content": [content], - "isError": true - } - })) - } - } - } - None => Ok(serde_json::json!({ - "jsonrpc": "2.0", - "id": id, - "error": { - "code": -32602, - "message": format!("Tool '{}' not found", name) - } - })), - } - } - _ => { - if id.is_null() { - // Workaround: Python MCP SDK 1.16.0 cannot parse JSON-RPC - // error responses with `id: null`. Return Null so the - // caller can silently drop it. - return Ok(serde_json::Value::Null); - } - Ok(serde_json::json!({ - "jsonrpc": "2.0", - "id": id, - "error": { - "code": -32601, - "message": format!("Method '{}' not found", method) - } - })) - } - } - } - - /// Invoke a tool in streaming mode and return a sequence of events. - /// - /// This is used by the SSE transport to push progressive updates. - /// If the tool does not override `invoke_stream`, the default implementation - /// delegates to `invoke` and wraps the result as a single `Done` event. - pub async fn handle_streaming_call( - &self, - name: &str, - args: serde_json::Value, - ctx: &mut crate::storage::AppContext, - ) -> anyhow::Result> { - match self.tools.get(name) { - Some(tool) => tool.invoke_stream(args, ctx).await, - None => Err(anyhow::anyhow!("Tool '{}' not found", name)), - } - } -} - -/// Build an MCP server with optional tier filtering. -/// -/// If `tiers` is `None`, all 69 tools are registered (backward compatible). -/// If `tiers` is provided, only tools whose tier is in the set are registered. -pub fn build_server_with_tiers(tiers: Option<&HashSet>) -> McpServer { - let mut server = McpServer::new(); - let all_tools = [ - McpToolEnum::Scan(DevkitScanTool), - McpToolEnum::Health(DevkitHealthTool), - McpToolEnum::Sync(DevkitSyncTool), - McpToolEnum::Query(DevkitQueryTool), - McpToolEnum::QueryRepos(DevkitQueryReposTool), - McpToolEnum::Index(DevkitIndexTool), - McpToolEnum::IndexHealth(DevkitIndexHealthTool), - McpToolEnum::IndexStream(DevkitIndexStreamTool), - McpToolEnum::Status(DevkitStatusTool), - McpToolEnum::Note(DevkitNoteTool), - McpToolEnum::Digest(DevkitDigestTool), - McpToolEnum::Paper(DevkitPaperIndexTool), - McpToolEnum::Experiment(DevkitExperimentLogTool), - McpToolEnum::GithubInfo(DevkitGithubInfoTool), - McpToolEnum::CodeMetrics(DevkitCodeMetricsTool), - McpToolEnum::ModuleGraph(DevkitModuleGraphTool), - McpToolEnum::NaturalLanguageQuery(DevkitNaturalLanguageQueryTool), - McpToolEnum::VaultSearch(DevkitVaultSearchTool), - McpToolEnum::VaultRead(DevkitVaultReadTool), - McpToolEnum::VaultWrite(DevkitVaultWriteTool), - McpToolEnum::VaultBacklinks(DevkitVaultBacklinksTool), - McpToolEnum::VaultDaily(DevkitVaultDailyTool), - McpToolEnum::VaultGraph(DevkitVaultGraphTool), - McpToolEnum::VaultExport(DevkitVaultExportTool), - McpToolEnum::VaultHistory(DevkitVaultHistoryTool), - McpToolEnum::ProjectContext(DevkitProjectContextTool), - McpToolEnum::ProjectBrief(DevkitProjectBriefTool), - McpToolEnum::ImpactAnalysis(DevkitImpactAnalysisTool), - McpToolEnum::CodeSymbols(DevkitCodeSymbolsTool), - McpToolEnum::DependencyGraph(DevkitDependencyGraphTool), - McpToolEnum::CallGraph(DevkitCallGraphTool), - McpToolEnum::DeadCode(DevkitDeadCodeTool), - McpToolEnum::SemanticSearch(DevkitSemanticSearchTool), - McpToolEnum::ArxivFetch(DevkitArxivFetchTool), - McpToolEnum::EmbeddingStore(DevkitEmbeddingStoreTool), - McpToolEnum::EmbeddingSearch(DevkitEmbeddingSearchTool), - McpToolEnum::CrossRepoSearch(DevkitCrossRepoSearchTool), - McpToolEnum::KnowledgeReport(DevkitKnowledgeReportTool), - McpToolEnum::RelatedSymbols(DevkitRelatedSymbolsTool), - McpToolEnum::HybridSearch(DevkitHybridSearchTool), - McpToolEnum::SearchQuality(DevkitSearchQualityTool), - McpToolEnum::SkillList(DevkitSkillListTool), - McpToolEnum::SkillSearch(DevkitSkillSearchTool), - McpToolEnum::SkillRun(DevkitSkillRunTool), - McpToolEnum::SkillDiscover(DevkitSkillDiscoverTool), - McpToolEnum::KnownLimitStore(DevkitKnownLimitStoreTool), - McpToolEnum::KnownLimitList(DevkitKnownLimitListTool), - McpToolEnum::RelationStore(DevkitRelationStoreTool), - McpToolEnum::RelationQuery(DevkitRelationQueryTool), - McpToolEnum::RelationDelete(DevkitRelationDeleteTool), - McpToolEnum::SessionSave(DevkitSessionSaveTool), - McpToolEnum::SessionList(DevkitSessionListTool), - McpToolEnum::SessionResume(DevkitSessionResumeTool), - McpToolEnum::SessionAttach(DevkitSessionAttachTool), - McpToolEnum::SessionDetach(DevkitSessionDetachTool), - McpToolEnum::SessionActivate(DevkitSessionActivateTool), - McpToolEnum::SessionSearch(DevkitSessionSearchTool), - McpToolEnum::SessionCapture(DevkitSessionCaptureTool), - McpToolEnum::SessionWorkflows(DevkitSessionWorkflowsTool), - McpToolEnum::SessionRecall(DevkitSessionRecallTool), - McpToolEnum::SessionIndex(DevkitSessionIndexTool), - McpToolEnum::SessionExport(DevkitSessionExportTool), - McpToolEnum::SessionImport(DevkitSessionImportTool), - McpToolEnum::WorkflowList(DevkitWorkflowListTool), - McpToolEnum::WorkflowRun(DevkitWorkflowRunTool), - McpToolEnum::WorkflowStatus(DevkitWorkflowStatusTool), - McpToolEnum::OplogQuery(DevkitOplogQueryTool), - McpToolEnum::Evaluate(DevkitEvaluateTool), - McpToolEnum::DocumentConvert(DevkitDocumentConvertTool), - ]; - for tool in all_tools { - if let Some(allowed) = tiers - && !allowed.contains(&tool.tier()) - { - continue; - } - server.register_tool(tool); - } - server -} - -/// Build an MCP server with all tools (backward compatible). -pub fn build_server() -> McpServer { - build_server_with_tiers(None) -} - -pub fn format_mcp_message(body: &serde_json::Value) -> String { - format_mcp_message_auto(body, false) -} - -/// Format MCP message with optional NDJSON mode (no Content-Length headers). -/// NDJSON mode outputs raw JSON followed by a newline, for clients that -/// expect line-delimited JSON-RPC over stdio. -pub fn format_mcp_message_auto(body: &serde_json::Value, ndjson: bool) -> String { - let body_str = body.to_string(); - if ndjson { - format!("{}\n", body_str) - } else { - format!("Content-Length: {}\r\n\r\n{}", body_str.len(), body_str) - } -} - -/// Check whether destructive MCP tools are enabled via environment variable. -/// Returns Ok(()) if enabled, or an error with a clear message if disabled. -pub(crate) fn check_destructive_enabled() -> anyhow::Result<()> { - let enabled = std::env::var("DEVBASE_MCP_ENABLE_DESTRUCTIVE") - .map(|v| v == "1" || v.eq_ignore_ascii_case("true")) - .unwrap_or(false); - if !enabled { - anyhow::bail!( - "Destructive tools are disabled. \ - Set DEVBASE_MCP_ENABLE_DESTRUCTIVE=1 to enable." - ); - } - Ok(()) -} - -/// Parse tool tiers from a comma-separated string (e.g. "stable,beta"). -fn parse_tool_tiers(s: &str) -> HashSet { - s.split(',') - .map(|t| t.trim()) - .filter(|t| !t.is_empty()) - .filter_map(|s| s.parse().ok()) - .collect() -} - -pub async fn run_stdio() -> anyhow::Result<()> { - let mut ctx = crate::storage::AppContext::with_defaults()?; - let tiers: Option> = std::env::var("DEVBASE_MCP_TOOL_TIERS") - .ok() - .map(|s| parse_tool_tiers(&s)) - .filter(|set| !set.is_empty()); - let server = build_server_with_tiers(tiers.as_ref()); - let stdin = tokio::io::stdin(); - let mut stdout = tokio::io::stdout(); - let mut reader = BufReader::new(stdin); - let mut line_buf = String::new(); - let mut use_ndjson = false; - - loop { - line_buf.clear(); - // Read header line to get Content-Length - let n = reader.read_line(&mut line_buf).await?; - if n == 0 { - break; // EOF - } - let line = line_buf.trim(); - if line.is_empty() { - continue; - } - - let content_length = if line.starts_with("Content-Length: ") { - line.strip_prefix("Content-Length: ").and_then(|v| v.parse::().ok()) - } else { - // Client is using NDJSON (raw JSON lines). Switch to NDJSON output. - use_ndjson = true; - // Fallback: parse raw JSON line for backward compatibility - let req: serde_json::Value = match serde_json::from_str(line) { - Ok(v) => v, - Err(e) => { - let resp = serde_json::json!({ - "jsonrpc": "2.0", - "id": null, - "error": { - "code": -32700, - "message": format!("Parse error: {}", e) - } - }); - let msg = format_mcp_message_auto(&resp, use_ndjson); - if stdout.write_all(msg.as_bytes()).await.is_err() - || stdout.flush().await.is_err() - { - break; - } - continue; - } - }; - let resp = server.handle_request(req, &mut ctx).await.unwrap_or_else(|e| { - serde_json::json!({ - "jsonrpc": "2.0", - "id": null, - "error": { - "code": -32603, - "message": format!("Internal error: {}", e) - } - }) - }); - if !resp.is_null() { - let msg = format_mcp_message_auto(&resp, use_ndjson); - if stdout.write_all(msg.as_bytes()).await.is_err() || stdout.flush().await.is_err() - { - break; - } - } - continue; - }; - - let content_length = match content_length { - Some(len) => len, - None => { - let resp = serde_json::json!({ - "jsonrpc": "2.0", - "id": null, - "error": { - "code": -32700, - "message": format!("Invalid Content-Length header: {}", line) - } - }); - let msg = format_mcp_message_auto(&resp, use_ndjson); - if stdout.write_all(msg.as_bytes()).await.is_err() || stdout.flush().await.is_err() - { - break; - } - continue; - } - }; - - // Read the empty line (\r\n or \n) - line_buf.clear(); - let _ = reader.read_line(&mut line_buf).await; - - // Read the exact number of bytes - let mut body_buf = vec![0u8; content_length]; - if let Err(e) = reader.read_exact(&mut body_buf).await { - let resp = serde_json::json!({ - "jsonrpc": "2.0", - "id": null, - "error": { - "code": -32700, - "message": format!("Failed to read request body: {}", e) - } - }); - let msg = format_mcp_message_auto(&resp, use_ndjson); - if stdout.write_all(msg.as_bytes()).await.is_err() || stdout.flush().await.is_err() { - break; - } - continue; - } - - let req: serde_json::Value = match String::from_utf8(body_buf) { - Ok(body) => match serde_json::from_str(&body) { - Ok(v) => v, - Err(e) => { - let resp = serde_json::json!({ - "jsonrpc": "2.0", - "id": null, - "error": { - "code": -32700, - "message": format!("Parse error: {}", e) - } - }); - let msg = format_mcp_message_auto(&resp, use_ndjson); - if stdout.write_all(msg.as_bytes()).await.is_err() - || stdout.flush().await.is_err() - { - break; // broken pipe - } - continue; - } - }, - Err(e) => { - let resp = serde_json::json!({ - "jsonrpc": "2.0", - "id": null, - "error": { - "code": -32700, - "message": format!("Invalid UTF-8: {}", e) - } - }); - let msg = format_mcp_message_auto(&resp, use_ndjson); - if stdout.write_all(msg.as_bytes()).await.is_err() || stdout.flush().await.is_err() - { - break; // broken pipe - } - continue; - } - }; - - // Notifications have no "id" field and require no response. - let is_notification = req.get("id").is_none(); - if is_notification { - // Silently acknowledge all notifications (not just notifications/*). - continue; - } - - let resp = server.handle_request(req, &mut ctx).await.unwrap_or_else(|e| { - serde_json::json!({ - "jsonrpc": "2.0", - "id": null, - "error": { - "code": -32603, - "message": format!("Internal error: {}", e) - } - }) - }); - - if !resp.is_null() { - let msg = format_mcp_message_auto(&resp, use_ndjson); - if stdout.write_all(msg.as_bytes()).await.is_err() || stdout.flush().await.is_err() { - break; // broken pipe - } - } - } - - Ok(()) -} - -pub use crate::clients::*; -#[cfg(test)] -pub mod tests; -pub mod tools; +// SPDX-License-Identifier: MIT +// Copyright (c) 2026 juice094 +use std::collections::{HashMap, HashSet}; +use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader}; + +pub use tools::*; + +/// Phase of a streaming tool invocation. +#[derive(Debug, Clone, serde::Serialize)] +#[serde(rename_all = "snake_case")] +pub enum StreamPhase { + /// Progress update (e.g., "Indexing repo 3/10..."). + Progress, + /// Intermediate partial result. + Partial, + /// Final result — stream ends after this. + Done, + /// Error occurred — stream ends after this. + Error, +} + +/// A single event in a streaming tool invocation. +#[derive(Debug, Clone, serde::Serialize)] +pub struct ToolStreamEvent { + pub phase: StreamPhase, + pub payload: serde_json::Value, +} + +#[allow(async_fn_in_trait)] +pub trait McpTool: Send + Sync + Clone { + fn name(&self) -> &'static str; + fn schema(&self) -> serde_json::Value; + async fn invoke( + &self, + args: serde_json::Value, + ctx: &mut crate::storage::AppContext, + ) -> anyhow::Result; + + /// Optional streaming interface for long-running operations. + /// + /// Default implementation delegates to `invoke` and emits a single `Done` event. + /// Override this for tools that support progressive output (e.g., indexing, + /// syncing large batches, or long-running analysis). + async fn invoke_stream( + &self, + args: serde_json::Value, + ctx: &mut crate::storage::AppContext, + ) -> anyhow::Result> { + let result = self.invoke(args, ctx).await?; + Ok(vec![ToolStreamEvent { + phase: StreamPhase::Done, + payload: result, + }]) + } +} + +#[derive(Clone)] +pub enum McpToolEnum { + Scan(DevkitScanTool), + Health(DevkitHealthTool), + Sync(DevkitSyncTool), + Query(DevkitQueryTool), + QueryRepos(DevkitQueryReposTool), + Index(DevkitIndexTool), + IndexHealth(DevkitIndexHealthTool), + IndexStream(DevkitIndexStreamTool), + Note(DevkitNoteTool), + Status(DevkitStatusTool), + Digest(DevkitDigestTool), + Paper(DevkitPaperIndexTool), + Experiment(DevkitExperimentLogTool), + GithubInfo(DevkitGithubInfoTool), + CodeMetrics(DevkitCodeMetricsTool), + ModuleGraph(DevkitModuleGraphTool), + NaturalLanguageQuery(DevkitNaturalLanguageQueryTool), + VaultSearch(DevkitVaultSearchTool), + VaultRead(DevkitVaultReadTool), + VaultWrite(DevkitVaultWriteTool), + VaultBacklinks(DevkitVaultBacklinksTool), + VaultDaily(DevkitVaultDailyTool), + VaultGraph(DevkitVaultGraphTool), + VaultExport(DevkitVaultExportTool), + VaultHistory(DevkitVaultHistoryTool), + ProjectContext(DevkitProjectContextTool), + ProjectBrief(DevkitProjectBriefTool), + ImpactAnalysis(DevkitImpactAnalysisTool), + CodeSymbols(DevkitCodeSymbolsTool), + DependencyGraph(DevkitDependencyGraphTool), + CallGraph(DevkitCallGraphTool), + DeadCode(DevkitDeadCodeTool), + SemanticSearch(DevkitSemanticSearchTool), + ArxivFetch(DevkitArxivFetchTool), + EmbeddingStore(DevkitEmbeddingStoreTool), + EmbeddingSearch(DevkitEmbeddingSearchTool), + CrossRepoSearch(DevkitCrossRepoSearchTool), + KnowledgeReport(DevkitKnowledgeReportTool), + RelatedSymbols(DevkitRelatedSymbolsTool), + HybridSearch(DevkitHybridSearchTool), + SearchQuality(DevkitSearchQualityTool), + SkillList(DevkitSkillListTool), + SkillSearch(DevkitSkillSearchTool), + SkillRun(DevkitSkillRunTool), + SkillDiscover(DevkitSkillDiscoverTool), + SkillSync(DevkitSkillSyncTool), + KnownLimitStore(DevkitKnownLimitStoreTool), + KnownLimitList(DevkitKnownLimitListTool), + RelationStore(DevkitRelationStoreTool), + RelationQuery(DevkitRelationQueryTool), + RelationDelete(DevkitRelationDeleteTool), + SessionSave(DevkitSessionSaveTool), + SessionList(DevkitSessionListTool), + SessionResume(DevkitSessionResumeTool), + SessionAttach(DevkitSessionAttachTool), + SessionDetach(DevkitSessionDetachTool), + SessionActivate(DevkitSessionActivateTool), + SessionSearch(DevkitSessionSearchTool), + SessionCapture(DevkitSessionCaptureTool), + SessionWorkflows(DevkitSessionWorkflowsTool), + SessionRecall(DevkitSessionRecallTool), + SessionIndex(DevkitSessionIndexTool), + SessionExport(DevkitSessionExportTool), + SessionImport(DevkitSessionImportTool), + WorkflowList(DevkitWorkflowListTool), + WorkflowRun(DevkitWorkflowRunTool), + WorkflowStatus(DevkitWorkflowStatusTool), + OplogQuery(DevkitOplogQueryTool), + Evaluate(DevkitEvaluateTool), + DocumentConvert(DevkitDocumentConvertTool), + OntologyImport(DevkitOntologyImportTool), +} + +/// Stability tier for MCP tools. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum ToolTier { + Stable, + Beta, + Experimental, +} + +impl std::str::FromStr for ToolTier { + type Err = (); + fn from_str(s: &str) -> Result { + match s.to_lowercase().as_str() { + "stable" => Ok(ToolTier::Stable), + "beta" => Ok(ToolTier::Beta), + "experimental" => Ok(ToolTier::Experimental), + _ => Err(()), + } + } +} + +impl McpToolEnum { + pub fn tier(&self) -> ToolTier { + match self { + // Stable: battle-tested, schema frozen, unit-tested + McpToolEnum::Health(_) => ToolTier::Stable, + McpToolEnum::QueryRepos(_) => ToolTier::Stable, + McpToolEnum::VaultSearch(_) => ToolTier::Stable, + McpToolEnum::VaultRead(_) => ToolTier::Stable, + McpToolEnum::ProjectContext(_) => ToolTier::Stable, + McpToolEnum::ProjectBrief(_) => ToolTier::Beta, + McpToolEnum::ImpactAnalysis(_) => ToolTier::Beta, + // Beta: validated but schema may微调, limited edge-case tests + McpToolEnum::Scan(_) => ToolTier::Beta, + McpToolEnum::Sync(_) => ToolTier::Beta, + McpToolEnum::Query(_) => ToolTier::Beta, + McpToolEnum::Index(_) => ToolTier::Beta, + McpToolEnum::IndexHealth(_) => ToolTier::Beta, + McpToolEnum::IndexStream(_) => ToolTier::Beta, + McpToolEnum::Status(_) => ToolTier::Beta, + McpToolEnum::Note(_) => ToolTier::Beta, + McpToolEnum::VaultWrite(_) => ToolTier::Beta, + McpToolEnum::VaultBacklinks(_) => ToolTier::Beta, + McpToolEnum::VaultDaily(_) => ToolTier::Beta, + McpToolEnum::VaultGraph(_) => ToolTier::Beta, + McpToolEnum::VaultExport(_) => ToolTier::Beta, + McpToolEnum::VaultHistory(_) => ToolTier::Beta, + McpToolEnum::NaturalLanguageQuery(_) => ToolTier::Beta, + McpToolEnum::GithubInfo(_) => ToolTier::Beta, + // Experimental: new, behavior may change, pending prod validation + McpToolEnum::Digest(_) => ToolTier::Experimental, + McpToolEnum::Paper(_) => ToolTier::Experimental, + McpToolEnum::Experiment(_) => ToolTier::Beta, + McpToolEnum::CodeMetrics(_) => ToolTier::Beta, + McpToolEnum::ModuleGraph(_) => ToolTier::Beta, + McpToolEnum::CodeSymbols(_) => ToolTier::Beta, + McpToolEnum::DependencyGraph(_) => ToolTier::Beta, + McpToolEnum::CallGraph(_) => ToolTier::Beta, + McpToolEnum::DeadCode(_) => ToolTier::Beta, + McpToolEnum::SemanticSearch(_) => ToolTier::Beta, + McpToolEnum::ArxivFetch(_) => ToolTier::Beta, + McpToolEnum::EmbeddingStore(_) => ToolTier::Beta, + McpToolEnum::EmbeddingSearch(_) => ToolTier::Beta, + McpToolEnum::CrossRepoSearch(_) => ToolTier::Beta, + McpToolEnum::KnowledgeReport(_) => ToolTier::Beta, + McpToolEnum::RelatedSymbols(_) => ToolTier::Experimental, + McpToolEnum::HybridSearch(_) => ToolTier::Beta, + McpToolEnum::SearchQuality(_) => ToolTier::Beta, + McpToolEnum::SkillList(_) => ToolTier::Beta, + McpToolEnum::SkillSearch(_) => ToolTier::Beta, + McpToolEnum::SkillRun(_) => ToolTier::Beta, + McpToolEnum::SkillDiscover(_) => ToolTier::Beta, + McpToolEnum::SkillSync(_) => ToolTier::Beta, + McpToolEnum::KnownLimitStore(_) => ToolTier::Beta, + McpToolEnum::KnownLimitList(_) => ToolTier::Beta, + McpToolEnum::RelationStore(_) => ToolTier::Beta, + McpToolEnum::RelationQuery(_) => ToolTier::Beta, + McpToolEnum::RelationDelete(_) => ToolTier::Beta, + McpToolEnum::SessionSave(_) => ToolTier::Beta, + McpToolEnum::SessionList(_) => ToolTier::Beta, + McpToolEnum::SessionResume(_) => ToolTier::Beta, + McpToolEnum::SessionAttach(_) => ToolTier::Beta, + McpToolEnum::SessionDetach(_) => ToolTier::Beta, + McpToolEnum::SessionActivate(_) => ToolTier::Beta, + McpToolEnum::SessionSearch(_) => ToolTier::Beta, + McpToolEnum::SessionCapture(_) => ToolTier::Beta, + McpToolEnum::SessionWorkflows(_) => ToolTier::Beta, + McpToolEnum::SessionRecall(_) => ToolTier::Experimental, + McpToolEnum::SessionIndex(_) => ToolTier::Experimental, + McpToolEnum::SessionExport(_) => ToolTier::Experimental, + McpToolEnum::SessionImport(_) => ToolTier::Experimental, + McpToolEnum::WorkflowList(_) => ToolTier::Beta, + McpToolEnum::WorkflowRun(_) => ToolTier::Beta, + McpToolEnum::WorkflowStatus(_) => ToolTier::Beta, + McpToolEnum::OplogQuery(_) => ToolTier::Beta, + McpToolEnum::Evaluate(_) => ToolTier::Beta, + McpToolEnum::DocumentConvert(_) => ToolTier::Experimental, + McpToolEnum::OntologyImport(_) => ToolTier::Beta, + } + } +} + +impl McpTool for McpToolEnum { + fn name(&self) -> &'static str { + match self { + McpToolEnum::Scan(t) => t.name(), + McpToolEnum::Health(t) => t.name(), + McpToolEnum::Sync(t) => t.name(), + McpToolEnum::Query(t) => t.name(), + McpToolEnum::QueryRepos(t) => t.name(), + McpToolEnum::Index(t) => t.name(), + McpToolEnum::IndexHealth(t) => t.name(), + McpToolEnum::IndexStream(t) => t.name(), + McpToolEnum::Status(t) => t.name(), + McpToolEnum::Note(t) => t.name(), + McpToolEnum::Digest(t) => t.name(), + McpToolEnum::Paper(t) => t.name(), + McpToolEnum::Experiment(t) => t.name(), + McpToolEnum::GithubInfo(t) => t.name(), + McpToolEnum::CodeMetrics(t) => t.name(), + McpToolEnum::ModuleGraph(t) => t.name(), + McpToolEnum::NaturalLanguageQuery(t) => t.name(), + McpToolEnum::VaultSearch(t) => t.name(), + McpToolEnum::VaultRead(t) => t.name(), + McpToolEnum::VaultWrite(t) => t.name(), + McpToolEnum::VaultBacklinks(t) => t.name(), + McpToolEnum::VaultDaily(t) => t.name(), + McpToolEnum::VaultGraph(t) => t.name(), + McpToolEnum::VaultExport(t) => t.name(), + McpToolEnum::VaultHistory(t) => t.name(), + McpToolEnum::ProjectContext(t) => t.name(), + McpToolEnum::ProjectBrief(t) => t.name(), + McpToolEnum::ImpactAnalysis(t) => t.name(), + McpToolEnum::CodeSymbols(t) => t.name(), + McpToolEnum::DependencyGraph(t) => t.name(), + McpToolEnum::CallGraph(t) => t.name(), + McpToolEnum::DeadCode(t) => t.name(), + McpToolEnum::SemanticSearch(t) => t.name(), + McpToolEnum::ArxivFetch(t) => t.name(), + McpToolEnum::EmbeddingStore(t) => t.name(), + McpToolEnum::EmbeddingSearch(t) => t.name(), + McpToolEnum::CrossRepoSearch(t) => t.name(), + McpToolEnum::KnowledgeReport(t) => t.name(), + McpToolEnum::RelatedSymbols(t) => t.name(), + McpToolEnum::HybridSearch(t) => t.name(), + McpToolEnum::SearchQuality(t) => t.name(), + McpToolEnum::SkillList(t) => t.name(), + McpToolEnum::SkillSearch(t) => t.name(), + McpToolEnum::SkillRun(t) => t.name(), + McpToolEnum::SkillDiscover(t) => t.name(), + McpToolEnum::SkillSync(t) => t.name(), + McpToolEnum::KnownLimitStore(t) => t.name(), + McpToolEnum::KnownLimitList(t) => t.name(), + McpToolEnum::RelationStore(t) => t.name(), + McpToolEnum::RelationQuery(t) => t.name(), + McpToolEnum::RelationDelete(t) => t.name(), + McpToolEnum::SessionSave(t) => t.name(), + McpToolEnum::SessionList(t) => t.name(), + McpToolEnum::SessionResume(t) => t.name(), + McpToolEnum::SessionAttach(t) => t.name(), + McpToolEnum::SessionDetach(t) => t.name(), + McpToolEnum::SessionActivate(t) => t.name(), + McpToolEnum::SessionSearch(t) => t.name(), + McpToolEnum::SessionCapture(t) => t.name(), + McpToolEnum::SessionWorkflows(t) => t.name(), + McpToolEnum::SessionRecall(t) => t.name(), + McpToolEnum::SessionIndex(t) => t.name(), + McpToolEnum::SessionExport(t) => t.name(), + McpToolEnum::SessionImport(t) => t.name(), + McpToolEnum::WorkflowList(t) => t.name(), + McpToolEnum::WorkflowRun(t) => t.name(), + McpToolEnum::WorkflowStatus(t) => t.name(), + McpToolEnum::OplogQuery(t) => t.name(), + McpToolEnum::Evaluate(t) => t.name(), + McpToolEnum::DocumentConvert(t) => t.name(), + McpToolEnum::OntologyImport(t) => t.name(), + } + } + + fn schema(&self) -> serde_json::Value { + match self { + McpToolEnum::Scan(t) => t.schema(), + McpToolEnum::Health(t) => t.schema(), + McpToolEnum::Sync(t) => t.schema(), + McpToolEnum::Query(t) => t.schema(), + McpToolEnum::QueryRepos(t) => t.schema(), + McpToolEnum::Index(t) => t.schema(), + McpToolEnum::IndexHealth(t) => t.schema(), + McpToolEnum::IndexStream(t) => t.schema(), + McpToolEnum::Status(t) => t.schema(), + McpToolEnum::Note(t) => t.schema(), + McpToolEnum::Digest(t) => t.schema(), + McpToolEnum::Paper(t) => t.schema(), + McpToolEnum::Experiment(t) => t.schema(), + McpToolEnum::GithubInfo(t) => t.schema(), + McpToolEnum::CodeMetrics(t) => t.schema(), + McpToolEnum::ModuleGraph(t) => t.schema(), + McpToolEnum::NaturalLanguageQuery(t) => t.schema(), + McpToolEnum::VaultSearch(t) => t.schema(), + McpToolEnum::VaultRead(t) => t.schema(), + McpToolEnum::VaultWrite(t) => t.schema(), + McpToolEnum::VaultBacklinks(t) => t.schema(), + McpToolEnum::VaultDaily(t) => t.schema(), + McpToolEnum::VaultGraph(t) => t.schema(), + McpToolEnum::VaultExport(t) => t.schema(), + McpToolEnum::VaultHistory(t) => t.schema(), + McpToolEnum::ProjectContext(t) => t.schema(), + McpToolEnum::ProjectBrief(t) => t.schema(), + McpToolEnum::ImpactAnalysis(t) => t.schema(), + McpToolEnum::CodeSymbols(t) => t.schema(), + McpToolEnum::DependencyGraph(t) => t.schema(), + McpToolEnum::CallGraph(t) => t.schema(), + McpToolEnum::DeadCode(t) => t.schema(), + McpToolEnum::SemanticSearch(t) => t.schema(), + McpToolEnum::ArxivFetch(t) => t.schema(), + McpToolEnum::EmbeddingStore(t) => t.schema(), + McpToolEnum::EmbeddingSearch(t) => t.schema(), + McpToolEnum::CrossRepoSearch(t) => t.schema(), + McpToolEnum::KnowledgeReport(t) => t.schema(), + McpToolEnum::RelatedSymbols(t) => t.schema(), + McpToolEnum::HybridSearch(t) => t.schema(), + McpToolEnum::SearchQuality(t) => t.schema(), + McpToolEnum::SkillList(t) => t.schema(), + McpToolEnum::SkillSearch(t) => t.schema(), + McpToolEnum::SkillRun(t) => t.schema(), + McpToolEnum::SkillDiscover(t) => t.schema(), + McpToolEnum::SkillSync(t) => t.schema(), + McpToolEnum::KnownLimitStore(t) => t.schema(), + McpToolEnum::KnownLimitList(t) => t.schema(), + McpToolEnum::RelationStore(t) => t.schema(), + McpToolEnum::RelationQuery(t) => t.schema(), + McpToolEnum::RelationDelete(t) => t.schema(), + McpToolEnum::SessionSave(t) => t.schema(), + McpToolEnum::SessionList(t) => t.schema(), + McpToolEnum::SessionResume(t) => t.schema(), + McpToolEnum::SessionAttach(t) => t.schema(), + McpToolEnum::SessionDetach(t) => t.schema(), + McpToolEnum::SessionActivate(t) => t.schema(), + McpToolEnum::SessionSearch(t) => t.schema(), + McpToolEnum::SessionCapture(t) => t.schema(), + McpToolEnum::SessionWorkflows(t) => t.schema(), + McpToolEnum::SessionRecall(t) => t.schema(), + McpToolEnum::SessionIndex(t) => t.schema(), + McpToolEnum::SessionExport(t) => t.schema(), + McpToolEnum::SessionImport(t) => t.schema(), + McpToolEnum::WorkflowList(t) => t.schema(), + McpToolEnum::WorkflowRun(t) => t.schema(), + McpToolEnum::WorkflowStatus(t) => t.schema(), + McpToolEnum::OplogQuery(t) => t.schema(), + McpToolEnum::Evaluate(t) => t.schema(), + McpToolEnum::DocumentConvert(t) => t.schema(), + McpToolEnum::OntologyImport(t) => t.schema(), + } + } + + async fn invoke( + &self, + args: serde_json::Value, + ctx: &mut crate::storage::AppContext, + ) -> anyhow::Result { + match self { + McpToolEnum::Scan(t) => t.invoke(args, ctx).await, + McpToolEnum::Health(t) => t.invoke(args, ctx).await, + McpToolEnum::Sync(t) => t.invoke(args, ctx).await, + McpToolEnum::Query(t) => t.invoke(args, ctx).await, + McpToolEnum::QueryRepos(t) => t.invoke(args, ctx).await, + McpToolEnum::Index(t) => t.invoke(args, ctx).await, + McpToolEnum::IndexHealth(t) => t.invoke(args, ctx).await, + McpToolEnum::IndexStream(t) => t.invoke(args, ctx).await, + McpToolEnum::Status(t) => t.invoke(args, ctx).await, + McpToolEnum::Note(t) => t.invoke(args, ctx).await, + McpToolEnum::Digest(t) => t.invoke(args, ctx).await, + McpToolEnum::Paper(t) => t.invoke(args, ctx).await, + McpToolEnum::Experiment(t) => t.invoke(args, ctx).await, + McpToolEnum::GithubInfo(t) => t.invoke(args, ctx).await, + McpToolEnum::CodeMetrics(t) => t.invoke(args, ctx).await, + McpToolEnum::ModuleGraph(t) => t.invoke(args, ctx).await, + McpToolEnum::NaturalLanguageQuery(t) => t.invoke(args, ctx).await, + McpToolEnum::VaultSearch(t) => t.invoke(args, ctx).await, + McpToolEnum::VaultRead(t) => t.invoke(args, ctx).await, + McpToolEnum::VaultWrite(t) => t.invoke(args, ctx).await, + McpToolEnum::VaultBacklinks(t) => t.invoke(args, ctx).await, + McpToolEnum::VaultDaily(t) => t.invoke(args, ctx).await, + McpToolEnum::VaultGraph(t) => t.invoke(args, ctx).await, + McpToolEnum::VaultExport(t) => t.invoke(args, ctx).await, + McpToolEnum::VaultHistory(t) => t.invoke(args, ctx).await, + McpToolEnum::ProjectContext(t) => t.invoke(args, ctx).await, + McpToolEnum::ProjectBrief(t) => t.invoke(args, ctx).await, + McpToolEnum::ImpactAnalysis(t) => t.invoke(args, ctx).await, + McpToolEnum::CodeSymbols(t) => t.invoke(args, ctx).await, + McpToolEnum::DependencyGraph(t) => t.invoke(args, ctx).await, + McpToolEnum::CallGraph(t) => t.invoke(args, ctx).await, + McpToolEnum::DeadCode(t) => t.invoke(args, ctx).await, + McpToolEnum::SemanticSearch(t) => t.invoke(args, ctx).await, + McpToolEnum::ArxivFetch(t) => t.invoke(args, ctx).await, + McpToolEnum::EmbeddingStore(t) => t.invoke(args, ctx).await, + McpToolEnum::EmbeddingSearch(t) => t.invoke(args, ctx).await, + McpToolEnum::CrossRepoSearch(t) => t.invoke(args, ctx).await, + McpToolEnum::KnowledgeReport(t) => t.invoke(args, ctx).await, + McpToolEnum::RelatedSymbols(t) => t.invoke(args, ctx).await, + McpToolEnum::HybridSearch(t) => t.invoke(args, ctx).await, + McpToolEnum::SearchQuality(t) => t.invoke(args, ctx).await, + McpToolEnum::SkillList(t) => t.invoke(args, ctx).await, + McpToolEnum::SkillSearch(t) => t.invoke(args, ctx).await, + McpToolEnum::SkillRun(t) => t.invoke(args, ctx).await, + McpToolEnum::SkillDiscover(t) => t.invoke(args, ctx).await, + McpToolEnum::SkillSync(t) => t.invoke(args, ctx).await, + McpToolEnum::KnownLimitStore(t) => t.invoke(args, ctx).await, + McpToolEnum::KnownLimitList(t) => t.invoke(args, ctx).await, + McpToolEnum::RelationStore(t) => t.invoke(args, ctx).await, + McpToolEnum::RelationQuery(t) => t.invoke(args, ctx).await, + McpToolEnum::RelationDelete(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionSave(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionList(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionResume(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionAttach(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionDetach(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionActivate(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionSearch(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionCapture(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionWorkflows(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionRecall(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionIndex(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionExport(t) => t.invoke(args, ctx).await, + McpToolEnum::SessionImport(t) => t.invoke(args, ctx).await, + McpToolEnum::WorkflowList(t) => t.invoke(args, ctx).await, + McpToolEnum::WorkflowRun(t) => t.invoke(args, ctx).await, + McpToolEnum::WorkflowStatus(t) => t.invoke(args, ctx).await, + McpToolEnum::OplogQuery(t) => t.invoke(args, ctx).await, + McpToolEnum::Evaluate(t) => t.invoke(args, ctx).await, + McpToolEnum::DocumentConvert(t) => t.invoke(args, ctx).await, + McpToolEnum::OntologyImport(t) => t.invoke(args, ctx).await, + } + } +} + +/// Long-lived oplog file handle — opened once, reused across all MCP calls. +static OPLOG_FILE: std::sync::OnceLock>> = + std::sync::OnceLock::new(); + +fn get_oplog_file() -> &'static std::sync::Mutex> { + OPLOG_FILE.get_or_init(|| { + let file = dirs::data_local_dir().and_then(|data_dir| { + let log_path = data_dir.join("devbase").join("mcp-oplog.ndjson"); + std::fs::OpenOptions::new().create(true).append(true).open(&log_path).ok() + }); + std::sync::Mutex::new(file) + }) +} + +/// Append a single MCP tool invocation record to the oplog file. +/// +/// Path: `%LOCALAPPDATA%/devbase/mcp-oplog.ndjson` +/// Format: newline-delimited JSON (NDJSON) +fn append_mcp_oplog(tool_name: &str, duration_ms: u128, success: bool, error_type: Option<&str>) { + let entry = serde_json::json!({ + "timestamp": chrono::Utc::now().to_rfc3339(), + "tool": tool_name, + "duration_ms": duration_ms, + "success": success, + "error_type": error_type, + }); + + if let Ok(mut guard) = get_oplog_file().lock() { + if let Some(ref mut file) = *guard { + use std::io::Write; + if let Err(e) = writeln!(file, "{}", entry) { + tracing::warn!("Failed to write MCP oplog: {}", e); + } + } + } +} + +pub struct McpServer { + tools: HashMap, +} + +impl Default for McpServer { + fn default() -> Self { + Self::new() + } +} + +impl McpServer { + pub fn new() -> Self { + Self { tools: HashMap::new() } + } + + pub fn register_tool(&mut self, tool: McpToolEnum) { + self.tools.insert(tool.name().to_string(), tool); + } + + pub async fn handle_request( + &self, + req: serde_json::Value, + ctx: &mut crate::storage::AppContext, + ) -> anyhow::Result { + let id = req.get("id").cloned().unwrap_or(serde_json::Value::Null); + let method = req.get("method").and_then(|v| v.as_str()).unwrap_or(""); + + match method { + "ping" => Ok(serde_json::json!({ + "jsonrpc": "2.0", + "id": id, + "result": {} + })), + "initialize" => { + // Verify client protocol version for compatibility + let client_version = req + .get("params") + .and_then(|p| p.get("protocolVersion")) + .and_then(|v| v.as_str()) + .unwrap_or("unknown"); + let supported = ["2024-11-05"]; + if !supported.contains(&client_version) { + tracing::warn!( + "Client protocol version '{}' not in supported list {:?}; proceeding with 2024-11-05", + client_version, + supported + ); + } + Ok(serde_json::json!({ + "jsonrpc": "2.0", + "id": id, + "result": { + "protocolVersion": "2024-11-05", + "capabilities": { + "tools": {} + }, + "serverInfo": { + "name": "devbase", + "version": env!("CARGO_PKG_VERSION") + } + } + })) + } + "tools/list" => { + let tools: Vec = self + .tools + .values() + .map(|t| { + let schema = t.schema(); + serde_json::json!({ + "name": t.name(), + "description": schema.get("description").and_then(|v| v.as_str()).unwrap_or(""), + "inputSchema": schema.get("inputSchema").cloned().unwrap_or(serde_json::json!({})) + }) + }) + .collect(); + Ok(serde_json::json!({ + "jsonrpc": "2.0", + "id": id, + "result": { "tools": tools } + })) + } + "tools/call" => { + let params = req.get("params").cloned().unwrap_or(serde_json::Value::Null); + let name = params.get("name").and_then(|v| v.as_str()).unwrap_or(""); + let args = params.get("arguments").cloned().unwrap_or(serde_json::Value::Null); + let stream = params.get("stream").and_then(|v| v.as_bool()).unwrap_or(false); + + match self.tools.get(name) { + Some(_tool) if stream => { + let start = std::time::Instant::now(); + match self.handle_streaming_call(name, args, ctx).await { + Ok(events) => { + append_mcp_oplog(name, start.elapsed().as_millis(), true, None); + let events_json = serde_json::to_string(&events)?; + let content = serde_json::json!({ + "type": "text", + "text": events_json + }); + Ok(serde_json::json!({ + "jsonrpc": "2.0", + "id": id, + "result": { + "content": [content], + "isError": false + } + })) + } + Err(e) => { + append_mcp_oplog( + name, + start.elapsed().as_millis(), + false, + Some("invoke_error"), + ); + let payload = + serde_json::json!({ "success": false, "error": e.to_string() }); + let text = serde_json::to_string(&payload)?; + let content = serde_json::json!({ "type": "text", "text": text }); + Ok(serde_json::json!({ + "jsonrpc": "2.0", + "id": id, + "result": { + "content": [content], + "isError": true + } + })) + } + } + } + Some(tool) => { + let start = std::time::Instant::now(); + match tool.invoke(args, ctx).await { + Ok(result) => { + let text = result.to_string(); + let is_error = !result + .get("success") + .and_then(|v: &serde_json::Value| v.as_bool()) + .unwrap_or(true); + append_mcp_oplog( + name, + start.elapsed().as_millis(), + !is_error, + None, + ); + let content = serde_json::json!({ + "type": "text", + "text": text + }); + Ok(serde_json::json!({ + "jsonrpc": "2.0", + "id": id, + "result": { + "content": [content], + "isError": is_error + } + })) + } + Err(e) => { + append_mcp_oplog( + name, + start.elapsed().as_millis(), + false, + Some("invoke_error"), + ); + let payload = + serde_json::json!({ "success": false, "error": e.to_string() }); + let text = serde_json::to_string(&payload)?; + let content = serde_json::json!({ "type": "text", "text": text }); + Ok(serde_json::json!({ + "jsonrpc": "2.0", + "id": id, + "result": { + "content": [content], + "isError": true + } + })) + } + } + } + None => Ok(serde_json::json!({ + "jsonrpc": "2.0", + "id": id, + "error": { + "code": -32602, + "message": format!("Tool '{}' not found", name) + } + })), + } + } + _ => { + if id.is_null() { + // Workaround: Python MCP SDK 1.16.0 cannot parse JSON-RPC + // error responses with `id: null`. Return Null so the + // caller can silently drop it. + return Ok(serde_json::Value::Null); + } + Ok(serde_json::json!({ + "jsonrpc": "2.0", + "id": id, + "error": { + "code": -32601, + "message": format!("Method '{}' not found", method) + } + })) + } + } + } + + /// Invoke a tool in streaming mode and return a sequence of events. + /// + /// This is used by the SSE transport to push progressive updates. + /// If the tool does not override `invoke_stream`, the default implementation + /// delegates to `invoke` and wraps the result as a single `Done` event. + pub async fn handle_streaming_call( + &self, + name: &str, + args: serde_json::Value, + ctx: &mut crate::storage::AppContext, + ) -> anyhow::Result> { + match self.tools.get(name) { + Some(tool) => tool.invoke_stream(args, ctx).await, + None => Err(anyhow::anyhow!("Tool '{}' not found", name)), + } + } +} + +/// Build an MCP server with optional tier filtering. +/// +/// If `tiers` is `None`, all 69 tools are registered (backward compatible). +/// If `tiers` is provided, only tools whose tier is in the set are registered. +pub fn build_server_with_tiers(tiers: Option<&HashSet>) -> McpServer { + let mut server = McpServer::new(); + let all_tools = [ + McpToolEnum::Scan(DevkitScanTool), + McpToolEnum::Health(DevkitHealthTool), + McpToolEnum::Sync(DevkitSyncTool), + McpToolEnum::Query(DevkitQueryTool), + McpToolEnum::QueryRepos(DevkitQueryReposTool), + McpToolEnum::Index(DevkitIndexTool), + McpToolEnum::IndexHealth(DevkitIndexHealthTool), + McpToolEnum::IndexStream(DevkitIndexStreamTool), + McpToolEnum::Status(DevkitStatusTool), + McpToolEnum::Note(DevkitNoteTool), + McpToolEnum::Digest(DevkitDigestTool), + McpToolEnum::Paper(DevkitPaperIndexTool), + McpToolEnum::Experiment(DevkitExperimentLogTool), + McpToolEnum::GithubInfo(DevkitGithubInfoTool), + McpToolEnum::CodeMetrics(DevkitCodeMetricsTool), + McpToolEnum::ModuleGraph(DevkitModuleGraphTool), + McpToolEnum::NaturalLanguageQuery(DevkitNaturalLanguageQueryTool), + McpToolEnum::VaultSearch(DevkitVaultSearchTool), + McpToolEnum::VaultRead(DevkitVaultReadTool), + McpToolEnum::VaultWrite(DevkitVaultWriteTool), + McpToolEnum::VaultBacklinks(DevkitVaultBacklinksTool), + McpToolEnum::VaultDaily(DevkitVaultDailyTool), + McpToolEnum::VaultGraph(DevkitVaultGraphTool), + McpToolEnum::VaultExport(DevkitVaultExportTool), + McpToolEnum::VaultHistory(DevkitVaultHistoryTool), + McpToolEnum::ProjectContext(DevkitProjectContextTool), + McpToolEnum::ProjectBrief(DevkitProjectBriefTool), + McpToolEnum::ImpactAnalysis(DevkitImpactAnalysisTool), + McpToolEnum::CodeSymbols(DevkitCodeSymbolsTool), + McpToolEnum::DependencyGraph(DevkitDependencyGraphTool), + McpToolEnum::CallGraph(DevkitCallGraphTool), + McpToolEnum::DeadCode(DevkitDeadCodeTool), + McpToolEnum::SemanticSearch(DevkitSemanticSearchTool), + McpToolEnum::ArxivFetch(DevkitArxivFetchTool), + McpToolEnum::EmbeddingStore(DevkitEmbeddingStoreTool), + McpToolEnum::EmbeddingSearch(DevkitEmbeddingSearchTool), + McpToolEnum::CrossRepoSearch(DevkitCrossRepoSearchTool), + McpToolEnum::KnowledgeReport(DevkitKnowledgeReportTool), + McpToolEnum::RelatedSymbols(DevkitRelatedSymbolsTool), + McpToolEnum::HybridSearch(DevkitHybridSearchTool), + McpToolEnum::SearchQuality(DevkitSearchQualityTool), + McpToolEnum::SkillList(DevkitSkillListTool), + McpToolEnum::SkillSearch(DevkitSkillSearchTool), + McpToolEnum::SkillRun(DevkitSkillRunTool), + McpToolEnum::SkillDiscover(DevkitSkillDiscoverTool), + McpToolEnum::SkillSync(DevkitSkillSyncTool), + McpToolEnum::KnownLimitStore(DevkitKnownLimitStoreTool), + McpToolEnum::KnownLimitList(DevkitKnownLimitListTool), + McpToolEnum::RelationStore(DevkitRelationStoreTool), + McpToolEnum::RelationQuery(DevkitRelationQueryTool), + McpToolEnum::RelationDelete(DevkitRelationDeleteTool), + McpToolEnum::SessionSave(DevkitSessionSaveTool), + McpToolEnum::SessionList(DevkitSessionListTool), + McpToolEnum::SessionResume(DevkitSessionResumeTool), + McpToolEnum::SessionAttach(DevkitSessionAttachTool), + McpToolEnum::SessionDetach(DevkitSessionDetachTool), + McpToolEnum::SessionActivate(DevkitSessionActivateTool), + McpToolEnum::SessionSearch(DevkitSessionSearchTool), + McpToolEnum::SessionCapture(DevkitSessionCaptureTool), + McpToolEnum::SessionWorkflows(DevkitSessionWorkflowsTool), + McpToolEnum::SessionRecall(DevkitSessionRecallTool), + McpToolEnum::SessionIndex(DevkitSessionIndexTool), + McpToolEnum::SessionExport(DevkitSessionExportTool), + McpToolEnum::SessionImport(DevkitSessionImportTool), + McpToolEnum::WorkflowList(DevkitWorkflowListTool), + McpToolEnum::WorkflowRun(DevkitWorkflowRunTool), + McpToolEnum::WorkflowStatus(DevkitWorkflowStatusTool), + McpToolEnum::OplogQuery(DevkitOplogQueryTool), + McpToolEnum::Evaluate(DevkitEvaluateTool), + McpToolEnum::DocumentConvert(DevkitDocumentConvertTool), + McpToolEnum::OntologyImport(DevkitOntologyImportTool), + ]; + for tool in all_tools { + if let Some(allowed) = tiers + && !allowed.contains(&tool.tier()) + { + continue; + } + server.register_tool(tool); + } + server +} + +/// Build an MCP server with all tools (backward compatible). +pub fn build_server() -> McpServer { + build_server_with_tiers(None) +} + +pub fn format_mcp_message(body: &serde_json::Value) -> String { + format_mcp_message_auto(body, false) +} + +/// Format MCP message with optional NDJSON mode (no Content-Length headers). +/// NDJSON mode outputs raw JSON followed by a newline, for clients that +/// expect line-delimited JSON-RPC over stdio. +pub fn format_mcp_message_auto(body: &serde_json::Value, ndjson: bool) -> String { + let body_str = body.to_string(); + if ndjson { + format!("{}\n", body_str) + } else { + format!("Content-Length: {}\r\n\r\n{}", body_str.len(), body_str) + } +} + +/// Check whether destructive MCP tools are enabled via environment variable. +/// Returns Ok(()) if enabled, or an error with a clear message if disabled. +pub(crate) fn check_destructive_enabled() -> anyhow::Result<()> { + let enabled = std::env::var("DEVBASE_MCP_ENABLE_DESTRUCTIVE") + .map(|v| v == "1" || v.eq_ignore_ascii_case("true")) + .unwrap_or(false); + if !enabled { + anyhow::bail!( + "Destructive tools are disabled. \ + Set DEVBASE_MCP_ENABLE_DESTRUCTIVE=1 to enable." + ); + } + Ok(()) +} + +/// Parse tool tiers from a comma-separated string (e.g. "stable,beta"). +fn parse_tool_tiers(s: &str) -> HashSet { + s.split(',') + .map(|t| t.trim()) + .filter(|t| !t.is_empty()) + .filter_map(|s| s.parse().ok()) + .collect() +} + +pub async fn run_stdio() -> anyhow::Result<()> { + let mut ctx = crate::storage::AppContext::with_defaults()?; + let tiers: Option> = std::env::var("DEVBASE_MCP_TOOL_TIERS") + .ok() + .map(|s| parse_tool_tiers(&s)) + .filter(|set| !set.is_empty()); + let server = build_server_with_tiers(tiers.as_ref()); + let stdin = tokio::io::stdin(); + let mut stdout = tokio::io::stdout(); + let mut reader = BufReader::new(stdin); + let mut line_buf = String::new(); + let mut use_ndjson = false; + + loop { + line_buf.clear(); + // Read header line to get Content-Length + let n = reader.read_line(&mut line_buf).await?; + if n == 0 { + break; // EOF + } + let line = line_buf.trim(); + if line.is_empty() { + continue; + } + + let content_length = if line.starts_with("Content-Length: ") { + line.strip_prefix("Content-Length: ").and_then(|v| v.parse::().ok()) + } else { + // Client is using NDJSON (raw JSON lines). Switch to NDJSON output. + use_ndjson = true; + // Fallback: parse raw JSON line for backward compatibility + let req: serde_json::Value = match serde_json::from_str(line) { + Ok(v) => v, + Err(e) => { + let resp = serde_json::json!({ + "jsonrpc": "2.0", + "id": null, + "error": { + "code": -32700, + "message": format!("Parse error: {}", e) + } + }); + let msg = format_mcp_message_auto(&resp, use_ndjson); + if stdout.write_all(msg.as_bytes()).await.is_err() + || stdout.flush().await.is_err() + { + break; + } + continue; + } + }; + let resp = server.handle_request(req, &mut ctx).await.unwrap_or_else(|e| { + serde_json::json!({ + "jsonrpc": "2.0", + "id": null, + "error": { + "code": -32603, + "message": format!("Internal error: {}", e) + } + }) + }); + if !resp.is_null() { + let msg = format_mcp_message_auto(&resp, use_ndjson); + if stdout.write_all(msg.as_bytes()).await.is_err() || stdout.flush().await.is_err() + { + break; + } + } + continue; + }; + + let content_length = match content_length { + Some(len) => len, + None => { + let resp = serde_json::json!({ + "jsonrpc": "2.0", + "id": null, + "error": { + "code": -32700, + "message": format!("Invalid Content-Length header: {}", line) + } + }); + let msg = format_mcp_message_auto(&resp, use_ndjson); + if stdout.write_all(msg.as_bytes()).await.is_err() || stdout.flush().await.is_err() + { + break; + } + continue; + } + }; + + // Read the empty line (\r\n or \n) + line_buf.clear(); + let _ = reader.read_line(&mut line_buf).await; + + // Read the exact number of bytes + let mut body_buf = vec![0u8; content_length]; + if let Err(e) = reader.read_exact(&mut body_buf).await { + let resp = serde_json::json!({ + "jsonrpc": "2.0", + "id": null, + "error": { + "code": -32700, + "message": format!("Failed to read request body: {}", e) + } + }); + let msg = format_mcp_message_auto(&resp, use_ndjson); + if stdout.write_all(msg.as_bytes()).await.is_err() || stdout.flush().await.is_err() { + break; + } + continue; + } + + let req: serde_json::Value = match String::from_utf8(body_buf) { + Ok(body) => match serde_json::from_str(&body) { + Ok(v) => v, + Err(e) => { + let resp = serde_json::json!({ + "jsonrpc": "2.0", + "id": null, + "error": { + "code": -32700, + "message": format!("Parse error: {}", e) + } + }); + let msg = format_mcp_message_auto(&resp, use_ndjson); + if stdout.write_all(msg.as_bytes()).await.is_err() + || stdout.flush().await.is_err() + { + break; // broken pipe + } + continue; + } + }, + Err(e) => { + let resp = serde_json::json!({ + "jsonrpc": "2.0", + "id": null, + "error": { + "code": -32700, + "message": format!("Invalid UTF-8: {}", e) + } + }); + let msg = format_mcp_message_auto(&resp, use_ndjson); + if stdout.write_all(msg.as_bytes()).await.is_err() || stdout.flush().await.is_err() + { + break; // broken pipe + } + continue; + } + }; + + // Notifications have no "id" field and require no response. + let is_notification = req.get("id").is_none(); + if is_notification { + // Silently acknowledge all notifications (not just notifications/*). + continue; + } + + let resp = server.handle_request(req, &mut ctx).await.unwrap_or_else(|e| { + serde_json::json!({ + "jsonrpc": "2.0", + "id": null, + "error": { + "code": -32603, + "message": format!("Internal error: {}", e) + } + }) + }); + + if !resp.is_null() { + let msg = format_mcp_message_auto(&resp, use_ndjson); + if stdout.write_all(msg.as_bytes()).await.is_err() || stdout.flush().await.is_err() { + break; // broken pipe + } + } + } + + Ok(()) +} + +pub use crate::clients::*; +#[cfg(test)] +pub mod tests; +pub mod tools; diff --git a/src/mcp/tests.rs b/src/mcp/tests.rs index 653463b..defd275 100644 --- a/src/mcp/tests.rs +++ b/src/mcp/tests.rs @@ -1,981 +1,982 @@ -// SPDX-License-Identifier: MIT -// Copyright (c) 2026 juice094 -use super::*; -use crate::storage::StorageBackend; - -fn test_ctx() -> (crate::storage::AppContext, tempfile::TempDir) { - let backend = std::sync::Arc::new(crate::storage::TempStorageBackend::new()); - let ctx = crate::storage::AppContext::with_storage(backend).unwrap(); - // Return a dummy TempDir to keep call-site destructuring compatible. - let tmp = tempfile::tempdir().unwrap(); - (ctx, tmp) -} - -/// Lightweight helper: seed a single repo into the entities table. -fn seed_repo(ctx: &crate::storage::AppContext, id: &str, lang: &str) { - let conn = ctx.conn().unwrap(); - let now = chrono::Utc::now().to_rfc3339(); - conn.execute( - "INSERT INTO entities (id, entity_type, name, local_path, metadata, created_at, updated_at, language, discovered_at, workspace_type, data_tier, stars) - VALUES (?1, 'repo', ?2, ?3, ?4, ?5, ?5, ?6, ?5, 'git', 'private', 0)", - rusqlite::params![id, id, format!("/tmp/{}", id), "{}", &now, lang], - ).unwrap(); -} - -#[tokio::test] -async fn test_initialize() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 1, - "method": "initialize" - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - assert_eq!(resp.get("jsonrpc").unwrap(), "2.0"); - let result = resp.get("result").unwrap(); - assert_eq!(result.get("protocolVersion").unwrap(), "2024-11-05"); - assert_eq!(result.get("serverInfo").unwrap().get("name").unwrap(), "devbase"); - assert!(result.get("capabilities").unwrap().get("tools").is_some()); -} - -#[tokio::test] -async fn test_tools_list() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 2, - "method": "tools/list" - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let tools = resp.get("result").unwrap().get("tools").unwrap().as_array().unwrap(); - assert_eq!(tools.len(), 69); - let names: Vec<&str> = tools.iter().map(|t| t.get("name").unwrap().as_str().unwrap()).collect(); - assert!(names.contains(&"devkit_index_health")); - assert!(names.contains(&"devkit_vault_export")); - assert!(names.contains(&"devkit_vault_history")); - assert!(names.contains(&"devkit_search_quality")); - assert!(names.contains(&"devkit_session_save")); - assert!(names.contains(&"devkit_session_list")); - assert!(names.contains(&"devkit_session_resume")); - assert!(names.contains(&"devkit_session_recall")); - assert!(names.contains(&"devkit_session_index")); - assert!(names.contains(&"devkit_session_export")); - assert!(names.contains(&"devkit_session_import")); - assert!(names.contains(&"devkit_evaluate")); - assert!(names.contains(&"devkit_document_convert")); - assert!(names.contains(&"devkit_scan")); - assert!(names.contains(&"devkit_health")); - assert!(names.contains(&"devkit_sync")); - assert!(names.contains(&"devkit_query")); - assert!(names.contains(&"devkit_query_repos")); - assert!(names.contains(&"devkit_index")); - assert!(names.contains(&"devkit_index_stream")); - assert!(names.contains(&"devkit_status")); - assert!(names.contains(&"devkit_note")); - assert!(names.contains(&"devkit_digest")); - assert!(names.contains(&"devkit_paper_index")); - assert!(names.contains(&"devkit_experiment_log")); - assert!(names.contains(&"devkit_github_info")); - assert!(names.contains(&"devkit_code_metrics")); - assert!(names.contains(&"devkit_module_graph")); - assert!(names.contains(&"devkit_code_symbols")); - assert!(names.contains(&"devkit_dependency_graph")); - assert!(names.contains(&"devkit_call_graph")); - assert!(names.contains(&"devkit_dead_code")); - assert!(names.contains(&"devkit_semantic_search")); - assert!(names.contains(&"devkit_embedding_store")); - assert!(names.contains(&"devkit_embedding_search")); - assert!(names.contains(&"devkit_natural_language_query")); - assert!(names.contains(&"devkit_vault_search")); - assert!(names.contains(&"devkit_vault_read")); - assert!(names.contains(&"devkit_vault_write")); - assert!(names.contains(&"devkit_vault_backlinks")); - assert!(names.contains(&"devkit_vault_daily")); - assert!(names.contains(&"devkit_vault_graph")); - assert!(names.contains(&"devkit_project_context")); - assert!(names.contains(&"devkit_project_brief")); - assert!(names.contains(&"devkit_impact_analysis")); - assert!(names.contains(&"devkit_cross_repo_search")); - assert!(names.contains(&"devkit_knowledge_report")); - assert!(names.contains(&"devkit_related_symbols")); - assert!(names.contains(&"devkit_hybrid_search")); - assert!(names.contains(&"devkit_skill_list")); - assert!(names.contains(&"devkit_skill_search")); - assert!(names.contains(&"devkit_skill_run")); - assert!(names.contains(&"devkit_skill_discover")); - assert!(names.contains(&"devkit_known_limit_store")); - assert!(names.contains(&"devkit_known_limit_list")); - assert!(names.contains(&"devkit_relation_store")); - assert!(names.contains(&"devkit_relation_query")); - assert!(names.contains(&"devkit_relation_delete")); - assert!(names.contains(&"devkit_workflow_list")); - assert!(names.contains(&"devkit_workflow_run")); - assert!(names.contains(&"devkit_workflow_status")); - for tool in tools { - assert!(tool.get("name").is_some()); - assert!(tool.get("description").is_some()); - assert!(tool.get("inputSchema").is_some()); - } -} - -#[tokio::test] -async fn test_tools_call_devkit_health() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 3, - "method": "tools/call", - "params": { - "name": "devkit_health", - "arguments": { "detail": false } - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - if parsed.get("success").unwrap() != &serde_json::Value::Bool(true) { - eprintln!( - "devkit_health returned error: {}", - serde_json::to_string_pretty(&parsed).unwrap() - ); - } - assert_eq!(parsed.get("success").unwrap(), true); - let summary = parsed.get("summary").unwrap(); - assert!(summary.get("total_repos").unwrap().as_i64().unwrap() >= 0); -} - -#[tokio::test] -async fn test_tools_call_devkit_query() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 4, - "method": "tools/call", - "params": { - "name": "devkit_query", - "arguments": { "expression": "lang:rust" } - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - assert!(parsed.get("count").unwrap().as_i64().unwrap() >= 0); -} - -#[tokio::test] -async fn test_tools_call_unknown_tool() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 5, - "method": "tools/call", - "params": { - "name": "unknown_tool", - "arguments": {} - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - assert!(resp.get("error").is_some()); - let error = resp.get("error").unwrap(); - assert_eq!(error.get("code").unwrap().as_i64().unwrap(), -32602); -} - -#[tokio::test] -async fn test_unknown_method() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 6, - "method": "unknown/method" - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - assert!(resp.get("error").is_some()); - let error = resp.get("error").unwrap(); - assert_eq!(error.get("code").unwrap().as_i64().unwrap(), -32601); -} - -#[tokio::test] -async fn test_tools_call_devkit_project_context() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 7, - "method": "tools/call", - "params": { - "name": "devkit_project_context", - "arguments": { "project": "nonexistent-project-xyz" } - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - assert_eq!(result.get("content").unwrap().as_array().unwrap().len(), 1); - let text = result["content"][0]["text"].as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - assert!(parsed.get("repo").unwrap().is_null()); - assert!(parsed.get("vault_notes").unwrap().as_array().unwrap().is_empty()); - assert!(parsed.get("assets").unwrap().as_array().unwrap().is_empty()); -} - -#[tokio::test] -async fn test_tools_call_devkit_query_repos() { - let server = build_server(); - let (mut ctx, _tmp) = test_ctx(); - - // 1. Empty registry returns empty results - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 10, - "method": "tools/call", - "params": { - "name": "devkit_query_repos", - "arguments": { "language": "" } - } - }); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - assert_eq!(parsed.get("count").unwrap().as_i64().unwrap(), 0); - - // 2. Seeded repo is returned with correct filtering - seed_repo(&ctx, "test-repo", "rust"); - let req2 = serde_json::json!({ - "jsonrpc": "2.0", - "id": 11, - "method": "tools/call", - "params": { - "name": "devkit_query_repos", - "arguments": { "language": "rust" } - } - }); - let resp2 = server.handle_request(req2, &mut ctx).await.unwrap(); - let result2 = resp2.get("result").unwrap(); - let content2 = result2.get("content").unwrap().as_array().unwrap(); - let text2 = content2[0].get("text").unwrap().as_str().unwrap(); - let parsed2: serde_json::Value = serde_json::from_str(text2).unwrap(); - assert_eq!(parsed2.get("success").unwrap(), true); - let repos = parsed2.get("repos").unwrap().as_array().unwrap(); - assert_eq!(repos.len(), 1); - assert_eq!(repos[0].get("id").unwrap().as_str().unwrap(), "test-repo"); - assert_eq!(repos[0].get("language").unwrap().as_str().unwrap(), "rust"); -} - -#[tokio::test] -async fn test_tools_call_devkit_vault_search() { - let server = build_server(); - let (mut ctx, _tmp) = test_ctx(); - - // Setup: create vault note and scan - let ws = ctx.storage.workspace_dir().unwrap(); - let vault_dir = ws.join("vault"); - std::fs::create_dir_all(&vault_dir).unwrap(); - std::fs::write( - vault_dir.join("test-note.md"), - "---\ntitle: Test Note\ntags: [test, vault]\n---\n\nThis is a test note for vault search.\n", - ).unwrap(); - let mut conn = ctx.conn().unwrap(); - crate::vault::scanner::scan_vault(&mut conn, Some(&vault_dir)).unwrap(); - - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 12, - "method": "tools/call", - "params": { - "name": "devkit_vault_search", - "arguments": { "query": "test note" } - } - }); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - let notes = parsed.get("notes").unwrap().as_array().unwrap(); - assert!(!notes.is_empty(), "vault_search should find the test-note"); - assert!( - notes - .iter() - .any(|n| n.get("title").and_then(|v| v.as_str()) == Some("Test Note")), - "vault_search should return Test Note" - ); -} - -#[tokio::test] -async fn test_tools_call_devkit_vault_read() { - let server = build_server(); - let (mut ctx, _tmp) = test_ctx(); - - // Setup: create vault note and scan - let ws = ctx.storage.workspace_dir().unwrap(); - let vault_dir = ws.join("vault"); - std::fs::create_dir_all(&vault_dir).unwrap(); - let note_path = vault_dir.join("test-read.md"); - std::fs::write( - ¬e_path, - "---\ntitle: Readable Note\ntags: [read]\n---\n\nContent body here.\n", - ) - .unwrap(); - let mut conn = ctx.conn().unwrap(); - crate::vault::scanner::scan_vault(&mut conn, Some(&vault_dir)).unwrap(); - - // 1. Read existing note by absolute path - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 13, - "method": "tools/call", - "params": { - "name": "devkit_vault_read", - "arguments": { "path": note_path.to_str().unwrap() } - } - }); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - assert_eq!(parsed.get("path").unwrap().as_str().unwrap(), note_path.to_str().unwrap()); - let frontmatter = parsed.get("frontmatter").unwrap().as_str().unwrap(); - assert!(frontmatter.contains("title: Readable Note")); - let body = parsed.get("content").unwrap().as_str().unwrap(); - assert!(body.contains("Content body here.")); - - // 2. Read non-existent note returns error - let req2 = serde_json::json!({ - "jsonrpc": "2.0", - "id": 14, - "method": "tools/call", - "params": { - "name": "devkit_vault_read", - "arguments": { "path": "/nonexistent/path/note.md" } - } - }); - let resp2 = server.handle_request(req2, &mut ctx).await.unwrap(); - let result2 = resp2.get("result").unwrap(); - assert_eq!(result2.get("isError").unwrap(), true); - let content2 = result2.get("content").unwrap().as_array().unwrap(); - let text2 = content2[0].get("text").unwrap().as_str().unwrap(); - let parsed2: serde_json::Value = serde_json::from_str(text2).unwrap(); - assert_eq!(parsed2.get("success").unwrap(), false); - assert!( - parsed2.get("error").unwrap().as_str().unwrap().contains("not found") - || parsed2.get("error").unwrap().as_str().unwrap().contains("unreadable") - ); -} - -#[tokio::test] -async fn test_tools_call_devkit_arxiv_fetch() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 8, - "method": "tools/call", - "params": { - "name": "devkit_arxiv_fetch", - "arguments": { "arxiv_id": "" } - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - // Empty arxiv_id should result in an error from the arXiv API or parser - assert_eq!(parsed.get("success").unwrap(), false); - assert!(!parsed.get("error").unwrap().as_str().unwrap().is_empty()); -} - -#[tokio::test] -async fn test_tools_call_devkit_status() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 15, - "method": "tools/call", - "params": { - "name": "devkit_status", - "arguments": {} - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - // Empty registry → overall "fresh" (vacuous truth: all 0 repos are fresh) - assert_eq!(parsed.get("overall").unwrap().as_str().unwrap(), "fresh"); - let repos = parsed.get("repos").unwrap().as_array().unwrap(); - assert!(repos.is_empty()); -} - -#[tokio::test] -async fn test_tools_call_devkit_workflow_list() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 16, - "method": "tools/call", - "params": { - "name": "devkit_workflow_list", - "arguments": {} - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - assert_eq!(parsed.get("count").unwrap().as_i64().unwrap(), 0); - let workflows = parsed.get("workflows").unwrap().as_array().unwrap(); - assert!(workflows.is_empty()); -} - -#[tokio::test] -async fn test_tools_call_devkit_index() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 17, - "method": "tools/call", - "params": { - "name": "devkit_index", - "arguments": { "path": "" } - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - // Empty registry → indexed 0 repos - assert_eq!(parsed.get("indexed").unwrap().as_i64().unwrap(), 0); -} - -#[tokio::test] -async fn test_tools_call_devkit_skill_list() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 9, - "method": "tools/call", - "params": { - "name": "devkit_skill_list", - "arguments": {} - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - assert!(parsed.get("skills").unwrap().is_array()); - assert!(parsed.get("count").unwrap().as_i64().unwrap() >= 0); -} - -#[tokio::test] -async fn test_tools_call_devkit_skill_search() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 10, - "method": "tools/call", - "params": { - "name": "devkit_skill_search", - "arguments": { "query": "report" } - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - assert!(parsed.get("skills").unwrap().is_array()); - assert!(parsed.get("count").unwrap().as_i64().unwrap() >= 0); -} - -#[tokio::test] -async fn test_tools_call_devkit_skill_discover() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 11, - "method": "tools/call", - "params": { - "name": "devkit_skill_discover", - "arguments": { - "path": ".", - "skill_id": "mcp-test-discover", - "dry_run": true - } - } - }); - // SAFETY: test-only env var mutation; test runner guarantees no concurrent - // reads of DEVBASE_MCP_ENABLE_DESTRUCTIVE in this process. - unsafe { - std::env::set_var("DEVBASE_MCP_ENABLE_DESTRUCTIVE", "1"); - } - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - assert!(!parsed.get("id").unwrap().as_str().unwrap().is_empty()); - assert!(!parsed.get("name").unwrap().as_str().unwrap().is_empty()); - assert!(parsed.get("version").unwrap().as_str().is_some()); - assert!(parsed.get("category").is_some()); -} - -#[test] -fn test_destructive_gate_disabled_by_default() { - // Ensure the variable is unset - // SAFETY: test-only env var mutation; no concurrent reads of this var. - unsafe { - std::env::remove_var("DEVBASE_MCP_ENABLE_DESTRUCTIVE"); - } - let result = crate::mcp::check_destructive_enabled(); - assert!(result.is_err()); - let msg = result.unwrap_err().to_string(); - assert!(msg.contains("DEVBASE_MCP_ENABLE_DESTRUCTIVE")); -} - -#[test] -fn test_destructive_gate_enabled() { - // SAFETY: test-only env var mutation; no concurrent reads of this var. - unsafe { - std::env::set_var("DEVBASE_MCP_ENABLE_DESTRUCTIVE", "1"); - } - let result = crate::mcp::check_destructive_enabled(); - assert!(result.is_ok()); - // Cleanup - // SAFETY: test-only env var mutation; no concurrent reads of this var. - unsafe { - std::env::remove_var("DEVBASE_MCP_ENABLE_DESTRUCTIVE"); - } -} - -#[tokio::test] -#[ignore = "requires knowledge-report skill installed and may run external Python process"] -async fn test_tools_call_devkit_skill_run() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 11, - "method": "tools/call", - "params": { - "name": "devkit_skill_run", - "arguments": { - "skill_id": "knowledge-report", - "args": { "repo_id": "devbase" } - } - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), true); - assert!(parsed.get("status").is_some()); - assert!(parsed.get("stdout").is_some()); -} - -#[tokio::test] -async fn test_stdio_content_length_format() { - let body = serde_json::json!({ "jsonrpc": "2.0", "id": 1, "result": {} }); - let msg = format_mcp_message(&body); - assert!(msg.starts_with("Content-Length: ")); - let parts: Vec<&str> = msg.split("\r\n\r\n").collect(); - assert_eq!(parts.len(), 2); - let body_part = parts[1]; - // No trailing newline — Content-Length must match exact body bytes - assert!(!body_part.ends_with("\n")); - let parsed: serde_json::Value = serde_json::from_str(body_part).unwrap(); - assert_eq!(parsed, body); - // Verify Content-Length header matches actual body byte count - let header = parts[0]; - let cl_str = header.strip_prefix("Content-Length: ").unwrap(); - let cl: usize = cl_str.parse().unwrap(); - assert_eq!(cl, body_part.len()); -} - -static NL_FILTER_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); - -fn mock_repo( - id: &str, - language: Option<&str>, - tags: Vec<&str>, - stars: Option, -) -> crate::registry::RepoEntry { - crate::registry::RepoEntry { - id: id.to_string(), - local_path: std::path::PathBuf::from(format!("/tmp/{}", id)), - tags: tags.into_iter().map(String::from).collect(), - discovered_at: chrono::Utc::now(), - language: language.map(String::from), - workspace_type: "git".to_string(), - data_tier: "private".to_string(), - last_synced_at: None, - stars, - remotes: vec![], - } -} - -#[test] -fn test_nl_filter_repos_empty_query_returns_empty() -> anyhow::Result<()> { - let _guard = NL_FILTER_TEST_LOCK.lock().unwrap(); - let conn = crate::registry::WorkspaceRegistry::init_in_memory()?; - let repos: Vec = vec![]; - let backend = crate::storage::TempStorageBackend::new(); - let index_path = backend.index_path()?; - let searcher = crate::search::SearchClientImpl; - let analyzer = crate::health::RepoAnalyzerImpl; - let results = crate::mcp::tools::repo::nl_filter_repos_at( - &index_path, - "", - &repos, - &conn, - &searcher, - &analyzer, - )?; - assert!(results.is_empty()); - Ok(()) -} - -#[test] -fn test_nl_filter_repos_fallback_finds_by_language() -> anyhow::Result<()> { - let _guard = NL_FILTER_TEST_LOCK.lock().unwrap(); - let conn = crate::registry::WorkspaceRegistry::init_in_memory()?; - let repos = vec![ - mock_repo("repo1", Some("rust"), vec!["cli"], Some(10)), - mock_repo("repo2", Some("python"), vec!["web"], Some(5)), - ]; - let backend = crate::storage::TempStorageBackend::new(); - let index_path = backend.index_path()?; - let searcher = crate::search::SearchClientImpl; - let analyzer = crate::health::RepoAnalyzerImpl; - let results = crate::mcp::tools::repo::nl_filter_repos_at( - &index_path, - "rust cli tool", - &repos, - &conn, - &searcher, - &analyzer, - )?; - assert_eq!(results.len(), 1); - assert_eq!(results[0].id, "repo1"); - Ok(()) -} - -#[test] -fn test_nl_filter_repos_tantivy_finds_devbase() -> anyhow::Result<()> { - let backend = std::sync::Arc::new(crate::storage::TempStorageBackend::new()); - let index_path = backend.index_path()?; - - // Ensure DB schema exists - let conn = crate::registry::WorkspaceRegistry::init_db_with(&*backend)?; - - // Populate Tantivy index with devbase doc - let (index, _reader) = crate::search::init_index_at(&index_path)?; - let mut writer = crate::search::get_writer(&index)?; - let schema = index.schema(); - crate::search::add_repo_doc( - &mut writer, - &schema, - "devbase", - "devbase developer workspace manager", - "rust, cli, workspace, developer", - &["rust".to_string(), "cli".to_string()], - )?; - crate::search::commit_writer(&mut writer)?; - - let repos = vec![crate::registry::RepoEntry { - id: "devbase".to_string(), - local_path: std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")), - tags: vec!["rust".to_string(), "cli".to_string()], - discovered_at: chrono::Utc::now(), - language: Some("rust".to_string()), - workspace_type: "git".to_string(), - data_tier: "private".to_string(), - last_synced_at: None, - stars: Some(10), - remotes: vec![], - }]; - - let searcher = crate::search::SearchClientImpl; - let analyzer = crate::health::RepoAnalyzerImpl; - let results = crate::mcp::tools::repo::nl_filter_repos_at( - &index_path, - "developer workspace", - &repos, - &conn, - &searcher, - &analyzer, - )?; - assert!(!results.is_empty(), "tantivy path should find devbase"); - assert_eq!(results[0].id, "devbase"); - Ok(()) -} - -#[test] -fn test_format_mcp_message() { - let body = serde_json::json!({"jsonrpc": "2.0", "id": 1}); - let msg = format_mcp_message(&body); - assert!(msg.starts_with("Content-Length:")); - assert!(msg.contains("\r\n\r\n")); - // No trailing newline — spec-compliant MCP message ends after JSON body - assert!(!msg.ends_with("\n")); -} - -#[test] -fn test_parse_tool_tiers() { - let tiers = parse_tool_tiers("stable,beta"); - assert!(tiers.contains(&ToolTier::Stable)); - assert!(tiers.contains(&ToolTier::Beta)); - assert!(!tiers.contains(&ToolTier::Experimental)); -} - -#[test] -fn test_parse_tool_tiers_empty() { - let tiers = parse_tool_tiers(""); - assert!(tiers.is_empty()); -} - -// --- Claude Scenario Validation Tests --- - -fn seed_scenario_data(ctx: &crate::storage::AppContext) { - let mut conn = ctx.conn().unwrap(); - let now = chrono::Utc::now().to_rfc3339(); - - // 1. Register a repo in the entities table (single source of truth) - conn.execute( - "INSERT INTO entities (id, entity_type, name, local_path, metadata, created_at, updated_at, language, discovered_at, workspace_type, data_tier, stars) - VALUES (?1, 'repo', ?2, ?3, ?4, ?5, ?5, ?6, ?5, ?7, ?8, ?9)", - rusqlite::params!["scenario-repo", "scenario-repo", "/tmp/scenario-repo", "{}", &now, "rust", "git", "private", 42i64], - ).unwrap(); - - // 2. Tags (including "managed" for is_managed coverage) - for tag in &["rust", "cli", "managed"] { - conn.execute( - "INSERT INTO repo_tags (repo_id, tag) VALUES (?1, ?2)", - rusqlite::params!["scenario-repo", tag], - ) - .unwrap(); - } - - // 3. Code symbols: 10 entries, mix of functions and structs. - // Include auth-related signatures so "authentication flow" keyword search hits. - let symbols: [(&str, &str, &str, i64, Option<&str>); 10] = [ - ( - "src/auth.rs", - "function", - "authenticate_user", - 10, - Some("pub fn authenticate_user(token: &str) // authentication flow handler"), - ), - ( - "src/auth.rs", - "function", - "validate_token", - 20, - Some("fn validate_token(t: &str) -> bool"), - ), - ( - "src/lib.rs", - "function", - "handle_error", - 30, - Some("pub fn handle_error(e: Error)"), - ), - ( - "src/lib.rs", - "function", - "parse_config", - 40, - Some("fn parse_config() -> Config"), - ), - ("src/main.rs", "function", "main", 1, Some("fn main()")), - ("src/lib.rs", "struct", "Config", 5, None), - ("src/models.rs", "struct", "User", 10, None), - ("src/models.rs", "function", "new_user", 15, Some("fn new_user() -> User")), - ("src/db.rs", "function", "connect_pool", 5, Some("fn connect_pool() -> Pool")), - ("src/api.rs", "function", "serve", 1, Some("pub async fn serve(addr: &str)")), - ]; - for (path, ty, name, line, sig) in &symbols { - conn.execute( - "INSERT INTO code_symbols (repo_id, file_path, symbol_type, name, line_start, signature) - VALUES (?1, ?2, ?3, ?4, ?5, ?6)", - rusqlite::params!["scenario-repo", path, ty, name, line, *sig], - ).unwrap(); - } - - // 4. Vault notes: create filesystem files then scan into registry - let ws = ctx.storage.workspace_dir().unwrap(); - let vault_dir = ws.join("vault"); - std::fs::create_dir_all(&vault_dir).unwrap(); - std::fs::write( - vault_dir.join("auth-design.md"), - "---\ntitle: Authentication Flow Design\nrepo: scenario-repo\ntags: [auth, design]\n---\n\nThis document describes the authentication flow for the scenario repo.\nThe authenticate_user function handles token validation.\n", - ).unwrap(); - crate::vault::scanner::scan_vault(&mut conn, Some(&vault_dir)).unwrap(); -} - -#[tokio::test] -async fn test_scenario_one_project_onboarding() { - let backend = std::sync::Arc::new(crate::storage::TempStorageBackend::new()); - let mut ctx = crate::storage::AppContext::with_storage(backend).unwrap(); - seed_scenario_data(&ctx); - - // Tool 1: devkit_health - let health_tool = DevkitHealthTool; - let health_result = health_tool - .invoke(serde_json::json!({ "detail": true }), &mut ctx) - .await - .unwrap(); - assert_eq!(health_result.get("success").unwrap(), true); - let summary = health_result.get("summary").unwrap(); - assert!(summary.get("total_repos").unwrap().as_i64().unwrap() >= 1); - - // Tool 2: devkit_project_brief - let brief_tool = DevkitProjectBriefTool; - let brief_result = brief_tool - .invoke(serde_json::json!({ "repo_id": "scenario-repo" }), &mut ctx) - .await - .unwrap(); - assert_eq!(brief_result.get("success").unwrap(), true); - let brief = brief_result.get("brief").unwrap().as_str().unwrap(); - // Acceptance: brief contains >= 5 key modules/symbols - let symbol_count = brief.matches("- `").count(); - assert!( - symbol_count >= 5, - "Expected >= 5 symbols in brief, found {}. Brief:\n{}", - symbol_count, - brief - ); - assert!(brief.contains("## Architecture")); - assert!(brief.contains("Key Symbols:")); - - // Tool 3: devkit_query_repos - let query_tool = DevkitQueryReposTool; - let query_result = query_tool.invoke(serde_json::json!({}), &mut ctx).await.unwrap(); - assert_eq!(query_result.get("success").unwrap(), true); - let repos = query_result.get("repos").unwrap().as_array().unwrap(); - assert!( - repos - .iter() - .any(|r| r.get("id").and_then(|v| v.as_str()) == Some("scenario-repo")), - "scenario-repo should be listed in query_repos" - ); -} - -#[tokio::test] -async fn test_tools_call_devkit_document_convert_not_found() { - let server = build_server(); - let req = serde_json::json!({ - "jsonrpc": "2.0", - "id": 18, - "method": "tools/call", - "params": { - "name": "devkit_document_convert", - "arguments": { "source_path": "/nonexistent/file.pdf" } - } - }); - let (mut ctx, _tmp) = test_ctx(); - let resp = server.handle_request(req, &mut ctx).await.unwrap(); - let result = resp.get("result").unwrap(); - let content = result.get("content").unwrap().as_array().unwrap(); - let text = content[0].get("text").unwrap().as_str().unwrap(); - let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); - assert_eq!(parsed.get("success").unwrap(), false); - let err = parsed.get("error").unwrap().as_str().unwrap(); - assert!(err.contains("not found") || err.contains("Source file")); -} - -#[tokio::test] -async fn test_scenario_two_semantic_exploration() { - let backend = std::sync::Arc::new(crate::storage::TempStorageBackend::new()); - let mut ctx = crate::storage::AppContext::with_storage(backend).unwrap(); - seed_scenario_data(&ctx); - - // Tool 1: devkit_hybrid_search — keyword fallback path (no embeddings seeded) - let search_tool = DevkitHybridSearchTool; - let search_result = search_tool - .invoke( - serde_json::json!({ "repo_id": "scenario-repo", "query_text": "authentication flow", "limit": 10 }), - &mut ctx, - ) - .await - .unwrap(); - assert_eq!(search_result.get("success").unwrap(), true); - let symbols = search_result.get("symbols").unwrap().as_array().unwrap(); - assert!( - !symbols.is_empty(), - "hybrid_search should return at least 1 auth-related symbol via keyword fallback" - ); - let names: Vec<&str> = - symbols.iter().filter_map(|s| s.get("name").and_then(|v| v.as_str())).collect(); - assert!( - names.contains(&"authenticate_user"), - "authenticate_user should appear in hybrid_search results for 'authentication flow'. Got: {:?}", - names - ); - - // Tool 2: devkit_project_context - let context_tool = DevkitProjectContextTool; - let ctx_result = context_tool - .invoke(serde_json::json!({ "project": "scenario-repo" }), &mut ctx) - .await - .unwrap(); - assert_eq!(ctx_result.get("success").unwrap(), true); - let ctx_symbols = ctx_result.get("symbols").unwrap().as_array().unwrap(); - assert!( - ctx_symbols.len() >= 3, - "project_context should return >= 3 symbols for understanding. Got: {}", - ctx_symbols.len() - ); - - // Tool 3: devkit_vault_search - let vault_tool = DevkitVaultSearchTool; - let vault_result = vault_tool - .invoke(serde_json::json!({ "query": "authentication" }), &mut ctx) - .await - .unwrap(); - assert_eq!(vault_result.get("success").unwrap(), true); - let notes = vault_result.get("notes").unwrap().as_array().unwrap(); - assert!(!notes.is_empty(), "vault_search should find the auth-design note"); - assert!( - notes - .iter() - .any(|n| n.get("title").and_then(|v| v.as_str()) == Some("Authentication Flow Design")), - "vault_search should return auth-design note" - ); -} +// SPDX-License-Identifier: MIT +// Copyright (c) 2026 juice094 +use super::*; +use crate::storage::StorageBackend; + +fn test_ctx() -> (crate::storage::AppContext, tempfile::TempDir) { + let backend = std::sync::Arc::new(crate::storage::TempStorageBackend::new()); + let ctx = crate::storage::AppContext::with_storage(backend).unwrap(); + // Return a dummy TempDir to keep call-site destructuring compatible. + let tmp = tempfile::tempdir().unwrap(); + (ctx, tmp) +} + +/// Lightweight helper: seed a single repo into the entities table. +fn seed_repo(ctx: &crate::storage::AppContext, id: &str, lang: &str) { + let conn = ctx.conn().unwrap(); + let now = chrono::Utc::now().to_rfc3339(); + conn.execute( + "INSERT INTO entities (id, entity_type, name, local_path, metadata, created_at, updated_at, language, discovered_at, workspace_type, data_tier, stars) + VALUES (?1, 'repo', ?2, ?3, ?4, ?5, ?5, ?6, ?5, 'git', 'private', 0)", + rusqlite::params![id, id, format!("/tmp/{}", id), "{}", &now, lang], + ).unwrap(); +} + +#[tokio::test] +async fn test_initialize() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize" + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + assert_eq!(resp.get("jsonrpc").unwrap(), "2.0"); + let result = resp.get("result").unwrap(); + assert_eq!(result.get("protocolVersion").unwrap(), "2024-11-05"); + assert_eq!(result.get("serverInfo").unwrap().get("name").unwrap(), "devbase"); + assert!(result.get("capabilities").unwrap().get("tools").is_some()); +} + +#[tokio::test] +async fn test_tools_list() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/list" + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let tools = resp.get("result").unwrap().get("tools").unwrap().as_array().unwrap(); + assert_eq!(tools.len(), 71); + let names: Vec<&str> = tools.iter().map(|t| t.get("name").unwrap().as_str().unwrap()).collect(); + assert!(names.contains(&"devkit_index_health")); + assert!(names.contains(&"devkit_vault_export")); + assert!(names.contains(&"devkit_vault_history")); + assert!(names.contains(&"devkit_search_quality")); + assert!(names.contains(&"devkit_session_save")); + assert!(names.contains(&"devkit_session_list")); + assert!(names.contains(&"devkit_session_resume")); + assert!(names.contains(&"devkit_session_recall")); + assert!(names.contains(&"devkit_session_index")); + assert!(names.contains(&"devkit_session_export")); + assert!(names.contains(&"devkit_session_import")); + assert!(names.contains(&"devkit_evaluate")); + assert!(names.contains(&"devkit_document_convert")); + assert!(names.contains(&"devkit_scan")); + assert!(names.contains(&"devkit_health")); + assert!(names.contains(&"devkit_sync")); + assert!(names.contains(&"devkit_query")); + assert!(names.contains(&"devkit_query_repos")); + assert!(names.contains(&"devkit_index")); + assert!(names.contains(&"devkit_index_stream")); + assert!(names.contains(&"devkit_status")); + assert!(names.contains(&"devkit_note")); + assert!(names.contains(&"devkit_digest")); + assert!(names.contains(&"devkit_paper_index")); + assert!(names.contains(&"devkit_experiment_log")); + assert!(names.contains(&"devkit_github_info")); + assert!(names.contains(&"devkit_code_metrics")); + assert!(names.contains(&"devkit_module_graph")); + assert!(names.contains(&"devkit_code_symbols")); + assert!(names.contains(&"devkit_dependency_graph")); + assert!(names.contains(&"devkit_call_graph")); + assert!(names.contains(&"devkit_dead_code")); + assert!(names.contains(&"devkit_semantic_search")); + assert!(names.contains(&"devkit_embedding_store")); + assert!(names.contains(&"devkit_embedding_search")); + assert!(names.contains(&"devkit_natural_language_query")); + assert!(names.contains(&"devkit_vault_search")); + assert!(names.contains(&"devkit_vault_read")); + assert!(names.contains(&"devkit_vault_write")); + assert!(names.contains(&"devkit_vault_backlinks")); + assert!(names.contains(&"devkit_vault_daily")); + assert!(names.contains(&"devkit_vault_graph")); + assert!(names.contains(&"devkit_project_context")); + assert!(names.contains(&"devkit_project_brief")); + assert!(names.contains(&"devkit_impact_analysis")); + assert!(names.contains(&"devkit_cross_repo_search")); + assert!(names.contains(&"devkit_knowledge_report")); + assert!(names.contains(&"devkit_related_symbols")); + assert!(names.contains(&"devkit_hybrid_search")); + assert!(names.contains(&"devkit_skill_list")); + assert!(names.contains(&"devkit_skill_search")); + assert!(names.contains(&"devkit_skill_run")); + assert!(names.contains(&"devkit_skill_discover")); + assert!(names.contains(&"devkit_skill_sync")); + assert!(names.contains(&"devkit_known_limit_store")); + assert!(names.contains(&"devkit_known_limit_list")); + assert!(names.contains(&"devkit_relation_store")); + assert!(names.contains(&"devkit_relation_query")); + assert!(names.contains(&"devkit_relation_delete")); + assert!(names.contains(&"devkit_workflow_list")); + assert!(names.contains(&"devkit_workflow_run")); + assert!(names.contains(&"devkit_workflow_status")); + for tool in tools { + assert!(tool.get("name").is_some()); + assert!(tool.get("description").is_some()); + assert!(tool.get("inputSchema").is_some()); + } +} + +#[tokio::test] +async fn test_tools_call_devkit_health() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "devkit_health", + "arguments": { "detail": false } + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + if parsed.get("success").unwrap() != &serde_json::Value::Bool(true) { + eprintln!( + "devkit_health returned error: {}", + serde_json::to_string_pretty(&parsed).unwrap() + ); + } + assert_eq!(parsed.get("success").unwrap(), true); + let summary = parsed.get("summary").unwrap(); + assert!(summary.get("total_repos").unwrap().as_i64().unwrap() >= 0); +} + +#[tokio::test] +async fn test_tools_call_devkit_query() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 4, + "method": "tools/call", + "params": { + "name": "devkit_query", + "arguments": { "expression": "lang:rust" } + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + assert!(parsed.get("count").unwrap().as_i64().unwrap() >= 0); +} + +#[tokio::test] +async fn test_tools_call_unknown_tool() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 5, + "method": "tools/call", + "params": { + "name": "unknown_tool", + "arguments": {} + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + assert!(resp.get("error").is_some()); + let error = resp.get("error").unwrap(); + assert_eq!(error.get("code").unwrap().as_i64().unwrap(), -32602); +} + +#[tokio::test] +async fn test_unknown_method() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 6, + "method": "unknown/method" + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + assert!(resp.get("error").is_some()); + let error = resp.get("error").unwrap(); + assert_eq!(error.get("code").unwrap().as_i64().unwrap(), -32601); +} + +#[tokio::test] +async fn test_tools_call_devkit_project_context() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 7, + "method": "tools/call", + "params": { + "name": "devkit_project_context", + "arguments": { "project": "nonexistent-project-xyz" } + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + assert_eq!(result.get("content").unwrap().as_array().unwrap().len(), 1); + let text = result["content"][0]["text"].as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + assert!(parsed.get("repo").unwrap().is_null()); + assert!(parsed.get("vault_notes").unwrap().as_array().unwrap().is_empty()); + assert!(parsed.get("assets").unwrap().as_array().unwrap().is_empty()); +} + +#[tokio::test] +async fn test_tools_call_devkit_query_repos() { + let server = build_server(); + let (mut ctx, _tmp) = test_ctx(); + + // 1. Empty registry returns empty results + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 10, + "method": "tools/call", + "params": { + "name": "devkit_query_repos", + "arguments": { "language": "" } + } + }); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + assert_eq!(parsed.get("count").unwrap().as_i64().unwrap(), 0); + + // 2. Seeded repo is returned with correct filtering + seed_repo(&ctx, "test-repo", "rust"); + let req2 = serde_json::json!({ + "jsonrpc": "2.0", + "id": 11, + "method": "tools/call", + "params": { + "name": "devkit_query_repos", + "arguments": { "language": "rust" } + } + }); + let resp2 = server.handle_request(req2, &mut ctx).await.unwrap(); + let result2 = resp2.get("result").unwrap(); + let content2 = result2.get("content").unwrap().as_array().unwrap(); + let text2 = content2[0].get("text").unwrap().as_str().unwrap(); + let parsed2: serde_json::Value = serde_json::from_str(text2).unwrap(); + assert_eq!(parsed2.get("success").unwrap(), true); + let repos = parsed2.get("repos").unwrap().as_array().unwrap(); + assert_eq!(repos.len(), 1); + assert_eq!(repos[0].get("id").unwrap().as_str().unwrap(), "test-repo"); + assert_eq!(repos[0].get("language").unwrap().as_str().unwrap(), "rust"); +} + +#[tokio::test] +async fn test_tools_call_devkit_vault_search() { + let server = build_server(); + let (mut ctx, _tmp) = test_ctx(); + + // Setup: create vault note and scan + let ws = ctx.storage.workspace_dir().unwrap(); + let vault_dir = ws.join("vault"); + std::fs::create_dir_all(&vault_dir).unwrap(); + std::fs::write( + vault_dir.join("test-note.md"), + "---\ntitle: Test Note\ntags: [test, vault]\n---\n\nThis is a test note for vault search.\n", + ).unwrap(); + let mut conn = ctx.conn().unwrap(); + crate::vault::scanner::scan_vault(&mut conn, Some(&vault_dir)).unwrap(); + + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 12, + "method": "tools/call", + "params": { + "name": "devkit_vault_search", + "arguments": { "query": "test note" } + } + }); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + let notes = parsed.get("notes").unwrap().as_array().unwrap(); + assert!(!notes.is_empty(), "vault_search should find the test-note"); + assert!( + notes + .iter() + .any(|n| n.get("title").and_then(|v| v.as_str()) == Some("Test Note")), + "vault_search should return Test Note" + ); +} + +#[tokio::test] +async fn test_tools_call_devkit_vault_read() { + let server = build_server(); + let (mut ctx, _tmp) = test_ctx(); + + // Setup: create vault note and scan + let ws = ctx.storage.workspace_dir().unwrap(); + let vault_dir = ws.join("vault"); + std::fs::create_dir_all(&vault_dir).unwrap(); + let note_path = vault_dir.join("test-read.md"); + std::fs::write( + ¬e_path, + "---\ntitle: Readable Note\ntags: [read]\n---\n\nContent body here.\n", + ) + .unwrap(); + let mut conn = ctx.conn().unwrap(); + crate::vault::scanner::scan_vault(&mut conn, Some(&vault_dir)).unwrap(); + + // 1. Read existing note by absolute path + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 13, + "method": "tools/call", + "params": { + "name": "devkit_vault_read", + "arguments": { "path": note_path.to_str().unwrap() } + } + }); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + assert_eq!(parsed.get("path").unwrap().as_str().unwrap(), note_path.to_str().unwrap()); + let frontmatter = parsed.get("frontmatter").unwrap().as_str().unwrap(); + assert!(frontmatter.contains("title: Readable Note")); + let body = parsed.get("content").unwrap().as_str().unwrap(); + assert!(body.contains("Content body here.")); + + // 2. Read non-existent note returns error + let req2 = serde_json::json!({ + "jsonrpc": "2.0", + "id": 14, + "method": "tools/call", + "params": { + "name": "devkit_vault_read", + "arguments": { "path": "/nonexistent/path/note.md" } + } + }); + let resp2 = server.handle_request(req2, &mut ctx).await.unwrap(); + let result2 = resp2.get("result").unwrap(); + assert_eq!(result2.get("isError").unwrap(), true); + let content2 = result2.get("content").unwrap().as_array().unwrap(); + let text2 = content2[0].get("text").unwrap().as_str().unwrap(); + let parsed2: serde_json::Value = serde_json::from_str(text2).unwrap(); + assert_eq!(parsed2.get("success").unwrap(), false); + assert!( + parsed2.get("error").unwrap().as_str().unwrap().contains("not found") + || parsed2.get("error").unwrap().as_str().unwrap().contains("unreadable") + ); +} + +#[tokio::test] +async fn test_tools_call_devkit_arxiv_fetch() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 8, + "method": "tools/call", + "params": { + "name": "devkit_arxiv_fetch", + "arguments": { "arxiv_id": "" } + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + // Empty arxiv_id should result in an error from the arXiv API or parser + assert_eq!(parsed.get("success").unwrap(), false); + assert!(!parsed.get("error").unwrap().as_str().unwrap().is_empty()); +} + +#[tokio::test] +async fn test_tools_call_devkit_status() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 15, + "method": "tools/call", + "params": { + "name": "devkit_status", + "arguments": {} + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + // Empty registry → overall "fresh" (vacuous truth: all 0 repos are fresh) + assert_eq!(parsed.get("overall").unwrap().as_str().unwrap(), "fresh"); + let repos = parsed.get("repos").unwrap().as_array().unwrap(); + assert!(repos.is_empty()); +} + +#[tokio::test] +async fn test_tools_call_devkit_workflow_list() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 16, + "method": "tools/call", + "params": { + "name": "devkit_workflow_list", + "arguments": {} + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + assert_eq!(parsed.get("count").unwrap().as_i64().unwrap(), 0); + let workflows = parsed.get("workflows").unwrap().as_array().unwrap(); + assert!(workflows.is_empty()); +} + +#[tokio::test] +async fn test_tools_call_devkit_index() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 17, + "method": "tools/call", + "params": { + "name": "devkit_index", + "arguments": { "path": "" } + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + // Empty registry → indexed 0 repos + assert_eq!(parsed.get("indexed").unwrap().as_i64().unwrap(), 0); +} + +#[tokio::test] +async fn test_tools_call_devkit_skill_list() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 9, + "method": "tools/call", + "params": { + "name": "devkit_skill_list", + "arguments": {} + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + assert!(parsed.get("skills").unwrap().is_array()); + assert!(parsed.get("count").unwrap().as_i64().unwrap() >= 0); +} + +#[tokio::test] +async fn test_tools_call_devkit_skill_search() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 10, + "method": "tools/call", + "params": { + "name": "devkit_skill_search", + "arguments": { "query": "report" } + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + assert!(parsed.get("skills").unwrap().is_array()); + assert!(parsed.get("count").unwrap().as_i64().unwrap() >= 0); +} + +#[tokio::test] +async fn test_tools_call_devkit_skill_discover() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 11, + "method": "tools/call", + "params": { + "name": "devkit_skill_discover", + "arguments": { + "path": ".", + "skill_id": "mcp-test-discover", + "dry_run": true + } + } + }); + // SAFETY: test-only env var mutation; test runner guarantees no concurrent + // reads of DEVBASE_MCP_ENABLE_DESTRUCTIVE in this process. + unsafe { + std::env::set_var("DEVBASE_MCP_ENABLE_DESTRUCTIVE", "1"); + } + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + assert!(!parsed.get("id").unwrap().as_str().unwrap().is_empty()); + assert!(!parsed.get("name").unwrap().as_str().unwrap().is_empty()); + assert!(parsed.get("version").unwrap().as_str().is_some()); + assert!(parsed.get("category").is_some()); +} + +#[test] +fn test_destructive_gate_disabled_by_default() { + // Ensure the variable is unset + // SAFETY: test-only env var mutation; no concurrent reads of this var. + unsafe { + std::env::remove_var("DEVBASE_MCP_ENABLE_DESTRUCTIVE"); + } + let result = crate::mcp::check_destructive_enabled(); + assert!(result.is_err()); + let msg = result.unwrap_err().to_string(); + assert!(msg.contains("DEVBASE_MCP_ENABLE_DESTRUCTIVE")); +} + +#[test] +fn test_destructive_gate_enabled() { + // SAFETY: test-only env var mutation; no concurrent reads of this var. + unsafe { + std::env::set_var("DEVBASE_MCP_ENABLE_DESTRUCTIVE", "1"); + } + let result = crate::mcp::check_destructive_enabled(); + assert!(result.is_ok()); + // Cleanup + // SAFETY: test-only env var mutation; no concurrent reads of this var. + unsafe { + std::env::remove_var("DEVBASE_MCP_ENABLE_DESTRUCTIVE"); + } +} + +#[tokio::test] +#[ignore = "requires knowledge-report skill installed and may run external Python process"] +async fn test_tools_call_devkit_skill_run() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 11, + "method": "tools/call", + "params": { + "name": "devkit_skill_run", + "arguments": { + "skill_id": "knowledge-report", + "args": { "repo_id": "devbase" } + } + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), true); + assert!(parsed.get("status").is_some()); + assert!(parsed.get("stdout").is_some()); +} + +#[tokio::test] +async fn test_stdio_content_length_format() { + let body = serde_json::json!({ "jsonrpc": "2.0", "id": 1, "result": {} }); + let msg = format_mcp_message(&body); + assert!(msg.starts_with("Content-Length: ")); + let parts: Vec<&str> = msg.split("\r\n\r\n").collect(); + assert_eq!(parts.len(), 2); + let body_part = parts[1]; + // No trailing newline — Content-Length must match exact body bytes + assert!(!body_part.ends_with("\n")); + let parsed: serde_json::Value = serde_json::from_str(body_part).unwrap(); + assert_eq!(parsed, body); + // Verify Content-Length header matches actual body byte count + let header = parts[0]; + let cl_str = header.strip_prefix("Content-Length: ").unwrap(); + let cl: usize = cl_str.parse().unwrap(); + assert_eq!(cl, body_part.len()); +} + +static NL_FILTER_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); + +fn mock_repo( + id: &str, + language: Option<&str>, + tags: Vec<&str>, + stars: Option, +) -> crate::registry::RepoEntry { + crate::registry::RepoEntry { + id: id.to_string(), + local_path: std::path::PathBuf::from(format!("/tmp/{}", id)), + tags: tags.into_iter().map(String::from).collect(), + discovered_at: chrono::Utc::now(), + language: language.map(String::from), + workspace_type: "git".to_string(), + data_tier: "private".to_string(), + last_synced_at: None, + stars, + remotes: vec![], + } +} + +#[test] +fn test_nl_filter_repos_empty_query_returns_empty() -> anyhow::Result<()> { + let _guard = NL_FILTER_TEST_LOCK.lock().unwrap(); + let conn = crate::registry::WorkspaceRegistry::init_in_memory()?; + let repos: Vec = vec![]; + let backend = crate::storage::TempStorageBackend::new(); + let index_path = backend.index_path()?; + let searcher = crate::search::SearchClientImpl; + let analyzer = crate::health::RepoAnalyzerImpl; + let results = crate::mcp::tools::repo::nl_filter_repos_at( + &index_path, + "", + &repos, + &conn, + &searcher, + &analyzer, + )?; + assert!(results.is_empty()); + Ok(()) +} + +#[test] +fn test_nl_filter_repos_fallback_finds_by_language() -> anyhow::Result<()> { + let _guard = NL_FILTER_TEST_LOCK.lock().unwrap(); + let conn = crate::registry::WorkspaceRegistry::init_in_memory()?; + let repos = vec![ + mock_repo("repo1", Some("rust"), vec!["cli"], Some(10)), + mock_repo("repo2", Some("python"), vec!["web"], Some(5)), + ]; + let backend = crate::storage::TempStorageBackend::new(); + let index_path = backend.index_path()?; + let searcher = crate::search::SearchClientImpl; + let analyzer = crate::health::RepoAnalyzerImpl; + let results = crate::mcp::tools::repo::nl_filter_repos_at( + &index_path, + "rust cli tool", + &repos, + &conn, + &searcher, + &analyzer, + )?; + assert_eq!(results.len(), 1); + assert_eq!(results[0].id, "repo1"); + Ok(()) +} + +#[test] +fn test_nl_filter_repos_tantivy_finds_devbase() -> anyhow::Result<()> { + let backend = std::sync::Arc::new(crate::storage::TempStorageBackend::new()); + let index_path = backend.index_path()?; + + // Ensure DB schema exists + let conn = crate::registry::WorkspaceRegistry::init_db_with(&*backend)?; + + // Populate Tantivy index with devbase doc + let (index, _reader) = crate::search::init_index_at(&index_path)?; + let mut writer = crate::search::get_writer(&index)?; + let schema = index.schema(); + crate::search::add_repo_doc( + &mut writer, + &schema, + "devbase", + "devbase developer workspace manager", + "rust, cli, workspace, developer", + &["rust".to_string(), "cli".to_string()], + )?; + crate::search::commit_writer(&mut writer)?; + + let repos = vec![crate::registry::RepoEntry { + id: "devbase".to_string(), + local_path: std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")), + tags: vec!["rust".to_string(), "cli".to_string()], + discovered_at: chrono::Utc::now(), + language: Some("rust".to_string()), + workspace_type: "git".to_string(), + data_tier: "private".to_string(), + last_synced_at: None, + stars: Some(10), + remotes: vec![], + }]; + + let searcher = crate::search::SearchClientImpl; + let analyzer = crate::health::RepoAnalyzerImpl; + let results = crate::mcp::tools::repo::nl_filter_repos_at( + &index_path, + "developer workspace", + &repos, + &conn, + &searcher, + &analyzer, + )?; + assert!(!results.is_empty(), "tantivy path should find devbase"); + assert_eq!(results[0].id, "devbase"); + Ok(()) +} + +#[test] +fn test_format_mcp_message() { + let body = serde_json::json!({"jsonrpc": "2.0", "id": 1}); + let msg = format_mcp_message(&body); + assert!(msg.starts_with("Content-Length:")); + assert!(msg.contains("\r\n\r\n")); + // No trailing newline — spec-compliant MCP message ends after JSON body + assert!(!msg.ends_with("\n")); +} + +#[test] +fn test_parse_tool_tiers() { + let tiers = parse_tool_tiers("stable,beta"); + assert!(tiers.contains(&ToolTier::Stable)); + assert!(tiers.contains(&ToolTier::Beta)); + assert!(!tiers.contains(&ToolTier::Experimental)); +} + +#[test] +fn test_parse_tool_tiers_empty() { + let tiers = parse_tool_tiers(""); + assert!(tiers.is_empty()); +} + +// --- Claude Scenario Validation Tests --- + +fn seed_scenario_data(ctx: &crate::storage::AppContext) { + let mut conn = ctx.conn().unwrap(); + let now = chrono::Utc::now().to_rfc3339(); + + // 1. Register a repo in the entities table (single source of truth) + conn.execute( + "INSERT INTO entities (id, entity_type, name, local_path, metadata, created_at, updated_at, language, discovered_at, workspace_type, data_tier, stars) + VALUES (?1, 'repo', ?2, ?3, ?4, ?5, ?5, ?6, ?5, ?7, ?8, ?9)", + rusqlite::params!["scenario-repo", "scenario-repo", "/tmp/scenario-repo", "{}", &now, "rust", "git", "private", 42i64], + ).unwrap(); + + // 2. Tags (including "managed" for is_managed coverage) + for tag in &["rust", "cli", "managed"] { + conn.execute( + "INSERT INTO repo_tags (repo_id, tag) VALUES (?1, ?2)", + rusqlite::params!["scenario-repo", tag], + ) + .unwrap(); + } + + // 3. Code symbols: 10 entries, mix of functions and structs. + // Include auth-related signatures so "authentication flow" keyword search hits. + let symbols: [(&str, &str, &str, i64, Option<&str>); 10] = [ + ( + "src/auth.rs", + "function", + "authenticate_user", + 10, + Some("pub fn authenticate_user(token: &str) // authentication flow handler"), + ), + ( + "src/auth.rs", + "function", + "validate_token", + 20, + Some("fn validate_token(t: &str) -> bool"), + ), + ( + "src/lib.rs", + "function", + "handle_error", + 30, + Some("pub fn handle_error(e: Error)"), + ), + ( + "src/lib.rs", + "function", + "parse_config", + 40, + Some("fn parse_config() -> Config"), + ), + ("src/main.rs", "function", "main", 1, Some("fn main()")), + ("src/lib.rs", "struct", "Config", 5, None), + ("src/models.rs", "struct", "User", 10, None), + ("src/models.rs", "function", "new_user", 15, Some("fn new_user() -> User")), + ("src/db.rs", "function", "connect_pool", 5, Some("fn connect_pool() -> Pool")), + ("src/api.rs", "function", "serve", 1, Some("pub async fn serve(addr: &str)")), + ]; + for (path, ty, name, line, sig) in &symbols { + conn.execute( + "INSERT INTO code_symbols (repo_id, file_path, symbol_type, name, line_start, signature) + VALUES (?1, ?2, ?3, ?4, ?5, ?6)", + rusqlite::params!["scenario-repo", path, ty, name, line, *sig], + ).unwrap(); + } + + // 4. Vault notes: create filesystem files then scan into registry + let ws = ctx.storage.workspace_dir().unwrap(); + let vault_dir = ws.join("vault"); + std::fs::create_dir_all(&vault_dir).unwrap(); + std::fs::write( + vault_dir.join("auth-design.md"), + "---\ntitle: Authentication Flow Design\nrepo: scenario-repo\ntags: [auth, design]\n---\n\nThis document describes the authentication flow for the scenario repo.\nThe authenticate_user function handles token validation.\n", + ).unwrap(); + crate::vault::scanner::scan_vault(&mut conn, Some(&vault_dir)).unwrap(); +} + +#[tokio::test] +async fn test_scenario_one_project_onboarding() { + let backend = std::sync::Arc::new(crate::storage::TempStorageBackend::new()); + let mut ctx = crate::storage::AppContext::with_storage(backend).unwrap(); + seed_scenario_data(&ctx); + + // Tool 1: devkit_health + let health_tool = DevkitHealthTool; + let health_result = health_tool + .invoke(serde_json::json!({ "detail": true }), &mut ctx) + .await + .unwrap(); + assert_eq!(health_result.get("success").unwrap(), true); + let summary = health_result.get("summary").unwrap(); + assert!(summary.get("total_repos").unwrap().as_i64().unwrap() >= 1); + + // Tool 2: devkit_project_brief + let brief_tool = DevkitProjectBriefTool; + let brief_result = brief_tool + .invoke(serde_json::json!({ "repo_id": "scenario-repo" }), &mut ctx) + .await + .unwrap(); + assert_eq!(brief_result.get("success").unwrap(), true); + let brief = brief_result.get("brief").unwrap().as_str().unwrap(); + // Acceptance: brief contains >= 5 key modules/symbols + let symbol_count = brief.matches("- `").count(); + assert!( + symbol_count >= 5, + "Expected >= 5 symbols in brief, found {}. Brief:\n{}", + symbol_count, + brief + ); + assert!(brief.contains("## Architecture")); + assert!(brief.contains("Key Symbols:")); + + // Tool 3: devkit_query_repos + let query_tool = DevkitQueryReposTool; + let query_result = query_tool.invoke(serde_json::json!({}), &mut ctx).await.unwrap(); + assert_eq!(query_result.get("success").unwrap(), true); + let repos = query_result.get("repos").unwrap().as_array().unwrap(); + assert!( + repos + .iter() + .any(|r| r.get("id").and_then(|v| v.as_str()) == Some("scenario-repo")), + "scenario-repo should be listed in query_repos" + ); +} + +#[tokio::test] +async fn test_tools_call_devkit_document_convert_not_found() { + let server = build_server(); + let req = serde_json::json!({ + "jsonrpc": "2.0", + "id": 18, + "method": "tools/call", + "params": { + "name": "devkit_document_convert", + "arguments": { "source_path": "/nonexistent/file.pdf" } + } + }); + let (mut ctx, _tmp) = test_ctx(); + let resp = server.handle_request(req, &mut ctx).await.unwrap(); + let result = resp.get("result").unwrap(); + let content = result.get("content").unwrap().as_array().unwrap(); + let text = content[0].get("text").unwrap().as_str().unwrap(); + let parsed: serde_json::Value = serde_json::from_str(text).unwrap(); + assert_eq!(parsed.get("success").unwrap(), false); + let err = parsed.get("error").unwrap().as_str().unwrap(); + assert!(err.contains("not found") || err.contains("Source file")); +} + +#[tokio::test] +async fn test_scenario_two_semantic_exploration() { + let backend = std::sync::Arc::new(crate::storage::TempStorageBackend::new()); + let mut ctx = crate::storage::AppContext::with_storage(backend).unwrap(); + seed_scenario_data(&ctx); + + // Tool 1: devkit_hybrid_search — keyword fallback path (no embeddings seeded) + let search_tool = DevkitHybridSearchTool; + let search_result = search_tool + .invoke( + serde_json::json!({ "repo_id": "scenario-repo", "query_text": "authentication flow", "limit": 10 }), + &mut ctx, + ) + .await + .unwrap(); + assert_eq!(search_result.get("success").unwrap(), true); + let symbols = search_result.get("symbols").unwrap().as_array().unwrap(); + assert!( + !symbols.is_empty(), + "hybrid_search should return at least 1 auth-related symbol via keyword fallback" + ); + let names: Vec<&str> = + symbols.iter().filter_map(|s| s.get("name").and_then(|v| v.as_str())).collect(); + assert!( + names.contains(&"authenticate_user"), + "authenticate_user should appear in hybrid_search results for 'authentication flow'. Got: {:?}", + names + ); + + // Tool 2: devkit_project_context + let context_tool = DevkitProjectContextTool; + let ctx_result = context_tool + .invoke(serde_json::json!({ "project": "scenario-repo" }), &mut ctx) + .await + .unwrap(); + assert_eq!(ctx_result.get("success").unwrap(), true); + let ctx_symbols = ctx_result.get("symbols").unwrap().as_array().unwrap(); + assert!( + ctx_symbols.len() >= 3, + "project_context should return >= 3 symbols for understanding. Got: {}", + ctx_symbols.len() + ); + + // Tool 3: devkit_vault_search + let vault_tool = DevkitVaultSearchTool; + let vault_result = vault_tool + .invoke(serde_json::json!({ "query": "authentication" }), &mut ctx) + .await + .unwrap(); + assert_eq!(vault_result.get("success").unwrap(), true); + let notes = vault_result.get("notes").unwrap().as_array().unwrap(); + assert!(!notes.is_empty(), "vault_search should find the auth-design note"); + assert!( + notes + .iter() + .any(|n| n.get("title").and_then(|v| v.as_str()) == Some("Authentication Flow Design")), + "vault_search should return auth-design note" + ); +} diff --git a/src/mcp/tools/mod.rs b/src/mcp/tools/mod.rs index cea8769..535261b 100644 --- a/src/mcp/tools/mod.rs +++ b/src/mcp/tools/mod.rs @@ -1,79 +1,83 @@ -// SPDX-License-Identifier: MIT -// Copyright (c) 2026 juice094 -pub mod brief; -pub mod context; -pub mod document_convert; -pub mod evaluate; -pub mod impact; -pub mod index_health; -pub mod known_limit; -pub mod oplog; -pub mod query; -pub mod relations; -pub mod repo; -pub mod session; -pub mod skill; -pub mod status; -pub mod vault; -pub mod workflow; - -pub mod code_analysis; -pub mod external; -pub mod knowledge; -pub mod search; - -pub use brief::*; -pub use context::*; -pub use document_convert::*; -pub use impact::*; -pub use index_health::*; -pub use known_limit::*; -pub use oplog::*; -pub use query::*; -pub use relations::*; -pub use repo::*; -pub use session::*; -pub use skill::*; -pub use status::*; -pub use vault::*; -pub use workflow::*; - -pub use code_analysis::*; -pub use evaluate::*; -pub use external::*; -pub use knowledge::*; -pub use search::*; - -#[cfg(test)] -mod tests { - #[test] - fn test_tool_modules_compile() { - // Smoke test: all tool structs are constructible - let _ = super::context::DevkitProjectContextTool; - let _ = super::known_limit::DevkitKnownLimitStoreTool; - let _ = super::oplog::DevkitOplogQueryTool; - let _ = super::query::DevkitQueryTool; - let _ = super::repo::DevkitIndexTool; - let _ = super::status::DevkitStatusTool; - let _ = super::skill::DevkitSkillListTool; - let _ = super::vault::DevkitVaultSearchTool; - let _ = super::vault::DevkitVaultDailyTool; - let _ = super::vault::DevkitVaultGraphTool; - let _ = super::workflow::DevkitWorkflowListTool; - let _ = super::session::DevkitSessionSaveTool; - let _ = super::session::DevkitSessionListTool; - let _ = super::session::DevkitSessionResumeTool; - let _ = super::session::DevkitSessionAttachTool; - let _ = super::session::DevkitSessionDetachTool; - let _ = super::session::DevkitSessionActivateTool; - let _ = super::session::DevkitSessionSearchTool; - let _ = super::session::DevkitSessionCaptureTool; - let _ = super::session::DevkitSessionWorkflowsTool; - let _ = super::session::DevkitSessionRecallTool; - let _ = super::session::DevkitSessionIndexTool; - let _ = super::session::DevkitSessionExportTool; - let _ = super::session::DevkitSessionImportTool; - let _ = super::brief::DevkitProjectBriefTool; - let _ = super::impact::DevkitImpactAnalysisTool; - } -} +// SPDX-License-Identifier: MIT +// Copyright (c) 2026 juice094 +pub mod brief; +pub mod context; +pub mod document_convert; +pub mod evaluate; +pub mod impact; +pub mod index_health; +pub mod known_limit; +pub mod ontology_import; +pub mod oplog; +pub mod query; +pub mod relations; +pub mod repo; +pub mod session; +pub mod skill; +pub mod skill_sync; +pub mod status; +pub mod vault; +pub mod workflow; + +pub mod code_analysis; +pub mod external; +pub mod knowledge; +pub mod search; + +pub use brief::*; +pub use context::*; +pub use document_convert::*; +pub use impact::*; +pub use index_health::*; +pub use known_limit::*; +pub use ontology_import::*; +pub use oplog::*; +pub use query::*; +pub use relations::*; +pub use repo::*; +pub use session::*; +pub use skill::*; +pub use skill_sync::*; +pub use status::*; +pub use vault::*; +pub use workflow::*; + +pub use code_analysis::*; +pub use evaluate::*; +pub use external::*; +pub use knowledge::*; +pub use search::*; + +#[cfg(test)] +mod tests { + #[test] + fn test_tool_modules_compile() { + // Smoke test: all tool structs are constructible + let _ = super::context::DevkitProjectContextTool; + let _ = super::known_limit::DevkitKnownLimitStoreTool; + let _ = super::oplog::DevkitOplogQueryTool; + let _ = super::query::DevkitQueryTool; + let _ = super::repo::DevkitIndexTool; + let _ = super::status::DevkitStatusTool; + let _ = super::skill::DevkitSkillListTool; + let _ = super::vault::DevkitVaultSearchTool; + let _ = super::vault::DevkitVaultDailyTool; + let _ = super::vault::DevkitVaultGraphTool; + let _ = super::workflow::DevkitWorkflowListTool; + let _ = super::session::DevkitSessionSaveTool; + let _ = super::session::DevkitSessionListTool; + let _ = super::session::DevkitSessionResumeTool; + let _ = super::session::DevkitSessionAttachTool; + let _ = super::session::DevkitSessionDetachTool; + let _ = super::session::DevkitSessionActivateTool; + let _ = super::session::DevkitSessionSearchTool; + let _ = super::session::DevkitSessionCaptureTool; + let _ = super::session::DevkitSessionWorkflowsTool; + let _ = super::session::DevkitSessionRecallTool; + let _ = super::session::DevkitSessionIndexTool; + let _ = super::session::DevkitSessionExportTool; + let _ = super::session::DevkitSessionImportTool; + let _ = super::brief::DevkitProjectBriefTool; + let _ = super::impact::DevkitImpactAnalysisTool; + } +} diff --git a/src/mcp/tools/ontology_import.rs b/src/mcp/tools/ontology_import.rs new file mode 100644 index 0000000..23c674b --- /dev/null +++ b/src/mcp/tools/ontology_import.rs @@ -0,0 +1,69 @@ +use crate::mcp::McpTool; + +#[derive(Clone)] +pub struct DevkitOntologyImportTool; + +impl McpTool for DevkitOntologyImportTool { + fn name(&self) -> &'static str { + "devkit_ontology_import" + } + + fn schema(&self) -> serde_json::Value { + serde_json::json!({ + "description": r#"Import ontology entities and relations from an OpenClaw-compatible workspace into devbase. + +Reads ontology/entities/*.json and ontology/relations/*.jsonl from the specified workspace path +and maps them into devbase's entities and relations tables. + +Entity JSON format: { "entity_id": "...", "type": "...", "name": "...", "aliases": [...], ... } +Relation JSONL format: { "relation_id": "...", "type": "...", "from": "...", "to": "...", ... } + +Requires DEVBASE_MCP_ENABLE_DESTRUCTIVE=1 since this modifies the registry."#, + "inputSchema": { + "type": "object", + "properties": { + "workspace_path": { + "type": "string", + "description": "Path to the OpenClaw workspace root (contains ontology/ subdirectory). Defaults to the configured openclaw workspace." + } + }, + "required": [] + } + }) + } + + async fn invoke( + &self, + args: serde_json::Value, + ctx: &mut crate::storage::AppContext, + ) -> anyhow::Result { + crate::mcp::check_destructive_enabled()?; + + let workspace = args + .get("workspace_path") + .and_then(|v| v.as_str()) + .map(std::path::PathBuf::from) + .unwrap_or_else(|| { + dirs::home_dir() + .unwrap_or_default() + .join(".kimi_openclaw") + .join("workspace") + }); + + let stats = { + let conn = ctx.conn()?; + crate::registry::import_ontology::import_ontology(&conn, &workspace)? + }; + + Ok(serde_json::json!({ + "workspace": workspace.to_string_lossy().to_string(), + "entities_added": stats.entities_added, + "entities_updated": stats.entities_updated, + "relations_added": stats.relations_added, + "relations_updated": stats.relations_updated, + "errors": stats.errors, + "total_entities": stats.entities_added + stats.entities_updated, + "total_relations": stats.relations_added + stats.relations_updated, + })) + } +} diff --git a/src/mcp/tools/skill_sync.rs b/src/mcp/tools/skill_sync.rs new file mode 100644 index 0000000..3f3d5c8 --- /dev/null +++ b/src/mcp/tools/skill_sync.rs @@ -0,0 +1,157 @@ +use anyhow::Context; + +use crate::mcp::McpTool; +use crate::skill_runtime::sources::{GitHubSource, LocalFileSource, SkillSource}; +use crate::skill_runtime::registry; + +#[derive(Clone)] +pub struct DevkitSkillSyncTool; + +impl McpTool for DevkitSkillSyncTool { + fn name(&self) -> &'static str { + "devkit_skill_sync" + } + + fn schema(&self) -> serde_json::Value { + serde_json::json!({ + "description": r#"Sync skills from external sources (GitHub repositories or local directories) into the devbase skill registry. +Each discovered SKILL.md file is parsed and installed. Sources are recorded and can be re-synced incrementally. + +Source URL formats: +- GitHub: https://github.com/owner/repo/tree/branch/path or owner/repo +- Local: file:///absolute/path or /absolute/path + +Requires DEVBASE_MCP_ENABLE_DESTRUCTIVE=1 since this modifies the skill registry."#, + "inputSchema": { + "type": "object", + "properties": { + "source": { + "type": "string", + "description": "Source URL or path to sync skills from. GitHub repo URL or local directory path." + }, + "source_path": { + "type": "string", + "description": "Path within the source to scan (default: '.' for local, 'skills' for GitHub)." + }, + "dry_run": { + "type": "boolean", + "description": "If true, list discovered skills without installing them.", + "default": false + } + }, + "required": ["source"] + } + }) + } + + async fn invoke( + &self, + args: serde_json::Value, + ctx: &mut crate::storage::AppContext, + ) -> anyhow::Result { + crate::mcp::check_destructive_enabled()?; + + let source_url = args + .get("source") + .and_then(|v| v.as_str()) + .context("Missing required argument: source")?; + let source_path = args.get("source_path").and_then(|v| v.as_str()); + let dry_run = args + .get("dry_run") + .and_then(|v| v.as_bool()) + .unwrap_or(false); + + let source: Box = if source_url.starts_with("https://github.com/") + || source_url.starts_with("http://github.com/") + || (source_url.contains('/') && !source_url.starts_with("/") && !source_url.contains("://")) + { + let (owner, repo) = parse_github_url(source_url)?; + let path = source_path.unwrap_or("skills"); + Box::new(GitHubSource::new(&owner, &repo, path)) + } else { + let path = source_url.strip_prefix("file://").unwrap_or(source_url); + let name = source_path.unwrap_or(path); + Box::new(LocalFileSource::new(name, std::path::Path::new(path))) + }; + + let skills = source.fetch().await?; + let count = skills.len(); + + if dry_run { + let names: Vec = skills.iter().map(|s| s.name.clone()).collect(); + return Ok(serde_json::json!({ + "dry_run": true, + "source": source.name(), + "skills_found": count, + "skill_names": names + })); + } + + let conn = ctx.conn_mut()?; + let mut added = 0usize; + let mut updated = 0usize; + + for skill in &skills { + let exists = registry::get_skill(&conn, &skill.id)?.is_some(); + registry::install_skill(&conn, skill)?; + if exists { + updated += 1; + } else { + added += 1; + } + } + + // Record sync in audit log + let _ = conn.execute( + "INSERT INTO sync_log (source_name, status, skills_added, skills_updated, finished_at) + VALUES (?1, ?2, ?3, ?4, datetime('now'))", + rusqlite::params![source.name(), "success", added as i64, updated as i64], + ); + + // Update last_sync_at on the source record + let _ = conn.execute( + "INSERT INTO sync_sources (name, url, source_type) + VALUES (?1, ?2, ?3) + ON CONFLICT(name) DO UPDATE SET last_sync_at = datetime('now')", + rusqlite::params![source.name(), source_url, source.name()], + ); + + Ok(serde_json::json!({ + "source": source.name(), + "skills_found": count, + "skills_added": added, + "skills_updated": updated, + "dry_run": false + })) + } +} + +fn parse_github_url(url: &str) -> anyhow::Result<(String, String)> { + let url = url.trim_end_matches(".git"); + if let Some(rest) = url.strip_prefix("https://github.com/") { + let parts: Vec<&str> = rest.split('/').collect(); + if parts.len() >= 2 { + return Ok((parts[0].to_string(), parts[1].to_string())); + } + } + if let Some(rest) = url.strip_prefix("http://github.com/") { + let parts: Vec<&str> = rest.split('/').collect(); + if parts.len() >= 2 { + return Ok((parts[0].to_string(), parts[1].to_string())); + } + } + // Bare owner/repo format + if let Some((owner, repo)) = url.split_once('/') { + if !owner.is_empty() && !repo.is_empty() + && !owner.contains("://") + && !owner.contains('\\') + && !owner.contains(' ') + { + return Ok((owner.to_string(), repo.to_string())); + } + } + Err(anyhow::anyhow!( + "Could not parse GitHub URL: {}. Expected format: owner/repo or https://github.com/owner/repo", + url + )) +} diff --git a/src/mcp/tools/vault.rs b/src/mcp/tools/vault.rs index e9689ce..b88b7c3 100644 --- a/src/mcp/tools/vault.rs +++ b/src/mcp/tools/vault.rs @@ -215,12 +215,7 @@ Returns: JSON with success status and the written file path."#, .context("Missing required argument: content")?; let append = args.get("append").and_then(|v| v.as_bool()).unwrap_or(false); - let vault_root = ctx - .storage - .workspace_dir() - .map(|ws| ws.join("vault")) - .unwrap_or_else(|_| std::path::PathBuf::from("vault")); - let target = resolve_vault_path(path, &vault_root)?; + let target = resolve_vault_write_path(ctx, path)?; if let Some(parent) = target.parent() { std::fs::create_dir_all(parent)?; @@ -241,7 +236,92 @@ Returns: JSON with success status and the written file path."#, } } +/// Resolve a vault write path by checking entities.local_path first, +/// then falling back to configured vault roots. +fn resolve_vault_write_path( + ctx: &crate::storage::AppContext, + path: &str, +) -> anyhow::Result { + // 1. Check if this note already exists in entities (has local_path) + if let Ok(conn) = ctx.conn() { + let local_path: Option = conn + .query_row( + "SELECT local_path FROM entities WHERE entity_type = ?1 AND (id = ?2 OR name = ?2)", + rusqlite::params![crate::registry::ENTITY_TYPE_VAULT_NOTE, path], + |row| row.get(0), + ) + .ok(); + if let Some(lp) = local_path { + let p = std::path::PathBuf::from(lp); + if p.exists() || p.parent().map(|d| d.exists()).unwrap_or(false) { + return Ok(p); + } + } + } + + // 2. Fall back to vault roots from config + let vault_roots = match crate::config::Config::load() { + Ok(cfg) if !cfg.vault.roots.is_empty() => { + cfg.vault.roots.iter().map(std::path::PathBuf::from).collect() + } + _ => { + vec![ctx + .storage + .workspace_dir() + .map(|ws| ws.join("vault")) + .unwrap_or_else(|_| std::path::PathBuf::from("vault"))] + } + }; + + let relative = std::path::Path::new(path); + for root in &vault_roots { + let target = resolve_vault_relative_path(relative, root)?; + if target.starts_with(root) { + return Ok(target); + } + } + + anyhow::bail!("Path '{}' cannot be resolved under any configured vault root", path) +} + +/// Resolve a relative path under a single vault root. +fn resolve_vault_relative_path( + relative_path: &std::path::Path, + vault_root: &std::path::Path, +) -> anyhow::Result { + let path = relative_path; + if path.is_absolute() { + anyhow::bail!("Absolute paths are not allowed in vault: {}", relative_path.display()); + } + let s = relative_path.to_string_lossy(); + if s.starts_with('/') || s.starts_with('\\') { + anyhow::bail!("Absolute paths are not allowed in vault: {}", relative_path.display()); + } + + let mut normalized = std::path::PathBuf::new(); + for component in path.components() { + match component { + std::path::Component::Normal(name) => normalized.push(name), + std::path::Component::CurDir => {} + std::path::Component::ParentDir => { + if !normalized.pop() { + anyhow::bail!("Path escapes vault root: {}", relative_path.display()); + } + } + _ => anyhow::bail!("Invalid path component in: {}", relative_path.display()), + } + } + + let target = vault_root.join(&normalized); + if !target.starts_with(vault_root) { + anyhow::bail!("Path escapes vault root: {}", relative_path.display()); + } + + Ok(target) +} + /// Resolve a vault-relative path, enforcing that it stays within the vault root. +#[allow(dead_code)] fn resolve_vault_path( relative_path: &str, vault_root: &std::path::Path, @@ -379,7 +459,7 @@ Returns: JSON with success status and the generated file path."#, let digest = ctx.generate_daily_digest()?; let digest_str = digest.get("digest").and_then(|v| v.as_str()).unwrap_or(""); - let target = resolve_vault_path(&rel_path, &vault_root)?; + let target = resolve_vault_relative_path(std::path::Path::new(&rel_path), &vault_root)?; if let Some(parent) = target.parent() { std::fs::create_dir_all(parent)?; diff --git a/src/registry.rs b/src/registry.rs index 7c2916b..f332000 100644 --- a/src/registry.rs +++ b/src/registry.rs @@ -1,537 +1,538 @@ -// SPDX-License-Identifier: MIT -// Copyright (c) 2026 juice094 -//! Registry layer: SQLite-backed entity storage and domain-specific submodules. -//! -//! Central types (`RepoEntry`, `VaultNote`, `PaperEntry`, etc.) and the -//! [`RegistryClient`] trait implementation on [`AppContext`]. -//! Submodules cover repos, health, knowledge, code metrics, call graphs, -//! dead-code analysis, and migrations. - -use crate::clients::RegistryClient; -use crate::storage::AppContext; -use chrono::{DateTime, Utc}; -use serde::{Deserialize, Serialize}; -use std::path::PathBuf; - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct RemoteEntry { - pub remote_name: String, - pub upstream_url: Option, - pub default_branch: Option, - pub last_sync: Option>, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct RepoEntry { - pub id: String, - pub local_path: PathBuf, - pub tags: Vec, - pub discovered_at: DateTime, - pub language: Option, - pub workspace_type: String, - pub data_tier: String, - pub last_synced_at: Option>, - pub stars: Option, - pub remotes: Vec, -} - -/// Tags that mark a repository as "managed" for sync purposes. -/// Stored in the `repo_tags` table (not metadata) because tags are the -/// queryable, filterable dimension — metadata is for opaque JSON. -pub const MANAGED_TAGS: &[&str] = &[ - "mirror", - "reference", - "third-party", - "collaborative", - "team", - "own-project", - "tool", - "active", - "managed", -]; - -impl RepoEntry { - /// Return the 'origin' remote if present, otherwise the first remote. - pub fn primary_remote(&self) -> Option<&RemoteEntry> { - self.remotes - .iter() - .find(|r| r.remote_name == "origin") - .or_else(|| self.remotes.first()) - } - - /// Whether this repo is considered "managed" for sync/health automation. - /// Managed status is determined by the presence of any tag in [`MANAGED_TAGS`]. - pub fn is_managed(&self) -> bool { - self.tags.iter().any(|t| MANAGED_TAGS.contains(&t.as_str())) - } -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct VaultNote { - pub id: String, - pub path: String, - pub title: Option, - pub content: String, - pub frontmatter: Option, - pub tags: Vec, - pub outgoing_links: Vec, - pub block_refs: Vec, - pub linked_repo: Option, - pub created_at: DateTime, - pub updated_at: DateTime, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct PaperEntry { - pub id: String, - pub title: String, - pub authors: Option, - pub venue: Option, - pub year: Option, - pub pdf_path: Option, - pub bibtex: Option, - pub tags: Vec, - pub added_at: DateTime, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct ExperimentEntry { - pub id: String, - pub repo_id: Option, - pub paper_id: Option, - pub config_json: Option, - pub result_path: Option, - pub git_commit: Option, - pub syncthing_folder_id: Option, - pub status: String, - pub timestamp: DateTime, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub struct WorkspaceRegistry { - pub version: String, - pub entries: Vec, -} - -impl Default for WorkspaceRegistry { - fn default() -> Self { - Self { - version: "0.1.0".to_string(), - entries: Vec::new(), - } - } -} - -pub use devbase_registry::health::HealthEntry; -pub use devbase_registry::metrics::CodeMetrics; -pub use devbase_registry::workspace::{OplogEntry, OplogEventType, WorkspaceSnapshot}; - -pub mod entity; -pub mod relation; - -// Backward-compatible re-exports (migrated to entity.rs in v0.15). -pub use entity::{ - ENTITY_TYPE_PAPER, ENTITY_TYPE_REPO, ENTITY_TYPE_SKILL, ENTITY_TYPE_VAULT_NOTE, - ENTITY_TYPE_WORKFLOW, upsert_entity, -}; - -pub mod agent_context; -pub mod call_graph; -pub mod code_symbols; -pub mod dead_code; -pub mod health; -pub mod knowledge; -pub mod knowledge_meta; -pub mod known_limits; -pub mod links; -pub mod metrics; -mod migrate; -pub mod migrations; -pub mod repo; -pub mod repos_toml; -pub mod vault; -pub mod workspace; - -impl RegistryClient for AppContext { - fn list_repos(&self, _filter: Option<&str>) -> anyhow::Result { - let conn = self.conn()?; - let repos = repo::list_repos(&conn)?; - let results: Vec = repos - .into_iter() - .map(|r| { - serde_json::json!({ - "id": r.id, - "local_path": r.local_path, - "language": r.language, - "tags": r.tags, - "workspace_type": r.workspace_type, - "data_tier": r.data_tier, - }) - }) - .collect(); - Ok(serde_json::json!({ "success": true, "count": results.len(), "repos": results })) - } - - fn get_repo(&self, repo_id: &str) -> anyhow::Result { - let conn = self.conn()?; - let repos = repo::list_repos(&conn)?; - match repos.into_iter().find(|r| r.id == repo_id) { - Some(r) => Ok(serde_json::json!({ - "success": true, - "id": r.id, - "local_path": r.local_path, - "language": r.language, - "tags": r.tags, - "workspace_type": r.workspace_type, - "data_tier": r.data_tier, - })), - None => Ok(serde_json::json!({ "success": false, "error": "repo not found" })), - } - } - - fn list_modules(&self, repo_id: &str) -> anyhow::Result { - let conn = self.conn()?; - let modules = knowledge::list_modules(&conn, repo_id)?; - let results: Vec = modules - .into_iter() - .map(|(name, ty, path)| { - serde_json::json!({ - "name": name, - "type": ty, - "path": path, - }) - }) - .collect(); - Ok(serde_json::json!({ "success": true, "count": results.len(), "modules": results })) - } - - fn save_paper(&self, paper: &serde_json::Value) -> anyhow::Result { - let conn = self.conn()?; - let paper_entry: PaperEntry = serde_json::from_value(paper.clone())?; - knowledge::save_paper(&conn, &paper_entry)?; - Ok(serde_json::json!({ "success": true })) - } - - fn save_experiment(&self, exp: &serde_json::Value) -> anyhow::Result { - let conn = self.conn()?; - let exp_entry: ExperimentEntry = serde_json::from_value(exp.clone())?; - WorkspaceRegistry::save_experiment(&conn, &exp_entry)?; - Ok(serde_json::json!({ "success": true })) - } - - fn list_code_metrics(&self) -> anyhow::Result { - let conn = self.conn()?; - let metrics = metrics::list_code_metrics(&conn)?; - let repos: Vec = metrics - .into_iter() - .map(|(id, m)| { - serde_json::json!({ - "repo_id": id, - "total_lines": m.total_lines, - "source_lines": m.source_lines, - "test_lines": m.test_lines, - "comment_lines": m.comment_lines, - "file_count": m.file_count, - "language_breakdown": m.language_breakdown, - "updated_at": m.updated_at.to_rfc3339() - }) - }) - .collect(); - Ok(serde_json::json!({ "success": true, "count": repos.len(), "repos": repos })) - } - - fn get_code_metrics(&self, repo_id: &str) -> anyhow::Result { - let conn = self.conn()?; - match metrics::get_code_metrics(&conn, repo_id)? { - Some(m) => Ok(serde_json::json!({ - "success": true, - "repo_id": repo_id, - "total_lines": m.total_lines, - "source_lines": m.source_lines, - "test_lines": m.test_lines, - "comment_lines": m.comment_lines, - "file_count": m.file_count, - "language_breakdown": m.language_breakdown, - "updated_at": m.updated_at.to_rfc3339() - })), - None => { - Ok(serde_json::json!({ "success": false, "error": "No metrics found for repo" })) - } - } - } - - fn get_health(&self, repo_id: &str) -> anyhow::Result { - let conn = self.conn()?; - match health::get_health(&conn, repo_id)? { - Some(h) => Ok(serde_json::json!({ - "success": true, - "repo_id": repo_id, - "status": h.status, - "ahead": h.ahead, - "behind": h.behind, - "checked_at": h.checked_at.to_rfc3339() - })), - None => Ok(serde_json::json!({ "success": false, "error": "No health data found" })), - } - } - - fn query_call_graph( - &self, - repo_id: &str, - callee: Option<&str>, - caller: Option<&str>, - file: Option<&str>, - limit: usize, - ) -> anyhow::Result { - let conn = self.conn()?; - let edges = call_graph::query_call_edges( - &conn, - repo_id, - callee.filter(|s| !s.is_empty()), - caller.filter(|s| !s.is_empty()), - file.filter(|s| !s.is_empty()), - limit, - )?; - let calls: Vec = edges - .into_iter() - .map(|e| { - serde_json::json!({ - "caller_file": e.caller_file, - "caller_symbol": e.caller_symbol, - "caller_line": e.caller_line, - "callee_name": e.callee_name, - }) - }) - .collect(); - Ok(serde_json::json!({ - "success": true, - "repo_id": repo_id, - "count": calls.len(), - "calls": calls - })) - } - - fn query_dependencies( - &self, - repo_id: &str, - direction: &str, - relation_type: Option<&str>, - ) -> anyhow::Result { - let conn = self.conn()?; - let rel_filter = relation_type.filter(|s| !s.is_empty()); - let label = if direction == "incoming" || direction == "reverse" { - "reverse dependencies" - } else { - "dependencies" - }; - let rows = if direction == "incoming" || direction == "reverse" { - crate::dependency_graph::list_reverse_dependencies(&conn, repo_id)? - } else { - crate::dependency_graph::list_dependencies(&conn, repo_id)? - }; - let deps: Vec = rows - .into_iter() - .filter(|(_, rel, _)| rel_filter.is_none_or(|f| f == rel)) - .map(|(id, rel, conf)| { - serde_json::json!({ - "repo_id": id, - "relation_type": rel, - "confidence": conf, - }) - }) - .collect(); - Ok(serde_json::json!({ - "success": true, - "repo_id": repo_id, - "direction": direction, - "label": label, - "count": deps.len(), - "dependencies": deps - })) - } - - fn query_code_symbols( - &self, - repo_id: &str, - name: Option<&str>, - symbol_type: Option<&str>, - file: Option<&str>, - limit: usize, - ) -> anyhow::Result { - let conn = self.conn()?; - let symbols = - code_symbols::query_code_symbols(&conn, repo_id, name, symbol_type, file, limit)?; - let out: Vec = symbols - .iter() - .map(|s| { - serde_json::json!({ - "file_path": s.file_path, - "symbol_type": s.symbol_type, - "name": s.name, - "line_start": s.line_start, - "line_end": s.line_end, - "signature": s.signature, - }) - }) - .collect(); - Ok(serde_json::json!({ - "success": true, - "repo_id": repo_id, - "count": out.len(), - "symbols": out - })) - } - - fn query_dead_code( - &self, - repo_id: &str, - include_pub: bool, - limit: usize, - ) -> anyhow::Result { - let conn = self.conn()?; - let dead = dead_code::query_dead_code(&conn, repo_id, include_pub, limit)?; - let out: Vec = dead - .iter() - .map(|d| { - serde_json::json!({ - "file_path": d.file_path, - "name": d.name, - "line_start": d.line_start, - "signature": d.signature, - }) - }) - .collect(); - Ok(serde_json::json!({ - "success": true, - "repo_id": repo_id, - "count": out.len(), - "dead_functions": out - })) - } - - fn save_relation( - &self, - from: &str, - to: &str, - relation_type: &str, - confidence: f64, - ) -> anyhow::Result { - let conn = self.conn()?; - relation::save_relation(&conn, from, to, relation_type, confidence)?; - Ok(serde_json::json!({ "success": true })) - } - - fn query_relations( - &self, - entity_id: &str, - direction: &str, - relation_type: Option<&str>, - ) -> anyhow::Result { - let conn = self.conn()?; - let results = match direction { - "bidirectional" => { - let rows = relation::find_related_entities(&conn, entity_id, relation_type)?; - rows.into_iter() - .map(|(from, to, rt, conf, created)| { - serde_json::json!({ - "from_entity_id": from, - "to_entity_id": to, - "relation_type": rt, - "confidence": conf, - "created_at": created - }) - }) - .collect::>() - } - "incoming" => { - let mut stmt = conn.prepare( - "SELECT from_entity_id, relation_type, confidence, created_at FROM relations - WHERE to_entity_id = ?1 - ORDER BY confidence DESC", - )?; - let rows = stmt.query_map([entity_id], |row| { - Ok(( - row.get::<_, String>(0)?, - row.get::<_, String>(1)?, - row.get::<_, f64>(2)?, - row.get::<_, String>(3)?, - )) - })?; - let filtered: Vec<_> = if let Some(rt) = relation_type.filter(|s| !s.is_empty()) { - rows.filter(|r| r.as_ref().map(|(_, t, _, _)| t == rt).unwrap_or(false)) - .collect::, _>>()? - } else { - rows.collect::, _>>()? - }; - filtered - .into_iter() - .map(|(from, rt, conf, created)| { - serde_json::json!({ - "from_entity_id": from, - "relation_type": rt, - "confidence": conf, - "created_at": created - }) - }) - .collect::>() - } - _ => { - let rows = relation::list_relations(&conn, entity_id, relation_type)?; - rows.into_iter() - .map(|(to, rt, conf, created)| { - serde_json::json!({ - "to_entity_id": to, - "relation_type": rt, - "confidence": conf, - "created_at": created - }) - }) - .collect::>() - } - }; - Ok(serde_json::json!({ "success": true, "relations": results })) - } - - fn delete_relations( - &self, - from: &str, - to: &str, - relation_type: Option<&str>, - ) -> anyhow::Result { - let conn = self.conn()?; - let count = match relation_type.filter(|s| !s.is_empty()) { - Some(rt) => conn.execute( - "DELETE FROM relations WHERE from_entity_id = ?1 AND to_entity_id = ?2 AND relation_type = ?3", - rusqlite::params![from, to, rt], - )?, - None => conn.execute( - "DELETE FROM relations WHERE from_entity_id = ?1 AND to_entity_id = ?2", - rusqlite::params![from, to], - )?, - }; - Ok(serde_json::json!({ "success": true, "deleted": count })) - } - - fn list_vault_notes(&self) -> anyhow::Result { - let conn = self.conn()?; - let notes = vault::list_vault_notes(&conn)?; - let results: Vec = notes - .into_iter() - .map(|n| { - serde_json::json!({ - "id": n.id, - "path": n.path, - "title": n.title, - "tags": n.tags, - }) - }) - .collect(); - Ok(serde_json::json!({ "success": true, "count": results.len(), "notes": results })) - } -} - -#[cfg(test)] -pub mod test_helpers; - -#[cfg(test)] -mod tests; +// SPDX-License-Identifier: MIT +// Copyright (c) 2026 juice094 +//! Registry layer: SQLite-backed entity storage and domain-specific submodules. +//! +//! Central types (`RepoEntry`, `VaultNote`, `PaperEntry`, etc.) and the +//! [`RegistryClient`] trait implementation on [`AppContext`]. +//! Submodules cover repos, health, knowledge, code metrics, call graphs, +//! dead-code analysis, and migrations. + +use crate::clients::RegistryClient; +use crate::storage::AppContext; +use chrono::{DateTime, Utc}; +use serde::{Deserialize, Serialize}; +use std::path::PathBuf; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct RemoteEntry { + pub remote_name: String, + pub upstream_url: Option, + pub default_branch: Option, + pub last_sync: Option>, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct RepoEntry { + pub id: String, + pub local_path: PathBuf, + pub tags: Vec, + pub discovered_at: DateTime, + pub language: Option, + pub workspace_type: String, + pub data_tier: String, + pub last_synced_at: Option>, + pub stars: Option, + pub remotes: Vec, +} + +/// Tags that mark a repository as "managed" for sync purposes. +/// Stored in the `repo_tags` table (not metadata) because tags are the +/// queryable, filterable dimension — metadata is for opaque JSON. +pub const MANAGED_TAGS: &[&str] = &[ + "mirror", + "reference", + "third-party", + "collaborative", + "team", + "own-project", + "tool", + "active", + "managed", +]; + +impl RepoEntry { + /// Return the 'origin' remote if present, otherwise the first remote. + pub fn primary_remote(&self) -> Option<&RemoteEntry> { + self.remotes + .iter() + .find(|r| r.remote_name == "origin") + .or_else(|| self.remotes.first()) + } + + /// Whether this repo is considered "managed" for sync/health automation. + /// Managed status is determined by the presence of any tag in [`MANAGED_TAGS`]. + pub fn is_managed(&self) -> bool { + self.tags.iter().any(|t| MANAGED_TAGS.contains(&t.as_str())) + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct VaultNote { + pub id: String, + pub path: String, + pub title: Option, + pub content: String, + pub frontmatter: Option, + pub tags: Vec, + pub outgoing_links: Vec, + pub block_refs: Vec, + pub linked_repo: Option, + pub created_at: DateTime, + pub updated_at: DateTime, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct PaperEntry { + pub id: String, + pub title: String, + pub authors: Option, + pub venue: Option, + pub year: Option, + pub pdf_path: Option, + pub bibtex: Option, + pub tags: Vec, + pub added_at: DateTime, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ExperimentEntry { + pub id: String, + pub repo_id: Option, + pub paper_id: Option, + pub config_json: Option, + pub result_path: Option, + pub git_commit: Option, + pub syncthing_folder_id: Option, + pub status: String, + pub timestamp: DateTime, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct WorkspaceRegistry { + pub version: String, + pub entries: Vec, +} + +impl Default for WorkspaceRegistry { + fn default() -> Self { + Self { + version: "0.1.0".to_string(), + entries: Vec::new(), + } + } +} + +pub use devbase_registry::health::HealthEntry; +pub use devbase_registry::metrics::CodeMetrics; +pub use devbase_registry::workspace::{OplogEntry, OplogEventType, WorkspaceSnapshot}; + +pub mod entity; +pub mod relation; + +// Backward-compatible re-exports (migrated to entity.rs in v0.15). +pub use entity::{ + ENTITY_TYPE_PAPER, ENTITY_TYPE_REPO, ENTITY_TYPE_SKILL, ENTITY_TYPE_VAULT_NOTE, + ENTITY_TYPE_WORKFLOW, upsert_entity, +}; + +pub mod agent_context; +pub mod call_graph; +pub mod code_symbols; +pub mod dead_code; +pub mod health; +pub mod import_ontology; +pub mod knowledge; +pub mod knowledge_meta; +pub mod known_limits; +pub mod links; +pub mod metrics; +mod migrate; +pub mod migrations; +pub mod repo; +pub mod repos_toml; +pub mod vault; +pub mod workspace; + +impl RegistryClient for AppContext { + fn list_repos(&self, _filter: Option<&str>) -> anyhow::Result { + let conn = self.conn()?; + let repos = repo::list_repos(&conn)?; + let results: Vec = repos + .into_iter() + .map(|r| { + serde_json::json!({ + "id": r.id, + "local_path": r.local_path, + "language": r.language, + "tags": r.tags, + "workspace_type": r.workspace_type, + "data_tier": r.data_tier, + }) + }) + .collect(); + Ok(serde_json::json!({ "success": true, "count": results.len(), "repos": results })) + } + + fn get_repo(&self, repo_id: &str) -> anyhow::Result { + let conn = self.conn()?; + let repos = repo::list_repos(&conn)?; + match repos.into_iter().find(|r| r.id == repo_id) { + Some(r) => Ok(serde_json::json!({ + "success": true, + "id": r.id, + "local_path": r.local_path, + "language": r.language, + "tags": r.tags, + "workspace_type": r.workspace_type, + "data_tier": r.data_tier, + })), + None => Ok(serde_json::json!({ "success": false, "error": "repo not found" })), + } + } + + fn list_modules(&self, repo_id: &str) -> anyhow::Result { + let conn = self.conn()?; + let modules = knowledge::list_modules(&conn, repo_id)?; + let results: Vec = modules + .into_iter() + .map(|(name, ty, path)| { + serde_json::json!({ + "name": name, + "type": ty, + "path": path, + }) + }) + .collect(); + Ok(serde_json::json!({ "success": true, "count": results.len(), "modules": results })) + } + + fn save_paper(&self, paper: &serde_json::Value) -> anyhow::Result { + let conn = self.conn()?; + let paper_entry: PaperEntry = serde_json::from_value(paper.clone())?; + knowledge::save_paper(&conn, &paper_entry)?; + Ok(serde_json::json!({ "success": true })) + } + + fn save_experiment(&self, exp: &serde_json::Value) -> anyhow::Result { + let conn = self.conn()?; + let exp_entry: ExperimentEntry = serde_json::from_value(exp.clone())?; + WorkspaceRegistry::save_experiment(&conn, &exp_entry)?; + Ok(serde_json::json!({ "success": true })) + } + + fn list_code_metrics(&self) -> anyhow::Result { + let conn = self.conn()?; + let metrics = metrics::list_code_metrics(&conn)?; + let repos: Vec = metrics + .into_iter() + .map(|(id, m)| { + serde_json::json!({ + "repo_id": id, + "total_lines": m.total_lines, + "source_lines": m.source_lines, + "test_lines": m.test_lines, + "comment_lines": m.comment_lines, + "file_count": m.file_count, + "language_breakdown": m.language_breakdown, + "updated_at": m.updated_at.to_rfc3339() + }) + }) + .collect(); + Ok(serde_json::json!({ "success": true, "count": repos.len(), "repos": repos })) + } + + fn get_code_metrics(&self, repo_id: &str) -> anyhow::Result { + let conn = self.conn()?; + match metrics::get_code_metrics(&conn, repo_id)? { + Some(m) => Ok(serde_json::json!({ + "success": true, + "repo_id": repo_id, + "total_lines": m.total_lines, + "source_lines": m.source_lines, + "test_lines": m.test_lines, + "comment_lines": m.comment_lines, + "file_count": m.file_count, + "language_breakdown": m.language_breakdown, + "updated_at": m.updated_at.to_rfc3339() + })), + None => { + Ok(serde_json::json!({ "success": false, "error": "No metrics found for repo" })) + } + } + } + + fn get_health(&self, repo_id: &str) -> anyhow::Result { + let conn = self.conn()?; + match health::get_health(&conn, repo_id)? { + Some(h) => Ok(serde_json::json!({ + "success": true, + "repo_id": repo_id, + "status": h.status, + "ahead": h.ahead, + "behind": h.behind, + "checked_at": h.checked_at.to_rfc3339() + })), + None => Ok(serde_json::json!({ "success": false, "error": "No health data found" })), + } + } + + fn query_call_graph( + &self, + repo_id: &str, + callee: Option<&str>, + caller: Option<&str>, + file: Option<&str>, + limit: usize, + ) -> anyhow::Result { + let conn = self.conn()?; + let edges = call_graph::query_call_edges( + &conn, + repo_id, + callee.filter(|s| !s.is_empty()), + caller.filter(|s| !s.is_empty()), + file.filter(|s| !s.is_empty()), + limit, + )?; + let calls: Vec = edges + .into_iter() + .map(|e| { + serde_json::json!({ + "caller_file": e.caller_file, + "caller_symbol": e.caller_symbol, + "caller_line": e.caller_line, + "callee_name": e.callee_name, + }) + }) + .collect(); + Ok(serde_json::json!({ + "success": true, + "repo_id": repo_id, + "count": calls.len(), + "calls": calls + })) + } + + fn query_dependencies( + &self, + repo_id: &str, + direction: &str, + relation_type: Option<&str>, + ) -> anyhow::Result { + let conn = self.conn()?; + let rel_filter = relation_type.filter(|s| !s.is_empty()); + let label = if direction == "incoming" || direction == "reverse" { + "reverse dependencies" + } else { + "dependencies" + }; + let rows = if direction == "incoming" || direction == "reverse" { + crate::dependency_graph::list_reverse_dependencies(&conn, repo_id)? + } else { + crate::dependency_graph::list_dependencies(&conn, repo_id)? + }; + let deps: Vec = rows + .into_iter() + .filter(|(_, rel, _)| rel_filter.is_none_or(|f| f == rel)) + .map(|(id, rel, conf)| { + serde_json::json!({ + "repo_id": id, + "relation_type": rel, + "confidence": conf, + }) + }) + .collect(); + Ok(serde_json::json!({ + "success": true, + "repo_id": repo_id, + "direction": direction, + "label": label, + "count": deps.len(), + "dependencies": deps + })) + } + + fn query_code_symbols( + &self, + repo_id: &str, + name: Option<&str>, + symbol_type: Option<&str>, + file: Option<&str>, + limit: usize, + ) -> anyhow::Result { + let conn = self.conn()?; + let symbols = + code_symbols::query_code_symbols(&conn, repo_id, name, symbol_type, file, limit)?; + let out: Vec = symbols + .iter() + .map(|s| { + serde_json::json!({ + "file_path": s.file_path, + "symbol_type": s.symbol_type, + "name": s.name, + "line_start": s.line_start, + "line_end": s.line_end, + "signature": s.signature, + }) + }) + .collect(); + Ok(serde_json::json!({ + "success": true, + "repo_id": repo_id, + "count": out.len(), + "symbols": out + })) + } + + fn query_dead_code( + &self, + repo_id: &str, + include_pub: bool, + limit: usize, + ) -> anyhow::Result { + let conn = self.conn()?; + let dead = dead_code::query_dead_code(&conn, repo_id, include_pub, limit)?; + let out: Vec = dead + .iter() + .map(|d| { + serde_json::json!({ + "file_path": d.file_path, + "name": d.name, + "line_start": d.line_start, + "signature": d.signature, + }) + }) + .collect(); + Ok(serde_json::json!({ + "success": true, + "repo_id": repo_id, + "count": out.len(), + "dead_functions": out + })) + } + + fn save_relation( + &self, + from: &str, + to: &str, + relation_type: &str, + confidence: f64, + ) -> anyhow::Result { + let conn = self.conn()?; + relation::save_relation(&conn, from, to, relation_type, confidence)?; + Ok(serde_json::json!({ "success": true })) + } + + fn query_relations( + &self, + entity_id: &str, + direction: &str, + relation_type: Option<&str>, + ) -> anyhow::Result { + let conn = self.conn()?; + let results = match direction { + "bidirectional" => { + let rows = relation::find_related_entities(&conn, entity_id, relation_type)?; + rows.into_iter() + .map(|(from, to, rt, conf, created)| { + serde_json::json!({ + "from_entity_id": from, + "to_entity_id": to, + "relation_type": rt, + "confidence": conf, + "created_at": created + }) + }) + .collect::>() + } + "incoming" => { + let mut stmt = conn.prepare( + "SELECT from_entity_id, relation_type, confidence, created_at FROM relations + WHERE to_entity_id = ?1 + ORDER BY confidence DESC", + )?; + let rows = stmt.query_map([entity_id], |row| { + Ok(( + row.get::<_, String>(0)?, + row.get::<_, String>(1)?, + row.get::<_, f64>(2)?, + row.get::<_, String>(3)?, + )) + })?; + let filtered: Vec<_> = if let Some(rt) = relation_type.filter(|s| !s.is_empty()) { + rows.filter(|r| r.as_ref().map(|(_, t, _, _)| t == rt).unwrap_or(false)) + .collect::, _>>()? + } else { + rows.collect::, _>>()? + }; + filtered + .into_iter() + .map(|(from, rt, conf, created)| { + serde_json::json!({ + "from_entity_id": from, + "relation_type": rt, + "confidence": conf, + "created_at": created + }) + }) + .collect::>() + } + _ => { + let rows = relation::list_relations(&conn, entity_id, relation_type)?; + rows.into_iter() + .map(|(to, rt, conf, created)| { + serde_json::json!({ + "to_entity_id": to, + "relation_type": rt, + "confidence": conf, + "created_at": created + }) + }) + .collect::>() + } + }; + Ok(serde_json::json!({ "success": true, "relations": results })) + } + + fn delete_relations( + &self, + from: &str, + to: &str, + relation_type: Option<&str>, + ) -> anyhow::Result { + let conn = self.conn()?; + let count = match relation_type.filter(|s| !s.is_empty()) { + Some(rt) => conn.execute( + "DELETE FROM relations WHERE from_entity_id = ?1 AND to_entity_id = ?2 AND relation_type = ?3", + rusqlite::params![from, to, rt], + )?, + None => conn.execute( + "DELETE FROM relations WHERE from_entity_id = ?1 AND to_entity_id = ?2", + rusqlite::params![from, to], + )?, + }; + Ok(serde_json::json!({ "success": true, "deleted": count })) + } + + fn list_vault_notes(&self) -> anyhow::Result { + let conn = self.conn()?; + let notes = vault::list_vault_notes(&conn)?; + let results: Vec = notes + .into_iter() + .map(|n| { + serde_json::json!({ + "id": n.id, + "path": n.path, + "title": n.title, + "tags": n.tags, + }) + }) + .collect(); + Ok(serde_json::json!({ "success": true, "count": results.len(), "notes": results })) + } +} + +#[cfg(test)] +pub mod test_helpers; + +#[cfg(test)] +mod tests; diff --git a/src/registry/import_ontology.rs b/src/registry/import_ontology.rs new file mode 100644 index 0000000..e42ddb3 --- /dev/null +++ b/src/registry/import_ontology.rs @@ -0,0 +1,221 @@ +use std::path::Path; + +use rusqlite::Connection; + +type Result = std::result::Result; + +/// Statistics from an ontology import run. +#[derive(Debug, Clone, Default)] +pub struct OntologyImportStats { + pub entities_added: usize, + pub entities_updated: usize, + pub relations_added: usize, + pub relations_updated: usize, + pub errors: Vec, +} + +/// Import ontology entities and relations from an OpenClaw-compatible workspace. +pub fn import_ontology( + conn: &Connection, + workspace_path: &Path, +) -> Result { + let entities_dir = workspace_path.join("ontology").join("entities"); + let relations_file = workspace_path.join("ontology").join("relations").join("core-relations.jsonl"); + + let mut stats = OntologyImportStats::default(); + + // Phase 1: Import entities + if entities_dir.is_dir() { + for entry in std::fs::read_dir(&entities_dir)? { + let entry = entry?; + let path = entry.path(); + if path.extension().map_or(false, |e| e == "json") { + match import_entity_file(conn, &path) { + Ok((added, updated)) => { + stats.entities_added += added; + stats.entities_updated += updated; + } + Err(e) => { + stats.errors.push(format!("{}: {}", path.display(), e)); + } + } + } + } + } + + // Phase 2: Import relations + if relations_file.exists() { + match import_relations_file(conn, &relations_file) { + Ok((added, updated)) => { + stats.relations_added += added; + stats.relations_updated += updated; + } + Err(e) => { + stats.errors.push(format!("{}: {}", relations_file.display(), e)); + } + } + } + + Ok(stats) +} + +fn import_entity_file(conn: &Connection, path: &Path) -> Result<(usize, usize)> { + let content = std::fs::read_to_string(path)?; + let entity: serde_json::Value = serde_json::from_str(&content)?; + + let entity_id = entity["entity_id"].as_str().unwrap_or("unknown"); + let entity_type = entity["type"].as_str().unwrap_or("ontology_node"); + let name = entity["name"].as_str().unwrap_or(entity_id); + + // Ensure entity type exists + conn.execute( + "INSERT OR IGNORE INTO entity_types (name, schema_json, description, created_at) VALUES (?1, '{}', ?2, datetime('now'))", + rusqlite::params![entity_type, format!("Ontology entity type: {}", entity_type)], + )?; + + let metadata = serde_json::to_string(&entity).unwrap_or_default(); + let now = chrono::Utc::now().to_rfc3339(); + let existing: Option = conn + .query_row( + "SELECT id FROM entities WHERE id = ?1", + rusqlite::params![entity_id], + |row| row.get(0), + ) + .ok(); + + conn.execute( + "INSERT INTO entities (id, entity_type, name, metadata, created_at, updated_at) + VALUES (?1, ?2, ?3, ?4, ?5, ?5) + ON CONFLICT(id) DO UPDATE SET + entity_type = excluded.entity_type, + name = excluded.name, + metadata = excluded.metadata, + updated_at = excluded.updated_at", + rusqlite::params![entity_id, entity_type, name, metadata, now], + )?; + + if existing.is_some() { + Ok((0, 1)) + } else { + Ok((1, 0)) + } +} + +fn import_relations_file(conn: &Connection, path: &Path) -> Result<(usize, usize)> { + let content = std::fs::read_to_string(path)?; + let mut added = 0usize; + let mut updated = 0usize; + + for line in content.lines() { + let trimmed = line.trim(); + if trimmed.is_empty() { + continue; + } + + let rel: serde_json::Value = match serde_json::from_str(trimmed) { + Ok(v) => v, + Err(e) => { + tracing::warn!("Skipping malformed relation line: {} ({})", trimmed, e); + continue; + } + }; + + let relation_id = rel["relation_id"].as_str().unwrap_or(""); + let rel_type = rel["type"].as_str().unwrap_or("unknown"); + let from_id = rel["from"].as_str().unwrap_or(""); + let to_id = rel["to"].as_str().unwrap_or(""); + + if relation_id.is_empty() || from_id.is_empty() || to_id.is_empty() { + continue; + } + + let metadata = serde_json::to_string(&rel).unwrap_or_default(); + let now = chrono::Utc::now().to_rfc3339(); + let exists = conn + .query_row( + "SELECT id FROM relations WHERE from_entity_id = ?1 AND to_entity_id = ?2 AND relation_type = ?3", + rusqlite::params![from_id, to_id, rel_type], + |row| row.get::<_, String>(0), + ) + .is_ok(); + + // Skip relations referencing non-existent entities (FK constraint) + let from_exists: bool = conn + .query_row( + "SELECT 1 FROM entities WHERE id = ?1", + rusqlite::params![from_id], + |_| Ok(true), + ) + .unwrap_or(false); + let to_exists: bool = conn + .query_row( + "SELECT 1 FROM entities WHERE id = ?1", + rusqlite::params![to_id], + |_| Ok(true), + ) + .unwrap_or(false); + if !from_exists || !to_exists { + tracing::warn!("Skipping relation {}: from or to entity not found", relation_id); + continue; + } + + let conn_exec = conn.execute( + "INSERT OR REPLACE INTO relations (id, from_entity_id, to_entity_id, relation_type, metadata, confidence, created_at) + VALUES (?1, ?2, ?3, ?4, ?5, 1.0, ?6)", + rusqlite::params![relation_id, from_id, to_id, rel_type, metadata, now], + ); + if let Err(e) = conn_exec { + tracing::warn!("Failed to insert relation {}: {}", relation_id, e); + continue; + } + + if exists { + updated += 1; + } else { + added += 1; + } + } + + Ok((added, updated)) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::registry::WorkspaceRegistry; + + #[test] + fn test_import_ontology_from_temp() { + let tmp = std::env::temp_dir().join(format!("devbase_onto_{}", std::process::id())); + let entities_dir = tmp.join("ontology").join("entities"); + let relations_dir = tmp.join("ontology").join("relations"); + std::fs::create_dir_all(&entities_dir).unwrap(); + std::fs::create_dir_all(&relations_dir).unwrap(); + + std::fs::write( + entities_dir.join("person-a.json"), + r#"{"entity_id":"person-a","type":"person","name":"Alpha","aliases":["a"]}"#, + ) + .unwrap(); + std::fs::write( + entities_dir.join("person-b.json"), + r#"{"entity_id":"person-b","type":"person","name":"Beta","aliases":["b"]}"#, + ) + .unwrap(); + std::fs::write( + relations_dir.join("core-relations.jsonl"), + r#"{"relation_id":"r-test","type":"knows","from":"person-a","to":"person-b"} +{"relation_id":"r-test2","type":"collaborates","from":"person-b","to":"person-a"}"#, + ) + .unwrap(); + + let conn = WorkspaceRegistry::init_in_memory().unwrap(); + let stats = import_ontology(&conn, &tmp).unwrap(); + + assert_eq!(stats.entities_added, 2); + assert_eq!(stats.relations_added, 2); + assert!(stats.errors.is_empty()); + + std::fs::remove_dir_all(&tmp).unwrap(); + } +} diff --git a/src/registry/migrate.rs b/src/registry/migrate.rs index 913ecf6..4e926aa 100644 --- a/src/registry/migrate.rs +++ b/src/registry/migrate.rs @@ -4,7 +4,7 @@ use super::*; use crate::storage::StorageBackend; use std::path::PathBuf; -pub const CURRENT_SCHEMA_VERSION: i32 = 34; +pub const CURRENT_SCHEMA_VERSION: i32 = 36; impl WorkspaceRegistry { pub fn db_path() -> anyhow::Result { diff --git a/src/registry/migrations/mod.rs b/src/registry/migrations/mod.rs index 01de61d..ca97093 100644 --- a/src/registry/migrations/mod.rs +++ b/src/registry/migrations/mod.rs @@ -36,6 +36,8 @@ pub mod v31_agent_contexts; pub mod v32_context_links; pub mod v33_workflow_context; pub mod v34_memory_vectors; +pub mod v35_skill_fts; +pub mod v36_skill_sources; pub fn run_all(conn: &mut Connection) -> anyhow::Result<()> { let user_version: i32 = conn.query_row("PRAGMA user_version", [], |row| row.get(0))?; @@ -142,6 +144,12 @@ pub fn run_all(conn: &mut Connection) -> anyhow::Result<()> { if user_version < 34 { v34_memory_vectors::run(conn)?; } + if user_version < 35 { + v35_skill_fts::run(conn)?; + } + if user_version < 36 { + v36_skill_sources::run(conn)?; + } Ok(()) } diff --git a/src/registry/migrations/v35_skill_fts.rs b/src/registry/migrations/v35_skill_fts.rs new file mode 100644 index 0000000..5be6369 --- /dev/null +++ b/src/registry/migrations/v35_skill_fts.rs @@ -0,0 +1,35 @@ +use rusqlite::Connection; + +pub fn run(conn: &Connection) -> anyhow::Result<()> { + conn.execute_batch( + "CREATE VIRTUAL TABLE IF NOT EXISTS skills_fts USING fts5( + name, + description, + tags, + category, + content='skills', + content_rowid='rowid', + tokenize='unicode61' + ); + + CREATE TRIGGER IF NOT EXISTS skills_fts_ai AFTER INSERT ON skills BEGIN + INSERT INTO skills_fts(rowid, name, description, tags, category) + VALUES (new.rowid, new.name, new.description, new.tags, new.category); + END; + + CREATE TRIGGER IF NOT EXISTS skills_fts_ad AFTER DELETE ON skills BEGIN + INSERT INTO skills_fts(skills_fts, rowid, name, description, tags, category) + VALUES ('delete', old.rowid, old.name, old.description, old.tags, old.category); + END; + + CREATE TRIGGER IF NOT EXISTS skills_fts_au AFTER UPDATE ON skills BEGIN + INSERT INTO skills_fts(skills_fts, rowid, name, description, tags, category) + VALUES ('delete', old.rowid, old.name, old.description, old.tags, old.category); + INSERT INTO skills_fts(rowid, name, description, tags, category) + VALUES (new.rowid, new.name, new.description, new.tags, new.category); + END;", + )?; + + conn.execute("PRAGMA user_version = 35", [])?; + Ok(()) +} diff --git a/src/registry/migrations/v36_skill_sources.rs b/src/registry/migrations/v36_skill_sources.rs new file mode 100644 index 0000000..71f5e38 --- /dev/null +++ b/src/registry/migrations/v36_skill_sources.rs @@ -0,0 +1,29 @@ +use rusqlite::Connection; + +pub fn run(conn: &Connection) -> anyhow::Result<()> { + conn.execute_batch( + "CREATE TABLE IF NOT EXISTS sync_sources ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + name TEXT NOT NULL UNIQUE, + url TEXT NOT NULL, + source_type TEXT NOT NULL DEFAULT 'github', + enabled INTEGER NOT NULL DEFAULT 1, + last_sync_at TEXT, + created_at TEXT NOT NULL DEFAULT (datetime('now')) + ); + + CREATE TABLE IF NOT EXISTS sync_log ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + source_name TEXT NOT NULL, + status TEXT NOT NULL, + skills_added INTEGER NOT NULL DEFAULT 0, + skills_updated INTEGER NOT NULL DEFAULT 0, + error_message TEXT, + started_at TEXT NOT NULL DEFAULT (datetime('now')), + finished_at TEXT + );", + )?; + + conn.execute("PRAGMA user_version = 36", [])?; + Ok(()) +} diff --git a/src/registry/test_helpers.rs b/src/registry/test_helpers.rs index 13385d7..f990516 100644 --- a/src/registry/test_helpers.rs +++ b/src/registry/test_helpers.rs @@ -195,6 +195,33 @@ CREATE TABLE IF NOT EXISTS skills ( ); CREATE INDEX IF NOT EXISTS idx_skills_type ON skills(skill_type); +CREATE VIRTUAL TABLE IF NOT EXISTS skills_fts USING fts5( + name, + description, + tags, + category, + content='skills', + content_rowid='rowid', + tokenize='unicode61' +); + +CREATE TRIGGER IF NOT EXISTS skills_fts_ai AFTER INSERT ON skills BEGIN + INSERT INTO skills_fts(rowid, name, description, tags, category) + VALUES (new.rowid, new.name, new.description, new.tags, new.category); +END; + +CREATE TRIGGER IF NOT EXISTS skills_fts_ad AFTER DELETE ON skills BEGIN + INSERT INTO skills_fts(skills_fts, rowid, name, description, tags, category) + VALUES ('delete', old.rowid, old.name, old.description, old.tags, old.category); +END; + +CREATE TRIGGER IF NOT EXISTS skills_fts_au AFTER UPDATE ON skills BEGIN + INSERT INTO skills_fts(skills_fts, rowid, name, description, tags, category) + VALUES ('delete', old.rowid, old.name, old.description, old.tags, old.category); + INSERT INTO skills_fts(rowid, name, description, tags, category) + VALUES (new.rowid, new.name, new.description, new.tags, new.category); +END; + CREATE TABLE IF NOT EXISTS skill_executions ( id INTEGER PRIMARY KEY AUTOINCREMENT, skill_id TEXT NOT NULL REFERENCES skills(id) ON DELETE CASCADE, @@ -208,6 +235,27 @@ CREATE TABLE IF NOT EXISTS skill_executions ( duration_ms INTEGER ); +CREATE TABLE IF NOT EXISTS sync_sources ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + name TEXT NOT NULL UNIQUE, + url TEXT NOT NULL, + source_type TEXT NOT NULL DEFAULT 'github', + enabled INTEGER NOT NULL DEFAULT 1, + last_sync_at TEXT, + created_at TEXT NOT NULL DEFAULT (datetime('now')) +); + +CREATE TABLE IF NOT EXISTS sync_log ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + source_name TEXT NOT NULL, + status TEXT NOT NULL, + skills_added INTEGER NOT NULL DEFAULT 0, + skills_updated INTEGER NOT NULL DEFAULT 0, + error_message TEXT, + started_at TEXT NOT NULL DEFAULT (datetime('now')), + finished_at TEXT +); + -- v16: Unified Entity Model CREATE TABLE IF NOT EXISTS entity_types ( name TEXT PRIMARY KEY, diff --git a/src/skill_runtime/mod.rs b/src/skill_runtime/mod.rs index 31f3445..442808c 100644 --- a/src/skill_runtime/mod.rs +++ b/src/skill_runtime/mod.rs @@ -8,6 +8,7 @@ pub mod parser; pub mod publish; pub mod registry; pub mod scoring; +pub mod sources; // Types migrated to devbase-skill-runtime-types crate. pub use devbase_skill_runtime_types::*; diff --git a/src/skill_runtime/registry.rs b/src/skill_runtime/registry.rs index cf76517..4216bcf 100644 --- a/src/skill_runtime/registry.rs +++ b/src/skill_runtime/registry.rs @@ -208,12 +208,67 @@ pub fn list_skills( rows.collect::, _>>().map_err(Into::into) } -/// Full-text search on skill name and description. +/// Full-text search on skill name, description, tags, and category. +/// Uses FTS5 with BM25 ranking when the FTS index is available, +/// falling back to SQLite LIKE for cases where FTS5 returns no results. pub fn search_skills_text( conn: &Connection, query: &str, limit: usize, category: Option<&str>, +) -> anyhow::Result> { + // Try FTS5 first with BM25 ranking + if let Ok(results) = search_skills_fts5(conn, query, limit, category) { + if !results.is_empty() { + return Ok(results); + } + } + // Fallback to LIKE for empty results or FTS5 errors + search_skills_like(conn, query, limit, category) +} + +fn search_skills_fts5( + conn: &Connection, + query: &str, + limit: usize, + category: Option<&str>, +) -> anyhow::Result> { + let fts_query = build_fts5_query(query); + + let sql = if category.is_some() { + "SELECT s.id, s.name, s.version, s.description, s.author, s.tags, s.entry_script, + s.skill_type, s.local_path, s.installed_at, s.updated_at, s.last_used_at, + s.dependencies, s.category + FROM skills_fts f + JOIN skills s ON s.rowid = f.rowid + WHERE skills_fts MATCH ?1 AND s.category = ?2 + ORDER BY bm25(skills_fts, 1.0, 0.8, 0.4, 0.2) ASC + LIMIT ?3" + } else { + "SELECT s.id, s.name, s.version, s.description, s.author, s.tags, s.entry_script, + s.skill_type, s.local_path, s.installed_at, s.updated_at, s.last_used_at, + s.dependencies, s.category + FROM skills_fts f + JOIN skills s ON s.rowid = f.rowid + WHERE skills_fts MATCH ?1 + ORDER BY bm25(skills_fts, 1.0, 0.8, 0.4, 0.2) ASC + LIMIT ?2" + }; + + let mut stmt = conn.prepare(sql)?; + let rows = if let Some(cat) = category { + stmt.query_map(params![&fts_query, cat, limit as i64], skill_row_from_sql)? + } else { + stmt.query_map(params![&fts_query, limit as i64], skill_row_from_sql)? + }; + rows.collect::, _>>().map_err(Into::into) +} + +fn search_skills_like( + conn: &Connection, + query: &str, + limit: usize, + category: Option<&str>, ) -> anyhow::Result> { let pattern = format!("%{}%", query.replace('%', "\\%").replace('_', "\\_")); let sql = if category.is_some() { @@ -240,6 +295,26 @@ pub fn search_skills_text( rows.collect::, _>>().map_err(Into::into) } +/// Build a safe FTS5 query string from user input. +/// Multi-word queries are AND'ed; empty input matches all. +fn build_fts5_query(text: &str) -> String { + let trimmed = text.trim(); + if trimmed.is_empty() { + return "*".to_string(); + } + let terms: Vec<&str> = trimmed.split_whitespace().collect(); + if terms.len() == 1 { + // Escape double-quotes within a term to avoid FTS5 syntax errors + format!("\"{}\"", terms[0].replace('"', "\"\"")) + } else { + terms + .iter() + .map(|t| format!("\"{}\"", t.replace('"', "\"\""))) + .collect::>() + .join(" AND ") + } +} + /// Semantic search on skill descriptions using cosine similarity. pub fn search_skills_semantic( conn: &Connection, diff --git a/src/skill_runtime/sources.rs b/src/skill_runtime/sources.rs new file mode 100644 index 0000000..72d1390 --- /dev/null +++ b/src/skill_runtime/sources.rs @@ -0,0 +1,277 @@ +use std::path::Path; + +use async_trait::async_trait; +use chrono::Utc; + +use super::{SkillMeta, SkillType}; + +/// Trait for pluggable external skill sources. +/// Each implementation knows how to fetch skills from a specific origin +/// (GitHub repo, HTTP endpoint, local directory, etc.). +#[async_trait] +pub trait SkillSource: Send + Sync { + /// Human-readable name for this source (e.g., "github:anthropics/skills"). + fn name(&self) -> &str; + + /// Fetch skills from this source. Called by the sync pipeline. + async fn fetch(&self) -> anyhow::Result>; +} + +// ── GitHub Source ────────────────────────────────────────────────── + +pub struct GitHubSource { + pub owner: String, + pub repo: String, + /// Path within the repo to scan for SKILL.md files (e.g., "skills"). + pub path: String, + client: reqwest::Client, +} + +impl GitHubSource { + pub fn new(owner: &str, repo: &str, path: &str) -> Self { + GitHubSource { + owner: owner.to_string(), + repo: repo.to_string(), + path: path.to_string(), + client: reqwest::Client::new(), + } + } +} + +#[async_trait] +impl SkillSource for GitHubSource { + fn name(&self) -> &str { + "github" + } + + async fn fetch(&self) -> anyhow::Result> { + let url = format!( + "https://api.github.com/repos/{}/{}/contents/{}", + self.owner, self.repo, self.path + ); + + let config = crate::config::Config::load()?; + let mut req = self + .client + .get(&url) + .header("User-Agent", "devbase-skill-sync") + .header("Accept", "application/vnd.github.v3+json"); + + if let Some(token) = config.github.token.as_deref() { + req = req.header("Authorization", format!("Bearer {}", token)); + } + + let resp = req.send().await?; + if !resp.status().is_success() { + return Err(anyhow::anyhow!( + "GitHub API returned {} for {}/{}", + resp.status(), + self.owner, + self.repo + )); + } + + let entries: Vec = resp.json().await?; + let mut skills = Vec::new(); + + for entry in entries { + let entry_type = entry["type"].as_str().unwrap_or(""); + let name = entry["name"].as_str().unwrap_or("unknown"); + + // Handle directories by recursing (Box::pin required for recursive async fn) + if entry_type == "dir" { + let dir_source = GitHubSource::new( + &self.owner, + &self.repo, + &format!("{}/{}", self.path, name), + ); + let fut = Box::pin(dir_source.fetch()); + if let Ok(dir_skills) = fut.await { + skills.extend(dir_skills); + } + continue; + } + + if !name.ends_with(".md") { + continue; + } + + let download_url = entry["download_url"].as_str().unwrap_or(""); + let html_url = entry["html_url"].as_str().unwrap_or(""); + if download_url.is_empty() { + continue; + } + + let content = match self + .client + .get(download_url) + .header("User-Agent", "devbase-skill-sync") + .send() + .await + { + Ok(resp) => resp.text().await.unwrap_or_default(), + Err(_) => continue, + }; + + let skill_id = name.trim_end_matches(".md").to_lowercase().replace('_', "-"); + + // Try parsing as SKILL.md first; fall back to plain markdown extraction + let skill_meta = if content.contains("---") { + parse_skill_or_extract(&content, &skill_id, html_url) + } else { + extract_skill_from_md(&content, &skill_id, html_url) + }; + + skills.push(skill_meta); + } + + Ok(skills) + } +} + +// ── Local File Source ────────────────────────────────────────────── + +pub struct LocalFileSource { + pub name_str: String, + pub dir_path: std::path::PathBuf, +} + +impl LocalFileSource { + pub fn new(name: &str, dir_path: &Path) -> Self { + LocalFileSource { + name_str: name.to_string(), + dir_path: dir_path.to_path_buf(), + } + } +} + +#[async_trait] +impl SkillSource for LocalFileSource { + fn name(&self) -> &str { + &self.name_str + } + + async fn fetch(&self) -> anyhow::Result> { + let mut skills = Vec::new(); + scan_dir_for_skills(&self.dir_path, &mut skills)?; + Ok(skills) + } +} + +fn scan_dir_for_skills(dir: &Path, skills: &mut Vec) -> anyhow::Result<()> { + if !dir.is_dir() { + return Ok(()); + } + for entry in std::fs::read_dir(dir)? { + let entry = entry?; + let path = entry.path(); + if path.is_dir() { + scan_dir_for_skills(&path, skills)?; + } else if path.extension().map_or(false, |e| e == "md") { + let content = std::fs::read_to_string(&path)?; + let name = path + .file_stem() + .unwrap_or_default() + .to_string_lossy() + .to_string(); + let skill_id = name.to_lowercase().replace('_', "-"); + let skill_meta = if content.contains("---") { + parse_skill_or_extract(&content, &skill_id, "") + } else { + extract_skill_from_md(&content, &skill_id, "") + }; + skills.push(skill_meta); + } + } + Ok(()) +} + +// ── Helpers ──────────────────────────────────────────────────────── + +fn parse_skill_or_extract(content: &str, skill_id: &str, source_url: &str) -> SkillMeta { + // Try the proper SKILL.md parser first + let skill_dir = std::env::temp_dir().join(format!("devbase-skill-import-{}", skill_id)); + std::fs::create_dir_all(&skill_dir).ok(); + let skill_md = skill_dir.join("SKILL.md"); + std::fs::write(&skill_md, content).ok(); + + let mut skill = crate::skill_runtime::parser::parse_skill_md(&skill_md) + .unwrap_or_else(|_| extract_skill_from_md(content, skill_id, source_url)); + + // Override with our computed id + let old_id = skill.id.clone(); + skill.id = skill_id.to_string(); + skill.local_path = skill_dir; + skill.skill_type = SkillType::Custom; + + // If the parser didn't pick up the description, try extracting + if skill.description.is_empty() || skill.description == old_id { + skill.description = extract_description(content); + } + + skill +} + +fn extract_skill_from_md(content: &str, skill_id: &str, _source_url: &str) -> SkillMeta { + let description = extract_description(content); + let tags = extract_tags(content); + + SkillMeta { + id: skill_id.to_string(), + name: skill_id.to_string(), + version: "0.1.0".to_string(), + description, + author: None, + tags, + entry_script: None, + category: None, + skill_type: SkillType::Custom, + local_path: std::path::PathBuf::new(), + inputs: vec![], + outputs: vec![], + dependencies: vec![], + embedding: None, + installed_at: Utc::now(), + updated_at: Utc::now(), + last_used_at: None, + body: content.to_string(), + } +} + +fn extract_description(content: &str) -> String { + for line in content.lines() { + let trimmed = line.trim(); + if let Some(desc) = trimmed.strip_prefix("description:") { + return desc.trim().trim_matches('"').to_string(); + } + } + content + .lines() + .find(|l| { + let t = l.trim(); + !t.is_empty() && !t.starts_with('#') && !t.starts_with("---") + }) + .unwrap_or("") + .trim() + .to_string() +} + +fn extract_tags(content: &str) -> Vec { + for line in content.lines() { + let trimmed = line.trim(); + if let Some(tags_str) = trimmed.strip_prefix("tags:") { + return tags_str + .split(',') + .map(|t| { + t.trim() + .trim_matches('"') + .trim_matches('[') + .trim_matches(']') + .to_string() + }) + .filter(|t| !t.is_empty()) + .collect(); + } + } + vec![] +} diff --git a/src/vault/mod.rs b/src/vault/mod.rs index cbfc0e0..7f108d0 100644 --- a/src/vault/mod.rs +++ b/src/vault/mod.rs @@ -1,287 +1,289 @@ -// SPDX-License-Identifier: MIT -// Copyright (c) 2026 juice094 -pub mod backlinks; -pub mod export; -pub mod frontmatter; -pub mod fs_io; -pub mod history; -pub mod indexer; -pub mod scanner; -pub mod wikilink; - -use crate::storage::AppContext; - -impl crate::clients::VaultClient for AppContext { - fn list_vault_notes(&self) -> anyhow::Result { - let conn = self.conn()?; - let notes = crate::registry::vault::list_vault_notes(&conn)?; - let results: Vec = notes - .into_iter() - .map(|n| { - serde_json::json!({ - "id": n.id, - "path": n.path, - "title": n.title, - "tags": n.tags, - }) - }) - .collect(); - Ok(serde_json::json!({"success": true, "count": results.len(), "notes": results})) - } - - fn read_vault_note(&self, path: &str) -> anyhow::Result { - let (body, frontmatter) = fs_io::read_note_body(path) - .ok_or_else(|| anyhow::anyhow!("note not found or unreadable"))?; - Ok(serde_json::json!({ - "success": true, - "path": path, - "content": body, - "frontmatter": frontmatter, - })) - } - - fn get_backlinks(&self, note_id: &str) -> anyhow::Result { - let backlinks = match self.conn() { - Ok(conn) => match crate::registry::vault::list_vault_notes(&conn) { - Ok(notes) => notes - .into_iter() - .filter(|n| { - n.outgoing_links.iter().any(|l| { - let normalized = l.replace('\\', "/"); - normalized == note_id.replace('\\', "/") - || normalized - == note_id - .replace('\\', "/") - .strip_suffix(".md") - .unwrap_or(¬e_id.replace('\\', "/")) - || l == note_id - }) - }) - .map(|n| n.id.replace('\\', "/")) - .collect(), - Err(_) => Vec::new(), - }, - Err(_) => Vec::new(), - }; - Ok(serde_json::json!({ - "success": true, - "target": note_id, - "count": backlinks.len(), - "backlinks": backlinks, - })) - } - - fn build_vault_graph( - &self, - repo_id: Option<&str>, - note_id: Option<&str>, - depth: usize, - ) -> anyhow::Result { - let conn = match self.conn() { - Ok(c) => c, - Err(_) => { - return Ok(serde_json::json!({ - "success": true, - "count": 0, - "edge_count": 0, - "nodes": [], - "edges": [], - })); - } - }; - - let notes = match crate::registry::vault::list_vault_notes(&conn) { - Ok(n) => n, - Err(_) => { - return Ok(serde_json::json!({ - "success": true, - "count": 0, - "edge_count": 0, - "nodes": [], - "edges": [], - })); - } - }; - - if notes.is_empty() { - return Ok(serde_json::json!({ - "success": true, - "count": 0, - "edge_count": 0, - "nodes": [], - "edges": [], - })); - } - - let mut id_to_title: std::collections::HashMap = - std::collections::HashMap::new(); - let mut id_to_repo: std::collections::HashMap = - std::collections::HashMap::new(); - let mut outgoing: std::collections::HashMap> = - std::collections::HashMap::new(); - let mut incoming: std::collections::HashMap> = - std::collections::HashMap::new(); - - for note in ¬es { - let id = note.id.replace('\\', "/"); - id_to_title.insert(id.clone(), note.title.clone().unwrap_or_else(|| id.clone())); - if let Some(ref r) = note.linked_repo { - id_to_repo.insert(id.clone(), r.clone()); - } - - let targets: Vec = - note.outgoing_links.iter().map(|t| t.replace('\\', "/")).collect(); - outgoing.insert(id.clone(), targets.clone()); - - for target in targets { - incoming.entry(target.clone()).or_default().push(id.clone()); - if let Some(stem) = target.strip_suffix(".md") { - incoming.entry(stem.to_string()).or_default().push(id.clone()); - } - } - } - - let mut id_lookup: std::collections::HashMap = - std::collections::HashMap::new(); - for id in id_to_title.keys() { - id_lookup.insert(id.clone(), id.clone()); - if let Some(stem) = id.strip_suffix(".md") { - id_lookup.insert(stem.to_string(), id.clone()); - } - } - - let allowed_ids: std::collections::HashSet = if let Some(rid) = repo_id { - id_to_repo.iter().filter(|(_, r)| *r == rid).map(|(id, _)| id.clone()).collect() - } else { - id_to_title.keys().cloned().collect() - }; - - let max_depth = depth.clamp(1, 3); - - let (selected_nodes, selected_edges): ( - std::collections::HashSet, - Vec<(String, String)>, - ) = if let Some(start_id) = note_id { - let start_normalized = - id_lookup.get(start_id).cloned().unwrap_or_else(|| start_id.replace('\\', "/")); - if !allowed_ids.contains(&start_normalized) { - return Ok(serde_json::json!({ - "success": true, - "count": 1, - "edge_count": 0, - "nodes": [serde_json::json!({ - "id": start_normalized, - "title": id_to_title.get(&start_normalized).unwrap_or(&start_normalized), - })], - "edges": [], - })); - } - - let mut visited: std::collections::HashSet = std::collections::HashSet::new(); - let mut edges: Vec<(String, String)> = Vec::new(); - let mut queue: Vec<(String, usize)> = vec![(start_normalized.clone(), 0)]; - visited.insert(start_normalized.clone()); - - while let Some((current, dist)) = queue.pop() { - if dist >= max_depth { - continue; - } - for target in outgoing.get(¤t).into_iter().flatten() { - let norm = id_lookup.get(target).cloned().unwrap_or_else(|| target.clone()); - if allowed_ids.contains(&norm) { - edges.push((current.clone(), norm.clone())); - if visited.insert(norm.clone()) { - queue.push((norm, dist + 1)); - } - } - } - for source in incoming.get(¤t).into_iter().flatten() { - let norm = id_lookup.get(source).cloned().unwrap_or_else(|| source.clone()); - if allowed_ids.contains(&norm) { - edges.push((norm.clone(), current.clone())); - if visited.insert(norm.clone()) { - queue.push((norm, dist + 1)); - } - } - } - } - - (visited, edges) - } else { - let mut all_edges: Vec<(String, String)> = Vec::new(); - for (source, targets) in &outgoing { - if !allowed_ids.contains(source) { - continue; - } - for target in targets { - let norm = id_lookup.get(target).cloned().unwrap_or_else(|| target.clone()); - if allowed_ids.contains(&norm) { - all_edges.push((source.clone(), norm.clone())); - } - } - } - (allowed_ids.clone(), all_edges) - }; - - let nodes: Vec<_> = selected_nodes - .iter() - .map(|id| { - serde_json::json!({ - "id": id, - "title": id_to_title.get(id).unwrap_or(id), - }) - }) - .collect(); - - let edges_json: Vec<_> = selected_edges - .iter() - .map(|(s, t)| serde_json::json!({ "source": s, "target": t })) - .collect(); - - Ok(serde_json::json!({ - "success": true, - "count": nodes.len(), - "edge_count": edges_json.len(), - "nodes": nodes, - "edges": edges_json, - })) - } - - fn get_vault_history(&self, note_id: &str) -> anyhow::Result { - let vault_dir = self.storage.workspace_dir().ok().map(|ws| ws.join("vault")); - let history = if let Some(ref vd) = vault_dir { - crate::vault::history::note_history(vd, note_id).unwrap_or_default() - } else { - Vec::new() - }; - let entries: Vec = history - .into_iter() - .map(|h| { - let ts = chrono::DateTime::from_timestamp(h.timestamp, 0) - .map(|dt| dt.format("%Y-%m-%d %H:%M:%S").to_string()) - .unwrap_or_else(|| "unknown".to_string()); - serde_json::json!({ - "commit": h.commit, - "author": h.author, - "email": h.email, - "timestamp": ts, - "message": h.message, - "insertions": h.insertions, - "deletions": h.deletions, - }) - }) - .collect(); - Ok(serde_json::json!({ - "success": true, - "note_id": note_id, - "count": entries.len(), - "history": entries, - })) - } - - fn export_vault(&self, output_dir: &str) -> anyhow::Result { - let vault_dir = self.storage.workspace_dir()?.join("vault"); - let out = std::path::PathBuf::from(output_dir); - crate::vault::export::export_vault(&vault_dir, &out) - } -} +// SPDX-License-Identifier: MIT +// Copyright (c) 2026 juice094 +pub mod backlinks; +pub mod export; +pub mod frontmatter; +pub mod fs_io; +pub mod history; +pub mod indexer; +pub mod scanner; +pub mod wikilink; + +pub use scanner::ScanOptions; + +use crate::storage::AppContext; + +impl crate::clients::VaultClient for AppContext { + fn list_vault_notes(&self) -> anyhow::Result { + let conn = self.conn()?; + let notes = crate::registry::vault::list_vault_notes(&conn)?; + let results: Vec = notes + .into_iter() + .map(|n| { + serde_json::json!({ + "id": n.id, + "path": n.path, + "title": n.title, + "tags": n.tags, + }) + }) + .collect(); + Ok(serde_json::json!({"success": true, "count": results.len(), "notes": results})) + } + + fn read_vault_note(&self, path: &str) -> anyhow::Result { + let (body, frontmatter) = fs_io::read_note_body(path) + .ok_or_else(|| anyhow::anyhow!("note not found or unreadable"))?; + Ok(serde_json::json!({ + "success": true, + "path": path, + "content": body, + "frontmatter": frontmatter, + })) + } + + fn get_backlinks(&self, note_id: &str) -> anyhow::Result { + let backlinks = match self.conn() { + Ok(conn) => match crate::registry::vault::list_vault_notes(&conn) { + Ok(notes) => notes + .into_iter() + .filter(|n| { + n.outgoing_links.iter().any(|l| { + let normalized = l.replace('\\', "/"); + normalized == note_id.replace('\\', "/") + || normalized + == note_id + .replace('\\', "/") + .strip_suffix(".md") + .unwrap_or(¬e_id.replace('\\', "/")) + || l == note_id + }) + }) + .map(|n| n.id.replace('\\', "/")) + .collect(), + Err(_) => Vec::new(), + }, + Err(_) => Vec::new(), + }; + Ok(serde_json::json!({ + "success": true, + "target": note_id, + "count": backlinks.len(), + "backlinks": backlinks, + })) + } + + fn build_vault_graph( + &self, + repo_id: Option<&str>, + note_id: Option<&str>, + depth: usize, + ) -> anyhow::Result { + let conn = match self.conn() { + Ok(c) => c, + Err(_) => { + return Ok(serde_json::json!({ + "success": true, + "count": 0, + "edge_count": 0, + "nodes": [], + "edges": [], + })); + } + }; + + let notes = match crate::registry::vault::list_vault_notes(&conn) { + Ok(n) => n, + Err(_) => { + return Ok(serde_json::json!({ + "success": true, + "count": 0, + "edge_count": 0, + "nodes": [], + "edges": [], + })); + } + }; + + if notes.is_empty() { + return Ok(serde_json::json!({ + "success": true, + "count": 0, + "edge_count": 0, + "nodes": [], + "edges": [], + })); + } + + let mut id_to_title: std::collections::HashMap = + std::collections::HashMap::new(); + let mut id_to_repo: std::collections::HashMap = + std::collections::HashMap::new(); + let mut outgoing: std::collections::HashMap> = + std::collections::HashMap::new(); + let mut incoming: std::collections::HashMap> = + std::collections::HashMap::new(); + + for note in ¬es { + let id = note.id.replace('\\', "/"); + id_to_title.insert(id.clone(), note.title.clone().unwrap_or_else(|| id.clone())); + if let Some(ref r) = note.linked_repo { + id_to_repo.insert(id.clone(), r.clone()); + } + + let targets: Vec = + note.outgoing_links.iter().map(|t| t.replace('\\', "/")).collect(); + outgoing.insert(id.clone(), targets.clone()); + + for target in targets { + incoming.entry(target.clone()).or_default().push(id.clone()); + if let Some(stem) = target.strip_suffix(".md") { + incoming.entry(stem.to_string()).or_default().push(id.clone()); + } + } + } + + let mut id_lookup: std::collections::HashMap = + std::collections::HashMap::new(); + for id in id_to_title.keys() { + id_lookup.insert(id.clone(), id.clone()); + if let Some(stem) = id.strip_suffix(".md") { + id_lookup.insert(stem.to_string(), id.clone()); + } + } + + let allowed_ids: std::collections::HashSet = if let Some(rid) = repo_id { + id_to_repo.iter().filter(|(_, r)| *r == rid).map(|(id, _)| id.clone()).collect() + } else { + id_to_title.keys().cloned().collect() + }; + + let max_depth = depth.clamp(1, 3); + + let (selected_nodes, selected_edges): ( + std::collections::HashSet, + Vec<(String, String)>, + ) = if let Some(start_id) = note_id { + let start_normalized = + id_lookup.get(start_id).cloned().unwrap_or_else(|| start_id.replace('\\', "/")); + if !allowed_ids.contains(&start_normalized) { + return Ok(serde_json::json!({ + "success": true, + "count": 1, + "edge_count": 0, + "nodes": [serde_json::json!({ + "id": start_normalized, + "title": id_to_title.get(&start_normalized).unwrap_or(&start_normalized), + })], + "edges": [], + })); + } + + let mut visited: std::collections::HashSet = std::collections::HashSet::new(); + let mut edges: Vec<(String, String)> = Vec::new(); + let mut queue: Vec<(String, usize)> = vec![(start_normalized.clone(), 0)]; + visited.insert(start_normalized.clone()); + + while let Some((current, dist)) = queue.pop() { + if dist >= max_depth { + continue; + } + for target in outgoing.get(¤t).into_iter().flatten() { + let norm = id_lookup.get(target).cloned().unwrap_or_else(|| target.clone()); + if allowed_ids.contains(&norm) { + edges.push((current.clone(), norm.clone())); + if visited.insert(norm.clone()) { + queue.push((norm, dist + 1)); + } + } + } + for source in incoming.get(¤t).into_iter().flatten() { + let norm = id_lookup.get(source).cloned().unwrap_or_else(|| source.clone()); + if allowed_ids.contains(&norm) { + edges.push((norm.clone(), current.clone())); + if visited.insert(norm.clone()) { + queue.push((norm, dist + 1)); + } + } + } + } + + (visited, edges) + } else { + let mut all_edges: Vec<(String, String)> = Vec::new(); + for (source, targets) in &outgoing { + if !allowed_ids.contains(source) { + continue; + } + for target in targets { + let norm = id_lookup.get(target).cloned().unwrap_or_else(|| target.clone()); + if allowed_ids.contains(&norm) { + all_edges.push((source.clone(), norm.clone())); + } + } + } + (allowed_ids.clone(), all_edges) + }; + + let nodes: Vec<_> = selected_nodes + .iter() + .map(|id| { + serde_json::json!({ + "id": id, + "title": id_to_title.get(id).unwrap_or(id), + }) + }) + .collect(); + + let edges_json: Vec<_> = selected_edges + .iter() + .map(|(s, t)| serde_json::json!({ "source": s, "target": t })) + .collect(); + + Ok(serde_json::json!({ + "success": true, + "count": nodes.len(), + "edge_count": edges_json.len(), + "nodes": nodes, + "edges": edges_json, + })) + } + + fn get_vault_history(&self, note_id: &str) -> anyhow::Result { + let vault_dir = self.storage.workspace_dir().ok().map(|ws| ws.join("vault")); + let history = if let Some(ref vd) = vault_dir { + crate::vault::history::note_history(vd, note_id).unwrap_or_default() + } else { + Vec::new() + }; + let entries: Vec = history + .into_iter() + .map(|h| { + let ts = chrono::DateTime::from_timestamp(h.timestamp, 0) + .map(|dt| dt.format("%Y-%m-%d %H:%M:%S").to_string()) + .unwrap_or_else(|| "unknown".to_string()); + serde_json::json!({ + "commit": h.commit, + "author": h.author, + "email": h.email, + "timestamp": ts, + "message": h.message, + "insertions": h.insertions, + "deletions": h.deletions, + }) + }) + .collect(); + Ok(serde_json::json!({ + "success": true, + "note_id": note_id, + "count": entries.len(), + "history": entries, + })) + } + + fn export_vault(&self, output_dir: &str) -> anyhow::Result { + let vault_dir = self.storage.workspace_dir()?.join("vault"); + let out = std::path::PathBuf::from(output_dir); + crate::vault::export::export_vault(&vault_dir, &out) + } +} diff --git a/src/vault/scanner.rs b/src/vault/scanner.rs index 13b46e9..ba3c1a1 100644 --- a/src/vault/scanner.rs +++ b/src/vault/scanner.rs @@ -1,144 +1,187 @@ -// SPDX-License-Identifier: MIT -// Copyright (c) 2026 juice094 -use crate::registry::VaultNote; -use crate::vault::frontmatter::extract_frontmatter; -use crate::vault::wikilink::extract_wikilinks; - -use chrono::Utc; -use std::path::{Path, PathBuf}; -use tracing::{info, warn}; - -fn default_vault_dir() -> anyhow::Result { - let ws = crate::registry::WorkspaceRegistry::workspace_dir()?; - let vault = ws.join("vault"); - // P1-2: PARA directory structure - for sub in &["00-Inbox", "01-Projects", "02-Areas", "03-Resources", "04-Archives", "99-Meta"] { - std::fs::create_dir_all(vault.join(sub))?; - } - Ok(vault) -} - -/// Scan a vault directory for Markdown notes and sync them into the registry. -/// -/// * `vault_dir` — root of the vault. If `None`, uses the default location. -/// * Returns the number of notes synced. -pub fn scan_vault( - conn: &mut rusqlite::Connection, - vault_dir: Option<&Path>, -) -> anyhow::Result { - let root = match vault_dir { - Some(p) => p.to_path_buf(), - None => default_vault_dir()?, - }; - - if !root.exists() { - info!("Vault directory does not exist yet: {:?}", root); - return Ok(0); - } - - let mut synced = 0; - - for entry in walkdir::WalkDir::new(&root) - .follow_links(false) - .into_iter() - .filter_map(|e| e.ok()) - .filter(|e| e.file_type().is_file()) - .filter(|e| e.path().extension().map(|ext| ext == "md").unwrap_or(false)) - { - let path = entry.path(); - let rel_path = path.strip_prefix(&root).unwrap_or(path); - let id = rel_path.to_string_lossy().replace('\\', "/"); - - match std::fs::read_to_string(path) { - Ok(content) => { - let (frontmatter, body_offset) = extract_frontmatter(&content) - .map(|(fm, off)| (Some(fm), off)) - .unwrap_or((None, 0)); - - let body = &content[body_offset..]; - let wikilinks = extract_wikilinks(body); - let outgoing: Vec = wikilinks.iter().map(|l| l.target.clone()).collect(); - let block_refs: Vec = - wikilinks.iter().filter_map(|l| l.anchor.clone()).collect(); - - let title = frontmatter.as_ref().and_then(|fm| fm.title.clone()).or_else(|| { - // Fallback: first H1 heading - body.lines() - .find_map(|l| l.trim().strip_prefix("# ").map(|s| s.trim().to_string())) - }); - - let tags = frontmatter.as_ref().map(|fm| fm.tags.clone()).unwrap_or_default(); - let linked_repo = frontmatter.as_ref().and_then(|fm| fm.repo.clone()); - let fm_raw = frontmatter.map(|fm| fm.raw); - - let note = VaultNote { - id, - path: path.to_string_lossy().to_string(), - title, - content: body.trim().to_string(), - frontmatter: fm_raw, - tags, - outgoing_links: outgoing, - block_refs, - linked_repo, - created_at: Utc::now(), - updated_at: Utc::now(), - }; - - if let Err(e) = crate::registry::vault::save_vault_note(conn, ¬e) { - warn!("Failed to save vault note {}: {}", note.id, e); - } else { - synced += 1; - } - } - Err(e) => { - warn!("Failed to read vault file {:?}: {}", path, e); - } - } - } - - info!("Vault scan complete: {} notes synced", synced); - Ok(synced) -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::registry::WorkspaceRegistry; - - #[test] - fn test_scan_vault_basic() { - let tmp = std::env::temp_dir().join(format!("devbase_vault_scan_{}", std::process::id())); - std::fs::create_dir_all(&tmp).unwrap(); - std::fs::write( - tmp.join("hello.md"), - "---\ntitle: Hello World\ntags: [rust, cli]\n---\n# Hello World\n\nThis is a [[test]] note.\n", - ) - .unwrap(); - - let mut conn = WorkspaceRegistry::init_in_memory().unwrap(); - let count = scan_vault(&mut conn, Some(&tmp)).unwrap(); - assert_eq!(count, 1); - - std::fs::remove_dir_all(&tmp).unwrap(); - } - - #[test] - fn test_scan_vault_empty_dir() { - let tmp = std::env::temp_dir().join(format!("devbase_vault_empty_{}", std::process::id())); - std::fs::create_dir_all(&tmp).unwrap(); - let mut conn = WorkspaceRegistry::init_in_memory().unwrap(); - let count = scan_vault(&mut conn, Some(&tmp)).unwrap(); - assert_eq!(count, 0); - std::fs::remove_dir_all(&tmp).unwrap(); - } - - #[test] - fn test_scan_vault_missing_dir() { - let tmp = - std::env::temp_dir().join(format!("devbase_vault_missing_{}", std::process::id())); - let mut conn = WorkspaceRegistry::init_in_memory().unwrap(); - let count = scan_vault(&mut conn, Some(&tmp)).unwrap(); - assert_eq!(count, 0); - } -} +// SPDX-License-Identifier: MIT +// Copyright (c) 2026 juice094 +use crate::registry::VaultNote; +use crate::vault::frontmatter::extract_frontmatter; +use crate::vault::wikilink::extract_wikilinks; + +use chrono::Utc; +use std::path::{Path, PathBuf}; +use tracing::{info, warn}; + +fn default_vault_dir() -> anyhow::Result { + let ws = crate::registry::WorkspaceRegistry::workspace_dir()?; + let vault = ws.join("vault"); + // P1-2: PARA directory structure + for sub in &["00-Inbox", "01-Projects", "02-Areas", "03-Resources", "04-Archives", "99-Meta"] { + std::fs::create_dir_all(vault.join(sub))?; + } + Ok(vault) +} + +/// Options for scanning vault directories. +#[derive(Debug, Clone)] +pub struct ScanOptions { + pub roots: Vec, + pub follow_links: bool, +} + +impl Default for ScanOptions { + fn default() -> Self { + Self { + roots: vec![], + follow_links: true, + } + } +} + +/// Scan vault directories for Markdown notes and sync them into the registry. +/// +/// * `options` — scan options (roots, follow_links). If roots is empty, uses the default vault location. +/// * Returns the number of notes synced. +pub fn scan_vault_with_options( + conn: &mut rusqlite::Connection, + options: &ScanOptions, +) -> anyhow::Result { + let roots = if options.roots.is_empty() { + vec![default_vault_dir()?] + } else { + options.roots.clone() + }; + + let mut synced = 0; + + let multi_root = roots.len() > 1; + + for root in &roots { + if !root.exists() { + info!("Vault root does not exist yet: {:?}", root); + continue; + } + + let walker = walkdir::WalkDir::new(root) + .follow_links(options.follow_links); + + for entry in walker + .into_iter() + .filter_map(|e| e.ok()) + .filter(|e| e.file_type().is_file()) + .filter(|e| e.path().extension().map(|ext| ext == "md").unwrap_or(false)) + { + let path = entry.path(); + let rel_path = path.strip_prefix(root).unwrap_or(path); + let id = if multi_root { + format!("{}/{}", root.file_name().unwrap_or_default().to_string_lossy(), + rel_path.to_string_lossy().replace('\\', "/")) + } else { + rel_path.to_string_lossy().replace('\\', "/") + }; + + match std::fs::read_to_string(path) { + Ok(content) => { + let (frontmatter, body_offset) = extract_frontmatter(&content) + .map(|(fm, off)| (Some(fm), off)) + .unwrap_or((None, 0)); + + let body = &content[body_offset..]; + let wikilinks = extract_wikilinks(body); + let outgoing: Vec = wikilinks.iter().map(|l| l.target.clone()).collect(); + let block_refs: Vec = + wikilinks.iter().filter_map(|l| l.anchor.clone()).collect(); + + let title = frontmatter.as_ref().and_then(|fm| fm.title.clone()).or_else(|| { + // Fallback: first H1 heading + body.lines() + .find_map(|l| l.trim().strip_prefix("# ").map(|s| s.trim().to_string())) + }); + + let tags = frontmatter.as_ref().map(|fm| fm.tags.clone()).unwrap_or_default(); + let linked_repo = frontmatter.as_ref().and_then(|fm| fm.repo.clone()); + let fm_raw = frontmatter.map(|fm| fm.raw); + + let note = VaultNote { + id, + path: path.to_string_lossy().to_string(), + title, + content: body.trim().to_string(), + frontmatter: fm_raw, + tags, + outgoing_links: outgoing, + block_refs, + linked_repo, + created_at: Utc::now(), + updated_at: Utc::now(), + }; + + if let Err(e) = crate::registry::vault::save_vault_note(conn, ¬e) { + warn!("Failed to save vault note {}: {}", note.id, e); + } else { + synced += 1; + } + } + Err(e) => { + warn!("Failed to read vault file {:?}: {}", path, e); + } + } + } + } + + info!("Vault scan complete: {} notes synced", synced); + Ok(synced) +} + +/// Legacy API: scan a single vault directory. +/// +/// * `vault_dir` — root of the vault. If `None`, uses the default location. +/// * Returns the number of notes synced. +pub fn scan_vault( + conn: &mut rusqlite::Connection, + vault_dir: Option<&Path>, +) -> anyhow::Result { + let options = ScanOptions { + roots: vault_dir.map(|p| vec![p.to_path_buf()]).unwrap_or_default(), + follow_links: false, + }; + scan_vault_with_options(conn, &options) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::registry::WorkspaceRegistry; + + #[test] + fn test_scan_vault_basic() { + let tmp = std::env::temp_dir().join(format!("devbase_vault_scan_{}", std::process::id())); + std::fs::create_dir_all(&tmp).unwrap(); + std::fs::write( + tmp.join("hello.md"), + "---\ntitle: Hello World\ntags: [rust, cli]\n---\n# Hello World\n\nThis is a [[test]] note.\n", + ) + .unwrap(); + + let mut conn = WorkspaceRegistry::init_in_memory().unwrap(); + let count = scan_vault(&mut conn, Some(&tmp)).unwrap(); + assert_eq!(count, 1); + + std::fs::remove_dir_all(&tmp).unwrap(); + } + + #[test] + fn test_scan_vault_empty_dir() { + let tmp = std::env::temp_dir().join(format!("devbase_vault_empty_{}", std::process::id())); + std::fs::create_dir_all(&tmp).unwrap(); + let mut conn = WorkspaceRegistry::init_in_memory().unwrap(); + let count = scan_vault(&mut conn, Some(&tmp)).unwrap(); + assert_eq!(count, 0); + std::fs::remove_dir_all(&tmp).unwrap(); + } + + #[test] + fn test_scan_vault_missing_dir() { + let tmp = + std::env::temp_dir().join(format!("devbase_vault_missing_{}", std::process::id())); + let mut conn = WorkspaceRegistry::init_in_memory().unwrap(); + let count = scan_vault(&mut conn, Some(&tmp)).unwrap(); + assert_eq!(count, 0); + } +}