indexer-cli 0.2.5 → 0.2.6

package/README.md

@@ -46,8 +46,8 @@ npx indexer-cli search "authentication middleware"
 ```
 
 After `init`, the repo also contains `.claude/skills/repo-discovery/SKILL.md`, so coding agents can be steered toward
-`npx indexer-cli search`, `npx indexer-cli structure`, and `npx indexer-cli architecture` before they start burning tokens on broad
-filesystem scans.
+`npx indexer-cli search`, `npx indexer-cli structure`, `npx indexer-cli architecture`, `npx indexer-cli context`,
+`npx indexer-cli explain`, and `npx indexer-cli deps` before they start burning tokens on broad filesystem scans.
 
 ## Why agents save tokens with this
 
@@ -110,9 +110,13 @@ Run a semantic search against the indexed codebase. Automatically re-indexes cha
 
 | Option                   | Default | Description                                                                                                  |
 |--------------------------|---------|--------------------------------------------------------------------------------------------------------------|
-| `--top-k <number>`       | 10      | Number of results to return                                                                                  |
+| `--top-k <number>`       | 3       | Number of results to return                                                                                  |
 | `--path-prefix <string>` | —       | Limit results to files under this path                                                                       |
 | `--chunk-types <string>` | —       | Comma-separated filter: `full_file`, `imports`, `preamble`, `declaration`, `module_section`, `impl`, `types` |
+| `--fields <list>`        | —       | Comma-separated output fields: `filePath`, `startLine`, `endLine`, `score`, `primarySymbol`, `content`       |
+| `--min-score <number>`   | —       | Filter out results below this score (0..1)                                                                   |
+| `--omit-content`         | —       | Exclude content from results (token-saving)                                                                  |
+| `--include-content`      | —       | Include content in JSON output                                                                               |
 | `--json`                 | —       | Output results as JSON                                                                                       |
 
 ### `npx indexer-cli structure`
@@ -124,6 +128,8 @@ files if needed.
 |--------------------------|-----------------------------------------------------------------------------------------------------------|
 | `--path-prefix <string>` | Limit output to files under this path                                                                     |
 | `--kind <string>`        | Filter by symbol kind: `function`, `class`, `method`, `interface`, `type`, `variable`, `module`, `signal` |
+| `--max-depth <number>`   | Limit directory traversal depth in the rendered tree                                                      |
+| `--max-files <number>`   | Limit number of files shown in output                                                                     |
 | `--json`                 | Output structure as JSON                                                                                  |
 
 ### `npx indexer-cli architecture`
@@ -131,10 +137,49 @@ files if needed.
 Print an architecture snapshot for the current working directory: file statistics, detected entry points, and a
 dependency graph.
 
+| Option                   | Description                                  |
+|--------------------------|----------------------------------------------|
+| `--path-prefix <string>` | Limit output to files under this path        |
+| `--include-fixtures`     | Include fixture/vendor paths in output       |
+| `--json`                 | Output as JSON                               |
+
+### `npx indexer-cli context`
+
+Output dense project context aggregated from the index. Useful for getting a concise overview of a codebase area
+without pulling in entire files.
+
+| Option                | Default | Description                                                              |
+|-----------------------|---------|--------------------------------------------------------------------------|
+| `--format <format>`   | plain   | Output format: `plain` or `json`                                         |
+| `--scope <scope>`     | all     | `all`, `changed` (uncommitted changes), or `relevant-to:<path>`          |
+| `--max-deps <number>` | 30      | Maximum number of dependency edges to output                             |
+| `--include-fixtures`  | —       | Include fixture/vendor paths in output                                   |
+| `--json`              | —       | Shorthand for `--format=json`                                            |
+
+### `npx indexer-cli explain <symbol>`
+
+Show context for a symbol: its signature, callers, and containing module. Use this to quickly understand what a
+specific function, class, or type does and how it is used.
+
+| Option   | Description          |
+|----------|----------------------|
+| `--json` | Output as JSON       |
+
+### `npx indexer-cli deps <path>`
+
+Show callers (who imports this) and callees (what this imports) for a module or symbol. Useful for tracing impact
+of changes and understanding dependency chains.
+
+| Option              | Default | Description                                       |
+|---------------------|---------|---------------------------------------------------|
+| `--direction <dir>` | both    | `callers`, `callees`, or `both`                   |
+| `--depth <n>`       | 1       | Traversal depth                                   |
+| `--json`            | —       | Output as JSON                                    |
+
 ### `npx indexer-cli uninstall`
 
 Remove the `.indexer-cli/` directory from the current working directory. Also removes the generated
-`.claude/skills/repo-discovery/` skill directory when present, then prompts for confirmation before deleting.
+`.claude/skills/repo-discovery/` skill directory when present. Prompts for confirmation unless `-f` is given.
 
 ## License
 

package/dist/cli/commands/skill-template.d.ts

@@ -3,4 +3,4 @@
  *
  * Written to `.claude/skills/repo-discovery/SKILL.md` during `indexer-cli init`.
  */
-export declare const SKILL_MD = "---\nname: repo-discovery\ndescription: Mandatory for repository discovery. Before grep/glob/find, first use indexer-cli whenever the task involves finding implementations, tracing behavior, locating symbols, identifying entry points, inspecting module structure, or understanding an unfamiliar area of this repo.\nallowed-tools: Bash(npx indexer-cli:*)\n---\n\n# Repository discovery with indexer-cli\n\nUse this skill for discovery tasks inside this repository.\n\n## Required behavior\n\nAlways start with indexer-cli for repository discovery.\nDo not use grep, glob, or find until indexer-cli was insufficient, or you need an exact literal text match after narrowing the area.\n\n## Load this skill when\n\n- You need to find where something is implemented\n- You need to trace a symbol, handler, feature, or behavior\n- You are entering an unfamiliar module or directory\n- You need structure, entry points, or dependency context\n- The task is exploratory and you do not yet know the right file\n\n## Skip this skill when\n\n- The exact file is already known and the task stays inside it\n- You only need an exact literal text match\n- The task is outside this repository\n\n## First command\n\nRun one of these first:\n\n ```bash\n npx indexer-cli search \"<query>\" --json\n npx indexer-cli search \"<query>\" --json --path-prefix src/<area>\n npx indexer-cli search \"<query>\" --json --chunk-types impl,types\n npx indexer-cli structure --json --path-prefix src/<area>\n npx indexer-cli structure --json --kind class\n npx indexer-cli architecture --json\n npx indexer-cli index --status --json\n ```\n\n## Reading search results\n\n `npx indexer-cli search --json` returns ranked code chunks, not whole files.\nEach result includes `filePath`, `startLine`, `endLine`, `score`, `primarySymbol`, and `content`.\n\n- Use `score` to prefer the most relevant chunks first and filter obvious low-relevance noise.\n- Use `primarySymbol` to see which function/class/type the chunk belongs to before opening the file.\n- Treat `content` as supporting context, but rank and filter with `score` + `primarySymbol` instead of raw text alone.\n\n## Reference\n\n### Chunk types (--chunk-types)\n\n`full_file`, `imports`, `preamble`, `declaration`, `module_section`, `impl`, `types`\n\n### Symbol kinds (--kind)\n\n`function`, `class`, `method`, `interface`, `type`, `variable`, `module`, `signal`\n";
+export declare const SKILL_MD: string;

package/dist/cli/commands/skill-template.js

@@ -1,72 +1,15 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SKILL_MD = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
 /**
  * SKILL.md template for Claude Code integration.
  *
  * Written to `.claude/skills/repo-discovery/SKILL.md` during `indexer-cli init`.
  */
-exports.SKILL_MD = `\
----
-name: repo-discovery
-description: Mandatory for repository discovery. Before grep/glob/find, first use indexer-cli whenever the task involves finding implementations, tracing behavior, locating symbols, identifying entry points, inspecting module structure, or understanding an unfamiliar area of this repo.
-allowed-tools: Bash(npx indexer-cli:*)
----
-
-# Repository discovery with indexer-cli
-
-Use this skill for discovery tasks inside this repository.
-
-## Required behavior
-
-Always start with indexer-cli for repository discovery.
-Do not use grep, glob, or find until indexer-cli was insufficient, or you need an exact literal text match after narrowing the area.
-
-## Load this skill when
-
-- You need to find where something is implemented
-- You need to trace a symbol, handler, feature, or behavior
-- You are entering an unfamiliar module or directory
-- You need structure, entry points, or dependency context
-- The task is exploratory and you do not yet know the right file
-
-## Skip this skill when
-
-- The exact file is already known and the task stays inside it
-- You only need an exact literal text match
-- The task is outside this repository
-
-## First command
-
-Run one of these first:
-
- \`\`\`bash
- npx indexer-cli search "<query>" --json
- npx indexer-cli search "<query>" --json --path-prefix src/<area>
- npx indexer-cli search "<query>" --json --chunk-types impl,types
- npx indexer-cli structure --json --path-prefix src/<area>
- npx indexer-cli structure --json --kind class
- npx indexer-cli architecture --json
- npx indexer-cli index --status --json
- \`\`\`
-
-## Reading search results
-
- \`npx indexer-cli search --json\` returns ranked code chunks, not whole files.
-Each result includes \`filePath\`, \`startLine\`, \`endLine\`, \`score\`, \`primarySymbol\`, and \`content\`.
-
-- Use \`score\` to prefer the most relevant chunks first and filter obvious low-relevance noise.
-- Use \`primarySymbol\` to see which function/class/type the chunk belongs to before opening the file.
-- Treat \`content\` as supporting context, but rank and filter with \`score\` + \`primarySymbol\` instead of raw text alone.
-
-## Reference
-
-### Chunk types (--chunk-types)
-
-\`full_file\`, \`imports\`, \`preamble\`, \`declaration\`, \`module_section\`, \`impl\`, \`types\`
-
-### Symbol kinds (--kind)
-
-\`function\`, \`class\`, \`method\`, \`interface\`, \`type\`, \`variable\`, \`module\`, \`signal\`
-`;
+exports.SKILL_MD = (0, node_fs_1.readFileSync)(node_path_1.default.join(__dirname, "skill-template.md"), "utf8");
 //# sourceMappingURL=skill-template.js.map

package/dist/cli/commands/skill-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-template.js","sourceRoot":"","sources":["../../../src/cli/commands/skill-template.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACU,QAAA,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8DvB,CAAC"}
+{"version":3,"file":"skill-template.js","sourceRoot":"","sources":["../../../src/cli/commands/skill-template.ts"],"names":[],"mappings":";;;;;;AAAA,qCAAuC;AACvC,0DAA6B;AAE7B;;;;GAIG;AACU,QAAA,QAAQ,GAAG,IAAA,sBAAY,EACnC,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,mBAAmB,CAAC,EACzC,MAAM,CACN,CAAC"}

package/dist/cli/commands/skill-template.md

@@ -0,0 +1,145 @@
+---
+name: repo-discovery
+description: Mandatory for repository discovery. Use indexer-cli before grep/glob/find when locating implementations, tracing behavior, finding symbols or entry points, inspecting module structure, or exploring an unfamiliar area of this repo.
+allowed-tools: Bash(npx indexer-cli:*)
+---
+
+# Repository discovery with indexer-cli
+
+## Required behavior
+
+Always start with indexer-cli for repository discovery.
+Do not use grep, glob, or find unless indexer-cli was insufficient or you need an exact literal match after narrowing the area.
+
+## Load this skill when
+
+- You need to find where something is implemented
+- You need to trace a symbol, handler, feature, or behavior
+- You are entering an unfamiliar module or directory
+- You need structure, entry points, or dependency context
+- The task is exploratory and you do not yet know the right file
+
+## Skip this skill when
+
+- The exact file is already known and the task stays inside it
+- You only need an exact literal text match
+- The task is outside this repository
+
+## First command
+
+Run one of these first:
+
+```bash
+npx indexer-cli search "<query>" --json
+npx indexer-cli search "<query>" --json --path-prefix src/<area>
+npx indexer-cli search "<query>" --json --chunk-types impl,types
+npx indexer-cli structure --json --path-prefix src/<area>
+npx indexer-cli structure --json --kind class
+npx indexer-cli architecture --json
+npx indexer-cli index --status --json
+```
+
+## Reading search results
+
+`npx indexer-cli search --json` returns ranked code chunks, not whole files.
+Each result includes `filePath`, `startLine`, `endLine`, `score`, `primarySymbol`, and `content`.
+
+- Use `score` to prefer the most relevant chunks first and filter obvious low-relevance noise.
+- Use `primarySymbol` to see which function/class/type the chunk belongs to before opening the file.
+- Treat `content` as supporting context, but rank and filter with `score` + `primarySymbol` instead of raw text alone.
+- Content is omitted by default in JSON output; use `--include-content` to include it, or `--omit-content` to make that explicit and save tokens.
+
+## Commands Reference
+
+### `search <query>` — Semantic code search
+
+Semantic search over indexed code. Re-indexes changed files if needed.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--top-k <number>` | 3 | Max results |
+| `--path-prefix <string>` | — | Restrict to this path prefix |
+| `--chunk-types <string>` | — | Comma-separated chunk type filter |
+| `--fields <list>` | — | Return only these comma-separated fields: `filePath`, `startLine`, `endLine`, `score`, `primarySymbol`, `content` |
+| `--min-score <number>` | — | Drop results below this score (0..1) |
+| `--omit-content` | — | Exclude content to save tokens |
+| `--include-content` | — | Include content in JSON |
+| `--json` | — | JSON output |
+
+### `structure` — File tree with symbols
+
+Annotated file tree with extracted symbols. Re-indexes changed files if needed.
+
+| Option | Description |
+|--------|-------------|
+| `--path-prefix <string>` | Restrict to this path prefix |
+| `--kind <string>` | Filter symbol kinds |
+| `--max-depth <number>` | Limit traversal depth |
+| `--max-files <number>` | Limit files shown |
+| `--json` | JSON output |
+
+### `architecture` — Architecture snapshot
+
+Repo snapshot: file stats, entry points, and dependency graph.
+
+| Option | Description |
+|--------|-------------|
+| `--path-prefix <string>` | Restrict to this path prefix |
+| `--include-fixtures` | Include fixture/vendor paths |
+| `--json` | JSON output |
+
+### `context` — Dense project context
+
+Dense project context from the index. Useful for a concise area overview.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--format <format>` | plain | `plain` or `json` |
+| `--scope <scope>` | all | `all`, `changed`, or `relevant-to:<path>` |
+| `--max-deps <number>` | 30 | Max dependency edges |
+| `--include-fixtures` | — | Include fixture/vendor paths |
+| `--json` | — | Shorthand for `--format=json` |
+
+### `explain <symbol>` — Symbol context
+
+Show a symbol's signature, callers, and containing module.
+
+| Option | Description |
+|--------|-------------|
+| `--json` | JSON output |
+
+### `deps <path>` — Dependency graph for a path
+
+Show importers and imports for a module or symbol.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--direction <dir>` | both | `callers`, `callees`, or `both` |
+| `--depth <n>` | 1 | Traversal depth |
+| `--json` | — | JSON output |
+
+### `index` — Index project files
+
+| Option | Description |
+|--------|-------------|
+| `--full` | Force full reindex instead of incremental |
+| `--dry-run` | Preview what would be indexed |
+| `--status` | Show indexing status |
+| `--tree` | Show indexed file tree (use with `--status`) |
+| `--json` | Output status as JSON (use with `--status`) |
+
+### `setup` / `init` / `uninstall`
+
+- `setup` — Check prerequisites and prepare the Ollama embedding model.
+- `init` — Create `.indexer-cli/`, initialize databases, and install this skill.
+- `uninstall` — Remove indexer data (`-f` skips confirmation).
+
+## Type Reference
+
+### Chunk types (--chunk-types)
+
+`full_file`, `imports`, `preamble`, `declaration`, `module_section`, `impl`, `types`
+
+### Symbol kinds (--kind)
+
+`function`, `class`, `method`, `interface`, `type`, `variable`, `module`, `signal`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "indexer-cli",
-	"version": "0.2.5",
+	"version": "0.2.6",
 	"description": "Lightweight CLI project indexer with semantic search via Ollama",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
 		"access": "public"
 	},
 	"scripts": {
-		"build": "tsc",
+		"build": "tsc && node scripts/copy-skill-template.mjs",
 		"dev": "tsc --watch",
 		"start": "tsx bin/indexer-cli.js",
 		"indexer-cli": "tsx bin/indexer-cli.js",