Merge pull request #12 from costiash/fix/auto-update-big

fix: resolve auto-update self-destruction bug and remove unused hook

Author: costiash

CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to the enhanced edition of claude-code-docs will be document
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.2] - 2025-11-25
+
+### Fixed
+- **Critical Auto-Update Bug**: Fixed issue where `/docs -t` would destroy the installation directory
+  - Root cause: Running `install.sh` from within `~/.claude-code-docs` caused the script to delete its own working directory
+  - Solution: Replaced full reinstall with lightweight script sync after `git pull`
+- **Template Fallback**: Enhanced helper now gracefully degrades if template is missing instead of failing completely
+- **Security: Path Traversal Protection**: Added realpath validation in fallback mode to ensure files stay within docs directory
+  - Input sanitization removes special characters (already existed)
+  - New: Resolved path validation ensures no escape from docs directory
+- **Silent Failure Logging**: sync_helper_script() now logs failures to stderr for debugging
+  - Previously errors were silently suppressed with `|| true`
+  - Now provides feedback when copy or move operations fail
+
+### Removed
+- **Useless Hook**: Removed the PreToolUse hook that did nothing (just `exit 0`)
+  - The hook fired on every Read tool use but provided no functionality
+  - Updates now happen on-demand via `/docs -t` command
+
+### Added
+- **Post-Installation Verification**: Installer now validates all critical components after installation
+  - Checks helper script, template, docs directory, and command file
+  - Reports issues instead of silently failing
+- **Lock File Mechanism**: Added lock file to prevent concurrent update operations
+  - Prevents race conditions when multiple `/docs` commands run simultaneously
+  - Automatically cleans up stale locks (older than 60 seconds)
+- **Integration Tests**: Added 9 new tests for critical bug fix scenarios (627 tests total)
+  - Tests for sync_helper_script() atomic copy behavior
+  - Tests verifying update doesn't delete working directory
+  - Tests for template fallback functionality
+  - Tests for lock file mechanism
+  - Tests for path traversal protection
+
+### Changed
+- **Documentation Accuracy**: Updated README and installer messages to clarify update behavior
+  - Removed misleading "Auto-updates: Enabled" claims
+  - Clarified that updates are on-demand via `/docs -t`
+- **Test Suite**: Updated from 618 to 627 passing tests (78.7% coverage maintained)
+
 ## [0.4.1] - 2025-11-24
 
 ### Fixed
@@ -76,9 +115,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Full macOS compatibility
 - Linux support (Ubuntu, Debian, Fedora)
 - Improved installer
-- Automatic documentation updates via GitHub Actions
+- Documentation updates via GitHub Actions (repository-side)
 - `/docs` slash command integration
-- PreToolUse Read hook for automatic updates
 
 ---
 

CONTRIBUTING.md

@@ -125,8 +125,8 @@ pip install -e ".[dev]"
 ~/.claude-code-docs/claude-docs-helper.sh --validate
 
 # Run tests (REQUIRED before submitting PR)
-pytest tests/ -v  # Should see: 598 passed, 2 skipped
-pytest --cov=scripts --cov-report=term  # Should see: ~78%
+pytest tests/ -v  # Should see: 627 passed, 2 skipped
+pytest --cov=scripts --cov-report=term  # Should see: ~78.7%
 
 # Test specific changes
 python scripts/lookup_paths.py "your test query"
@@ -137,7 +137,7 @@ python scripts/fetch_claude_docs.py --help
 - `scripts/fetch_claude_docs.py` - Documentation fetcher with auto-regeneration
 - `scripts/lookup_paths.py` - Search & validation
 - `scripts/build_search_index.py` - Full-text search indexing
-- `tests/` - Test suite (600 tests)
+- `tests/` - Test suite (629 tests)
 
 ## Code Standards
 
@@ -331,10 +331,10 @@ def test_search_paths_with_limit():
 ```
 
 **Current test status:**
-- Total: 600 tests
-- Passing: 598 (99.7%)
+- Total: 629 tests
+- Passing: 627 (99.7%)
 - Skipped: 2 (intentional)
-- Coverage: 78.32%
+- Coverage: 78.70%
 
 ## Pull Request Guidelines
 
@@ -417,7 +417,7 @@ git push origin v0.x.x
 
 **When to release:**
 - New Python features complete
-- All tests passing (600/600 or 598/600)
+- All tests passing (629/629 or 627/629)
 - Documentation updated
 
 **Process:**
@@ -426,7 +426,7 @@ git push origin v0.x.x
 pytest
 
 # Check coverage
-pytest --cov=scripts --cov-report=term  # Should be ~78%
+pytest --cov=scripts --cov-report=term  # Should be ~78.7%
 
 # Update versions
 # Edit install.sh, README.md

README.md

@@ -1,7 +1,7 @@
 # Claude Code Documentation Tool
 
 [![Last Update](https://img.shields.io/github/last-commit/costiash/claude-code-docs/main.svg?label=docs%20updated)](https://github.com/costiash/claude-code-docs/commits/main)
-[![Tests](https://img.shields.io/badge/tests-618%20passing-success)](https://github.com/costiash/claude-code-docs/actions)
+[![Tests](https://img.shields.io/badge/tests-627%20passing-success)](https://github.com/costiash/claude-code-docs/actions)
 [![Coverage](https://img.shields.io/badge/coverage-78.7%25-green)](https://github.com/costiash/claude-code-docs)
 [![Python](https://img.shields.io/badge/python-3.9+-blue)](https://www.python.org/)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)](https://github.com/costiash/claude-code-docs)
@@ -25,9 +25,20 @@ Stop hunting through scattered docs. This tool provides instant access to **273
 - 📚 **Complete Coverage** - 273 active documentation paths, ~266-270 files downloaded (~97% coverage)
 - 🔍 **Semantic Understanding** - No primitive keyword matching, leverages Claude's language understanding
 - ✅ **Auto-Validated** - Continuous validation detects broken links automatically
-- 🔄 **Always Fresh** - Auto-updates every 3 hours from official sources
+- 🔄 **Always Fresh** - Repository updated every 3 hours; run `/docs -t` to pull latest
 - 🎯 **Graceful Degradation** - Works with or without Python
-- 🧪 **Well-Tested** - 620 tests (618 passing, 2 skipped), 78.7% coverage
+- 🧪 **Well-Tested** - 629 tests (627 passing, 2 skipped), 78.7% coverage
+
+## How It Works
+
+This tool takes a different approach to documentation access:
+
+1. **Local Mirror** - Instead of fetching docs from the web each time, we keep a local copy that's always ready
+2. **AI as the Interface** - You ask questions in plain English, Claude figures out which docs to read
+3. **Smart Routing** - The `/docs` command understands context ("hooks in agent sdk" vs "cli hooks")
+4. **Works Offline** - Once installed, docs are available even without internet
+
+The magic is in combining a simple local file system with Claude's language understanding. No complex search engines or databases - just markdown files and AI smarts.
 
 ## What's Included
 
@@ -61,7 +72,7 @@ curl -fsSL https://raw.githubusercontent.com/costiash/claude-code-docs/main/inst
 1. Clones repository to `~/.claude-code-docs`
 2. Installs 266 documentation files
 3. Sets up `/docs` command in Claude Code
-4. Enables auto-updates
+4. Verifies installation integrity
 
 **Python features activate automatically if Python 3.9+ is installed.**
 
@@ -198,7 +209,7 @@ For power users who want direct access to helper functions:
 - 273 documentation paths tracked in manifest
 - ~266-270 files downloaded (varies based on fetch success)
 - 7 Python scripts for enhanced features
-- Full test suite (620 tests)
+- Full test suite (629 tests)
 
 **Graceful Degradation** - Features adapt to environment:
 - **Without Python**: Basic documentation reading via `/docs` command
@@ -210,8 +221,8 @@ For power users who want direct access to helper functions:
 
 Documentation stays current through:
 
-1. **Automated Updates** - GitHub Actions fetches new docs every 3 hours
-2. **Pre-Command Check** - `/docs` checks for GitHub updates automatically
+1. **Repository Updates** - GitHub Actions fetches new docs every 3 hours
+2. **On-Demand Sync** - Run `/docs -t` to check for and pull updates
 3. **Auto-Regeneration** - Manifests regenerate from sitemaps on each fetch
 4. **Visual Feedback** - See "🔄 Updating documentation..." when updates occur
 
@@ -313,7 +324,7 @@ See [UNINSTALL.md](UNINSTALL.md) for manual removal instructions.
 - You can fork and install from your own repository
 
 **Validation:**
-- 618/620 tests passing (99.7% pass rate, 2 skipped)
+- 627/629 tests passing (99.7% pass rate, 2 skipped)
 - 78.7% code coverage
 - Automated security testing in CI/CD
 
@@ -338,7 +349,7 @@ source .venv/bin/activate
 pip install -e ".[dev]"
 
 # Run tests
-pytest tests/ -v  # Should see: 618 passed, 2 skipped
+pytest tests/ -v  # Should see: 627 passed, 2 skipped
 
 # Test coverage
 pytest --cov=scripts --cov-report=term  # Should see: ~78.7%

UNINSTALL.md

@@ -26,7 +26,7 @@ Navigate to your installation directory and run:
 The uninstaller will remove:
 
 1. **The /docs command** from `~/.claude/commands/docs.md`
-2. **The auto-update hook** from `~/.claude/settings.json`
+2. **Any legacy hooks** from `~/.claude/settings.json` (if present from older versions)
 3. **The installation directory**:
    - v0.3+: `~/.claude-code-docs`
    - v0.2 or older: wherever you installed it
@@ -40,8 +40,8 @@ If you prefer to uninstall manually:
 rm -f ~/.claude/commands/docs.md
 ```
 
-### 2. Remove the hook from Claude settings:
-Use /hooks in Claude Code CLI or Edit `~/.claude/settings.json` direction to remove the PreToolUse hook that references claude-code-docs.
+### 2. Remove any legacy hooks from Claude settings (if present):
+If you installed an older version (v0.4.1 or earlier), check `~/.claude/settings.json` and remove any PreToolUse hooks that reference claude-code-docs. Current versions (v0.4.2+) do not install hooks.
 
 ### 3. Remove the installation directory:
 

enhancements/CAPABILITIES.md

@@ -91,7 +91,7 @@ Searches within documentation content (not just path names):
 **Implementation**:
 - Pre-built search index: `docs/.search_index.json`
 - Index builder: `scripts/build_search_index.py`
-- Index size: ~45KB for 449 documents
+- Index size: ~45KB for 273 documents
 - Search speed: <100ms per query
 
 ## Validation Features
@@ -109,7 +109,7 @@ Validates HTTP reachability of all documentation paths:
 - **Broken link detection**: Identifies and reports unreachable paths
 
 **Validation metrics**:
-- Average validation time: ~30 seconds for 449 paths
+- Average validation time: ~30 seconds for 273 paths
 - Concurrent requests: Configurable (default: 10)
 - Request timeout: 10 seconds per path
 - Error handling: Retries with exponential backoff
@@ -149,7 +149,7 @@ Efficiently updates only changed documentation:
 
 Advanced fetching with enterprise features:
 
-- **Batch fetching**: Update all 449 paths efficiently
+- **Batch fetching**: Update all 273 paths efficiently
 - **Category updates**: Update specific categories only
 - **Rate limiting**: 0.5s delay between requests
 - **Retry logic**: Exponential backoff on failures
@@ -206,7 +206,7 @@ Advanced fetching with enterprise features:
 {
   "metadata": {
     "generated_at": "timestamp",
-    "total_paths": 449,
+    "total_paths": 273,
     "cleaned_at": "timestamp",
     "removed_broken_paths": 10,
     "original_total_paths": 459
@@ -246,7 +246,7 @@ Enhanced features integrate seamlessly:
 
 - **Path search**: ~90ms average
 - **Content search**: <100ms per query
-- **Index build**: ~2 seconds for 449 documents
+- **Index build**: ~2 seconds for 273 documents
 - **Index size**: ~45KB (minimal disk usage)
 
 ### Fetch Performance
@@ -258,7 +258,7 @@ Enhanced features integrate seamlessly:
 
 ### Validation Performance
 
-- **Full validation**: ~30 seconds for 449 paths
+- **Full validation**: ~30 seconds for 273 paths
 - **Parallel requests**: 10 concurrent by default
 - **Success rate**: >99%
 - **Resource usage**: Low CPU, minimal memory

enhancements/EXAMPLES.md

@@ -230,11 +230,11 @@ The system suggests:
 /docs --validate
 ```
 
-Validates that all 449 documentation paths are reachable on docs.anthropic.com.
+Validates that all 273 documentation paths are reachable on docs.anthropic.com.
 
 **Output includes**:
-- Total paths checked: 449
-- Successful: 449
+- Total paths checked: 273
+- Successful: 273
 - Failed: 0
 - Validation time: ~30s
 

enhancements/FEATURES.md

@@ -35,7 +35,7 @@ Searches across all documentation content, not just path names.
 
 **Command**: `/docs --validate`
 
-Validates all 449 paths are reachable on docs.anthropic.com.
+Validates all 273 paths are reachable on docs.anthropic.com.
 
 **Features**:
 - HTTP reachability testing
@@ -49,7 +49,7 @@ Validates all 449 paths are reachable on docs.anthropic.com.
 
 **Command**: `/docs --search 'query'`
 
-Fuzzy search across all 449 paths with relevance ranking.
+Fuzzy search across all 273 paths with relevance ranking.
 
 **Features**:
 - Levenshtein distance matching
@@ -76,7 +76,7 @@ Fuzzy search across all 449 paths with relevance ranking.
 **Script**: `scripts/main.py` (662 lines)
 
 **Features**:
-- Batch fetching of 449 paths
+- Batch fetching of 273 paths
 - SHA256-based change detection (only fetch what changed)
 - Retry logic with exponential backoff
 - Rate limiting (0.5s between requests)
@@ -85,7 +85,7 @@ Fuzzy search across all 449 paths with relevance ranking.
 
 **Usage**:
 ```bash
-python scripts/main.py --update-all           # Fetch all 449 docs
+python scripts/main.py --update-all           # Fetch all 273 docs
 python scripts/main.py --update-category core # Update specific category
 python scripts/main.py --verify              # Check what needs updating
 ```
@@ -166,7 +166,7 @@ These enhancements are designed to be contributed back to upstream as optional f
 
 **Proposed PRs**:
 1. **Optional Enhanced Mode** - Install script with Python features
-2. **Extended Path Coverage** - 449 paths manifest (opt-in)
+2. **Extended Path Coverage** - 273 paths manifest
 3. **Full-Text Search** - Search capability (opt-in)
 4. **Testing Framework** - Test suite for validation
 5. **Developer Documentation** - Enhanced docs
@@ -189,11 +189,11 @@ These enhancements are designed to be contributed back to upstream as optional f
 **Search Performance**:
 - Path search: ~90ms average
 - Content search: < 100ms per query
-- Index build time: ~2 seconds for 449 docs
+- Index build time: ~2 seconds for 273 docs
 - Index size: ~45KB
 
 **Validation Performance**:
-- Full validation: ~30 seconds for 449 paths (parallel)
+- Full validation: ~30 seconds for 273 paths (parallel)
 - Configurable concurrency
 
 ## License