indexer-cli 0.10.6 → 0.10.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -207,7 +207,7 @@ and performs a full uninstall + init for each. Useful for batch-updating project
207
207
 
208
208
  | Option | Description |
209
209
  |---------------------|--------------------------------------------------|
210
- | `--refresh-skills` | Recreate `.claude/skills/` during reinit |
210
+ | `--skills-only` | Only refresh skills without full reinstall |
211
211
  | `-f, --force` | Skip confirmation prompt |
212
212
 
213
213
  ## License
@@ -26,7 +26,7 @@ function registerReinitCommand(program) {
26
26
  .command("reinit")
27
27
  .description("Reinitialize indexer in all projects within a directory (uninstall + init)")
28
28
  .argument("<dir>", "path to workspace directory containing projects")
29
- .option("--refresh-skills", "recreate .claude/skills during reinit")
29
+ .option("--skills-only", "only refresh skills without full reinstall")
30
30
  .option("-f, --force", "skip confirmation prompt")
31
31
  .addHelpText("after", `\n${help_text_js_1.PROJECT_ROOT_COMMAND_HELP}\n`)
32
32
  .action(async (dir, options) => {
@@ -69,15 +69,18 @@ function registerReinitCommand(program) {
69
69
  return;
70
70
  }
71
71
  if (!options.force) {
72
- console.error("The following projects will be reinitialized:");
72
+ const action = options.skillsOnly
73
+ ? "have skills refreshed"
74
+ : "be reinitialized";
75
+ console.error(`The following projects will ${action}:`);
73
76
  for (const projectPath of projectPaths) {
74
77
  console.error(`- ${projectPath}`);
75
78
  }
76
79
  const rl = (0, promises_2.createInterface)({ input: node_process_1.stdin, output: node_process_1.stdout });
77
80
  try {
78
- const answer = await rl.question("Proceed with reinit? [y/N] ");
81
+ const answer = await rl.question("Proceed? [y/N] ");
79
82
  if (!/^y(es)?$/i.test(answer.trim())) {
80
- console.log("Reinit cancelled.");
83
+ console.log("Cancelled.");
81
84
  return;
82
85
  }
83
86
  }
@@ -88,22 +91,27 @@ function registerReinitCommand(program) {
88
91
  let reinitializedCount = 0;
89
92
  for (const projectPath of projectPaths) {
90
93
  const projectName = node_path_1.default.basename(projectPath);
91
- console.log(`Reinitializing: ${projectName}`);
94
+ console.log(`${options.skillsOnly ? "Refreshing skills" : "Reinitializing"}: ${projectName}`);
92
95
  try {
93
- await (0, uninstall_js_1.performUninstall)(projectPath);
94
- await (0, init_js_1.performInit)(projectPath, {
95
- refreshSkills: options?.refreshSkills,
96
- });
96
+ if (options.skillsOnly) {
97
+ await (0, init_js_1.refreshClaudeSkills)(projectPath);
98
+ }
99
+ else {
100
+ await (0, uninstall_js_1.performUninstall)(projectPath);
101
+ await (0, init_js_1.performInit)(projectPath);
102
+ }
97
103
  console.log(`Done: ${projectName}`);
98
104
  reinitializedCount += 1;
99
105
  }
100
106
  catch (error) {
101
107
  const message = error instanceof Error ? error.message : String(error);
102
- console.error(`Failed to reinitialize ${projectName}: ${message}`);
108
+ console.error(`Failed to ${options.skillsOnly ? "refresh skills in" : "reinitialize"} ${projectName}: ${message}`);
103
109
  process.exitCode = 1;
104
110
  }
105
111
  }
106
- console.log(`Reinitialized ${reinitializedCount} of ${projectPaths.length} projects`);
112
+ console.log(options.skillsOnly
113
+ ? `Refreshed skills in ${reinitializedCount} of ${projectPaths.length} projects`
114
+ : `Reinitialized ${reinitializedCount} of ${projectPaths.length} projects`);
107
115
  });
108
116
  }
109
117
  //# sourceMappingURL=reinit.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"reinit.js","sourceRoot":"","sources":["../../../src/cli/commands/reinit.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"reinit.js","sourceRoot":"","sources":["../../../src/cli/commands/reinit.ts"],"names":[],"mappings":"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"}
@@ -11,57 +11,83 @@ description: FIRST choice for repository discovery and code understanding. Use t
11
11
  allowed-tools: Bash(idx architecture:*), Bash(idx structure:*), Bash(idx search:*), Bash(idx explain:*), Bash(idx deps:*)
12
12
  ---
13
13
 
14
- # Use repo-discovery as the single indexed entry point
14
+ # Use repo-discovery as the indexed entry point
15
15
 
16
- Use this skill first when the task is about understanding an unfamiliar codebase, locating behavior, identifying important symbols, or tracing impact.
16
+ Use this skill first for unfamiliar codebases, high-level exploration, behavior tracing, symbol discovery, or impact analysis.
17
17
 
18
- Choose the single cheapest discovery path, run it, and stop as soon as you have enough context.
18
+ Pick the single cheapest command that answers the question, run it, and stop when you have enough context.
19
19
 
20
- ## Routing rules
20
+ ## Route to one command
21
21
 
22
- - Use \`idx architecture\` for repo shape, entry points, and high-level module boundaries.
23
- - Use \`idx structure\` for file trees, exported symbols, and "what's in this directory/module?" questions.
24
- - Use \`idx search\` for behavior and flow questions like "how does X work?" or "what happens when Y?".
25
- - Use \`idx explain\` when the symbol name is already known.
26
- - Use \`idx deps\` when the path/module is already known and you need callers, callees, or impact.
22
+ - \`idx architecture\` repo shape, entry points, module boundaries
23
+ - \`idx structure\` file trees, exported symbols, contents of a directory/module
24
+ - \`idx search\` conceptual behavior questions like "how does X work?"
25
+ - \`idx explain\` a known symbol when you want indexed explanation
26
+ - \`idx deps\` callers, callees, or impact for a known path/module
27
27
 
28
- ## Hard rules
28
+ ## Operating rules
29
29
 
30
- - Start with exactly one indexed command, not several.
31
- - Prefer the cheapest matching command.
32
- - Do not run overlapping discovery commands for the same question unless the first one clearly failed.
33
- - After \`idx search\`, read the returned files and ranges instead of re-running search from another angle.
34
- - Narrow with \`--path-prefix\` whenever the subsystem is known.
35
- - For \`idx structure\`, use \`--path-prefix\` or \`--kind\` unless the repo is tiny.
36
- - For \`idx deps\`, start with \`--depth 1\` and increase only when first-hop impact is insufficient.
37
- - For \`idx explain\`, prefer \`<file>::<symbol>\` when the name may be ambiguous.
30
+ - Start with exactly **ONE** idx command. Each idx result is large; parallel or overlapping discovery burns tokens on duplicate context.
31
+ - Prefer the cheapest route that fits the question. Only run a second idx command if the first clearly failed or left a specific gap.
32
+ - Use \`--path-prefix\` whenever the subsystem is known, e.g. \`src/api/\`, \`src/auth/\`.
33
+ - For \`idx structure\`, also narrow with \`--kind\` when possible.
34
+ - For \`idx deps\`, start with \`--depth 1\`; increase only if first-hop impact is insufficient.
35
+ - For \`idx explain\`, prefer \`file::symbol\` when the name may be ambiguous.
36
+ - \`--include-content\` is expensive. Use it only when you need implementation detail *without* planning to \`Read\`; if you'll read files anyway, skip it.
37
+ - After \`idx search\`, read the returned files/ranges. Do **not** follow search with \`idx explain\` on the same results.
38
+ - Do **not** run \`idx explain\` as a prelude to reading a file you already know you need.
39
+ - Do **not** chain discovery steps mechanically (\`search → explain\`, \`explain → Read\`) when direct reading is cheaper.
38
40
 
39
- ## Escalation path
41
+ ## Use idx vs grep/LSP
40
42
 
41
- - architecture structure
42
- - structure → explain
43
- - search → Read tool on returned files
44
- - explain → deps
45
- - deps → architecture only if broader system context is still missing
43
+ idx is **semantic** search: use it when you do **not** know the exact name and need to find code by meaning.
46
44
 
47
- ## Skip when
45
+ Use \`grep\`/LSP when the target is already concrete:
46
+ - exact identifier name → \`grep\`, \`lsp_symbols\`, or references/definition tools
47
+ - exact file path → \`Read\`
48
+ - known file + known symbol → \`idx explain file::symbol\` or LSP if exact lookup is enough
48
49
 
49
- - you already know the exact file and lines to read
50
- - the task is an exact identifier lookup better handled by grep/LSP
51
- - you are no longer in discovery mode and are already editing code
50
+ Rule of thumb: if you can write an exact search pattern, use \`grep\`/LSP. Use idx for exploration, not lookup.
52
51
 
53
- ## Command samples
52
+ ## Query guidance
54
53
 
55
- Use one matching example; these are alternatives, not a sequence.
54
+ - Good \`idx search\` queries are specific concepts, not generic phrases.
55
+ - Broad natural-language queries produce noise across unrelated files.
56
+ - Prefer domain-specific wording over vague phrases like \`"validate data"\` or \`"send notification"\`.
57
+ - Pair broad concepts with \`--path-prefix\` and cap output with \`--max-files\` when exploring large areas.
58
+
59
+ ## Examples
56
60
 
57
61
  \`\`\`bash
58
- idx architecture --path-prefix src/cli
59
- idx structure --path-prefix src/cli --kind function
60
- idx search "refresh skills"
61
- idx explain src/cli/commands/init.ts::refreshClaudeSkills
62
- idx deps src/cli/commands/init.ts --direction callers
62
+ # Good: high-level repo shape
63
+ idx architecture --path-prefix src/
64
+
65
+ # Good: inspect one subsystem
66
+ idx structure --path-prefix src/api/ --kind function
67
+
68
+ # Good: semantic discovery for unknown behavior
69
+ idx search "how request retries are scheduled" --path-prefix src/jobs/ --max-files 5
70
+
71
+ # Good: explain a known symbol, scoped to a file
72
+ idx explain src/api/client.ts::createClient
73
+
74
+ # Good: first-hop impact from a known module
75
+ idx deps src/api/client.ts --direction callers --depth 1
76
+
77
+ # Bad: semantic search for an exact identifier
78
+ idx search "MyType" --path-prefix src/models/
79
+
80
+ # Better: exact lookup is cheaper
81
+ grep "MyType" src/models/
63
82
  \`\`\`
64
83
 
84
+ ## Skip idx when
85
+
86
+ - you already know the exact file to read
87
+ - you need an exact identifier lookup
88
+ - you already know the file and want document-local symbols/usages
89
+ - you are done discovering and are now editing or validating code
90
+
65
91
  ## CLI reference
66
92
 
67
93
  - Architecture: \`idx architecture [--path-prefix <area>] [--include-fixtures]\`
@@ -1 +1 @@
1
- {"version":3,"file":"skills.js","sourceRoot":"","sources":["../../../src/cli/commands/skills.ts"],"names":[],"mappings":";;;AAMa,QAAA,gBAAgB,GAAqB;IACjD;QACC,IAAI,EAAE,gBAAgB;QACtB,SAAS,EAAE,gBAAgB;QAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgEV;KACC;CACD,CAAC;AAEW,QAAA,4BAA4B,GAAG;IAC3C,cAAc;IACd,iBAAiB;IACjB,gBAAgB;IAChB,mBAAmB;IACnB,gBAAgB;IAChB,kBAAkB;CAClB,CAAC;AAEW,QAAA,2BAA2B,GAAG,wBAAgB,CAAC,GAAG,CAC9D,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAC1B,CAAC"}
1
+ {"version":3,"file":"skills.js","sourceRoot":"","sources":["../../../src/cli/commands/skills.ts"],"names":[],"mappings":";;;AAMa,QAAA,gBAAgB,GAAqB;IACjD;QACC,IAAI,EAAE,gBAAgB;QACtB,SAAS,EAAE,gBAAgB;QAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0FV;KACC;CACD,CAAC;AAEW,QAAA,4BAA4B,GAAG;IAC3C,cAAc;IACd,iBAAiB;IACjB,gBAAgB;IAChB,mBAAmB;IACnB,gBAAgB;IAChB,kBAAkB;CAClB,CAAC;AAEW,QAAA,2BAA2B,GAAG,wBAAgB,CAAC,GAAG,CAC9D,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAC1B,CAAC"}
package/dist/cli/entry.js CHANGED
@@ -26,6 +26,7 @@ const HANDLED_COMMANDER_EXIT_CODES = new Set([
26
26
  "commander.help",
27
27
  "commander.version",
28
28
  "commander.unknownCommand",
29
+ "commander.missingArgument",
29
30
  "indexer.preActionFailed",
30
31
  ]);
31
32
  async function runPreActionChecks(commandName) {
@@ -1 +1 @@
1
- {"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/cli/entry.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/cli/entry.ts"],"names":[],"mappings":"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"}
@@ -8,7 +8,7 @@ const node_fs_1 = require("node:fs");
8
8
  const node_os_1 = __importDefault(require("node:os"));
9
9
  const node_path_1 = __importDefault(require("node:path"));
10
10
  const SCRIPT_CONTENT = `#!/bin/sh
11
- exec npm exec --yes --prefix "\${TMPDIR:-/tmp}" --package=indexer-cli@latest -- indexer-cli "$@"
11
+ exec npm exec --yes --loglevel=silent --prefix "\${TMPDIR:-/tmp}" --package=indexer-cli@latest -- indexer-cli "$@"
12
12
  `;
13
13
  /**
14
14
  * Ensure ~/.local/bin/idx exists and is executable.
@@ -1 +1 @@
1
- export declare const SKILLS_VERSION = 2355297332;
1
+ export declare const SKILLS_VERSION = 1077015671;
@@ -1,5 +1,5 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.SKILLS_VERSION = void 0;
4
- exports.SKILLS_VERSION = 2355297332;
4
+ exports.SKILLS_VERSION = 1077015671;
5
5
  //# sourceMappingURL=skills-version.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "indexer-cli",
3
- "version": "0.10.6",
3
+ "version": "0.10.9",
4
4
  "description": "Lightweight CLI project indexer with semantic search via Ollama",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",