@backbencher/brain 0.0.0-stage → 0.1.0

package/dist/doctor-GXCKSJOX.js

@@ -0,0 +1,395 @@
+import {
+  describeEmbeddingConfig,
+  embedding_diagnosis_exports
+} from "./chunk-J4PMBXQQ.js";
+import "./chunk-2RRBMNBQ.js";
+import {
+  diagnosePoolStartupSync,
+  findPackageRoot
+} from "./chunk-4H22TLOT.js";
+import {
+  SemanticEngine,
+  isEmbeddingDisabled
+} from "./chunk-5SD45FLC.js";
+import "./chunk-7AN7U5IZ.js";
+import "./chunk-UGR4QIGS.js";
+import "./chunk-BQ3OVQ3P.js";
+import {
+  bbDataDir
+} from "./chunk-2BSKD7O3.js";
+import "./chunk-MLKGABMK.js";
+
+// src/setup/doctor.ts
+import { existsSync, readFileSync, statSync, chmodSync } from "fs";
+import { createRequire } from "module";
+import path from "path";
+var ROOT_PKG = findPackageRoot(import.meta.dirname ?? ".") ?? path.resolve(import.meta.dirname ?? ".", "../..");
+function poolModuleDir() {
+  const dist = path.join(ROOT_PKG, "dist");
+  return existsSync(path.join(dist, "pool-worker.js")) ? dist : path.join(ROOT_PKG, "src", "ast");
+}
+var poolCache = null;
+function runPoolDoctor(moduleDir, probe) {
+  const key = `${moduleDir}|${process.env.BB_POOL_WORKER ?? ""}|${probe === false ? "noprobe" : "probe"}`;
+  if (poolCache && poolCache.key === key) return poolCache.report;
+  const report = diagnosePoolStartupSync({ moduleDir, probe });
+  poolCache = { key, report };
+  return report;
+}
+function resetPoolDoctorCache() {
+  poolCache = null;
+}
+function openProjectDbReadonly(dbPath) {
+  const require2 = createRequire(path.join(ROOT_PKG, "package.json"));
+  if (typeof globalThis.Bun !== "undefined") {
+    const { Database: Database2 } = require2("bun:sqlite");
+    return new Database2(dbPath, { readonly: true });
+  }
+  const Database = require2("better-sqlite3");
+  return new Database(dbPath, { readonly: true, fileMustExist: true });
+}
+function readStoredModels(projectId, dataDir) {
+  const dbPath = path.join(dataDir, "projects", projectId, "brain.db");
+  if (!existsSync(dbPath)) return { models: [], unreadable: null };
+  try {
+    const db = openProjectDbReadonly(dbPath);
+    try {
+      const rows = db.prepare(
+        `SELECT embedding_model AS model, COUNT(*) AS count FROM brain_semantic_embedding WHERE project_id = ? GROUP BY embedding_model`
+      ).all(projectId);
+      return { models: rows.map((r) => ({ model: String(r.model), count: Number(r.count) })), unreadable: null };
+    } finally {
+      db.close();
+    }
+  } catch (e) {
+    const message = String(e?.message ?? e);
+    if (message.includes("no such table")) return { models: [], unreadable: null };
+    return { models: [], unreadable: message.slice(0, 200) };
+  }
+}
+function tierIssues(t) {
+  const missing = [];
+  if (t.present && !t.complete) {
+    const reason = t.incompleteReason ?? "";
+    if (reason.includes("base URL")) missing.push("base URL");
+    if (reason.includes("model")) missing.push("model");
+    if (!t.keyFingerprint) missing.push("API key");
+  }
+  const modeWrong = t.fileMode !== void 0 && t.fileMode !== 384;
+  return { missing, modeWrong };
+}
+function runDoctorChecks(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const env = opts.env ?? process.env;
+  const dataDir = opts.dataDir ?? bbDataDir();
+  const state = describeEmbeddingConfig(cwd, env, dataDir);
+  const findings = [];
+  const embeddingChain = [];
+  const localLabel = SemanticEngine.LOCAL_MODEL_LABEL;
+  if (!state.configured) {
+    const skipped = state.tiers.some((t) => t.skippedMarker);
+    findings.push({
+      id: "no-config",
+      severity: "fail",
+      message: skipped ? "No embedding configuration (the wizard was skipped earlier)." : "No embedding configuration.",
+      fix: "bb setup"
+    });
+  }
+  for (const t of state.tiers) {
+    const { missing, modeWrong } = tierIssues(t);
+    if (missing.length > 0) {
+      findings.push({
+        id: `incomplete-${t.tier}`,
+        severity: "fail",
+        message: `${t.tier} tier is incomplete: missing ${missing.join(" + ")}.`,
+        fix: "bb setup"
+      });
+    }
+    if (modeWrong) {
+      findings.push({
+        id: `mode-${t.tier}`,
+        severity: "warn",
+        message: `${t.tier} config file has mode ${t.fileMode?.toString(8)} \u2014 the key may be world-readable.`,
+        fix: "bb doctor --fix"
+      });
+    }
+  }
+  const winnerTier = state.tiers.find((t) => t.complete);
+  const winnerModel = winnerTier?.model;
+  const storedRead = opts.storedModels ? { models: opts.storedModels, unreadable: null } : opts.projectId ? readStoredModels(opts.projectId, dataDir) : { models: [], unreadable: null };
+  const storedModels = storedRead.models;
+  if (storedRead.unreadable) {
+    findings.push({
+      id: "index-unreadable",
+      severity: "warn",
+      message: `This project's index exists but doctor could not read its embedding table from this runtime (${storedRead.unreadable}). Stored vectors are UNKNOWN, not absent \u2014 the model-consistency checks below cannot run.`,
+      fix: "run the shipped binary (npx @backbencher/brain doctor) or check the database file permissions"
+    });
+  }
+  if (winnerModel && storedModels.length > 0) {
+    const matches = storedModels.filter((s) => s.model === winnerModel);
+    if (matches.length === 0) {
+      const storedDesc = storedModels.map((s) => `${s.model} (${s.count} rows)`).join(", ");
+      findings.push({
+        id: "model-mismatch",
+        severity: "fail",
+        message: `Model mismatch: config has ${winnerModel}, index has ${storedDesc}. Vectors from different models cannot be compared \u2014 the stored vectors are unusable.`,
+        fix: "bb index --force"
+      });
+    } else {
+      const foreign = storedModels.filter((s) => s.model !== winnerModel);
+      if (foreign.length > 0) {
+        const foreignDesc = foreign.map((s) => `${s.model} (${s.count} rows)`).join(", ");
+        findings.push({
+          id: "model-mixed",
+          severity: "warn",
+          message: `The index contains foreign-model vectors: ${foreignDesc}. They are never compared with ${winnerModel} queries.`,
+          fix: "bb index --force"
+        });
+      }
+    }
+  } else if (!winnerModel && storedModels.length > 0) {
+    const total = storedModels.reduce((sum, m) => sum + m.count, 0);
+    const storedDesc = storedModels.map((s) => `${s.model} (${s.count} rows)`).join(", ");
+    const mixed = storedModels.length > 1;
+    findings.push({
+      id: "stored-unconfigured",
+      severity: "info",
+      message: `The index holds ${total.toLocaleString()} vector(s) from ${storedDesc}, but no embedding provider is configured from this directory. Queries would use ${localLabel}, which is a DIFFERENT embedding space, so those vectors are not comparable to new queries.` + (mixed ? " The index also contains vectors from more than one model, so even a configured query compares only one of them." : ""),
+      fix: "bb setup (or run bb doctor from the directory whose config built this index)"
+    });
+  } else if (winnerModel && storedModels.length === 0) {
+    findings.push({
+      id: "no-index",
+      severity: "info",
+      message: `No stored vectors for this project (no index or empty). Config model: ${winnerModel}.`,
+      fix: "bb index ."
+    });
+  }
+  if (!winnerModel) {
+    findings.push({
+      id: "semantic-degraded",
+      severity: "warn",
+      message: `Semantic search will use ${localLabel} (weaker).`,
+      fix: "bb setup"
+    });
+  }
+  try {
+    const { buildEmbeddingDiagnosis } = embedding_diagnosis_exports;
+    const diagnosis = buildEmbeddingDiagnosis({ state, env: process.env });
+    for (const p of diagnosis.problems ?? []) {
+      findings.push({
+        id: p.envVar ? `embedding.${p.envVar.toLowerCase()}` : "embedding.config",
+        severity: p.severity === "error" ? "fail" : "warn",
+        message: p.message,
+        // Never echo a key value — `envVar` is a variable NAME, and the module
+        // guarantees `message` carries only presence/source, never the secret.
+        ...p.envVar ? { fix: `set ${p.envVar} (bb setup walks through it)` } : {}
+      });
+    }
+    if (diagnosis.tierOrderDisagreement) {
+      findings.push({
+        id: "embedding.tier-order-disagreement",
+        severity: "warn",
+        message: `embedding configuration layers disagree on precedence: reports ${diagnosis.tierOrderDisagreement.reported} but resolves ${diagnosis.tierOrderDisagreement.actual} \u2014 ${diagnosis.tierOrderDisagreement.detail}`,
+        fix: "run `bb setup show` to see which layer wins"
+      });
+    }
+    if (diagnosis.chain?.length) {
+      for (const layer of diagnosis.chain) {
+        embeddingChain.push({
+          order: layer.order,
+          role: layer.role,
+          label: layer.label,
+          endpoint: layer.endpoint,
+          model: layer.model,
+          keyState: layer.keyState,
+          source: layer.source,
+          active: layer.active
+        });
+      }
+    }
+    if (isEmbeddingDisabled(process.env)) {
+      findings.push({
+        id: "embedding.disabled",
+        severity: "warn",
+        message: "embeddings are DISABLED (BB_EMBEDDING_DISABLED) \u2014 semantic search will not run at all",
+        fix: "unset BB_EMBEDDING_DISABLED to enable semantic search"
+      });
+    }
+  } catch (e) {
+    findings.push({
+      id: "embedding.diagnosis-unavailable",
+      severity: "warn",
+      message: `embedding diagnosis could not run: ${e?.message ?? e}`,
+      fix: "run `bb setup show` to inspect the embedding configuration"
+    });
+  }
+  const poolReport = runPoolDoctor(opts.poolModuleDir ?? poolModuleDir(), opts.poolProbe);
+  findings.push(...poolReport.findings.filter((f) => f.severity !== "info"));
+  const healthy = !findings.some((f) => f.severity === "fail");
+  return {
+    findings,
+    healthy,
+    winner: state.winner,
+    storedModels,
+    pool: summarizePool(poolReport),
+    ...embeddingChain.length ? { embeddingChain } : {}
+  };
+}
+function summarizePool(report) {
+  const res = report.resolution;
+  const probe = report.probe;
+  const facts = [
+    `runtime: ${process.execPath} (${process.version})`,
+    res.ok ? `worker: ${res.source === "compiled-dist" ? "compiled dist/pool-worker.js" : `tsx + ${path.basename(res.workerArgs[0] ?? "?")}`}` : `worker: not resolvable (${res.reason})`
+  ];
+  if (res.ok) facts.push(`root: ${res.projectRoot}`);
+  if (!res.ok) {
+    return {
+      status: report.status === "disabled" ? "disabled" : "unavailable",
+      summary: report.status === "disabled" ? "Pool workers are switched off (BB_POOL_WORKER) \u2014 indexing runs in-process, so it is slower." : `Pool workers cannot start (${res.reason}): ${res.message}`,
+      reasonCode: res.reason,
+      remediation: res.remediation,
+      facts
+    };
+  }
+  if (!probe) {
+    return {
+      status: "unchecked",
+      summary: `Pool fork target resolved (${res.source}) but was not started.`,
+      facts
+    };
+  }
+  if (!probe.ok) {
+    const unverifiable = probe.reason === "worker-selftest-unsupported";
+    return {
+      status: unverifiable ? "unchecked" : "unavailable",
+      summary: unverifiable ? `Pool workers could not be verified (${probe.reason}) \u2014 the installed worker predates the self-test.` : `Pool workers do not start (${probe.reason}): ${probe.message}`,
+      reasonCode: probe.reason,
+      remediation: probe.remediation,
+      facts
+    };
+  }
+  const r = probe.report;
+  facts.push(`self-test: ${probe.ms}ms (pid ${r.pid}, node ${r.node})`);
+  if (r.engine === "ok" && r.wasm === "ok") {
+    return {
+      status: "ok",
+      summary: `Pool workers start normally (${res.source}); engine and grammars loaded in ${probe.ms}ms.`,
+      facts
+    };
+  }
+  const broken = [];
+  if (r.engine !== "ok") broken.push("the AST engine did not load, so files are parsed by regex (fewer symbols)");
+  if (r.wasm !== "ok") broken.push("the tree-sitter grammars did not load, so there is no grammar-based parsing");
+  return {
+    status: "degraded",
+    summary: `Pool workers start but are DEGRADED: ${broken.join("; ")}.`,
+    reasonCode: r.engine !== "ok" ? "pool-engine-unavailable" : "pool-wasm-unavailable",
+    cause: r.diagnostics.join(" | ") || void 0,
+    remediation: ["npm rebuild --build-from-source && rm -rf node_modules && npm install --include=dev"],
+    facts
+  };
+}
+function renderDoctorReport(r) {
+  const lines = [];
+  lines.push("bb doctor \u2014 diagnostics");
+  lines.push("");
+  if (r.findings.length === 0) {
+    lines.push("\u2713 No problems found \u2014 config and index look consistent.");
+  }
+  if (r.pool) {
+    const poolIcon = {
+      ok: "\u2713",
+      degraded: "!",
+      unavailable: "\u2717",
+      disabled: "\xB7",
+      unchecked: "?"
+    };
+    lines.push(`${poolIcon[r.pool.status]} pool workers: ${r.pool.summary}`);
+    if (r.pool.reasonCode) lines.push(`  reason: ${r.pool.reasonCode}`);
+    if (r.pool.cause) lines.push(`  cause: ${r.pool.cause}`);
+    for (const fact of r.pool.facts ?? []) lines.push(`  ${fact}`);
+    (r.pool.remediation ?? []).forEach((fix, i) => {
+      const [first, ...rest] = fix.split("\n");
+      lines.push(`  fix ${i + 1}: ${first.trim()}`);
+      for (const cont of rest) if (cont.trim()) lines.push(`         ${cont.trim()}`);
+    });
+    lines.push("");
+  }
+  if (r.embeddingChain?.length) {
+    lines.push("embedding layers, in the order bb resolves them:");
+    for (const layer of r.embeddingChain) {
+      const mark = layer.active ? "\u2192" : " ";
+      const key = layer.keyState === "present" ? "key present" : `key ${layer.keyState}`;
+      lines.push(`  ${mark} ${layer.order}. ${layer.label} \u2014 ${layer.model} @ ${layer.endpoint} (${key}, from ${layer.source})`);
+    }
+    lines.push("");
+  }
+  const iconFor = { fail: "\u2717", warn: "!", info: "\xB7" };
+  for (const f of r.findings) {
+    lines.push(`${iconFor[f.severity]} ${f.message}`);
+    if (f.fix) lines.push(`  Fix: ${f.fix}`);
+  }
+  return lines.join("\n") + "\n";
+}
+var MAX_FIX_ACTIONS = 8;
+function planDoctorFixes(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const env = opts.env ?? process.env;
+  const dataDir = opts.dataDir ?? bbDataDir();
+  const state = describeEmbeddingConfig(cwd, env, dataDir);
+  const actions = [];
+  const refusals = [];
+  for (const t of state.tiers) {
+    if (t.fileMode !== void 0 && t.fileMode !== 384 && t.file) {
+      if (actions.length >= MAX_FIX_ACTIONS) {
+        refusals.push({ id: `mode-${t.tier}`, reason: `repair cap exceeded (${MAX_FIX_ACTIONS}) \u2014 unexpected state, manual review required` });
+        continue;
+      }
+      actions.push({ id: `mode-${t.tier}`, file: t.file, fromMode: t.fileMode, toMode: 384 });
+    }
+  }
+  return { actions, refusals };
+}
+function renderFixPlan(plan, applied) {
+  const lines = [];
+  lines.push(applied ? "bb doctor --fix \u2014 applied" : "bb doctor --fix \u2014 dry run (nothing changed; pass --fix to apply)");
+  lines.push("");
+  if (plan.actions.length === 0 && plan.refusals.length === 0) {
+    lines.push("\u2713 No permission problems to fix.");
+  }
+  for (const a of plan.actions) {
+    lines.push(`${applied ? "\u2713" : "\xB7"} ${a.file}: mode ${a.fromMode?.toString(8)} -> ${a.toMode.toString(8)} ${applied ? "(applied)" : "(proposed)"}`);
+  }
+  for (const ref of plan.refusals) {
+    lines.push(`\u2717 REFUSED ${ref.id}: ${ref.reason}`);
+  }
+  return lines.join("\n") + "\n";
+}
+function applyDoctorFixes(opts) {
+  const plan = planDoctorFixes(opts);
+  const applied = opts.apply === true;
+  if (applied) {
+    for (const a of plan.actions) {
+      try {
+        const st = statSync(a.file);
+        if (!st.isFile()) throw new Error("not a regular file");
+        chmodSync(a.file, a.toMode);
+      } catch {
+        plan.refusals.push({ id: a.id, reason: "file changed between plan and apply \u2014 manual review required" });
+        plan.actions = plan.actions.filter((x) => x !== a);
+      }
+    }
+  }
+  return { plan, applied };
+}
+export {
+  applyDoctorFixes,
+  planDoctorFixes,
+  renderDoctorReport,
+  renderFixPlan,
+  resetPoolDoctorCache,
+  runDoctorChecks
+};

package/dist/edit-engine-KM7MPFEC.js

@@ -0,0 +1,51 @@
+import {
+  BATCH_ENTRY_MODES,
+  BATCH_WIDE_OPTIONS,
+  MAX_BATCH_EDITS,
+  WRITE_GUARD,
+  executeEdit,
+  expandBatchRequest,
+  fileHash,
+  findDeclarationName,
+  isBindingParentType,
+  isReferenceSite,
+  lineCount,
+  preImageMismatches,
+  resolveSafeEditPath,
+  writeGuardMessage
+} from "./chunk-CW4XXSNN.js";
+import "./chunk-PJTNGD3Z.js";
+import "./chunk-4H22TLOT.js";
+import "./chunk-GEFFO6O2.js";
+import "./chunk-VURYFIHW.js";
+import "./chunk-DYM4FQEE.js";
+import "./chunk-YI6FF2ZR.js";
+import "./chunk-QLK6ED4Q.js";
+import "./chunk-KLK3PBTO.js";
+import "./chunk-V44PGPA6.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-SK6YVHFZ.js";
+import "./chunk-2BSKD7O3.js";
+import "./chunk-KAET47ZL.js";
+import "./chunk-KCDECRJY.js";
+import "./chunk-D2Q4Y47A.js";
+import "./chunk-SM7RFQRO.js";
+import "./chunk-L5TDYKYK.js";
+import "./chunk-ROMM6KMC.js";
+import "./chunk-MLKGABMK.js";
+export {
+  BATCH_ENTRY_MODES,
+  BATCH_WIDE_OPTIONS,
+  MAX_BATCH_EDITS,
+  WRITE_GUARD,
+  executeEdit,
+  expandBatchRequest,
+  fileHash,
+  findDeclarationName,
+  isBindingParentType,
+  isReferenceSite,
+  lineCount,
+  preImageMismatches,
+  resolveSafeEditPath,
+  writeGuardMessage
+};

package/dist/engine-42TZFNIZ.js

@@ -0,0 +1,11 @@
+import {
+  SemanticEngine
+} from "./chunk-5SD45FLC.js";
+import "./chunk-7AN7U5IZ.js";
+import "./chunk-UGR4QIGS.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-2BSKD7O3.js";
+import "./chunk-MLKGABMK.js";
+export {
+  SemanticEngine
+};

package/dist/engine-LO6L4JLQ.js

@@ -0,0 +1,18 @@
+import {
+  ASTEngine,
+  getCachedParser,
+  getParser,
+  parseFile
+} from "./chunk-V44PGPA6.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-SK6YVHFZ.js";
+import "./chunk-2BSKD7O3.js";
+import "./chunk-KAET47ZL.js";
+import "./chunk-KCDECRJY.js";
+import "./chunk-MLKGABMK.js";
+export {
+  ASTEngine,
+  getCachedParser,
+  getParser,
+  parseFile
+};

package/dist/fingerprint-XDXFRWO6.js

@@ -0,0 +1,33 @@
+import {
+  computeCheckoutFingerprint,
+  computeDbFingerprint,
+  gitIdentity,
+  persistProjectFingerprint,
+  readStoredFingerprint,
+  relativePathFingerprint
+} from "./chunk-3LFTSMIV.js";
+import "./chunk-PJTNGD3Z.js";
+import "./chunk-4H22TLOT.js";
+import "./chunk-GEFFO6O2.js";
+import "./chunk-VURYFIHW.js";
+import "./chunk-DYM4FQEE.js";
+import "./chunk-KLK3PBTO.js";
+import "./chunk-V44PGPA6.js";
+import "./chunk-BQ3OVQ3P.js";
+import "./chunk-SK6YVHFZ.js";
+import "./chunk-2BSKD7O3.js";
+import "./chunk-KAET47ZL.js";
+import "./chunk-KCDECRJY.js";
+import "./chunk-D2Q4Y47A.js";
+import "./chunk-SM7RFQRO.js";
+import "./chunk-L5TDYKYK.js";
+import "./chunk-ROMM6KMC.js";
+import "./chunk-MLKGABMK.js";
+export {
+  computeCheckoutFingerprint,
+  computeDbFingerprint,
+  gitIdentity,
+  persistProjectFingerprint,
+  readStoredFingerprint,
+  relativePathFingerprint
+};