@yurtsever/capsa 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/index.js

@@ -10053,7 +10053,7 @@ function loadSqlite() {
 }
 var DB_DIR = ".capsa";
 var DB_FILE = "index.db";
-var SCHEMA_VERSION = 2;
+var SCHEMA_VERSION = 3;
 function dbPath(projectRoot) {
   return join6(projectRoot, DB_DIR, DB_FILE);
 }
@@ -10075,9 +10075,20 @@ var Store = class {
     const row = this.db.prepare("SELECT value FROM meta WHERE key = 'schema'").get();
     return row?.value !== String(SCHEMA_VERSION);
   }
-  /** Drop all indexed content (not the log, not decisions) and mark the schema current. */
+  /**
+    * Drop all indexed content (not the log, not decisions) and mark the schema
+    * current. The virtual tables are dropped and recreated, not emptied:
+    * `CREATE VIRTUAL TABLE IF NOT EXISTS` would keep an old tokenizer alive
+    * through a rebuild — which once left FTS without stemming after v2.
+    */
   reset() {
-    this.db.exec("DELETE FROM chunks_vec; DELETE FROM chunks_fts; DELETE FROM chunks; DELETE FROM items;");
+    this.db.exec(`
+      DROP TABLE IF EXISTS chunks_fts;
+      DROP TABLE IF EXISTS chunks_vec;
+      DELETE FROM chunks;
+      DELETE FROM items;
+    `);
+    this.migrate();
     this.db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES ('schema', ?)").run(String(SCHEMA_VERSION));
   }
   migrate() {
@@ -10216,6 +10227,10 @@ var Store = class {
       }
     }));
   }
+  /** All chunks of one item, in document order. */
+  chunksForItem(itemId) {
+    return this.db.prepare("SELECT id, item_id, idx, heading_path, text FROM chunks WHERE item_id = ? ORDER BY idx").all(itemId);
+  }
   listItems() {
     return this.db.prepare("SELECT * FROM items ORDER BY kind, rel_path").all();
   }
@@ -10555,6 +10570,40 @@ function rrf(lists, k = DEFAULT_WEIGHTS.rrfK) {
   return scores;
 }
 
+// ../index/dist/pin.js
+var LEADING_ID = /^([A-Za-z]{1,8}-?\d{1,5}(?:-\d{1,5})?|\d{2,6})(?=[-_.\s]|$)/;
+function leadingId(relPath) {
+  const base = relPath.split(/[\\/]/).pop() ?? "";
+  return LEADING_ID.exec(base)?.[1];
+}
+function pinnedItems(query, items) {
+  const q = query.toLowerCase();
+  const idCount = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const id = leadingId(item.rel_path)?.toLowerCase();
+    if (id)
+      idCount.set(id, (idCount.get(id) ?? 0) + 1);
+  }
+  const out = [];
+  for (const item of items) {
+    const rel = item.rel_path.toLowerCase();
+    if (q.includes(rel)) {
+      out.push(item);
+      continue;
+    }
+    const id = leadingId(item.rel_path);
+    if (!id || (idCount.get(id.toLowerCase()) ?? 0) > 1)
+      continue;
+    const re = new RegExp(`(^|[^\\w-])${escape2(id)}(?=$|[^\\w-])`, "i");
+    if (re.test(query))
+      out.push(item);
+  }
+  return out;
+}
+function escape2(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 // ../index/dist/retrieve.js
 async function retrieve(store, embedder, query, options = {}) {
   const started = Date.now();
@@ -10562,31 +10611,97 @@ async function retrieve(store, embedder, query, options = {}) {
   const candidates = options.candidates ?? 30;
   const weights = options.weights ?? DEFAULT_WEIGHTS;
   const minRelative = options.minRelativeScore ?? 0.5;
+  const perItem = /* @__PURE__ */ new Map();
+  const chunks = [];
+  const debug = [];
+  let tokens = 0;
+  const pinned = pinnedItems(query, store.listItems());
+  for (const item of pinned) {
+    for (const c of store.chunksForItem(item.id)) {
+      const t = estimateTokens(c.text);
+      const fits = tokens + t <= maxTokens || chunks.length === 0;
+      if (options.debug) {
+        debug.push({
+          chunkId: c.id,
+          relPath: item.rel_path,
+          headingPath: JSON.parse(c.heading_path),
+          kind: item.kind,
+          status: item.status,
+          vecRank: null,
+          ftsRank: null,
+          fused: 0,
+          factor: 1,
+          score: Number.POSITIVE_INFINITY,
+          kept: fits,
+          why: fits ? "pinned" : "budget"
+        });
+      }
+      if (!fits)
+        continue;
+      perItem.set(item.id, (perItem.get(item.id) ?? 0) + 1);
+      tokens += t;
+      chunks.push({
+        chunkId: c.id,
+        score: Number.POSITIVE_INFINITY,
+        kind: item.kind,
+        status: item.status,
+        updatedAt: item.updated_at,
+        relPath: item.rel_path,
+        headingPath: JSON.parse(c.heading_path),
+        text: c.text,
+        tokens: t
+      });
+    }
+  }
+  const pinnedIds = new Set(pinned.map((i) => i.id));
+  const neighbourCutoff = pinned.length ? Math.max(minRelative, 0.75) : minRelative;
+  const neighbourBudget = pinned.length ? Math.min(maxTokens, tokens + Math.floor(maxTokens / 3)) : maxTokens;
   const [qv] = await embedder.embed([query]);
   const vec = qv ? store.vectorSearch(qv, candidates).map((r) => r.chunkId) : [];
   const fts = store.textSearch(query, candidates).map((r) => r.chunkId);
   const fused = rrf([vec, fts], weights.rrfK);
-  const rows = store.chunksWithItems([...fused.keys()]);
+  const rows = store.chunksWithItems([...fused.keys()]).filter((r) => !pinnedIds.has(r.item_id));
   const now = Date.now();
-  const scored = rows.map((r) => ({
-    row: r,
-    score: (fused.get(r.id) ?? 0) * signalFactor({ kind: r.item.kind, status: r.item.status, updatedAt: r.item.updated_at }, weights, now)
-  })).sort((a, b) => b.score - a.score);
-  const perItem = /* @__PURE__ */ new Map();
-  const chunks = [];
-  let tokens = 0;
+  const scored = rows.map((r) => {
+    const fusedScore = fused.get(r.id) ?? 0;
+    const factor = signalFactor({ kind: r.item.kind, status: r.item.status, updatedAt: r.item.updated_at }, weights, now);
+    return { row: r, fusedScore, factor, score: fusedScore * factor };
+  }).sort((a, b) => b.score - a.score);
   const best = scored[0]?.score ?? 0;
-  for (const { row, score } of scored) {
-    if (chunks.length > 0 && score < best * minRelative)
-      break;
-    const used = perItem.get(row.item_id) ?? 0;
-    if (used >= 2)
+  let cut = tokens >= maxTokens;
+  let kept = 0;
+  for (const { row, fusedScore, factor, score } of scored) {
+    let why = "kept";
+    if (cut || kept > 0 && score < best * neighbourCutoff) {
+      cut = true;
+      why = "cutoff";
+    } else if ((perItem.get(row.item_id) ?? 0) >= 2) {
+      why = "per-item cap";
+    } else if (tokens + estimateTokens(row.text) > neighbourBudget && chunks.length > 0) {
+      why = "budget";
+    }
+    if (options.debug) {
+      debug.push({
+        chunkId: row.id,
+        relPath: row.item.rel_path,
+        headingPath: JSON.parse(row.heading_path),
+        kind: row.item.kind,
+        status: row.item.status,
+        vecRank: rankIn(vec, row.id),
+        ftsRank: rankIn(fts, row.id),
+        fused: fusedScore,
+        factor,
+        score,
+        kept: why === "kept",
+        why
+      });
+    }
+    if (why !== "kept")
       continue;
     const t = estimateTokens(row.text);
-    if (tokens + t > maxTokens && chunks.length > 0)
-      continue;
-    perItem.set(row.item_id, used + 1);
+    perItem.set(row.item_id, (perItem.get(row.item_id) ?? 0) + 1);
     tokens += t;
+    kept++;
     chunks.push({
       chunkId: row.id,
       score,
@@ -10598,8 +10713,8 @@ async function retrieve(store, embedder, query, options = {}) {
       text: row.text,
       tokens: t
     });
-    if (tokens >= maxTokens)
-      break;
+    if (tokens >= neighbourBudget)
+      cut = true;
   }
   const durationMs = Date.now() - started;
   store.logContext({
@@ -10609,7 +10724,28 @@ async function retrieve(store, embedder, query, options = {}) {
     tokensEst: tokens,
     durationMs
   });
-  return { query, chunks, tokensEst: tokens, durationMs };
+  return { query, chunks, tokensEst: tokens, durationMs, ...options.debug ? { debug } : {} };
+}
+function rankIn(list, id) {
+  const i = list.indexOf(id);
+  return i === -1 ? null : i + 1;
+}
+function formatDebug(result) {
+  if (!result.debug)
+    return "";
+  const lines = ["  vec  fts  factor  score    keep         where"];
+  for (const d of result.debug) {
+    const where = [d.relPath, ...d.headingPath].join(" \u203A ").slice(0, 70);
+    lines.push([
+      String(d.vecRank ?? "-").padStart(5),
+      String(d.ftsRank ?? "-").padStart(4),
+      d.factor.toFixed(2).padStart(7),
+      (Number.isFinite(d.score) ? d.score.toFixed(4) : "pin").padStart(8),
+      (d.kept ? d.why === "pinned" ? "pinned" : "yes" : d.why).padEnd(12),
+      where
+    ].join(" "));
+  }
+  return lines.join("\n");
 }
 function formatContext(result) {
   if (result.chunks.length === 0)
@@ -10631,7 +10767,8 @@ function projectState(store) {
   for (const i of items)
     counts[i.kind] = (counts[i.kind] ?? 0) + 1;
   const live = (i) => (i.kind === "ticket" || i.kind === "plan") && (i.status === "open" || i.status === "in-progress");
-  const open2 = items.filter(live).sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? "")).map((i) => ({ relPath: i.rel_path, name: i.name, status: i.status ?? "unknown", updatedAt: i.updated_at }));
+  const rank = (i) => i.status === "in-progress" ? 0 : 1;
+  const open2 = items.filter(live).sort((a, b) => rank(a) - rank(b) || a.rel_path.localeCompare(b.rel_path)).map((i) => ({ relPath: i.rel_path, name: i.name, status: i.status ?? "unknown", updatedAt: i.updated_at }));
   const recentlyChanged = [...items].sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? "")).slice(0, 10).map((i) => ({ relPath: i.rel_path, kind: i.kind, updatedAt: i.updated_at }));
   const decisions = store.db.prepare("SELECT id, created_at, title FROM decisions ORDER BY id DESC LIMIT 10").all().map((d) => ({ id: d.id, createdAt: d.created_at, title: d.title }));
   return { counts, open: open2, recentlyChanged, decisions };
@@ -40000,17 +40137,37 @@ async function guarded(run) {
     process.exit(1);
   }
 }
-function rootFrom(args) {
-  const positional = args.filter((a) => !a.startsWith("--"));
-  return resolve3(positional[0] ?? process.cwd());
+var VALUE_FLAGS = /* @__PURE__ */ new Set(["--model", "--tokens"]);
+function parseArgs(args) {
+  const positional = [];
+  const flags = /* @__PURE__ */ new Map();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (VALUE_FLAGS.has(arg)) {
+      const value = args[++i];
+      if (value === void 0 || value.startsWith("--")) {
+        throw new Error(`${arg} expects a value`);
+      }
+      flags.set(arg, value);
+    } else if (arg.startsWith("--")) {
+      flags.set(arg, "true");
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags };
 }
-function flag(args, name) {
-  const i = args.indexOf(name);
-  return i >= 0 ? args[i + 1] : void 0;
+function tokensFlag(flags) {
+  const raw2 = flags.get("--tokens");
+  if (raw2 === void 0) return void 0;
+  const n = Number(raw2);
+  if (!Number.isInteger(n) || n < 200) throw new Error(`--tokens expects an integer \u2265 200, got "${raw2}"`);
+  return n;
 }
 async function runIndexCommand(args) {
-  const root = rootFrom(args);
-  const embedder = ollamaEmbedder({ model: flag(args, "--model") });
+  const { positional, flags } = parseArgs(args);
+  const root = resolve3(positional[0] ?? process.cwd());
+  const embedder = ollamaEmbedder({ model: flags.get("--model") });
   console.error(`capsa: indexing ${root} with ${embedder.model} \u2026`);
   const res = await indexProject(root, embedder, (p) => {
     if (p.phase === "rebuild") console.error("capsa: index schema changed, rebuilding from scratch \u2026");
@@ -40023,19 +40180,25 @@ async function runIndexCommand(args) {
   for (const i of res.issues.slice(0, 10)) console.error(`  ! ${i.path}: ${i.message}`);
 }
 async function runSearchCommand(args) {
-  const positional = args.filter((a) => !a.startsWith("--"));
+  const { positional, flags } = parseArgs(args);
   const query = positional[0];
   if (!query) {
-    console.error("capsa search <query> [path]");
+    console.error("capsa search <query> [path] [--tokens n] [--model name] [--debug]");
     process.exit(1);
   }
   const root = resolve3(positional[1] ?? process.cwd());
-  const embedder = ollamaEmbedder({ model: flag(args, "--model") });
-  const maxTokens = flag(args, "--tokens") ? Number(flag(args, "--tokens")) : void 0;
+  const embedder = ollamaEmbedder({ model: flags.get("--model") });
+  const maxTokens = tokensFlag(flags);
   const store = openStore(root, embedder);
   try {
-    const res = await retrieve(store, embedder, query, { maxTokens, source: "cli:search" });
-    console.log(formatContext(res));
+    const debug = flags.get("--debug") === "true";
+    const res = await retrieve(store, embedder, query, { maxTokens, source: "cli:search", debug });
+    if (debug) {
+      console.log(formatDebug(res));
+      console.log("");
+    } else {
+      console.log(formatContext(res));
+    }
     console.error(`
 ${res.chunks.length} chunks, ~${res.tokensEst} tokens, ${res.durationMs} ms`);
   } finally {
@@ -40043,7 +40206,7 @@ ${res.chunks.length} chunks, ~${res.tokensEst} tokens, ${res.durationMs} ms`);
   }
 }
 async function runStateCommand(args) {
-  const root = rootFrom(args);
+  const root = resolve3(parseArgs(args).positional[0] ?? process.cwd());
   const store = openStore(root, ollamaEmbedder());
   try {
     console.log(formatState(projectState(store)));
@@ -40052,7 +40215,11 @@ async function runStateCommand(args) {
   }
 }
 async function runMcpCommand(args) {
-  await serveStdio({ projectRoot: rootFrom(args) });
+  const { positional, flags } = parseArgs(args);
+  await serveStdio({
+    projectRoot: resolve3(positional[0] ?? process.cwd()),
+    embedder: ollamaEmbedder({ model: flags.get("--model") })
+  });
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yurtsever/capsa",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Your project's knowledge in one capsule. Local-first project memory and cockpit for AI coding agents: indexes runbooks, tickets, plans and instruction files, serves the smallest relevant context over MCP.",
   "type": "module",
   "license": "MIT",