cc-md-search-cli 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.2] - 2026-01-17
+
+### Changed
+- Reorganized installation section with grouped options (Bun, NPM, Clone Repository)
+- Added package location paths for each installation method
+- Added guidance for locating skill and rule template files
+- Clarified automatic CLI registration for global installs
+
+### Fixed
+- Fixed missing `-g` flag for npm global install command
+
+### Added
+- Header image to README
+
+## [1.0.1] - 2026-01-17
+
+### Added
+- New `outline` command - show document structure (headings only) without loading content
+- New `section` command - extract specific sections by heading name
+- New `grep` command alias - regex pattern matching with smart context
+- Smart context extraction - preserves code blocks and respects paragraph boundaries
+- Heading path display (e.g., `## Setup > ### Prerequisites`) for grep matches
+- Adaptive preview lengths for search results (600/300/150 chars based on rank)
+- Frontmatter filtering - only includes useful fields (title, description, tags, etc.)
+- `--raw` flag to disable context optimizations when needed
+- Multi-directory search support
+- New `CONFIGURATION.md` guide for documentation path setup
+- Cursor rules file (`rules/docs-search.mdc`) for IDE integration
+- Comprehensive test suite with 1900+ lines of tests
+- Test fixtures for various markdown scenarios
+
+### Changed
+- Shebang changed from `node` to `bun` for improved performance
+- Enhanced skill file with detailed usage examples and context-efficient patterns
+- Expanded README with full command reference and examples
+- Improved skill template for easier customization
+
+### Fixed
+- Context deduplication for overlapping grep matches
+
+## [1.0.0] - 2026-01-17
+
+### Added
+- Initial release of Claude Code Markdown Search CLI
+- Fuzzy search functionality using Fuse.js for flexible text matching
+- Regex pattern matching support for precise searches
+- Recursive directory scanning for markdown files
+- YAML frontmatter parsing via gray-matter
+- Multiple output formats: `plain`, `json`, `minimal`
+- Context-efficient output designed for AI assistant integration
+- Support for `.md` and `.mdx` file extensions
+- CLI commands: `search`, `list`, `stats`
+- Configurable search options (depth, limit, threshold)
+- Claude Code skill integration (`md-search`)
+
+[1.0.2]: https://github.com/bjeber/cc-md-search-cli/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/bjeber/cc-md-search-cli/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/bjeber/cc-md-search-cli/releases/tag/v1.0.0

package/CONFIGURATION.md

@@ -54,6 +54,9 @@ cp skills/SKILL.md ~/.claude/skills/md-search.md
 # Test that the CLI can find your docs
 ccmds list ./docs
 
+# View document structure
+ccmds outline ./docs -d 2
+
 # Try a search
 ccmds find "setup" ./docs -l 5
 ```
@@ -100,6 +103,35 @@ Once configured, Claude Code will **automatically search** your documentation wh
 
 **No manual path specification needed!**
 
+## Context Efficiency Features
+
+The CLI includes several optimizations to reduce AI context usage by 30-50%:
+
+### Smart Context (grep)
+- **Code block preservation** - Returns full code blocks when match is inside one
+- **Paragraph boundaries** - Stops at blank lines instead of arbitrary line counts
+- **Heading paths** - Shows `## Setup > ### Prerequisites` for each match
+- **Deduplication** - Overlapping matches are merged
+
+### Adaptive Previews (find)
+- Top 3 results: 600 characters
+- Results 4-7: 300 characters
+- Remaining: 150 characters
+
+### Frontmatter Filtering
+Only includes useful fields: `title`, `description`, `tags`, `category`, `summary`, `keywords`
+
+### New Commands for Targeted Access
+- `ccmds outline` - View structure without loading content
+- `ccmds section` - Extract only the section you need
+
+### Opt-out with --raw
+Use `--raw` flag to disable optimizations if needed:
+```bash
+ccmds grep "pattern" ./docs --raw -c 3  # Line-based context
+ccmds find "query" ./docs --raw          # Full frontmatter, fixed previews
+```
+
 ## Recommended Documentation Structure
 
 Organize your docs for best search results:

package/README.md

@@ -1,16 +1,24 @@
+![CC-MD-Search-CLI](assets/header.png)
+
 # CC-MD-Search-CLI
 
-**Claude Code Markdown Search - Efficient documentation search CLI for Claude Code integration**
+**Claude Code Markdown Search - Efficient documentation search CLI for AI coding assistants**
 
-Fast, context-efficient markdown documentation search tool designed for [Claude Code](https://claude.ai/claude-code). Quickly find relevant information across large documentation sets without loading entire files into context.
+Fast, context-efficient markdown documentation search tool designed for [Claude Code](https://claude.ai/claude-code) and [Cursor IDE](https://cursor.com). Quickly find relevant information across large documentation sets without loading entire files into context.
 
 ## Features
 
 - **Fuzzy Search** - Find relevant docs even with typos or variations
 - **Pattern/Regex Search** - Exact matches with regex support
+- **Smart Context** - Paragraph and code-block aware context extraction
+- **Heading Paths** - Shows parent heading hierarchy for each match
+- **Document Outlines** - View document structure without content
+- **Section Extraction** - Fetch specific sections by heading
 - **Frontmatter Aware** - Parses YAML metadata for better search
+- **Adaptive Previews** - Top results get longer previews automatically
 - **Multiple Output Modes** - compact, detailed, files, json
-- **Claude Code Skill** - Pre-built skill template for AI integration
+- **Claude Code Skill** - Pre-built skill template for Claude Code integration
+- **Cursor Rule** - Pre-built rule template for Cursor IDE integration
 - **Context Efficient** - Minimize token usage when searching docs
 
 ## Installation
@@ -20,10 +28,29 @@ Fast, context-efficient markdown documentation search tool designed for [Claude
 - [Bun](https://bun.sh/) (recommended) or Node.js 18+
 - npm or pnpm
 
-### Install
+### Option 1: Bun (Recommended)
+
+```bash
+bun add -g cc-md-search-cli
+```
+
+The `ccmds` command is automatically registered globally.
+
+**Package location:** `~/.bun/install/global/node_modules/cc-md-search-cli/`
+
+### Option 2: NPM
+
+```bash
+npm i -g cc-md-search-cli
+```
+
+The `ccmds` command is automatically registered globally.
+
+**Package location:** Run `npm root -g` to find the path (typically `/usr/local/lib/node_modules/cc-md-search-cli/` or `~/.npm-global/lib/node_modules/cc-md-search-cli/`)
+
+### Option 3: Clone Repository
 
 ```bash
-# Clone the repository
 git clone https://github.com/bjeber/cc-md-search-cli.git
 cd cc-md-search-cli
 
@@ -31,11 +58,15 @@ cd cc-md-search-cli
 bun install
 # or: npm install
 
-# Link the CLI globally
+# Link the CLI globally (required for cloned repos)
 npm link
 ```
 
-After linking, the `ccmds` command will be available globally.
+**Package location:** Your cloned directory
+
+**Skill & Rule files** are located in the package directory:
+- `skills/SKILL.md` - Claude Code skill template
+- `rules/docs-search.mdc` - Cursor IDE rule template
 
 ## Quick Start
 
@@ -43,11 +74,29 @@ After linking, the `ccmds` command will be available globally.
 # List all markdown files in a directory
 ccmds list ./docs
 
+# List files from multiple directories
+ccmds list ./docs ./api/docs ./guides
+
 # Fuzzy search for relevant documents
 ccmds find "authentication" ./docs -l 5
 
-# Pattern search with regex
-ccmds grep "TODO|FIXME" ./docs -c 3
+# Search across multiple directories
+ccmds find "authentication" ./docs ./api/docs ./guides -l 5
+
+# Pattern search with regex (smart context preserves code blocks)
+ccmds grep "TODO|FIXME" ./docs
+
+# Grep across multiple directories
+ccmds grep "TODO|FIXME" ./docs ./api/docs
+
+# View document structure without content
+ccmds outline ./docs
+
+# View structure across multiple directories
+ccmds outline ./docs ./api/docs -d 2
+
+# Extract a specific section by heading
+ccmds section ./docs/setup.md "Installation"
 
 # Show a specific file
 ccmds show ./docs/api/auth.md
@@ -55,36 +104,50 @@ ccmds show ./docs/api/auth.md
 
 ## Commands
 
-### `ccmds find <query> [directory]` - Fuzzy Search
+### `ccmds find <query> [directories...]` - Fuzzy Search
+
+Find relevant documents using fuzzy matching with extended search syntax. Great for exploratory searches. Features adaptive preview lengths (top results get more content) and filtered frontmatter. Supports searching across multiple directories simultaneously.
 
-Find relevant documents using fuzzy matching. Great for exploratory searches.
+**Extended Search Syntax:**
+| Pattern | Meaning | Example |
+|---------|---------|---------|
+| `word1 word2` | AND (all must match) | `auth setup` |
+| `word1 \| word2` | OR (either matches) | `install \| setup` |
+| `'exact` | Exact substring | `'authentication` |
+| `^prefix` | Starts with | `^Config` |
+| `suffix$` | Ends with | `Guide$` |
 
 ```bash
-ccmds find "user authentication" ./docs -l 5 -o compact
-ccmds find "deploy production" ./docs -o files
+ccmds find "authentication middleware" ./docs -l 5  # AND search
+ccmds find "setup | installation" ./docs            # OR search
+ccmds find "'API Reference" ./docs -o files         # Exact match
+ccmds find "deploy" ./docs --raw                    # Disable optimizations
 ```
 
 **Options:**
 - `-l, --limit <number>` - Maximum results (default: 10)
 - `-o, --output <mode>` - Output format: compact, detailed, files, json
+- `-r, --raw` - Disable adaptive previews and frontmatter filtering
 
-### `ccmds grep <pattern> [directory]` - Pattern Search
+### `ccmds grep <pattern> [directories...]` - Pattern Search
 
-Search for exact text patterns with regex support.
+Search for exact text patterns with regex support. Uses smart context that preserves code blocks and paragraph boundaries, and shows heading paths for each match. Supports searching across multiple directories simultaneously.
 
 ```bash
-ccmds grep "ERROR_[0-9]+" ./docs -c 3
+ccmds grep "ERROR_[0-9]+" ./docs
 ccmds grep "GraphQL" ./docs --case-sensitive
+ccmds grep "TODO" ./docs --raw -c 3  # Line-based context instead
 ```
 
 **Options:**
-- `-c, --context <lines>` - Lines of context around matches (default: 2)
+- `-c, --context <lines>` - Lines of context around matches (default: 2, used with --raw)
 - `-s, --case-sensitive` - Case sensitive search
 - `-o, --output <mode>` - Output format
+- `-r, --raw` - Disable smart context (use line-based context)
 
-### `ccmds list [directory]` - List Files
+### `ccmds list [directories...]` - List Files
 
-List all markdown files in a directory.
+List all markdown files in one or more directories.
 
 ```bash
 ccmds list ./docs
@@ -108,6 +171,35 @@ ccmds show ./docs/guide.md --body-only
 - `-f, --frontmatter-only` - Show only YAML frontmatter
 - `-b, --body-only` - Show only body content
 
+### `ccmds outline [paths...]` - Document Structure
+
+Show document structure (headings only) without content. Great for understanding document organization. Supports files, directories, or multiple paths.
+
+```bash
+ccmds outline ./docs/guide.md           # Single file
+ccmds outline ./docs                     # All files in directory
+ccmds outline ./docs -d 2                # Limit to h1 and h2
+ccmds outline ./docs -o json             # JSON output
+```
+
+**Options:**
+- `-d, --depth <number>` - Maximum heading depth (default: 6)
+- `-o, --output <mode>` - Output format: text, json
+
+### `ccmds section <file> <heading>` - Extract Section
+
+Extract a specific section by heading text. Useful for fetching just the content you need.
+
+```bash
+ccmds section ./docs/setup.md "Installation"
+ccmds section ./docs/api.md "Authentication"
+ccmds section ./docs/guide.md "Setup > Prerequisites"  # Nested heading
+ccmds section ./docs/api.md "Endpoints" -o json
+```
+
+**Options:**
+- `-o, --output <mode>` - Output format: text, json
+
 ## Claude Code Integration
 
 To use this tool with Claude Code, install the skill to your Claude Code skills directory.
@@ -147,6 +239,58 @@ The SKILL.md includes:
 - **Workflow strategies** for efficient documentation search
 - **Best practices** for context-efficient searches
 
+## Cursor Integration
+
+To use this tool with Cursor IDE, install the rule to your project's `.cursor/rules/` directory.
+
+### 1. Install the Rule
+
+```bash
+# Create the rules directory in your project
+mkdir -p .cursor/rules
+
+# Copy the rule file
+cp rules/docs-search.mdc .cursor/rules/docs-search.mdc
+```
+
+### 2. Configure Your Docs Path
+
+Edit `.cursor/rules/docs-search.mdc` and update the `DOCS_PATH` variable at the top:
+
+```markdown
+## Configuration
+
+**DOCS_PATH**: `./docs`  # Change this to your docs directory
+```
+
+Replace `./docs` with your actual documentation path (e.g., `./documentation`, `./docs/api`, etc.).
+
+### 3. Use with Cursor
+
+Once installed, Cursor will automatically include this rule when relevant (Agent Requested mode). The rule activates when you ask questions about documentation:
+
+- "How do I set up authentication?"
+- "What are the API endpoints?"
+- "Where is the deployment guide?"
+
+Cursor will use `ccmds` to search your documentation with minimal context usage.
+
+### 4. Rule Structure
+
+The rule follows Cursor's `.mdc` format:
+
+```
+.cursor/rules/
+└── docs-search.mdc    # Rule definition with YAML frontmatter
+```
+
+The rule includes:
+- **YAML frontmatter** with `description` for Agent Requested mode
+- **Configurable DOCS_PATH** at the top for easy customization
+- **Command reference** for all `ccmds` commands
+- **Workflow strategies** for efficient documentation search
+- **Best practices** for context-efficient searches
+
 ## Output Modes
 
 | Mode | Description | Use Case |
@@ -160,19 +304,34 @@ The SKILL.md includes:
 
 ### Progressive Search
 
-1. Start broad with `find` to discover relevant docs
-2. Narrow down with `grep` for specific patterns
-3. Use `show` to read the exact file you need
+1. Start with `outline` to understand document structure
+2. Use `find` to discover relevant docs
+3. Use `section` to extract just what you need
 
 ```bash
-# Discover
+# Understand structure
+ccmds outline ./docs -d 2
+
+# Discover relevant docs
 ccmds find "database" ./docs -o files
 
-# Narrow down
-ccmds grep "migration" ./docs/database -c 5
+# Extract specific section
+ccmds section ./docs/database/migrations.md "Schema Changes"
+```
 
-# Read specific file
-ccmds show ./docs/database/migrations.md
+### Smart Context Search
+
+Grep automatically preserves code blocks and shows heading paths:
+
+```bash
+# Search returns full code blocks when match is inside one
+ccmds grep "npm install" ./docs
+
+# Output shows heading path:
+# ◆ ## Installation > ### Prerequisites (lines 10-25)
+# ```bash
+# npm install my-package
+# ```
 ```
 
 ### Quick Lookup
@@ -180,6 +339,9 @@ ccmds show ./docs/database/migrations.md
 ```bash
 # Find and show top result
 ccmds find "installation" ./docs -l 1 -o files | xargs ccmds show
+
+# Or extract just the installation section
+ccmds section ./docs/setup.md "Installation"
 ```
 
 ## Documentation Structure (Recommended)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-md-search-cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Claude Code Markdown Search - Efficient documentation search CLI for Claude Code integration",
   "type": "module",
   "bin": {
@@ -8,7 +8,10 @@
   },
   "scripts": {
     "build": "echo 'No build needed for Bun'",
-    "link": "npm link"
+    "link": "npm link",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "test:watch": "bun test --watch"
   },
   "keywords": [
     "markdown",