cc-md-search-cli 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.4] - 2026-01-23
+
+### Added
+
+- **Interactive `init` wizard** - `ccmds init` now runs an interactive configuration wizard in TTY environments
+  - Prompts for document directories with option to create non-existent paths
+  - Named directory support with optional descriptions
+  - Common exclude pattern presets via checkbox selection
+  - Output mode selection
+  - Advanced options: result limit, fuzzy threshold, file extensions, caching
+- **`--no-interactive` flag** - Skip the wizard and use non-interactive mode
+- **`update` command** - `ccmds update` to check for and install latest version
+- **Version check on `--version`** - Shows update availability when checking version
+- **New dependencies** - @inquirer/prompts, chalk, ora for terminal UI
+- **Context-aware previews for `find`** - Previews now show the paragraph or code block where the search term appears, instead of the beginning of the file
+  - Uses smart boundary detection (blank lines, headings, code fences)
+  - Preserves complete code blocks when match is in code
+  - Shows full bullet lists and paragraphs for text matches
+  - Falls back to description/file start if no body match found
+  - Configurable via `preview.maxLines` (default: 20) to limit context size
+- **Extended query operators** - `'term` for exact substring match, `!term` for exclusion, space-separated terms for AND search
+- **`--clear-cache` flag** - Clear search index cache before running `find` or `grep` commands
+
+### Changed
+
+- **Minimal config generation** - Generated configs only include values that differ from defaults
+- **Exclude patterns prompt** - Now asks "Add exclude patterns?" first (default: No) before showing the list
+- **README quickstart** - Simplified to use `ccmds init` interactive wizard
+- **Replaced Fuse.js with FlexSearch** - New search engine with forward tokenization and resolution-based ranking
+- **Index storage format** - Changed from `.ccmds-fuse-index.json` + `.ccmds-fuse-index-meta.json` files to `.ccmds-flexsearch/` directory structure
+- **Search index version** - Bumped to version 5 for automatic cache invalidation
+- **Default index path** - Changed from `.ccmds-fuse-index.json` to `.ccmds-flexsearch/`
+
+### Removed
+
+- **Fuse.js dependency** - Replaced by FlexSearch
+- **Fuse.js-specific config options** - `ignoreLocation`, `ignoreFieldNorm`, `distance` no longer apply
+
 ## [1.0.3] - 2026-01-22
 
 ### Added
@@ -99,6 +137,7 @@ All notable changes to this project will be documented in this file.
 - Configurable search options (depth, limit, threshold)
 - Claude Code skill integration (`ccmds`)
 
+[1.0.4]: https://github.com/bjeber/cc-md-search-cli/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/bjeber/cc-md-search-cli/compare/v1.0.2...v1.0.3
 [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

package/CONFIGURATION.md

@@ -23,17 +23,32 @@ ccmds find "authentication"
 
 ### Creating a Config File
 
+The `init` command creates a `.ccmdsrc` configuration file. By default, it runs an **interactive wizard** when in a terminal (TTY).
+
 ```bash
-# Create with default settings
-ccmds init
+# Interactive mode (default in terminal)
+ccmds init                    # Guides you through configuration options
 
-# Create with custom directories
-ccmds init -d ./docs ./wiki
+# Non-interactive mode
+ccmds init --no-interactive   # Creates config with defaults
+ccmds init -d ./docs ./wiki   # Pre-fills directories, still interactive
+ccmds init --no-interactive -d ./docs  # Fully non-interactive
 
 # Overwrite existing config
-ccmds init --force
+ccmds init --force            # Works with both interactive/non-interactive
 ```
 
+**Interactive mode** prompts for:
+1. Document directories (with option to create non-existent dirs)
+2. Exclude patterns (common presets + custom)
+3. Output mode
+4. Advanced options (limit, fuzzy threshold, extensions, caching)
+
+**Non-interactive mode** is used automatically when:
+- Running in CI/CD pipelines (no TTY)
+- Using `--no-interactive` flag
+- Piping input/output
+
 ### File Locations
 
 The CLI looks for config files in this order:
@@ -73,6 +88,7 @@ The CLI looks for config files in this order:
     }
   },
   "preview": {
+    "maxLines": 20,
     "topResults": 600,
     "midResults": 300,
     "otherResults": 150
@@ -93,15 +109,19 @@ The CLI looks for config files in this order:
 | `limit` | `number` | `10` | Default result limit for find |
 | `fuzzy.threshold` | `number` | `0.4` | Fuzzy match threshold (0=exact, 1=loose) |
 | `fuzzy.weights` | `object` | See above | Field weights for search scoring |
-| `preview.topResults` | `number` | `600` | Preview chars for results 1-3 |
-| `preview.midResults` | `number` | `300` | Preview chars for results 4-7 |
-| `preview.otherResults` | `number` | `150` | Preview chars for remaining results |
+| `preview.maxLines` | `number` | `20` | Max lines for context-aware previews |
+| `preview.topResults` | `number` | `600` | Fallback preview chars for results 1-3 |
+| `preview.midResults` | `number` | `300` | Fallback preview chars for results 4-7 |
+| `preview.otherResults` | `number` | `150` | Fallback preview chars for remaining |
 | `frontmatterFields` | `string[]` | See above | Frontmatter fields to include |
 | `extensions` | `string[]` | `[".md", ".markdown"]` | File extensions to search |
 | `aliases` | `object` | `{}` | Command shortcuts (planned) |
 | `cache.enabled` | `boolean` | `false` | Enable result caching |
 | `cache.ttl` | `number` | `300` | Cache expiration in seconds |
 | `cache.maxEntries` | `number` | `50` | Maximum cached queries |
+| `index.enabled` | `boolean` | `true` | Enable FlexSearch index caching |
+| `index.path` | `string` | `".ccmds-flexsearch/"` | Index directory location |
+| `index.autoRebuild` | `boolean` | `true` | Auto-rebuild when files change |
 
 ---
 
@@ -382,6 +402,85 @@ Cache is stored in `.ccmds-cache.json` in the project root.
 
 ---
 
+## Search Index (Performance)
+
+The CLI automatically caches the FlexSearch index to dramatically improve search performance (60-80% faster on subsequent searches).
+
+### How It Works
+
+1. **First search**: Builds index, saves to `.ccmds-flexsearch/` directory
+2. **Subsequent searches**: Loads cached index if files haven't changed
+3. **Auto-invalidation**: Detects file changes via mtime hashes
+
+### Configuration
+
+```json
+{
+  "index": {
+    "enabled": true,
+    "path": ".ccmds-flexsearch/",
+    "autoRebuild": true
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `true` | Enable index caching |
+| `path` | `".ccmds-flexsearch/"` | Index directory location |
+| `autoRebuild` | `true` | Automatically rebuild when files change |
+
+### Index Commands
+
+```bash
+# View index statistics
+ccmds index stats
+
+# Clear cached index
+ccmds index clear
+
+# Force rebuild index
+ccmds index rebuild
+```
+
+### Force Rebuild on Search
+
+```bash
+ccmds find "query" --rebuild-index
+```
+
+### Clear Cache Before Search
+
+```bash
+ccmds find "query" --clear-cache
+```
+
+### Query Operators
+
+FlexSearch supports extended query operators:
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| (default) | `auth` | Fuzzy/prefix match |
+| `'term` | `'authentication` | Exact substring match |
+| `!term` | `!deprecated` | Exclude results containing term |
+| space | `auth api` | AND search (both terms required) |
+
+### Files Created
+
+- `.ccmds-flexsearch/` - FlexSearch index directory containing:
+  - `meta.json` - Metadata with version, timestamp, and file hashes
+  - Multiple `.json` segment files - Indexed document data
+
+Add to `.gitignore`:
+
+```
+.ccmds-flexsearch/
+.ccmds-cache.json
+```
+
+---
+
 ## Context Efficiency Features
 
 The CLI includes optimizations to reduce AI context usage by 30-50%:
@@ -392,10 +491,12 @@ The CLI includes optimizations to reduce AI context usage by 30-50%:
 - **Heading paths** - Shows `## Setup > ### Prerequisites` for each match
 - **Deduplication** - Overlapping matches are merged
 
-### Adaptive Previews (find)
-- Top 3 results: 600 characters (configurable via `preview.topResults`)
-- Results 4-7: 300 characters (configurable via `preview.midResults`)
-- Remaining: 150 characters (configurable via `preview.otherResults`)
+### Context-Aware Previews (find)
+- **Shows the actual paragraph or code block** where the search term appears
+- Uses smart boundary detection (blank lines, headings, code fences)
+- Preserves complete code blocks when match is inside one
+- Configurable line limit via `preview.maxLines` (default: 20)
+- Falls back to file start when no body match (uses `preview.topResults`/`midResults`/`otherResults`)
 
 ### Frontmatter Filtering
 Only includes useful fields by default: `title`, `description`, `tags`, `category`, `summary`, `keywords`

package/README.md

@@ -34,18 +34,10 @@ npm i -g cc-md-search-cli
 
 ```bash
 cd your-project
-ccmds init -d ./docs    # Creates .ccmdsrc config file
-```
-
-This creates a `.ccmdsrc` file with `documentDirectories` pointing to your docs folder. **This is the key setting** - it tells ccmds where your documentation lives:
-
-```json
-{
-  "documentDirectories": ["./docs"]
-}
+ccmds init
 ```
 
-Adjust the path to match your project's documentation location (e.g., `./documentation`, `./wiki`, or multiple directories).
+This runs an interactive wizard that creates a `.ccmdsrc` configuration file in the current directory. It guides you through setting up your documentation directories and search preferences.
 
 #### Project-Level Agent Instructions
 
@@ -133,6 +125,7 @@ The AI uses these commands behind the scenes when you ask questions like:
 | `ccmds docs`                     | List all configured documentations      |
 | `ccmds config`                   | Show current configuration              |
 | `ccmds init`                     | Create configuration file               |
+| `ccmds update`                   | Update to latest version                |
 
 **Common options:**
 
@@ -148,7 +141,9 @@ See `ccmds --help` or `ccmds <command> --help` for full options.
 Create a `.ccmdsrc` file in your project root:
 
 ```bash
-ccmds init
+ccmds init              # Interactive wizard (in terminal)
+ccmds init -d ./docs    # Pre-fill directories
+ccmds init --no-interactive  # Skip wizard, use defaults
 ```
 
 Example configuration:
@@ -209,6 +204,28 @@ bun install
 npm link
 ```
 
+## Updating
+
+Check for and install updates:
+
+```bash
+# Check if update available
+ccmds update --check
+
+# Update to latest version
+ccmds update
+```
+
+Or update manually:
+
+```bash
+# Using Bun
+bun update -g cc-md-search-cli
+
+# Using npm
+npm update -g cc-md-search-cli
+```
+
 ## AI Assistant Integration
 
 ### Claude Code

package/bun.lock

@@ -5,35 +5,127 @@
     "": {
       "name": "cc-md-search-cli",
       "dependencies": {
+        "@inquirer/prompts": "^8.2.0",
+        "chalk": "^5.6.2",
         "commander": "^11.1.0",
-        "fuse.js": "^7.0.0",
+        "flexsearch": "^0.8.0",
         "gray-matter": "^4.0.3",
+        "ora": "^9.1.0",
+      },
+      "devDependencies": {
+        "@inquirer/testing": "^3.0.4",
       },
     },
   },
   "packages": {
+    "@inquirer/ansi": ["@inquirer/ansi@2.0.3", "", {}, "sha512-g44zhR3NIKVs0zUesa4iMzExmZpLUdTLRMCStqX3GE5NT6VkPcxQGJ+uC8tDgBUC/vB1rUhUd55cOf++4NZcmw=="],
+
+    "@inquirer/checkbox": ["@inquirer/checkbox@5.0.4", "", { "dependencies": { "@inquirer/ansi": "^2.0.3", "@inquirer/core": "^11.1.1", "@inquirer/figures": "^2.0.3", "@inquirer/type": "^4.0.3" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-DrAMU3YBGMUAp6ArwTIp/25CNDtDbxk7UjIrrtM25JVVrlVYlVzHh5HR1BDFu9JMyUoZ4ZanzeaHqNDttf3gVg=="],
+
+    "@inquirer/confirm": ["@inquirer/confirm@6.0.4", "", { "dependencies": { "@inquirer/core": "^11.1.1", "@inquirer/type": "^4.0.3" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-WdaPe7foUnoGYvXzH4jp4wH/3l+dBhZ3uwhKjXjwdrq5tEIFaANxj6zrGHxLdsIA0yKM0kFPVcEalOZXBB5ISA=="],
+
+    "@inquirer/core": ["@inquirer/core@11.1.1", "", { "dependencies": { "@inquirer/ansi": "^2.0.3", "@inquirer/figures": "^2.0.3", "@inquirer/type": "^4.0.3", "cli-width": "^4.1.0", "mute-stream": "^3.0.0", "signal-exit": "^4.1.0", "wrap-ansi": "^9.0.2" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-hV9o15UxX46OyQAtaoMqAOxGR8RVl1aZtDx1jHbCtSJy1tBdTfKxLPKf7utsE4cRy4tcmCQ4+vdV+ca+oNxqNA=="],
+
+    "@inquirer/editor": ["@inquirer/editor@5.0.4", "", { "dependencies": { "@inquirer/core": "^11.1.1", "@inquirer/external-editor": "^2.0.3", "@inquirer/type": "^4.0.3" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-QI3Jfqcv6UO2/VJaEFONH8Im1ll++Xn/AJTBn9Xf+qx2M+H8KZAdQ5sAe2vtYlo+mLW+d7JaMJB4qWtK4BG3pw=="],
+
+    "@inquirer/expand": ["@inquirer/expand@5.0.4", "", { "dependencies": { "@inquirer/core": "^11.1.1", "@inquirer/type": "^4.0.3" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-0I/16YwPPP0Co7a5MsomlZLpch48NzYfToyqYAOWtBmaXSB80RiNQ1J+0xx2eG+Wfxt0nHtpEWSRr6CzNVnOGg=="],
+
+    "@inquirer/external-editor": ["@inquirer/external-editor@2.0.3", "", { "dependencies": { "chardet": "^2.1.1", "iconv-lite": "^0.7.2" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-LgyI7Agbda74/cL5MvA88iDpvdXI2KuMBCGRkbCl2Dg1vzHeOgs+s0SDcXV7b+WZJrv2+ERpWSM65Fpi9VfY3w=="],
+
+    "@inquirer/figures": ["@inquirer/figures@2.0.3", "", {}, "sha512-y09iGt3JKoOCBQ3w4YrSJdokcD8ciSlMIWsD+auPu+OZpfxLuyz+gICAQ6GCBOmJJt4KEQGHuZSVff2jiNOy7g=="],
+
+    "@inquirer/input": ["@inquirer/input@5.0.4", "", { "dependencies": { "@inquirer/core": "^11.1.1", "@inquirer/type": "^4.0.3" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-4B3s3jvTREDFvXWit92Yc6jF1RJMDy2VpSqKtm4We2oVU65YOh2szY5/G14h4fHlyQdpUmazU5MPCFZPRJ0AOw=="],
+
+    "@inquirer/number": ["@inquirer/number@4.0.4", "", { "dependencies": { "@inquirer/core": "^11.1.1", "@inquirer/type": "^4.0.3" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-CmMp9LF5HwE+G/xWsC333TlCzYYbXMkcADkKzcawh49fg2a1ryLc7JL1NJYYt1lJ+8f4slikNjJM9TEL/AljYQ=="],
+
+    "@inquirer/password": ["@inquirer/password@5.0.4", "", { "dependencies": { "@inquirer/ansi": "^2.0.3", "@inquirer/core": "^11.1.1", "@inquirer/type": "^4.0.3" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-ZCEPyVYvHK4W4p2Gy6sTp9nqsdHQCfiPXIP9LbJVW4yCinnxL/dDDmPaEZVysGrj8vxVReRnpfS2fOeODe9zjg=="],
+
+    "@inquirer/prompts": ["@inquirer/prompts@8.2.0", "", { "dependencies": { "@inquirer/checkbox": "^5.0.4", "@inquirer/confirm": "^6.0.4", "@inquirer/editor": "^5.0.4", "@inquirer/expand": "^5.0.4", "@inquirer/input": "^5.0.4", "@inquirer/number": "^4.0.4", "@inquirer/password": "^5.0.4", "@inquirer/rawlist": "^5.2.0", "@inquirer/search": "^4.1.0", "@inquirer/select": "^5.0.4" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-rqTzOprAj55a27jctS3vhvDDJzYXsr33WXTjODgVOru21NvBo9yIgLIAf7SBdSV0WERVly3dR6TWyp7ZHkvKFA=="],
+
+    "@inquirer/rawlist": ["@inquirer/rawlist@5.2.0", "", { "dependencies": { "@inquirer/core": "^11.1.1", "@inquirer/type": "^4.0.3" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-CciqGoOUMrFo6HxvOtU5uL8fkjCmzyeB6fG7O1vdVAZVSopUBYECOwevDBlqNLyyYmzpm2Gsn/7nLrpruy9RFg=="],
+
+    "@inquirer/search": ["@inquirer/search@4.1.0", "", { "dependencies": { "@inquirer/core": "^11.1.1", "@inquirer/figures": "^2.0.3", "@inquirer/type": "^4.0.3" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-EAzemfiP4IFvIuWnrHpgZs9lAhWDA0GM3l9F4t4mTQ22IFtzfrk8xbkMLcAN7gmVML9O/i+Hzu8yOUyAaL6BKA=="],
+
+    "@inquirer/select": ["@inquirer/select@5.0.4", "", { "dependencies": { "@inquirer/ansi": "^2.0.3", "@inquirer/core": "^11.1.1", "@inquirer/figures": "^2.0.3", "@inquirer/type": "^4.0.3" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-s8KoGpPYMEQ6WXc0dT9blX2NtIulMdLOO3LA1UKOiv7KFWzlJ6eLkEYTDBIi+JkyKXyn8t/CD6TinxGjyLt57g=="],
+
+    "@inquirer/testing": ["@inquirer/testing@3.0.4", "", { "dependencies": { "@inquirer/type": "^4.0.3", "mute-stream": "^3.0.0" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-iSx1+r44QsBWD0o/a3xIM8EoXcyVNncBhZ7cofHbGNtHfJk5X16Ne/gNNYVb0jdYbENSCMH0deWjgJ5P2cjJRg=="],
+
+    "@inquirer/type": ["@inquirer/type@4.0.3", "", { "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-cKZN7qcXOpj1h+1eTTcGDVLaBIHNMT1Rz9JqJP5MnEJ0JhgVWllx7H/tahUp5YEK1qaByH2Itb8wLG/iScD5kw=="],
+
+    "ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="],
+
+    "ansi-styles": ["ansi-styles@6.2.3", "", {}, "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg=="],
+
     "argparse": ["argparse@1.0.10", "", { "dependencies": { "sprintf-js": "~1.0.2" } }, "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg=="],
 
+    "chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
+
+    "chardet": ["chardet@2.1.1", "", {}, "sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ=="],
+
+    "cli-cursor": ["cli-cursor@5.0.0", "", { "dependencies": { "restore-cursor": "^5.0.0" } }, "sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw=="],
+
+    "cli-spinners": ["cli-spinners@3.4.0", "", {}, "sha512-bXfOC4QcT1tKXGorxL3wbJm6XJPDqEnij2gQ2m7ESQuE+/z9YFIWnl/5RpTiKWbMq3EVKR4fRLJGn6DVfu0mpw=="],
+
+    "cli-width": ["cli-width@4.1.0", "", {}, "sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ=="],
+
     "commander": ["commander@11.1.0", "", {}, "sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ=="],
 
+    "emoji-regex": ["emoji-regex@10.6.0", "", {}, "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A=="],
+
     "esprima": ["esprima@4.0.1", "", { "bin": { "esparse": "./bin/esparse.js", "esvalidate": "./bin/esvalidate.js" } }, "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="],
 
     "extend-shallow": ["extend-shallow@2.0.1", "", { "dependencies": { "is-extendable": "^0.1.0" } }, "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug=="],
 
-    "fuse.js": ["fuse.js@7.1.0", "", {}, "sha512-trLf4SzuuUxfusZADLINj+dE8clK1frKdmqiJNb1Es75fmI5oY6X2mxLVUciLLjxqw/xr72Dhy+lER6dGd02FQ=="],
+    "flexsearch": ["flexsearch@0.8.212", "", {}, "sha512-wSyJr1GUWoOOIISRu+X2IXiOcVfg9qqBRyCPRUdLMIGJqPzMo+jMRlvE83t14v1j0dRMEaBbER/adQjp6Du2pw=="],
+
+    "get-east-asian-width": ["get-east-asian-width@1.4.0", "", {}, "sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q=="],
 
     "gray-matter": ["gray-matter@4.0.3", "", { "dependencies": { "js-yaml": "^3.13.1", "kind-of": "^6.0.2", "section-matter": "^1.0.0", "strip-bom-string": "^1.0.0" } }, "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q=="],
 
+    "iconv-lite": ["iconv-lite@0.7.2", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw=="],
+
     "is-extendable": ["is-extendable@0.1.1", "", {}, "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw=="],
 
+    "is-interactive": ["is-interactive@2.0.0", "", {}, "sha512-qP1vozQRI+BMOPcjFzrjXuQvdak2pHNUMZoeG2eRbiSqyvbEf/wQtEOTOX1guk6E3t36RkaqiSt8A/6YElNxLQ=="],
+
+    "is-unicode-supported": ["is-unicode-supported@2.1.0", "", {}, "sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ=="],
+
     "js-yaml": ["js-yaml@3.14.2", "", { "dependencies": { "argparse": "^1.0.7", "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg=="],
 
     "kind-of": ["kind-of@6.0.3", "", {}, "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw=="],
 
+    "log-symbols": ["log-symbols@7.0.1", "", { "dependencies": { "is-unicode-supported": "^2.0.0", "yoctocolors": "^2.1.1" } }, "sha512-ja1E3yCr9i/0hmBVaM0bfwDjnGy8I/s6PP4DFp+yP+a+mrHO4Rm7DtmnqROTUkHIkqffC84YY7AeqX6oFk0WFg=="],
+
+    "mimic-function": ["mimic-function@5.0.1", "", {}, "sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA=="],
+
+    "mute-stream": ["mute-stream@3.0.0", "", {}, "sha512-dkEJPVvun4FryqBmZ5KhDo0K9iDXAwn08tMLDinNdRBNPcYEDiWYysLcc6k3mjTMlbP9KyylvRpd4wFtwrT9rw=="],
+
+    "onetime": ["onetime@7.0.0", "", { "dependencies": { "mimic-function": "^5.0.0" } }, "sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ=="],
+
+    "ora": ["ora@9.1.0", "", { "dependencies": { "chalk": "^5.6.2", "cli-cursor": "^5.0.0", "cli-spinners": "^3.2.0", "is-interactive": "^2.0.0", "is-unicode-supported": "^2.1.0", "log-symbols": "^7.0.1", "stdin-discarder": "^0.2.2", "string-width": "^8.1.0" } }, "sha512-53uuLsXHOAJl5zLrUrzY9/kE+uIFEx7iaH4g2BIJQK4LZjY4LpCCYZVKDWIkL+F01wAaCg93duQ1whnK/AmY1A=="],
+
+    "restore-cursor": ["restore-cursor@5.1.0", "", { "dependencies": { "onetime": "^7.0.0", "signal-exit": "^4.1.0" } }, "sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA=="],
+
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+
     "section-matter": ["section-matter@1.0.0", "", { "dependencies": { "extend-shallow": "^2.0.1", "kind-of": "^6.0.0" } }, "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA=="],
 
+    "signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="],
+
     "sprintf-js": ["sprintf-js@1.0.3", "", {}, "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g=="],
 
+    "stdin-discarder": ["stdin-discarder@0.2.2", "", {}, "sha512-UhDfHmA92YAlNnCfhmq0VeNL5bDbiZGg7sZ2IvPsXubGkiNa9EC+tUTsjBRsYUAz87btI6/1wf4XoVvQ3uRnmQ=="],
+
+    "string-width": ["string-width@8.1.0", "", { "dependencies": { "get-east-asian-width": "^1.3.0", "strip-ansi": "^7.1.0" } }, "sha512-Kxl3KJGb/gxkaUMOjRsQ8IrXiGW75O4E3RPjFIINOVH8AMl2SQ/yWdTzWwF3FevIX9LcMAjJW+GRwAlAbTSXdg=="],
+
+    "strip-ansi": ["strip-ansi@7.1.2", "", { "dependencies": { "ansi-regex": "^6.0.1" } }, "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA=="],
+
     "strip-bom-string": ["strip-bom-string@1.0.0", "", {}, "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g=="],
+
+    "wrap-ansi": ["wrap-ansi@9.0.2", "", { "dependencies": { "ansi-styles": "^6.2.1", "string-width": "^7.0.0", "strip-ansi": "^7.1.0" } }, "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww=="],
+
+    "yoctocolors": ["yoctocolors@2.1.2", "", {}, "sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug=="],
+
+    "wrap-ansi/string-width": ["string-width@7.2.0", "", { "dependencies": { "emoji-regex": "^10.3.0", "get-east-asian-width": "^1.0.0", "strip-ansi": "^7.1.0" } }, "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ=="],
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-md-search-cli",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Claude Code Markdown Search - Efficient documentation search CLI for Claude Code integration",
   "type": "module",
   "bin": {
@@ -32,8 +32,14 @@
     "url": "https://github.com/bjeber/cc-md-search-cli/issues"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.2.0",
+    "chalk": "^5.6.2",
     "commander": "^11.1.0",
+    "flexsearch": "^0.8.0",
     "gray-matter": "^4.0.3",
-    "fuse.js": "^7.0.0"
+    "ora": "^9.1.0"
+  },
+  "devDependencies": {
+    "@inquirer/testing": "^3.0.4"
   }
 }

package/skills/ccmds-config.md

@@ -52,6 +52,7 @@ The CLI looks for config files in this order:
     }
   },
   "preview": {
+    "maxLines": 20,
     "topResults": 600,
     "midResults": 300,
     "otherResults": 150
@@ -73,9 +74,10 @@ The CLI looks for config files in this order:
 | `limit` | `number` | `10` | Default result limit |
 | `fuzzy.threshold` | `number` | `0.4` | Match threshold (0=exact, 1=loose) |
 | `fuzzy.weights` | `object` | See above | Field weights for scoring |
-| `preview.topResults` | `number` | `600` | Preview chars for top 3 results |
-| `preview.midResults` | `number` | `300` | Preview chars for results 4-7 |
-| `preview.otherResults` | `number` | `150` | Preview chars for remaining |
+| `preview.maxLines` | `number` | `20` | Max lines for context-aware previews |
+| `preview.topResults` | `number` | `600` | Fallback preview chars for top 3 results |
+| `preview.midResults` | `number` | `300` | Fallback preview chars for results 4-7 |
+| `preview.otherResults` | `number` | `150` | Fallback preview chars for remaining |
 | `frontmatterFields` | `string[]` | See above | Frontmatter fields to include |
 | `extensions` | `string[]` | `[".md", ".markdown"]` | File extensions |
 | `cache.enabled` | `boolean` | `false` | Enable result caching |

package/src/cache/cache.js

@@ -0,0 +1,166 @@
+/**
+ * Search result cache system
+ */
+
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+
+const CACHE_FILE = '.ccmds-cache.json';
+const CACHE_VERSION = 1;
+
+/**
+ * Generate a cache key from command and options
+ * @param {string} command - Command name
+ * @param {object} params - Parameters to include in key
+ * @returns {string} - Cache key hash
+ */
+export function generateCacheKey(command, params) {
+  const keyData = JSON.stringify({ command, ...params });
+  return createHash('md5').update(keyData).digest('hex').substring(0, 12);
+}
+
+/**
+ * Get cache file path (in project root or config directory)
+ * @param {object} config - Configuration object
+ * @returns {string} - Cache file path
+ */
+export function getCacheFilePath(config) {
+  const baseDir = config._configDir || process.cwd();
+  return join(baseDir, CACHE_FILE);
+}
+
+/**
+ * Read cache from file
+ * @param {string} cachePath - Path to cache file
+ * @returns {object} - Cache data or empty cache structure
+ */
+export function readCache(cachePath) {
+  try {
+    if (existsSync(cachePath)) {
+      const data = JSON.parse(readFileSync(cachePath, 'utf-8'));
+      if (data.version === CACHE_VERSION) {
+        return data;
+      }
+    }
+  } catch (err) {
+    // Ignore corrupted cache
+  }
+  return { version: CACHE_VERSION, entries: {} };
+}
+
+/**
+ * Write cache to file
+ * @param {string} cachePath - Path to cache file
+ * @param {object} cache - Cache data
+ */
+export function writeCache(cachePath, cache) {
+  try {
+    writeFileSync(cachePath, JSON.stringify(cache));
+  } catch (err) {
+    // Ignore write errors
+  }
+}
+
+/**
+ * Get cached result if valid
+ * @param {object} config - Configuration object
+ * @param {string} cacheKey - Cache key
+ * @returns {object|null} - Cached results or null
+ */
+export function getCachedResult(config, cacheKey) {
+  if (!config.cache?.enabled) return null;
+
+  const cachePath = getCacheFilePath(config);
+  const cache = readCache(cachePath);
+  const entry = cache.entries[cacheKey];
+
+  if (!entry) return null;
+
+  // Check TTL
+  const ttl = config.cache.ttl || 300;
+  const age = (Date.now() - entry.created) / 1000;
+  if (age > ttl) {
+    // Expired - remove entry
+    delete cache.entries[cacheKey];
+    writeCache(cachePath, cache);
+    return null;
+  }
+
+  return entry.results;
+}
+
+/**
+ * Store result in cache
+ * @param {object} config - Configuration object
+ * @param {string} cacheKey - Cache key
+ * @param {string} command - Command name
+ * @param {any} results - Results to cache
+ */
+export function setCachedResult(config, cacheKey, command, results) {
+  if (!config.cache?.enabled) return;
+
+  const cachePath = getCacheFilePath(config);
+  const cache = readCache(cachePath);
+
+  // Add new entry
+  cache.entries[cacheKey] = {
+    created: Date.now(),
+    command,
+    results,
+  };
+
+  // Trim old entries if over limit
+  const maxEntries = config.cache.maxEntries || 50;
+  const entries = Object.entries(cache.entries);
+  if (entries.length > maxEntries) {
+    // Sort by created time, remove oldest
+    entries.sort((a, b) => a[1].created - b[1].created);
+    const toRemove = entries.slice(0, entries.length - maxEntries);
+    toRemove.forEach(([key]) => delete cache.entries[key]);
+  }
+
+  writeCache(cachePath, cache);
+}
+
+/**
+ * Clear all cache entries
+ * @param {object} config - Configuration object
+ * @returns {number} - Number of entries cleared
+ */
+export function clearCache(config) {
+  const cachePath = getCacheFilePath(config);
+  if (existsSync(cachePath)) {
+    const cache = readCache(cachePath);
+    const count = Object.keys(cache.entries).length;
+    unlinkSync(cachePath);
+    return count;
+  }
+  return 0;
+}
+
+/**
+ * Get cache statistics
+ * @param {object} config - Configuration object
+ * @returns {object} - Cache stats
+ */
+export function getCacheStats(config) {
+  const cachePath = getCacheFilePath(config);
+  const cache = readCache(cachePath);
+  const entries = Object.values(cache.entries);
+  const now = Date.now();
+  const ttl = (config.cache?.ttl || 300) * 1000;
+
+  return {
+    enabled: config.cache?.enabled || false,
+    path: cachePath,
+    exists: existsSync(cachePath),
+    totalEntries: entries.length,
+    validEntries: entries.filter((e) => now - e.created < ttl).length,
+    expiredEntries: entries.filter((e) => now - e.created >= ttl).length,
+    commands: entries.reduce((acc, e) => {
+      acc[e.command] = (acc[e.command] || 0) + 1;
+      return acc;
+    }, {}),
+  };
+}

package/src/cache/index.js

@@ -0,0 +1,14 @@
+/**
+ * Cache module exports
+ */
+
+export {
+  generateCacheKey,
+  getCacheFilePath,
+  readCache,
+  writeCache,
+  getCachedResult,
+  setCachedResult,
+  clearCache,
+  getCacheStats,
+} from './cache.js';