xindex 1.0.1 → 1.0.3

package/.xindex.json

@@ -18,5 +18,5 @@
     "utf8", "length", "map", "slice", "push", "join", "resolve", "stringify",
     "json", "settimeout", "path", "readfile"
   ],
-  "ignoreFiles": ["rnd/**", ".xindex"]
+  "ignoreFiles": [".xindex"]
 }

package/README.md

@@ -39,6 +39,73 @@ Drop this into `.mcp.json` at your project root:
 
 Open the project in Claude Code — it picks up the xindex MCP server and can call `xindex_search`, `xindex_index`, and `xindex_reset` directly. Fewer hallucinations, fewer round-trips.
 
+## Claude Code skills (`@xi`)
+
+Two optional [Claude Code skills](https://docs.claude.com/en/docs/claude-code/skills) wrap the MCP tools so you don't have to think about them:
+
+- **`ask-xi`** — read-only discovery. `@xi where is auth handled` drafts several focused queries, runs `xindex_search` for each, and returns ranked file paths with matched keywords. Use it as a cheap first step before grepping or asking a heavier model.
+- **`xindex`** — index management (`xindex_index`, `xindex_reset`). Reset requires explicit confirmation every time.
+
+Keeping them separate keeps `@xi` safe to fire casually while destructive ops stay behind the `xindex` skill.
+
+### Install
+
+Pick one — project-scoped or user-global:
+
+```bash
+# Project (checked in, shared with the repo)
+mkdir -p .claude/skills/ask-xi .claude/skills/xindex
+
+# Or user-global (available in every project)
+mkdir -p ~/.claude/skills/ask-xi ~/.claude/skills/xindex
+```
+
+Then drop these two files in.
+
+`ask-xi/SKILL.md`:
+
+````md
+---
+name: ask-xi
+description: Discovers relevant files via xindex semantic search — preps queries, auto-indexes on empty, returns file links with keywords. Triggered by @xi.
+argument-hint: "[question]"
+---
+Surface-level codebase discovery via xindex. Tool: `xindex_search` (natural-language, meaning-based).
+
+**Steps:**
+1. Draft 5–10 focused queries from $ARGUMENTS (entry points, routing, config, integrations, tests, related patterns).
+2. Run `xindex_search` for each.
+3. If results are empty/sparse/stale → scoped-index the most relevant content-heavy root folders (one path per `xindex_index` call, e.g. `src`, `apps`, `features`, `componets`), then re-search. Prefer scoped over full-repo.
+4. Refine with 2–3 narrower follow-ups.
+5. Return file paths + brief keywords showing why each matched.
+
+Output = file links + keywords, not analysis. For reset or full re-index, delegate to `/xindex` (owns safety rules).
+````
+
+`xindex/SKILL.md`:
+
+````md
+---
+name: xindex
+description: Manages xindex semantic search — index, search, reset via MCP tools. For research questions, use /ask-xi.
+argument-hint: "[search query | index | reset]"
+---
+Full xindex tool management. For research, use `/ask-xi`. Install: `npm i -g xindex`.
+
+**Tools:**
+- `xindex_search` — find files by meaning (synonyms, semantics). Try before grepping blindly.
+- `xindex_index` — index a path (recursive, respects .gitignore). **MUST** run one path per call.
+- `xindex_reset` — destructive wipe+rebuild. **MUST** get explicit user confirmation every time; if ambiguous, don't run.
+
+**Workflow:** stale/corrupt → confirm → `xindex_reset` → `xindex_index(["."])` → `xindex_search`. Incremental → one-path `xindex_index(["changed/path"])` calls.
+
+**Scoped indexing (preferred):** index only task-relevant content-heavy folders, sequentially. Full-repo `xindex_index(["."])` only for cross-cutting discovery.
+
+$ARGUMENTS
+````
+
+Both skills assume the `xindex` MCP server is registered (see the section above). Restart Claude Code after adding skills.
+
 ## Features
 
 - **Local** — everything runs on your machine; embeddings cached on disk

package/apps/mcpApp.ts

@@ -44,8 +44,8 @@ export function McpApp({
             inputSchema: z.object({
                 query: z.string()
                     .describe("Natural language search query"),
-                limit: z.number().int().min(1).max(100).default(5)
-                    .describe("Max results to return, 5 by default, 100 max"),
+                limit: z.number().int().min(1).max(50).default(7)
+                    .describe("Max results to return, 7 by default, 50 max"),
             }),
             annotations: {readOnlyHint: true},
         }, async ({query, limit}) => {

package/apps/run.search.ts

@@ -1,10 +1,8 @@
 import {BuildComponents} from "../componets/buildComponents.js";
 import {BufferedLoggerToStdOut} from "../componets/logger.js";
 import {SearchApp} from "./searchApp.js";
-import {AppId} from "../componets/appId.js";
 import {FormatSearchResults} from "../componets/index/formatSearchResults.js";
 
-const appId = AppId();
 const log = BufferedLoggerToStdOut();
 const {searchContentIndex, config} = await BuildComponents({log});
 const search = SearchApp({searchContentIndex});
@@ -15,7 +13,6 @@ if (!query) {
     process.exit(1);
 }
 
-log(`[${appId}] searching: "${query}"`);
 const results = await search(query);
 const format = FormatSearchResults();
 log(await format(query, results));

package/apps/searchApp.ts

@@ -3,7 +3,7 @@ import {ISearchIndex, IIndexRecord} from "../features/searchIndex.js";
 export type ISearchApp = (query: string, limit?: number) => Promise<IIndexRecord[]>;
 
 export function SearchApp({searchContentIndex}: {searchContentIndex: ISearchIndex}): ISearchApp {
-    return async function search(query, limit = 10) {
+    return async function search(query, limit = 7) {
         return await searchContentIndex(query, limit);
     }
 }

package/componets/index/formatSearchResults.ts

@@ -10,9 +10,9 @@ export function FormatSearchResults(): IFormatSearchResults {
         for (let i = 0; i < results.length; i++) {
             const r = results[i];
             const kw = r.keywords ? ` — ${r.keywords}` : "";
-            lines.push("", `${i + 1}. ${r.id}${kw}`);
+            lines.push(`${i + 1}. ${r.id}${kw}`);
         }
 
-        return `Search: "${query}" — ${results.length} result(s)\n\n${lines.join("\n")}`;
+        return `\n# Search: "${query}" — ${results.length} result(s)\n\n${lines.join(";\n\n")}\n`;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xindex",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Local semantic code search — index codebase, search by meaning or keywords",
   "type": "module",
   "main": "xindex.ts",

package/rnd/hf.ts

@@ -1,14 +0,0 @@
-import { pipeline } from "@huggingface/transformers";
-
-const generator = await pipeline(
-  "text-generation",
-  "HuggingFaceTB/SmolLM2-135M-Instruct"
-);
-
-const messages = [
-  { role: "system", content: "You are a helpful assistant." },
-  { role: "user", content: "Who is Microsoft?" },
-];
-
-const output = await generator(messages, { max_new_tokens: 64 });
-console.log(output[0].generated_text.at(-1).content);

package/rnd/keywords-compromise.ts

@@ -1,18 +0,0 @@
-import nlp from "compromise";
-import { readFile } from "fs/promises";
-
-const filePath = process.argv[2];
-if (!filePath) {
-  console.error("Usage: npx tsx keywords-compromise.ts <file>");
-  process.exit(1);
-}
-
-const text = await readFile(filePath, "utf8");
-const doc = nlp(text);
-
-console.log(`Keywords from: ${filePath}\n`);
-console.log("Topics:", doc.topics().out("array"));
-console.log("\nNouns:", doc.nouns().out("array"));
-console.log("\nVerbs:", doc.verbs().out("array"));
-console.log("\nPeople:", doc.people().out("array"));
-console.log("\nOrganizations:", doc.organizations().out("array"));

package/rnd/keywords-pipeline.ts

@@ -1,79 +0,0 @@
-import nlp from "compromise";
-import {createRequire} from "module";
-import {readFile} from "fs/promises";
-import {pipeline} from "@huggingface/transformers";
-
-const require = createRequire(import.meta.url);
-const keyword_extractor = require("keyword-extractor");
-
-const generator = await pipeline(
-    "text-generation",
-    "HuggingFaceTB/SmolLM2-135M-Instruct"
-);
-
-export async function llm(input: string): Promise<string> {
-    const prompt = "Extract and list the most important keywords from the following text. Return only keywords separated by commas.";
-
-    const messages = [
-        {role: "system", content: prompt},
-        {role: "user", content: input},
-    ];
-
-    const output = await generator(messages, {max_new_tokens: 128});
-    return output[0].generated_text.at(-1).content;
-}
-
-const filePath = process.argv[2];
-if (!filePath) {
-    console.error("Usage: npx tsx keywords-pipeline.ts <file>");
-    process.exit(1);
-}
-
-// Step 1: Read file
-const text = await readFile(filePath, "utf8");
-console.log("=== Step 1: Read file ===");
-console.log(`${text.length} chars\n`);
-
-// Step 2: Compromise — extract nouns, verbs, topics
-const doc = nlp(text);
-const nouns = doc.nouns().out("array") as string[];
-const verbs = doc.verbs().out("array") as string[];
-const topics = doc.topics().out("array") as string[];
-const combined = [...topics, ...nouns, ...verbs].join(" ");
-console.log("=== Step 2: Compromise ===");
-console.log(`${topics.length} topics, ${nouns.length} nouns, ${verbs.length} verbs\n`);
-
-// Step 3: Regex — replace all non-word chars with space
-const cleaned = combined.replace(/\W+/g, " ").trim();
-console.log("=== Step 3: Regex cleanup ===");
-console.log(cleaned.slice(0, 200), "\n");
-
-// Step 4: LLM — pass cleaned text to local model
-const llmResult = await llm(cleaned);
-console.log("=== Step 4: LLM ===");
-console.log(llmResult, "\n");
-
-// Step 5: keyword-extractor
-const keywords: string[] = keyword_extractor.extract(cleaned, {
-    language: "english",
-    remove_digits: false,
-    return_changed_case: true,
-    remove_duplicates: true,
-    return_max_ngrams: 3,
-});
-
-// Score by frequency
-const lower = cleaned.toLowerCase();
-const scored = keywords
-    .filter((kw) => kw.length > 2)
-    .map((kw) => {
-        const re = new RegExp(`\\b${kw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "gi");
-        const count = (lower.match(re) || []).length;
-        return {keyword: kw, count};
-    });
-scored.sort((a, b) => b.count - a.count);
-
-console.log("=== Step 5: Keywords ===");
-for (const {keyword, count} of scored) {
-    console.log(`  ${keyword.padEnd(35)} (${count}x)`);
-}

package/rnd/keywords.ts

@@ -1,38 +0,0 @@
-import { createRequire } from "module";
-import { readFile } from "fs/promises";
-
-const require = createRequire(import.meta.url);
-const keyword_extractor = require("keyword-extractor");
-
-const filePath = process.argv[2];
-if (!filePath) {
-  console.error("Usage: npx tsx keywords.ts <file>");
-  process.exit(1);
-}
-
-const text = await readFile(filePath, "utf8");
-
-const keywords: string[] = keyword_extractor.extract(text, {
-  language: "english",
-  remove_digits: false,
-  return_changed_case: true,
-  remove_duplicates: true,
-  return_max_ngrams: 3,
-});
-
-// Count frequency of each keyword in original text (case-insensitive)
-const lower = text.toLowerCase();
-const scored = keywords
-  .filter((kw) => kw.length > 2 && !/^[^a-z]*$/.test(kw))
-  .map((kw) => {
-    const re = new RegExp(`\\b${kw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "gi");
-    const count = (lower.match(re) || []).length;
-    return { keyword: kw, count };
-  });
-
-scored.sort((a, b) => b.count - a.count);
-
-console.log(`Keywords from: ${filePath}\n`);
-for (const { keyword, count } of scored) {
-  console.log(`  ${keyword.padEnd(35)} (${count}x)`);
-}

package/rnd/test-vectra-memory.ts

@@ -1,63 +0,0 @@
-import { LocalIndex, VirtualFileStorage } from 'vectra';
-
-async function main() {
-    // 1. Create in-memory index
-    const storage = new VirtualFileStorage();
-    const index = new LocalIndex('mem://test', undefined, storage);
-    await index.createIndex({ version: 1 });
-    console.log('created index');
-
-    // 2. Insert items with fake 8-dim vectors
-    const dim = 8;
-    await index.insertItem({
-        id: 'doc-a',
-        vector: Array.from({ length: dim }, (_, i) => (i + 1) / dim),
-        metadata: { block: 'A', label: 'first' },
-    });
-    await index.insertItem({
-        id: 'doc-b',
-        vector: Array.from({ length: dim }, (_, i) => (dim - i) / dim),
-        metadata: { block: 'B', label: 'second' },
-    });
-    await index.insertItem({
-        id: 'doc-c',
-        vector: Array.from({ length: dim }, () => 0.5),
-        metadata: { block: 'C', label: 'third' },
-    });
-    console.log('inserted 3 items');
-
-    // 3. Query — vector close to doc-a
-    const queryVec = Array.from({ length: dim }, (_, i) => (i + 1) / dim);
-    const results = await index.queryItems(queryVec, '', 3);
-    console.log('query results:');
-    for (const r of results) {
-        console.log(`  ${r.item.id}  score=${r.score.toFixed(4)}  block=${r.item.metadata.block}`);
-    }
-
-    // 4. Upsert — update doc-a's vector
-    await index.upsertItem({
-        id: 'doc-a',
-        vector: Array.from({ length: dim }, () => 0.5),
-        metadata: { block: 'A', label: 'updated' },
-    });
-    const updated = await index.getItem('doc-a');
-    console.log(`upserted doc-a → label=${updated?.metadata.label}`);
-
-    // 5. List all items
-    const all = await index.listItems();
-    console.log(`total items: ${all.length}`);
-
-    // 6. Delete
-    await index.deleteItem('doc-b');
-    const afterDelete = await index.listItems();
-    console.log(`after delete: ${afterDelete.length} items`);
-
-    // 7. Verify no disk artifacts
-    const { default: fs } = await import('fs');
-    const exists = fs.existsSync('mem://test');
-    console.log(`disk folder exists: ${exists}`);
-
-    console.log('\ndone — all in-memory, nothing on disk');
-}
-
-main().catch(console.error);

package/rnd/vectra-keywords.ts

@@ -1,95 +0,0 @@
-import { LocalIndex } from "vectra";
-import { pipeline } from "@huggingface/transformers";
-import nlp from "compromise";
-import { createRequire } from "module";
-import { readFile } from "fs/promises";
-import { readdirSync } from "fs";
-
-const require = createRequire(import.meta.url);
-const keyword_extractor = require("keyword-extractor");
-
-// Init embedder + index
-const embedder = await pipeline(
-  "feature-extraction",
-  "sentence-transformers/all-MiniLM-L6-v2"
-);
-const index = new LocalIndex("./vectra-keyword-index");
-if (!(await index.isIndexCreated())) {
-  await index.createIndex();
-}
-
-async function embed(text: string): Promise<number[]> {
-  const result = await embedder(text, { pooling: "mean", normalize: true });
-  return Array.from(result.data as Float32Array);
-}
-
-function extractKeywords(text: string): string[] {
-  // Compromise: pull nouns, verbs, topics
-  const doc = nlp(text);
-  const parts = [
-    ...doc.topics().out("array"),
-    ...doc.nouns().out("array"),
-    ...doc.verbs().out("array"),
-  ] as string[];
-  const cleaned = parts.join(" ").replace(/\W+/g, " ").trim();
-
-  // keyword-extractor
-  const keywords: string[] = keyword_extractor.extract(cleaned, {
-    language: "english",
-    remove_digits: false,
-    return_changed_case: true,
-    remove_duplicates: true,
-    return_max_ngrams: 2,
-  });
-  return keywords.filter((kw: string) => kw.length > 2);
-}
-
-// --- Index files ---
-const files = process.argv.slice(2);
-if (!files.length) {
-  console.error("Usage: npx tsx vectra-keywords.ts <file1> [file2] ...");
-  process.exit(1);
-}
-
-console.log("=== Indexing ===");
-for (const filePath of files) {
-  const text = await readFile(filePath, "utf8");
-  const keywords = extractKeywords(text);
-  const keywordStr = keywords.join(", ");
-  const vector = await embed(keywordStr);
-
-  await index.upsertItem({
-    id: filePath,
-    vector,
-    metadata: { keywords: keywordStr, file: filePath },
-  });
-  console.log(`  ${filePath} → ${keywords.slice(0, 8).join(", ")}...`);
-}
-
-// --- Search by keyword ---
-async function search(query: string, topK = 5) {
-  const queryVector = await embed(query);
-  return index.queryItems(queryVector, query, topK);
-}
-
-console.log("\n=== Search: keyword 'fruit' ===");
-const r1 = await search("fruit");
-for (const r of r1) {
-  console.log(`  ${r.score.toFixed(4)} | ${r.item.id}`);
-  console.log(`    keywords: ${(r.item.metadata as any).keywords.slice(0, 100)}`);
-}
-
-// --- Search by synonym ---
-console.log("\n=== Search: synonym 'automobile' (for 'cars/vehicles') ===");
-const r2 = await search("automobile vehicle transportation");
-for (const r of r2) {
-  console.log(`  ${r.score.toFixed(4)} | ${r.item.id}`);
-  console.log(`    keywords: ${(r.item.metadata as any).keywords.slice(0, 100)}`);
-}
-
-console.log("\n=== Search: synonym 'embedding model neural network' ===");
-const r3 = await search("embedding model neural network");
-for (const r of r3) {
-  console.log(`  ${r.score.toFixed(4)} | ${r.item.id}`);
-  console.log(`    keywords: ${(r.item.metadata as any).keywords.slice(0, 100)}`);
-}

package/rnd/vectra.ts

@@ -1,50 +0,0 @@
-import { LocalIndex } from "vectra";
-import { pipeline } from "@huggingface/transformers";
-
-// Create/load index (folder-based)
-const index = new LocalIndex("./vectra-index");
-
-if (!(await index.isIndexCreated())) {
-  await index.createIndex();
-}
-
-// Embedding pipeline (fast local model)
-const embedder = await pipeline(
-  "feature-extraction",
-  "sentence-transformers/all-MiniLM-L6-v2"
-);
-
-async function embed(text: string): Promise<number[]> {
-  const result = await embedder(text, { pooling: "mean", normalize: true });
-  return Array.from(result.data as Float32Array);
-}
-
-// Add items with vectors + metadata
-const texts = [
-  { text: "Apples are red fruit", metadata: { category: "fruit" } },
-  { text: "Bananas are yellow", metadata: { category: "fruit" } },
-  { text: "Cars are vehicles", metadata: { category: "transport" } },
-];
-
-for (const item of texts) {
-  const vector = await embed(item.text);
-  await index.upsertItem({
-    id: item.text.slice(0, 20),
-    vector,
-    metadata: item.metadata,
-  });
-}
-console.log("Items indexed");
-
-// Query example
-const queryText = "red fruit";
-const queryVector = await embed(queryText);
-const results = await index.queryItems(queryVector, queryText, 3, {
-  category: { $eq: "fruit" },
-});
-
-for (const result of results) {
-  console.log(
-    `Score: ${result.score.toFixed(4)} | ID: ${result.item.id} | Metadata: ${JSON.stringify(result.item.metadata)}`
-  );
-}