@winci/local-rag 0.2.3 → 0.2.5

package/.claude-plugin/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

package/.claude-plugin/skills/local-rag/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: local-rag
+description: >
+  TRIGGER when: starting a new session, exploring unfamiliar code, searching for
+  functions/types/files, planning refactors, or needing context about past decisions.
+  Use local-rag MCP tools (search, read_relevant, project_map, etc.) instead of
+  manually grepping or reading files when semantic understanding is needed.
+user-invocable: false
+---
+
+## Using local-rag tools
+
+This project has a local RAG index (local-rag). Use these MCP tools:
+
+- **`search`**: Discover which files are relevant to a topic. Returns file paths
+  with snippet previews — use this when you need to know *where* something is.
+- **`read_relevant`**: Get the actual content of relevant semantic chunks —
+  individual functions, classes, or markdown sections — ranked by relevance.
+  Results include exact line ranges (`src/db.ts:42-67`) so you can navigate
+  directly to the edit location. Use this instead of `search` + `Read` when
+  you need the content itself. Two chunks from the same file can both appear
+  (no file deduplication).
+- **`project_map`**: When you need to understand how files relate to each other,
+  generate a dependency graph. Use `focus` to zoom into a specific file's
+  neighborhood. This is faster than reading import statements across many files.
+- **`search_conversation`**: Search past conversation history to recall previous
+  decisions, discussions, and tool outputs. Use this before re-investigating
+  something that may have been discussed in an earlier session.
+- **`create_checkpoint`**: Mark important moments — decisions, milestones,
+  blockers, direction changes. Do this liberally: after completing any feature
+  or task, after adding/modifying tools, after key technical decisions, before
+  and after large refactors, or when changing direction. If in doubt, create one.
+- **`list_checkpoints`** / **`search_checkpoints`**: Review or search past
+  checkpoints to understand project history and prior decisions.
+- **`index_files`**: If you've created or modified files and want them searchable,
+  re-index the project directory.
+- **`search_analytics`**: Check what queries return no results or low-relevance
+  results — this reveals documentation gaps.
+- **`search_symbols`**: When you know a symbol name (function, class, type, etc.),
+  find it directly by name instead of using semantic search.
+- **`find_usages`**: Before changing a function or type, find all its call sites.
+  Use this to understand the blast radius of a rename or API change. Faster and
+  more reliable than semantic search for finding usages.
+- **`git_context`**: At the start of a session (or any time you need orientation),
+  call this to see what files have already been modified, recent commits, and
+  which changed files are in the index. Avoids redundant searches and conflicting
+  edits on already-modified files.
+- **`annotate`**: Attach a persistent note to a file or symbol — "known race
+  condition", "don't refactor until auth rewrite lands", etc. Notes appear as
+  `[NOTE]` blocks inline in `read_relevant` results automatically.
+- **`get_annotations`**: Retrieve all notes for a file, or search semantically
+  across all annotations to find relevant caveats before editing.
+- **`write_relevant`**: Before adding new code or docs, find the best insertion
+  point — returns the most semantically appropriate file and anchor.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winci/local-rag",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Semantic search for your codebase — local-first RAG MCP server with hybrid search, AST-aware chunking, and usage analytics",
   "type": "module",
   "license": "MIT",

package/src/cli/setup.ts

@@ -2,7 +2,7 @@ import { existsSync } from "fs";
 import { readFile, writeFile, mkdir } from "fs/promises";
 import { join, resolve } from "path";
 import { createInterface } from "readline";
-import { writeDefaultConfig } from "../config";
+import { loadConfig } from "../config";
 
 const MARKER = "<!-- local-rag -->";
 
@@ -69,7 +69,8 @@ export interface SetupResult {
 export async function ensureConfig(projectDir: string): Promise<string | null> {
   const configPath = join(projectDir, ".rag", "config.json");
   if (existsSync(configPath)) return null;
-  await writeDefaultConfig(projectDir);
+  // loadConfig auto-creates the file with defaults if missing
+  await loadConfig(projectDir);
   return "Created .rag/config.json";
 }
 

package/src/config/index.ts

@@ -23,28 +23,40 @@ export type RagConfig = z.infer<typeof RagConfigSchema>;
 
 const DEFAULT_CONFIG: RagConfig = {
   include: [
+    // Source code — AST-aware chunking
+    "**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx",
+    "**/*.py",
+    "**/*.go",
+    "**/*.rs",
+    "**/*.java",
+    // Source code — heuristic chunking
+    "**/*.c", "**/*.cpp", "**/*.h", "**/*.hpp",
+    "**/*.rb",
+    "**/*.swift",
     // Markdown & plain text
-    "**/*.md", "**/*.txt",
+    "**/*.md", "**/*.mdx", "**/*.markdown", "**/*.txt",
     // Build / task runners (no extension or prefix-named)
     "**/Makefile", "**/makefile", "**/GNUmakefile",
     "**/Dockerfile", "**/Dockerfile.*",
     "**/Jenkinsfile", "**/Jenkinsfile.*",
     "**/Vagrantfile", "**/Gemfile", "**/Rakefile",
     "**/Brewfile", "**/Procfile",
+    // Shell & scripting
+    "**/*.sh", "**/*.bash", "**/*.zsh", "**/*.fish",
     // Structured data & config
     "**/*.yaml", "**/*.yml",
     "**/*.json",
     "**/*.toml",
     "**/*.xml",
-    // Shell & scripting
-    "**/*.sh", "**/*.bash", "**/*.zsh",
     // Infrastructure / schema languages
     "**/*.tf",
     "**/*.proto",
     "**/*.graphql", "**/*.gql",
     "**/*.sql",
     "**/*.mod",
+    // API collections
     "**/*.bru",
+    // Stylesheets
     "**/*.css", "**/*.scss", "**/*.less",
   ],
   exclude: ["node_modules/**", ".git/**", "dist/**", ".rag/**"],
@@ -60,28 +72,30 @@ const DEFAULT_CONFIG: RagConfig = {
 };
 
 /**
- * Load config from .rag/config.json, merged with defaults.
- * Note: array fields (include, exclude) from user config *replace* the defaults
- * entirely — they are not merged. This lets users fully control which files are indexed.
+ * Load config from .rag/config.json.
+ * If the file doesn't exist, writes the defaults there first so users can
+ * edit the file directly — no hidden merge logic, what's on disk is what runs.
  */
 export async function loadConfig(projectDir: string): Promise<RagConfig> {
-  const configPath = join(projectDir, ".rag", "config.json");
+  const ragDir = join(projectDir, ".rag");
+  const configPath = join(ragDir, "config.json");
 
   if (!existsSync(configPath)) {
+    await mkdir(ragDir, { recursive: true });
+    await writeFile(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
     return { ...DEFAULT_CONFIG };
   }
 
   const raw = await readFile(configPath, "utf-8");
-  let userConfig: unknown;
+  let parsed: unknown;
   try {
-    userConfig = JSON.parse(raw);
+    parsed = JSON.parse(raw);
   } catch {
     log.warn(`Invalid JSON in ${configPath}, using defaults`, "config");
     return { ...DEFAULT_CONFIG };
   }
 
-  const merged = { ...DEFAULT_CONFIG, ...(userConfig as Record<string, unknown>) };
-  const result = RagConfigSchema.safeParse(merged);
+  const result = RagConfigSchema.safeParse(parsed);
 
   if (!result.success) {
     const issues = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ");
@@ -91,11 +105,3 @@ export async function loadConfig(projectDir: string): Promise<RagConfig> {
 
   return result.data;
 }
-
-export async function writeDefaultConfig(projectDir: string): Promise<string> {
-  const ragDir = join(projectDir, ".rag");
-  await mkdir(ragDir, { recursive: true });
-  const configPath = join(ragDir, "config.json");
-  await writeFile(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
-  return configPath;
-}

package/src/server/index.ts

@@ -8,6 +8,7 @@ import { indexDirectory } from "../indexing/indexer";
 import { startWatcher, type Watcher } from "../indexing/watcher";
 import { discoverSessions } from "../conversation/parser";
 import { indexConversation, startConversationTail } from "../conversation/indexer";
+import { ensureGitignore } from "../cli/setup";
 import { registerAllTools } from "../tools";
 import { log } from "../utils/log";
 
@@ -54,6 +55,11 @@ export async function startServer() {
   let convWatcher: Watcher | null = null;
 
   if (!isHomeDirTrap) {
+    // Ensure .rag/ is gitignored
+    ensureGitignore(startupDir).catch((err) => {
+      log.warn(`Failed to update .gitignore: ${err instanceof Error ? err.message : err}`, "server");
+    });
+
     // Index in background — don't block server startup
     indexDirectory(startupDir, startupDb, startupConfig, (msg) => {
       process.stderr.write(`[local-rag] ${msg}\n`);

package/.mcp.json

@@ -1,11 +0,0 @@
-{
-    "mcpServers": {
-        "local-rag": {
-            "command": "bunx",
-            "args": [
-                "@winci/local-rag",
-                "serve"
-            ]
-        }
-    }
-}