From 555bb30a13e564d4d0b695902ee17e8be99c207c Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 20 Jan 2026 16:52:51 +0000 Subject: [PATCH 1/4] Bump version to 0.10.6, add hooks field to plugin.json The hooks field was missing, preventing hooks from loading. Co-developed-by: Claude Code v2.1.12 (claude-opus-4-5-20251101) --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 16e873c..7f4d2a4 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,7 +9,7 @@ "name": "context-daddy", "source": "./", "description": "Your codebase's context needs a responsible adult. Fast code exploration, living project narratives, and tribal knowledge that survives across sessions.", - "version": "0.10.5", + "version": "0.10.6", "author": { "name": "Robert Taylor" }, diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index cf97bcd..01758f7 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,12 +1,13 @@ { "name": "context-daddy", - "version": "0.10.5", + "version": "0.10.6", "description": "Your codebase's context needs a responsible adult. Fast code exploration, living project narratives, and tribal knowledge that survives across sessions.", "author": { "name": "Robert Taylor" }, "keywords": ["context", "narrative", "repo-map", "tribal-knowledge", "documentation"], "repository": "https://github.com/chipflow/context-daddy", + "hooks": "${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json", "mcpServers": { "repo-map": { "command": "uv", From 3d7304037b28eb40ba4553bb252f933accd403d2 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 20 Jan 2026 16:53:05 +0000 Subject: [PATCH 2/4] Reorganize documentation into docs/ directory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move PROCESS-ARCHITECTURE.md → docs/architecture.md - Move TESTING.md → docs/testing.md (updated for v0.10.x) - Move TODO.md → docs/roadmap.md - Delete duplicate .claude-plugin/SKILL.md - Add docs/index.md as documentation index Co-developed-by: Claude Code v2.1.12 (claude-opus-4-5-20251101) --- .claude-plugin/SKILL.md | 190 ------------------ .../architecture.md | 0 docs/index.md | 19 ++ TODO.md => docs/roadmap.md | 0 TESTING.md => docs/testing.md | 68 +++++++ 5 files changed, 87 insertions(+), 190 deletions(-) delete mode 100644 .claude-plugin/SKILL.md rename PROCESS-ARCHITECTURE.md => docs/architecture.md (100%) create mode 100644 docs/index.md rename TODO.md => docs/roadmap.md (100%) rename TESTING.md => docs/testing.md (72%) diff --git a/.claude-plugin/SKILL.md b/.claude-plugin/SKILL.md deleted file mode 100644 index 1b2b70e..0000000 --- a/.claude-plugin/SKILL.md +++ /dev/null @@ -1,190 +0,0 @@ -# Context Tools Plugin - Usage Guide - -## Dynamic Directory Support (v0.8.0+) - -**GOOD NEWS:** MCP tools automatically adapt to the current working directory! - -**How it works:** -```bash -cd /home/user/project-a -# MCP tools query/index project-a/.claude/repo-map.db - -cd /home/user/project-b -# MCP tools now query/index project-b/.claude/repo-map.db ✅ -``` - -**Behavior:** -- Tools check current working directory on each call -- If `.claude/repo-map.db` exists: query it -- If not: trigger indexing for current directory -- Logs show which directory is being queried - -**Benefits:** -- No need to restart session when changing projects -- Can work with multiple projects in one session -- Each project maintains its own index -- Tools "just work" wherever you are - -## Plugin Installation and Updates - -**CRITICAL: When the user runs `/plugin install` or `/plugin update`:** - -The MCP server configuration changes immediately, but the MCP server itself **does not restart automatically**. The new plugin features (especially MCP tools like `search_symbols`) will NOT be available until the session restarts. - -**YOU MUST tell the user:** - -``` -The plugin has been installed/updated successfully. To use the MCP tools (search_symbols, get_file_symbols, etc.), you need to restart the session: - -1. Exit this session (Ctrl+C or type 'exit') -2. Start a new session with: claude continue - -The MCP server will restart with the new plugin configuration. -``` - -**When to give this instruction:** -- Immediately after the user runs `/plugin install context-daddy` -- Immediately after the user runs `/plugin update context-daddy` -- When the user tries to use MCP tools but they're not available (and you suspect they just installed) - -**Why this matters:** -- MCP servers are started when Claude Code starts -- Plugin installation modifies MCP server configuration -- Changes only take effect on next Claude Code startup -- Users will be confused if tools don't work after installation - -## Available MCP Tools - -Once the session has been restarted after installation, the following MCP tools are available: - -### mcp__repo-map__search_symbols -Search for symbols (functions, classes, methods) by name pattern. - -**Faster than Grep/Search** - uses pre-built SQLite index. - -Parameters: -- `pattern` (required): Glob pattern like `get_*`, `*Handler`, `Config*` -- `kind` (optional): Filter by `"class"`, `"function"`, or `"method"` -- `limit` (optional): Max results (default: 20) - -Example: -```json -{ - "pattern": "parse_*", - "kind": "function", - "limit": 10 -} -``` - -### mcp__repo-map__get_file_symbols -Get all symbols defined in a specific file. - -Parameters: -- `file` (required): Relative path from project root (e.g., `"src/models/user.py"`) - -### mcp__repo-map__get_symbol_content -Get the source code content of a symbol by exact name. - -**Faster than Grep/Search+Read** - directly retrieves function/class source code. - -Parameters: -- `name` (required): Exact symbol name (e.g., `"MyClass"`, `"User.save"`) -- `kind` (optional): Filter by type if name is ambiguous - -### mcp__repo-map__reindex_repo_map -Trigger a reindex of the repository symbols. - -Parameters: -- `force` (optional): Force reindex even if cache is fresh (default: false) - -### mcp__repo-map__repo_map_status -Get the current status of the repo map index. - -Shows: -- Index status: `idle`, `indexing`, `completed`, or `failed` -- Symbol count -- Last indexed time -- Whether index is stale -- Indexing errors (if any) - -### mcp__repo-map__wait_for_index -Wait for indexing to complete. - -Parameters: -- `timeout_seconds` (optional): How long to wait (default: 60) - -**Note:** Most tools automatically wait for indexing to complete, so this is rarely needed. - -## Database Schema (.claude/repo-map.db) - -**symbols table:** -- `name` (TEXT): Symbol name -- `kind` (TEXT): `class`, `function`, or `method` -- `file_path` (TEXT): Relative path from project root -- `line_number` (INTEGER): Start line (1-indexed) -- `end_line_number` (INTEGER): End line (nullable) -- `parent` (TEXT): Parent class/module (nullable) -- `docstring` (TEXT): First line of docstring (nullable) -- `signature` (TEXT): Function/method signature (nullable) -- `language` (TEXT): `python`, `cpp`, or `rust` - -**metadata table (v0.7.0+):** -- `key` (TEXT PRIMARY KEY): Metadata key -- `value` (TEXT): Metadata value - -Keys: -- `status`: `idle` | `indexing` | `completed` | `failed` -- `index_start_time`: ISO8601 timestamp when indexing started -- `last_indexed`: ISO8601 timestamp when last completed -- `symbol_count`: Total symbols indexed (string) -- `error_message`: Error message if status='failed' - -## Indexing Status and Auto-Wait (v0.7.0+) - -**First Use Behavior:** -- On first use, indexing starts automatically in background -- Tools automatically wait (up to 60s) if indexing is in progress -- If timeout, tools return helpful error asking user to retry - -**Watchdog (v0.7.0+):** -- Detects hung indexing processes (>10 minutes) -- Automatically resets status to 'failed' -- Can be manually recovered with `reindex_repo_map` - -**Multiprocess Architecture (v0.8.0+):** -- Indexing runs in separate subprocess -- MCP server remains responsive even if indexing hangs -- Watchdog can kill hung subprocess without affecting MCP server -- Resource limits (Unix/macOS): 4GB memory, 20 min CPU time - -## When to Use MCP Tools vs Other Tools - -**Use MCP repo-map tools when:** -- Searching for symbols by name pattern (faster than Grep) -- Getting all symbols in a file (faster than Read + parsing) -- Getting source code of a specific function/class (faster than Grep + Read) -- Need to search across multiple languages (Python, C++, Rust) - -**Use other tools when:** -- Searching file contents (not symbol names) - use Grep -- Reading entire files - use Read -- Need to search files that aren't Python/C++/Rust -- Searching for non-code patterns (comments, strings, etc.) - -## Project-Specific Files - -**Automatically generated at session start:** -- `.claude/project-manifest.json` - Project structure and build commands -- `.claude/repo-map.md` - Human-readable code structure with duplicate detection -- `.claude/repo-map.db` - SQLite database for fast symbol queries (MCP server) - -**Optional (created manually):** -- `.claude/learnings.md` - Project-specific learnings and discoveries - -**Logs:** -- `.claude/logs/repo-map-server.log` - MCP server rotating log (1MB per file, 3 backups) - - Tool calls and results - - Indexing events and performance - - Watchdog actions and resource limit violations - - Server startup/shutdown -- Session start hook outputs are also logged for debugging diff --git a/PROCESS-ARCHITECTURE.md b/docs/architecture.md similarity index 100% rename from PROCESS-ARCHITECTURE.md rename to docs/architecture.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e30b4b2 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,19 @@ +# Documentation + +Internal documentation for context-daddy development. + +## Contents + +| Document | Description | +|----------|-------------| +| [architecture.md](architecture.md) | Process architecture - tree-sitter integration, multiprocess design, watchdog behavior | +| [testing.md](testing.md) | Testing guide - unit tests, CI workflows, E2E tests | +| [roadmap.md](roadmap.md) | Future enhancements and completed features | +| [FTS_DESIGN.md](FTS_DESIGN.md) | Full-text search design decisions | + +## Quick Links + +- **Main README**: [../README.md](../README.md) +- **Changelog**: [../CHANGELOG.md](../CHANGELOG.md) +- **Development Guide**: [../CLAUDE.md](../CLAUDE.md) +- **Plugin Skills**: [../SKILL.md](../SKILL.md) diff --git a/TODO.md b/docs/roadmap.md similarity index 100% rename from TODO.md rename to docs/roadmap.md diff --git a/TESTING.md b/docs/testing.md similarity index 72% rename from TESTING.md rename to docs/testing.md index 41d3cd4..551a9e6 100644 --- a/TESTING.md +++ b/docs/testing.md @@ -1,5 +1,73 @@ # Testing Documentation +## Current Test Suite (v0.10.x) + +### Automated Test Files + +| File | Purpose | Tests | +|------|---------|-------| +| `tests/test_plugin_config.py` | Plugin configuration validation | 7 tests | +| `tests/test_mcp_tools.py` | MCP tool functionality | Symbol search, file operations | +| `tests/test_list_files.py` | File listing with patterns | Glob matching, path resolution | + +### CI Workflows + +| Workflow | Trigger | Purpose | +|----------|---------|---------| +| `ci.yml` | push, PR | Structure validation, linting | +| `test-hooks.yml` | push to main | E2E hook execution (requires `ANTHROPIC_API_KEY`) | +| `e2e-test.yml` | manual | Full E2E testing with Claude | + +### Running Tests + +```bash +# Run all unit tests +uv run pytest tests/ + +# Run specific test file +uv run pytest tests/test_plugin_config.py + +# Run plugin config validation (standalone) +uv run tests/test_plugin_config.py +``` + +### Plugin Configuration Tests (v0.9.6+) + +`test_plugin_config.py` validates: + +1. **Required fields** - plugin.json has name, version, description, author, keywords, repository +2. **Hooks discovery** - hooks/hooks.json exists (autodiscovered by Claude Code) +3. **Hook types** - All hook types are valid (SessionStart, PreCompact, Stop, etc.) +4. **Script existence** - All referenced scripts in hooks.json exist +5. **Version format** - Version follows semver (X.Y.Z) +6. **MCP servers** - Referenced server scripts exist +7. **Version consistency** - plugin.json and marketplace.json versions match + +### E2E Hook Tests (v0.9.6+) + +`.github/workflows/test-hooks.yml` tests: + +- **SessionStart hook** - Creates .claude directory and manifest +- **PreCompact + Stop hooks** - Verifies compaction flow via turn limits +- **Artifact verification** - Checks repo-map.db creation and MCP logs + +--- + +## Historical Testing + +### v0.8.0+ - Multiprocess Architecture + +The v0.8.0 release changed from thread-based to multiprocess indexing. + +**Key changes tested:** +- Subprocess spawning for indexing +- MCP server remains responsive during indexing +- Watchdog can SIGKILL hung subprocess +- SQLite WAL handles concurrent read/write +- Resource limits (4GB memory, 20min CPU time) + +--- + ## v0.7.1 - Transaction Safety and Watchdog Testing ### Test Suite Summary From 17d7e68da3182d25dad7024a031f52657499a53f Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 20 Jan 2026 16:53:23 +0000 Subject: [PATCH 3/4] Add mdbook documentation with GitHub Pages deployment - Add book.toml configuration for mdbook - Add docs/SUMMARY.md for navigation structure - Add pages.yml workflow for main branch deployment - Add preview-docs.yml workflow for PR previews - Add book/ to .gitignore PR previews deploy to gh-pages branch under pr-preview/pr-{number}/ Co-developed-by: Claude Code v2.1.12 (claude-opus-4-5-20251101) --- .claude-plugin/plugin.json | 1 - .github/workflows/pages.yml | 34 ++++++++++++++++++++++++++ .github/workflows/preview-docs.yml | 39 ++++++++++++++++++++++++++++++ .gitignore | 1 + book.toml | 12 +++++++++ docs/SUMMARY.md | 13 ++++++++++ 6 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/pages.yml create mode 100644 .github/workflows/preview-docs.yml create mode 100644 book.toml create mode 100644 docs/SUMMARY.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 01758f7..4c3a816 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -7,7 +7,6 @@ }, "keywords": ["context", "narrative", "repo-map", "tribal-knowledge", "documentation"], "repository": "https://github.com/chipflow/context-daddy", - "hooks": "${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json", "mcpServers": { "repo-map": { "command": "uv", diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..d22d538 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,34 @@ +name: Deploy Documentation + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup mdbook + uses: peaceiris/actions-mdbook@v2 + with: + mdbook-version: 'latest' + + - name: Build documentation + run: mdbook build + + - name: Ensure .nojekyll exists + run: touch book/.nojekyll + + - name: Deploy to GitHub Pages + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: book + branch: gh-pages + clean-exclude: pr-preview diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml new file mode 100644 index 0000000..b91feaf --- /dev/null +++ b/.github/workflows/preview-docs.yml @@ -0,0 +1,39 @@ +name: PR Documentation Preview + +on: + pull_request: + types: [opened, reopened, synchronize, closed] + +concurrency: preview-${{ github.ref }} + +permissions: + contents: write + pull-requests: write + +jobs: + preview: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup mdbook + if: github.event.action != 'closed' + uses: peaceiris/actions-mdbook@v2 + with: + mdbook-version: 'latest' + + - name: Build documentation + if: github.event.action != 'closed' + run: mdbook build + + - name: Ensure .nojekyll exists + if: github.event.action != 'closed' + run: touch book/.nojekyll + + - name: Deploy PR preview + uses: rossjrw/pr-preview-action@v1 + with: + source-dir: book + umbrella-dir: pr-preview + action: auto diff --git a/.gitignore b/.gitignore index 3e5b6eb..5555d0a 100644 --- a/.gitignore +++ b/.gitignore @@ -27,3 +27,4 @@ Thumbs.db # Build artifacts skills.zip .pdm-python +book/ diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..1b30d43 --- /dev/null +++ b/book.toml @@ -0,0 +1,12 @@ +[book] +title = "context-daddy" +authors = ["Robert Taylor"] +language = "en" +src = "docs" + +[build] +build-dir = "book" + +[output.html] +git-repository-url = "https://github.com/ChipFlow/context-daddy" +edit-url-template = "https://github.com/ChipFlow/context-daddy/edit/main/{path}" diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..cfb3f47 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,13 @@ +# Summary + +[Introduction](index.md) + +# Developer Guide + +- [Architecture](architecture.md) +- [Testing](testing.md) +- [Roadmap](roadmap.md) + +# Design Decisions + +- [Full-Text Search](FTS_DESIGN.md) From b9d6e151345db5b495ce40f20c0e2ba5237918d2 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 20 Jan 2026 17:02:12 +0000 Subject: [PATCH 4/4] Add docs badge and documentation link to README Co-developed-by: Claude Code v2.1.12 (claude-opus-4-5-20251101) --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index f6fc51d..5435095 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,9 @@ *Your codebase's context needs a responsible adult.* [![CI](https://github.com/ChipFlow/context-daddy/actions/workflows/ci.yml/badge.svg)](https://github.com/ChipFlow/context-daddy/actions/workflows/ci.yml) +[![Docs](https://github.com/ChipFlow/context-daddy/actions/workflows/pages.yml/badge.svg)](https://chipflow.github.io/context-daddy/) + +**[Documentation](https://chipflow.github.io/context-daddy/)** · **[Changelog](CHANGELOG.md)** ## What