@virsanghavi/axis-server 1.9.2 → 1.10.0

package/.axis/instructions/context.md

@@ -21,7 +21,7 @@ The core value proposition: **agents that coordinate like a team, not individual
 2. **File Locking**: Atomic, per-file locks with 30-minute TTL. Agents call `propose_file_access` before editing. Prevents merge conflicts.
 3. **Live Notepad**: Real-time shared memory. Agents log progress so others know what's happening. Cleared on `finalize_session`.
 4. **Context Mirroring**: `get_project_soul` returns this file + conventions to ground agents in project reality.
-5. **RAG Search**: `search_codebase` and `search_docs` for semantic search over indexed files and documentation.
+5. **RAG Search**: `search_codebase` and `search_docs` for semantic search over indexed files and documentation. **Agents MUST use `search_codebase` before writing new code** — search for similar patterns (e.g. "authentication flow", "API route handler") before creating files. Call `index_file` after creating or significantly changing files.
 6. **Session Management**: `finalize_session` archives the notepad, clears locks, resets for new work.
 7. **Billing**: Stripe-based Pro tier ($25/mo) with API key management, usage tracking, and retention flow.
 

package/dist/mcp-server.mjs

@@ -1140,9 +1140,13 @@ ${conventions}`;
 
 ### MANDATORY: Project soul is not yet filled
 You MUST fill the project soul before doing any other work. Do not proceed with other tasks until it is filled.
-- If the codebase has content to search: use \`search_codebase\` to explore, then \`read_context\` and \`update_context\` to populate \`context.md\` and \`conventions.md\`.
-- If there is nothing in the directory to search through: you MUST ask the user what the project is about, then update the soul files with their answer.
-This requirement is mandatory; ignoring it means working without context.`;
+
+**How to fill the project soul:**
+1. Use \`search_codebase\` to explore the repo and infer what this project is about.
+2. Call \`update_project_soul\` with \`context\` (project overview, architecture, core features, deployment) and \`conventions\` (language standards, styling, code patterns, agent norms).
+3. If the codebase is empty or has nothing to search: ask the user what the project is about, then call \`update_project_soul\` with their answer.
+
+Do NOT skip this. Do NOT proceed with other work until the soul is populated. Working without a filled soul means every decision you make lacks context.`;
     }
     return soul;
   }
@@ -1283,6 +1287,7 @@ import fs4 from "fs";
 import fs3 from "fs/promises";
 import fsSync2 from "fs";
 import path3 from "path";
+import { spawnSync } from "child_process";
 var SKIP_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
   ".git",
@@ -1443,14 +1448,7 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "also",
   "very",
   "really",
-  "quite",
-  "show",
-  "look",
-  "locate",
-  "using",
-  "used",
-  "need",
-  "want"
+  "quite"
 ]);
 var MAX_FILE_SIZE = 256 * 1024;
 var MAX_RESULTS = 20;
@@ -1459,7 +1457,7 @@ var MAX_MATCHES_PER_FILE = 6;
 function extractKeywords(query) {
   const words = query.toLowerCase().replace(/[^\w\s\-_.]/g, " ").split(/\s+/).filter((w) => w.length >= 2);
   const filtered = words.filter((w) => !STOP_WORDS.has(w));
-  const result = filtered.length > 0 ? filtered : words.filter((w) => w.length >= 3);
+  const result = filtered.length > 0 ? filtered : words;
   return [...new Set(result)];
 }
 var PROJECT_ROOT_MARKERS = [
@@ -1477,7 +1475,7 @@ var PROJECT_ROOT_MARKERS = [
   "AGENTS.md"
 ];
 function detectProjectRoot(startDir) {
-  let current = startDir;
+  let current = path3.resolve(startDir);
   const root = path3.parse(current).root;
   while (current !== root) {
     for (const marker of PROJECT_ROOT_MARKERS) {
@@ -1540,8 +1538,7 @@ async function searchFile(filePath, rootDir, keywords) {
   const matchedKeywords = keywords.filter((kw) => contentLower.includes(kw));
   if (matchedKeywords.length === 0) return null;
   const coverage = matchedKeywords.length / keywords.length;
-  if (keywords.length >= 3 && coverage < 0.4) return null;
-  if (keywords.length === 2 && matchedKeywords.length < 1) return null;
+  if (coverage < 0.2) return null;
   const lines = content.split("\n");
   let score = coverage * coverage * matchedKeywords.length;
   const relLower = relativePath.toLowerCase();
@@ -1593,58 +1590,200 @@ async function searchFile(filePath, rootDir, keywords) {
   }
   return { filePath, relativePath, score, matchedKeywords, regions };
 }
+function runRipgrep(pattern, cwd) {
+  const p = (pattern || "").trim();
+  if (!p || p.length > 200) return [];
+  const result = spawnSync("rg", [
+    "--line-number",
+    "--no-heading",
+    "--color",
+    "never",
+    "--max-count",
+    "3",
+    // Max 3 matches per file per pattern
+    "-C",
+    "1",
+    // 1 line context
+    "--ignore-case",
+    "--max-filesize",
+    "256K",
+    "-F",
+    p,
+    // Fixed string (literal) — no regex escaping needed
+    "."
+  ], {
+    cwd,
+    encoding: "utf-8",
+    timeout: 8e3,
+    maxBuffer: 4 * 1024 * 1024
+  });
+  if (result.error || result.status !== 0) {
+    return [];
+  }
+  const hits = [];
+  const lines = (result.stdout || "").trim().split("\n").filter(Boolean);
+  for (const line of lines) {
+    const match = line.match(/^(.+?):(\d+):(.+)$/);
+    if (match) {
+      const [, file, lineNum, content] = match;
+      const relPath = path3.relative(cwd, file);
+      hits.push({
+        file: relPath,
+        line: parseInt(lineNum, 10),
+        content: content.trim(),
+        pattern: p
+      });
+    }
+  }
+  return hits;
+}
+function ripgrepAvailable() {
+  const r = spawnSync("rg", ["--version"], { encoding: "utf-8" });
+  return !r.error && r.status === 0;
+}
+async function warpgrepSearch(query, cwd) {
+  const keywords = extractKeywords(query);
+  if (keywords.length === 0) {
+    const tokens = query.replace(/[^\w\s]/g, " ").split(/\s+/).filter((w) => w.length >= 2);
+    if (tokens.length === 0) return "";
+    keywords.push(tokens[0]);
+  }
+  const allHits = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const kw of keywords.slice(0, 5)) {
+    const hits = runRipgrep(kw, cwd);
+    for (const h of hits) {
+      const key = `${h.file}:${h.line}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        allHits.push(h);
+      }
+    }
+  }
+  if (allHits.length === 0) return "";
+  const byFile = /* @__PURE__ */ new Map();
+  for (const h of allHits) {
+    const list = byFile.get(h.file) || [];
+    if (list.length < MAX_MATCHES_PER_FILE) list.push(h);
+    byFile.set(h.file, list);
+  }
+  const lines = [];
+  lines.push(`Found ${allHits.length} match(es) via ripgrep (keywords: ${keywords.join(", ")})
+`);
+  lines.push("\u2550".repeat(60) + "\n");
+  const sortedFiles = [...byFile.keys()].sort();
+  for (const relPath of sortedFiles.slice(0, MAX_RESULTS)) {
+    const hits = byFile.get(relPath);
+    lines.push(`${relPath}
+`);
+    for (const h of hits) {
+      lines.push(`   ${h.line.toString().padStart(4)}| ${h.content}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
 async function localSearch(query, rootDir) {
+  const q = typeof query === "string" ? query.trim() : "";
   const rawCwd = rootDir || process.cwd();
   const cwd = detectProjectRoot(rawCwd);
-  const keywords = extractKeywords(query);
+  const keywords = extractKeywords(q);
   if (cwd !== rawCwd) {
     logger.info(`[localSearch] Detected project root: ${cwd} (CWD was: ${rawCwd})`);
   }
-  if (keywords.length === 0) {
+  const hasTerms = keywords.length > 0 || q.replace(/[^\w\s]/g, " ").split(/\s+/).some((w) => w.length >= 2);
+  if (!hasTerms) {
     return "Could not extract meaningful search terms from the query. Try being more specific (e.g. 'authentication middleware' instead of 'how does it work').";
   }
-  logger.info(`[localSearch] Query: "${query}" \u2192 Keywords: [${keywords.join(", ")}] in ${cwd}`);
-  const files = await walkDir(cwd);
-  logger.info(`[localSearch] Scanning ${files.length} files`);
-  const BATCH_SIZE = 50;
-  const allMatches = [];
-  for (let i = 0; i < files.length; i += BATCH_SIZE) {
-    const batch = files.slice(i, i + BATCH_SIZE);
-    const results = await Promise.all(
-      batch.map((f) => searchFile(f, cwd, keywords))
-    );
-    for (const r of results) {
-      if (r) allMatches.push(r);
-    }
-  }
-  allMatches.sort((a, b) => b.score - a.score);
-  const topMatches = allMatches.slice(0, MAX_RESULTS);
-  if (topMatches.length === 0) {
-    return `No matches found for: "${query}" (searched ${files.length} files for keywords: ${keywords.join(", ")}).
-Try different terms or check if the code exists in this project.`;
-  }
-  let output = `Found ${allMatches.length} matching file${allMatches.length === 1 ? "" : "s"} (showing top ${topMatches.length}, searched ${files.length} files)
+  logger.info(`[localSearch] Query: "${q}" \u2192 Keywords: [${keywords.join(", ")}] in ${cwd}`);
+  const useRipgrep = ripgrepAvailable();
+  const [rgResults, keyResults] = await Promise.all([
+    useRipgrep ? warpgrepSearch(q, cwd) : Promise.resolve(""),
+    (async () => {
+      const kws2 = keywords.length > 0 ? keywords : q.replace(/[^\w\s]/g, " ").split(/\s+/).filter((w) => w.length >= 2).slice(0, 5);
+      if (kws2.length === 0) return "";
+      const files = await walkDir(cwd);
+      logger.info(`[localSearch] Scanning ${files.length} files (keyword search)`);
+      const BATCH_SIZE = 50;
+      const allMatches = [];
+      for (let i = 0; i < files.length; i += BATCH_SIZE) {
+        const batch = files.slice(i, i + BATCH_SIZE);
+        const results = await Promise.all(batch.map((f) => searchFile(f, cwd, kws2)));
+        for (const r of results) {
+          if (r) allMatches.push(r);
+        }
+      }
+      allMatches.sort((a, b) => b.score - a.score);
+      const topMatches = allMatches.slice(0, MAX_RESULTS);
+      if (topMatches.length === 0) return "";
+      let out = `Found ${allMatches.length} matching file${allMatches.length === 1 ? "" : "s"} (showing top ${topMatches.length}, searched ${files.length} files)
 `;
-  output += `Keywords: ${keywords.join(", ")}
+      out += `Keywords: ${kws2.join(", ")}
 `;
-  output += "\u2550".repeat(60) + "\n\n";
-  for (const match of topMatches) {
-    output += `\u{1F4C4} ${match.relativePath}
+      out += "\u2550".repeat(60) + "\n\n";
+      for (const match of topMatches) {
+        out += `${match.relativePath}
 `;
-    output += `   Keywords matched: ${match.matchedKeywords.join(", ")} | Score: ${match.score.toFixed(1)}
+        out += `   Keywords matched: ${match.matchedKeywords.join(", ")} | Score: ${match.score.toFixed(1)}
 `;
-    if (match.regions.length > 0) {
-      output += "   \u2500\u2500\u2500\u2500\u2500\n";
-      for (const region of match.regions) {
-        output += region.lines.split("\n").map((l) => `   ${l}`).join("\n") + "\n";
-        if (region !== match.regions[match.regions.length - 1]) {
-          output += "   ...\n";
+        if (match.regions.length > 0) {
+          out += "   \u2500\u2500\u2500\u2500\u2500\n";
+          for (const region of match.regions) {
+            out += region.lines.split("\n").map((l) => `   ${l}`).join("\n") + "\n";
+            if (region !== match.regions[match.regions.length - 1]) out += "   ...\n";
+          }
+        }
+        out += "\n";
+      }
+      return out;
+    })()
+  ]);
+  const rgHasResults = rgResults && !rgResults.startsWith("Found 0");
+  const keyHasResults = keyResults && keyResults.length > 50;
+  if (rgHasResults && keyHasResults) {
+    return rgResults + "\n\n--- Also from keyword search ---\n\n" + keyResults;
+  }
+  if (rgHasResults) return rgResults;
+  if (keyHasResults) return keyResults;
+  const kws = keywords.length > 0 ? keywords : q.replace(/[^\w\s]/g, " ").split(/\s+/).filter((w) => w.length >= 2).slice(0, 5);
+  if (kws.length >= 3) {
+    const fallbackKws = kws.slice(0, 2);
+    const files = await walkDir(cwd);
+    const fallbackMatches = [];
+    for (let i = 0; i < files.length; i += 50) {
+      const batch = files.slice(i, i + 50);
+      const results = await Promise.all(batch.map((f) => searchFile(f, cwd, fallbackKws)));
+      for (const r of results) {
+        if (r) fallbackMatches.push(r);
+      }
+    }
+    if (fallbackMatches.length > 0) {
+      fallbackMatches.sort((a, b) => b.score - a.score);
+      const top = fallbackMatches.slice(0, MAX_RESULTS);
+      let out = `Found ${fallbackMatches.length} matching file${fallbackMatches.length === 1 ? "" : "s"} (fallback: fewer keywords, showing top ${top.length})
+`;
+      out += `Keywords: ${fallbackKws.join(", ")} (original: ${kws.join(", ")})
+`;
+      out += "\u2550".repeat(60) + "\n\n";
+      for (const match of top) {
+        out += `\u{1F4C4} ${match.relativePath}
+`;
+        out += `   Keywords matched: ${match.matchedKeywords.join(", ")} | Score: ${match.score.toFixed(1)}
+`;
+        if (match.regions.length > 0) {
+          out += "   \u2500\u2500\u2500\u2500\u2500\n";
+          for (const region of match.regions) {
+            out += region.lines.split("\n").map((l) => `   ${l}`).join("\n") + "\n";
+            if (region !== match.regions[match.regions.length - 1]) out += "   ...\n";
+          }
         }
+        out += "\n";
       }
+      return out;
     }
-    output += "\n";
   }
-  return output;
+  return `No matches found for: "${q}" (searched for: ${kws.join(", ") || "query terms"}).
+Try different terms or check if the code exists in this project.`;
 }
 
 // ../../src/local/mcp-server.ts
@@ -1860,7 +1999,10 @@ async function ensureFileSystem() {
         ["context.md", `# Project Context
 
 ## Overview
-<!-- Describe your project's goals and what it does. If this file is still just placeholders, agents MUST fill it: use search_codebase to infer content from the repo, or if there is nothing to search, ask the user what the project is about, then update via update_context. Do not proceed with other work until the soul is filled. -->
+<!-- THIS FILE IS PART OF THE PROJECT SOUL. If it still contains placeholders, agents MUST fill it before doing any other work.
+How to fill: use search_codebase to explore the repo, then call update_project_soul(context: "...your content...") to replace this placeholder.
+If the repo is empty: ask the user what the project is about, then call update_project_soul with their answer.
+Do not proceed with other tasks until this file has real content. -->
 
 ## Architecture
 <!-- Stack, high-level design, and key systems -->
@@ -1995,11 +2137,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: UPDATE_CONTEXT_TOOL,
-      description: "**APPEND OR OVERWRITE** shared context files.\n- Use this to update the project's long-term memory (e.g., adding a new convention, updating the architectural goal).\n- For short-term updates (like 'I just fixed bug X'), use `update_shared_context` (Notepad) instead.\n- Supports `append: true` (default: false) to add to the end of a file.",
+      description: "**APPEND OR OVERWRITE** any shared context file.\n- To update the project soul (context.md / conventions.md), prefer `update_project_soul` instead \u2014 it handles both files in one call.\n- Use this tool for other context files (e.g., `activity.md`) or when you need to append to a file.\n- For short-term updates (like 'I just fixed bug X'), use `update_shared_context` (Notepad) instead.\n- Supports `append: true` (default: false) to add to the end of a file.",
       inputSchema: {
         type: "object",
         properties: {
-          filename: { type: "string", description: "File to update (e.g. 'activity.md')" },
+          filename: { type: "string", description: "File to update (e.g. 'activity.md'). For soul files, prefer update_project_soul instead." },
           content: { type: "string", description: "The new content to write or append." },
           append: { type: "boolean", description: "Whether to append to the end of the file (true) or overwrite it (false). Default: false." }
         },
@@ -2084,9 +2226,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "get_project_soul",
-      description: "**MANDATORY FIRST CALL**: Returns the project's goals, architecture, conventions, and active state.\n- Combines `context.md`, `conventions.md`, and other core directives into a single prompt.\n- You MUST call this as your FIRST action in every new session or task \u2014 before reading files, before responding to the user, before anything else.\n- If the project soul is not yet filled, you MUST fill it before any other work: use search_codebase then update_context, or if there is nothing to search, you MUST ask the user what the project is about and then update the soul files. Do not proceed with other tasks until the soul is filled.\n- Skipping this call means you are working without context and will make wrong decisions.",
+      description: "**MANDATORY FIRST CALL**: Returns the project's goals, architecture, conventions, and active state.\n- Combines `context.md` (project goals/architecture) and `conventions.md` (coding standards/norms) into a single prompt.\n- You MUST call this as your FIRST action in every new session or task \u2014 before reading files, before responding to the user, before anything else.\n- If the project soul is not yet filled (you'll see a 'MANDATORY: Project soul is not yet filled' message), you MUST fill it before any other work:\n  1. Use `search_codebase` to explore the repo and infer project details.\n  2. Call `update_project_soul` with `context` and/or `conventions` params to populate the soul in one call.\n  3. If there is nothing to search, ask the user what the project is about, then call `update_project_soul`.\n- Skipping this call means you are working without context and will make wrong decisions.",
       inputSchema: { type: "object", properties: {}, required: [] }
     },
+    {
+      name: "update_project_soul",
+      description: "**UPDATE THE PROJECT SOUL** \u2014 write project context and/or conventions in a single call.\n- The project soul consists of `context.md` (goals, architecture, core features) and `conventions.md` (coding standards, agent norms).\n- Provide `context` to update `context.md`, `conventions` to update `conventions.md`, or both.\n- Use this when `get_project_soul` says the soul is unfilled, or whenever you need to update long-term project knowledge.\n- This replaces the file contents entirely (not append). For appending, use `update_context` instead.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          context: { type: "string", description: "Full content for context.md (project overview, architecture, core features, deployment). Omit to leave unchanged." },
+          conventions: { type: "string", description: "Full content for conventions.md (language standards, styling, code patterns, agent norms). Omit to leave unchanged." }
+        },
+        required: []
+      }
+    },
     // --- Job Board (Task Orchestration) ---
     {
       name: "post_job",
@@ -2170,15 +2324,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   logger.info("Tool call", { name });
-  if (isSubscriptionStale()) {
-    await verifySubscription();
-  }
-  if (!subscription.valid) {
-    logger.warn(`[subscription] Blocking tool call "${name}" \u2014 subscription invalid`);
-    return {
-      content: [{ type: "text", text: getSubscriptionBlockMessage() }],
-      isError: true
-    };
+  if (process.env.AXIS_SKIP_SUBSCRIPTION_CHECK === "1") {
+  } else {
+    if (isSubscriptionStale()) {
+      await verifySubscription();
+    }
+    if (!subscription.valid) {
+      logger.warn(`[subscription] Blocking tool call "${name}" \u2014 subscription invalid`);
+      return {
+        content: [{ type: "text", text: getSubscriptionBlockMessage() }],
+        isError: true
+      };
+    }
   }
   if (name === READ_CONTEXT_TOOL) {
     const filename = String(args?.filename);
@@ -2331,6 +2488,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const result = await nerveCenter.getProjectSoul();
     return { content: [{ type: "text", text: result }] };
   }
+  if (name === "update_project_soul") {
+    const { context, conventions } = args;
+    const updated = [];
+    if (context) {
+      await manager.updateFile("context.md", context, false);
+      updated.push("context.md");
+    }
+    if (conventions) {
+      await manager.updateFile("conventions.md", conventions, false);
+      updated.push("conventions.md");
+    }
+    if (updated.length === 0) {
+      return { content: [{ type: "text", text: "No changes \u2014 provide `context` and/or `conventions` parameters." }] };
+    }
+    return { content: [{ type: "text", text: `Project soul updated: ${updated.join(", ")}` }] };
+  }
   if (name === "post_job") {
     const { title, description, priority, dependencies } = args;
     const result = await nerveCenter.postJob(title, description, priority, dependencies);

package/package.json

@@ -1,33 +1,37 @@
 {
-    "name": "@virsanghavi/axis-server",
-    "version": "1.9.2",
-    "description": "Axis MCP Server CLI",
-    "main": "dist/index.js",
-    "bin": {
-        "axis-server": "dist/cli.js"
-    },
-    "scripts": {
-        "start": "node dist/cli.js",
-        "build": "tsup bin/cli.ts --format cjs --out-dir dist --clean --shims && tsup ../../src/local/mcp-server.ts --format esm --out-dir dist",
-        "prepublishOnly": "npm run build"
-    },
-    "dependencies": {
-        "commander": "^11.0.0",
-        "chalk": "^5.3.0",
-        "@modelcontextprotocol/sdk": "^0.6.0",
-        "@supabase/supabase-js": "^2.39.0",
-        "async-mutex": "^0.5.0",
-        "dotenv": "^16.3.1",
-        "fs-extra": "^11.2.0",
-        "openai": "^4.24.0",
-        "zod": "^3.22.4",
-        "execa": "^8.0.0"
-    },
-    "devDependencies": {
-        "@types/node": "^20.0.0",
-        "@types/fs-extra": "^11.0.4",
-        "tsup": "^8.0.1",
-        "tsx": "^4.7.0",
-        "typescript": "^5.0.0"
-    }
+  "name": "@virsanghavi/axis-server",
+  "version": "1.10.0",
+  "description": "Axis MCP Server CLI",
+  "main": "dist/index.js",
+  "bin": {
+    "axis-server": "dist/cli.js"
+  },
+  "scripts": {
+    "start": "node dist/cli.js",
+    "build": "tsup bin/cli.ts --format cjs --out-dir dist --clean --shims && tsup ../../src/local/mcp-server.ts --format esm --out-dir dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "chalk": "^5.3.0",
+    "@modelcontextprotocol/sdk": "^0.6.0",
+    "@supabase/supabase-js": "^2.39.0",
+    "async-mutex": "^0.5.0",
+    "dotenv": "^16.3.1",
+    "fs-extra": "^11.2.0",
+    "openai": "^4.24.0",
+    "zod": "^3.22.4",
+    "execa": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/fs-extra": "^11.0.4",
+    "tsup": "^8.0.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
 }