tina4-nodejs 3.13.61 → 3.13.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.61",
+  "version": "3.13.63",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [

package/packages/core/src/context/chunker.ts

@@ -0,0 +1,161 @@
+// Tina4 Node.js
+//
+// Text folding + chunking for the Context subsystem.
+//
+// A thin, idiomatic TypeScript port of tina4-python's context/chunker.py
+// (itself the proven slice of neemee's tokenizer/chunkers). Zero dependencies —
+// nothing here touches SQLite; it produces the (folded body, raw text) pairs the
+// FTS5 index stores.
+
+// join comma-grouped numbers ("24,601" -> "24601") and split camelCase
+// ("ForeignKeyField" -> "foreign key field") so a query token reaches a
+// code identifier. snake_case already splits for free at the tokenizer.
+const NUM_COMMA = /(?<=\d),(?=\d)/g;
+const CAMEL = /(?<=[a-z0-9])(?=[A-Z])/g;
+const WORD_RE = /[a-z0-9]+/g;
+
+// Sentence boundary = end punctuation FOLLOWED BY whitespace/EOL, or a newline.
+// NOT a bare '.', which would shred embedded code in prose ("db.fetch()" ->
+// "db. fetch()"). Intra-token dots (method calls, module paths) stay intact.
+const SENT = /(?<=[.!?])\s+|\n+/;
+
+// Chunk boundaries across languages: python defs/classes/decorators, php/js
+// functions and methods, ts exports/interfaces, php traits, and Object Pascal
+// unit/type/routine headers (Delphi is case-insensitive, accept either case).
+// Anchored at line start; tested per line (parity with python's re.match).
+const TOPLEVEL =
+  /^(async def |def |class |@\w|\s*(?:public |private |protected |static |final |abstract )*function \w|(?:export )?(?:default )?(?:abstract )?class |interface |trait |export (?:const|function|interface|type|async) |[Uu]nit |[Pp]rocedure |[Ff]unction |[Cc]onstructor |[Dd]estructor |[Tt]ype$)/;
+
+/**
+ * Lowercase, strip diacritics, join comma-grouped numbers, split camelCase.
+ *
+ * Applied symmetrically to the indexed `body` and to query tokens so matching
+ * is consistent: a query for `field` reaches `IntegerField`. The trailing
+ * NFKD-normalise + strip-non-ASCII mirrors python's
+ * `unicodedata.normalize("NFKD", ...).encode("ascii", "ignore")`.
+ */
+export function fold(text: string): string {
+  const split = text.replace(NUM_COMMA, "").replace(CAMEL, " ").toLowerCase();
+  // eslint-disable-next-line no-control-regex
+  return split.normalize("NFKD").replace(/[^\x00-\x7f]/g, "");
+}
+
+/**
+ * Fold simple plurals: strip one trailing 's', never from ss/us/is endings
+ * (class, status, axis). QUERY-side only — so `fields` in a question also
+ * reaches `Field` definitions.
+ */
+export function lightStem(token: string): string {
+  if (token.length > 3 && token.endsWith("s") && !/(?:ss|us|is)$/.test(token)) {
+    return token.slice(0, -1);
+  }
+  return token;
+}
+
+/** Accent-folded lowercase alphanumeric tokens (digits kept). */
+export function terms(text: string): string[] {
+  return fold(text).match(WORD_RE) ?? [];
+}
+
+/**
+ * Split into lines the way python's `str.splitlines()` does: on any line
+ * terminator, WITHOUT a trailing empty element for a final newline. A plain
+ * `text.split("\n")` would append a spurious "" for "a\n" — this drops it so
+ * chunk boundaries and line counts match the reference.
+ */
+function splitLines(text: string): string[] {
+  const lines = text.split(/\r\n|\r|\n/);
+  if (lines.length > 0 && lines[lines.length - 1] === "" && /[\r\n]$/.test(text)) {
+    lines.pop();
+  }
+  return lines;
+}
+
+/**
+ * Pack line-segments into chunks of at most `maxLines` lines, hard-splitting
+ * any single oversized segment.
+ */
+function pack(segments: string[][], maxLines: number): string[][] {
+  const chunks: string[][] = [];
+  let cur: string[] = [];
+  for (let seg of segments) {
+    while (seg.length > maxLines) {
+      if (cur.length) {
+        chunks.push(cur);
+        cur = [];
+      }
+      chunks.push(seg.slice(0, maxLines));
+      seg = seg.slice(maxLines);
+    }
+    if (cur.length && cur.length + seg.length > maxLines) {
+      chunks.push(cur);
+      cur = [];
+    }
+    cur = cur.concat(seg);
+  }
+  if (cur.length) {
+    chunks.push(cur);
+  }
+  return chunks;
+}
+
+/**
+ * Chunk source on top-level def/class/decorator boundaries (sentence chunking
+ * shreds code). Segments are packed up to `maxLines`, and every chunk starts
+ * with a `# file: <path>` line so the path's tokens are indexed — 'where is the
+ * router?' should match core/router.ts by name.
+ *
+ * Returns a list of `[index, chunkText]` pairs.
+ */
+export function chunkCode(text: string, path = "", maxLines = 60): Array<[number, string]> {
+  const lines = splitLines(text);
+  let bounds: number[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (TOPLEVEL.test(lines[i])) bounds.push(i);
+  }
+  if (bounds.length === 0 || bounds[0] !== 0) {
+    bounds = [0, ...bounds];
+  }
+  const ends = [...bounds.slice(1), lines.length];
+  const segments: string[][] = [];
+  for (let k = 0; k < bounds.length; k++) {
+    segments.push(lines.slice(bounds[k], ends[k]));
+  }
+
+  const header = path ? `# file: ${path}` : null;
+  const packed = pack(segments, maxLines);
+  const out: Array<[number, string]> = [];
+  for (let i = 0; i < packed.length; i++) {
+    const body = (header ? [header, ...packed[i]] : packed[i]).join("\n");
+    out.push([i, body]);
+  }
+  return out;
+}
+
+/**
+ * Chunk prose/docs into sentence-packed windows of at most `maxWords` words.
+ * Returns a list of `[index, chunkText]` pairs.
+ */
+export function chunkText(text: string, maxWords = 350): Array<[number, string]> {
+  const sents = text
+    .split(SENT)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  const chunks: string[] = [];
+  let cur: string[] = [];
+  let curWords = 0;
+  for (const s of sents) {
+    const w = s.split(/\s+/).filter(Boolean).length;
+    if (cur.length && curWords + w > maxWords) {
+      chunks.push(cur.join(" "));
+      cur = [];
+      curWords = 0;
+    }
+    cur.push(s);
+    curWords += w;
+  }
+  if (cur.length) {
+    chunks.push(cur.join(" "));
+  }
+  return chunks.map((c, i): [number, string] => [i, c]);
+}

package/packages/core/src/context/index.ts

@@ -0,0 +1,424 @@
+// Tina4 Node.js
+//
+// Context — a native, zero-dependency code/doc grounding index.
+//
+// Lets a Tina4 app ground its own AI assistant on its own source, offline:
+// it walks the project, chunks code on def/class boundaries and docs as prose,
+// and answers keyword/fuzzy queries over a SQLite FTS5 index (Node's built-in
+// `node:sqlite` — FTS5 + `bm25()` are compiled in, so NO new dependency; the
+// same module the ORM/session/docstore subsystems already use).
+//
+//   import { Context } from "@tina4/core";
+//   const ctx = new Context(".tina4/context.db");
+//   ctx.indexRoot("src");
+//   ctx.search("where is the auth token issued?", 5);
+//   //  -> [{ path: "src/auth.ts", score: 2.31, snippet: "..." }, ...]
+//
+// A faithful TypeScript port of tina4-python's tina4_python/context/__init__.py
+// (the proven slice of neemee's SqliteFTS + source-over-tests / definition-first
+// reordering). It COMPLEMENTS the api_* reflection tools: api_* is exact
+// structural lookup, Context is fuzzy/semantic FTS over source + docs.
+//
+// On-disk index defaults to `.tina4/context.db` (gitignored). Guards a sqlite
+// build without FTS5: if absent, the Context degrades to safe no-ops rather than
+// crashing the app.
+//
+// node:sqlite is synchronous and JavaScript is single-threaded, so — unlike the
+// Python port — no lock is needed: every method runs to completion before the
+// event loop can dispatch another.
+
+import { DatabaseSync } from "node:sqlite";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+
+import { chunkCode, chunkText, fold, lightStem, terms } from "./chunker.js";
+
+// File classification — mirrors neemee's repo walk.
+const CODE_EXTS = new Set([
+  ".py", ".php", ".js", ".mjs", ".ts", ".rb",
+  ".pas", ".dpr", ".dpk", ".inc", ".dfm", ".fmx",
+]);
+const DOC_EXTS = new Set([".md", ".txt", ".rst", ".twig", ".html"]);
+// deploy/CLI/env answers live in config files, not sources — chunk as code
+// (line windows), since sentence chunking shreds YAML/Dockerfiles.
+const CONFIG_EXTS = new Set([".toml", ".yml", ".yaml"]);
+const SPECIAL_FILES = new Set([
+  "dockerfile", "makefile", "docker-compose.yml",
+  "package.json", "composer.json",
+  ".env.example", ".env.sample",
+]);
+// Same dirs neemee skips, plus Tina4 runtime dirs that hold no source of truth
+// (our own index/backups, session blobs, logs).
+const SKIP_DIRS = new Set([
+  ".git", "__pycache__", "node_modules", "vendor", "dist",
+  "build", "coverage", ".idea", ".venv", "venv", ".pytest_cache",
+  ".tina4", "sessions", "logs",
+]);
+
+// generic question/code vocabulary that never NAMES a symbol — kept small.
+const DEF_STOP = new Set(
+  ("the and what how does can which where when who why list all available " +
+    "module class function functions method methods def get set new return " +
+    "import from with that this are is was for into use used").split(" "),
+);
+
+// a chunk that DEFINES a queried symbol ('def get_token', 'class Widget') should
+// out-rank one that merely USES it. Matched against the folded body.
+const DEF_KW = "(?:async def|def|class|function|fn|func|interface|trait)";
+
+/** True if this build of node:sqlite supports FTS5. */
+export function fts5Supported(): boolean {
+  try {
+    const conn = new DatabaseSync(":memory:");
+    try {
+      conn.exec("CREATE VIRTUAL TABLE _probe USING fts5(x)");
+      return true;
+    } finally {
+      conn.close();
+    }
+  } catch {
+    return false;
+  }
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Resolve `abs` to its canonical (symlink-free) form, matching Python's
+ * `Path.resolve()`. If the file itself doesn't exist yet (a delete event), fall
+ * back to canonicalising the parent directory and re-joining the basename, then
+ * to the lexical path. Needed because macOS temp dirs (and /var) are symlinks,
+ * so a raw `process.cwd()` (already real) and a lexically-resolved index root
+ * would otherwise mismatch and drop every reindex as "outside root".
+ */
+function realResolve(abs: string): string {
+  try {
+    return realpathSync(abs);
+  } catch {
+    /* not created (deleted file) — fall through */
+  }
+  try {
+    return join(realpathSync(dirname(abs)), basename(abs));
+  } catch {
+    return abs;
+  }
+}
+
+export interface SearchHit {
+  path: string;
+  score: number;
+  snippet: string;
+}
+
+interface ChunkRow {
+  path: string;
+  raw: string;
+  body: string;
+  s: number;
+}
+
+/**
+ * A SQLite FTS5 index over a project's source + docs.
+ *
+ * - indexPath(file, label?)  upsert one file (delete-by-path, re-chunk, insert)
+ * - indexRoot(root)          walk a tree, index every eligible file
+ * - search(query, k)         [{path, score, snippet}] ranked by bm25() with
+ *                            source-over-tests + definition-first reordering
+ * - reindexFile(changed)     upsert one changed file against the indexed root
+ */
+export class Context {
+  path: string;
+  root: string | null = null;
+  available: boolean;
+  private conn: DatabaseSync | null = null;
+
+  /**
+   * @param dbPath    on-disk index file (its parent dir is created).
+   * @param fts5Check overrides FTS5 detection (used by tests to exercise the
+   *                  graceful-degradation path); defaults to a real probe.
+   */
+  constructor(dbPath = "./.tina4/context.db", fts5Check?: () => boolean) {
+    this.path = String(dbPath);
+    const check = fts5Check ?? fts5Supported;
+    this.available = Boolean(check());
+    if (!this.available) return;
+    const parent = dirname(this.path);
+    if (parent !== "" && parent !== ".") {
+      mkdirSync(parent, { recursive: true });
+    }
+    this.conn = new DatabaseSync(this.path);
+    this.ensureTable();
+  }
+
+  /** Whether this Node build's node:sqlite supports FTS5. */
+  static fts5Available(): boolean {
+    return fts5Supported();
+  }
+
+  private ensureTable(): void {
+    // `body` holds fold(text) so query/index tokenization is symmetric; `raw`
+    // (UNINDEXED) keeps the original text to return as a snippet; `path`/`cid`
+    // (UNINDEXED) are metadata used for upsert + citation.
+    this.conn!.exec(
+      "CREATE VIRTUAL TABLE IF NOT EXISTS chunks " +
+        "USING fts5(cid UNINDEXED, path UNINDEXED, raw UNINDEXED, body)",
+    );
+  }
+
+  /** Drop and recreate the index (full rebuild starting point). */
+  reset(): void {
+    if (!this.available) return;
+    this.conn!.exec("DROP TABLE IF EXISTS chunks");
+    this.ensureTable();
+  }
+
+  // ── indexing ───────────────────────────────────────────────
+  private static chunksFor(label: string, text: string): Array<[number, string]> {
+    const ext = extname(label).toLowerCase();
+    const special = SPECIAL_FILES.has(basename(label).toLowerCase());
+    if (CODE_EXTS.has(ext) || CONFIG_EXTS.has(ext) || special) {
+      return chunkCode(text, label);
+    }
+    return chunkText(text);
+  }
+
+  /**
+   * UPSERT one file into the index: delete this path's existing chunks,
+   * re-chunk the current contents, insert. `label` is the stored/citation path
+   * (defaults to `file`) and MUST be stable across calls for the same file so
+   * the delete targets the right rows. Returns rows inserted.
+   */
+  indexPath(file: string, label?: string): number {
+    if (!this.available) return 0;
+    const stored = label != null ? String(label) : String(file);
+    let text: string;
+    try {
+      text = readFileSync(file, "utf-8");
+    } catch {
+      return 0;
+    }
+    const rows = Context.chunksFor(stored, text).map(
+      ([i, chunk]): [string, string, string, string] => [`${stored}:${i}`, stored, chunk, fold(chunk)],
+    );
+    this.conn!.prepare("DELETE FROM chunks WHERE path = ?").run(stored);
+    if (rows.length) {
+      const ins = this.conn!.prepare("INSERT INTO chunks(cid, path, raw, body) VALUES (?, ?, ?, ?)");
+      for (const r of rows) ins.run(r[0], r[1], r[2], r[3]);
+    }
+    return rows.length;
+  }
+
+  /**
+   * The per-file filter used by both indexRoot and reindexFile. Directory
+   * skipping is handled separately.
+   */
+  private static eligible(filename: string): boolean {
+    const fn = filename.toLowerCase();
+    if (fn.endsWith(".min.js")) return false;
+    const ext = extname(fn);
+    return CODE_EXTS.has(ext) || DOC_EXTS.has(ext) || CONFIG_EXTS.has(ext) || SPECIAL_FILES.has(fn);
+  }
+
+  /**
+   * Walk `root`, indexing every eligible file (skips vendor/build/runtime
+   * dirs). Paths are stored RELATIVE to `root` for clean citations. Records
+   * `root` so reindexFile can relabel a changed file consistently. Returns the
+   * total number of chunks inserted.
+   */
+  indexRoot(root: string): number {
+    if (!this.available) return 0;
+    const rootAbs = realResolve(resolve(String(root)));
+    this.root = rootAbs;
+    let total = 0;
+    const walk = (dir: string): void => {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      const files: string[] = [];
+      const subdirs: string[] = [];
+      for (const e of entries) {
+        if (e.isDirectory()) {
+          if (!SKIP_DIRS.has(e.name) && !e.name.startsWith(".")) subdirs.push(e.name);
+        } else if (e.isFile()) {
+          files.push(e.name);
+        }
+      }
+      files.sort();
+      for (const fn of files) {
+        if (!Context.eligible(fn)) continue;
+        const full = join(dir, fn);
+        const rel = relative(rootAbs, full);
+        total += this.indexPath(full, rel);
+      }
+      for (const d of subdirs) walk(join(dir, d));
+    };
+    walk(rootAbs);
+    return total;
+  }
+
+  /**
+   * Re-index a single changed file into the LIVE index — the hook the dev
+   * WebSocket reload trigger (POST /__dev/api/reload) calls so code_search
+   * tracks edits without a rebuild. Resolves `changedPath` against the indexed
+   * root, then: outside root / under a skip-or-dot dir / ineligible → skip (-1);
+   * deleted → drop its chunks (0); otherwise UPSERT (rows). No-op (-1) until
+   * indexRoot has run (nothing to keep fresh yet).
+   */
+  reindexFile(changedPath: string): number {
+    if (!this.available || this.root === null) return -1;
+    const raw = String(changedPath);
+    // the reload trigger reports paths relative to the project root (cwd during
+    // `tina4 serve`); the index root may be a subdir like src/.
+    const abs = isAbsolute(raw) ? raw : join(process.cwd(), raw);
+    const resolved = realResolve(resolve(abs));
+    const rel = relative(this.root, resolved);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+      return -1; // outside the indexed root
+    }
+    const parts = rel.split(/[\\/]/);
+    const dirParts = parts.slice(0, -1);
+    if (parts.some((seg) => SKIP_DIRS.has(seg)) || dirParts.some((seg) => seg.startsWith("."))) {
+      return -1; // under a skipped / dot dir
+    }
+    if (!Context.eligible(basename(rel))) return -1;
+    const stored = rel;
+    if (!existsSync(abs)) {
+      // deleted → drop its chunks
+      this.conn!.prepare("DELETE FROM chunks WHERE path = ?").run(stored);
+      return 0;
+    }
+    return this.indexPath(abs, stored);
+  }
+
+  // ── query ──────────────────────────────────────────────────
+  private matchExpr(query: string): { expr: string | null; toks: Set<string> } {
+    const toks = new Set<string>();
+    for (const t of terms(query)) {
+      toks.add(t);
+      toks.add(lightStem(t));
+    }
+    toks.delete("");
+    if (toks.size === 0) return { expr: null, toks };
+    // Quoting keeps each term injection-safe inside the FTS5 MATCH string.
+    const expr = [...toks].sort().map((t) => `"${t}"`).join(" OR ");
+    return { expr, toks };
+  }
+
+  private static isTestlike(path: string): boolean {
+    const s = (path || "").toLowerCase();
+    return ["/test", "test/", "test_", "_test.", ".test.", "/example", "example/"].some((p) => s.includes(p));
+  }
+
+  private static defines(foldedBody: string, symbols: Set<string>): boolean {
+    if (symbols.size === 0) return false;
+    const alt = [...symbols].map(escapeRegex).join("|");
+    const pat = new RegExp(`${DEF_KW}\\s+(?:${alt})(?![a-z0-9])`);
+    return pat.test(foldedBody);
+  }
+
+  /**
+   * Return the top-`k` chunks as `[{path, score, snippet}]`, ranked by `bm25()`
+   * then reordered with two stable, proven passes:
+   *   - source-over-tests: a test that merely mentions a symbol sinks below the
+   *     source that defines it (skipped when the query is about tests);
+   *   - definition-first: a chunk that DEFINES a queried symbol rises above
+   *     chunks that only use it.
+   * Score is a higher-is-better float (sqlite's bm25 sign flipped).
+   */
+  search(query: string, k = 5): SearchHit[] {
+    if (!this.available) return [];
+    const { expr } = this.matchExpr(query);
+    if (expr === null) return [];
+    const poolN = Math.max(k * 3, 15);
+    const rows = this.conn!
+      .prepare("SELECT path, raw, body, bm25(chunks) AS s FROM chunks WHERE chunks MATCH ? ORDER BY s LIMIT ?")
+      .all(expr, poolN) as unknown as ChunkRow[];
+    if (rows.length === 0) return [];
+
+    // candidate symbol names from the query (drop generic vocab).
+    const symbols = new Set(terms(query).filter((t) => t.length >= 3 && !DEF_STOP.has(t)));
+    const aboutTests = query.toLowerCase().includes("test");
+
+    const isTest = (p: string): number => (!aboutTests && Context.isTestlike(p) ? 1 : 0);
+    const isDef = (b: string): number => (Context.defines(b, symbols) ? 0 : 1);
+
+    const ordered = rows
+      .map((r, i) => ({ r, i }))
+      .sort((a, b) => {
+        const at = isTest(a.r.path);
+        const bt = isTest(b.r.path);
+        if (at !== bt) return at - bt;
+        const ad = isDef(a.r.body);
+        const bd = isDef(b.r.body);
+        if (ad !== bd) return ad - bd;
+        return a.i - b.i; // bm25 order breaks ties
+      });
+
+    return ordered.slice(0, k).map(({ r }) => ({
+      path: r.path,
+      score: Math.round(-Number(r.s) * 1e6) / 1e6, // bm25: more negative = better
+      snippet: Context.snippet(r.raw),
+    }));
+  }
+
+  private static snippet(raw: string, limit = 280): string {
+    const text = (raw || "").trim();
+    if (text.length <= limit) return text;
+    return text.slice(0, limit).replace(/\s+$/, "") + " ...";
+  }
+
+  // ── misc ───────────────────────────────────────────────────
+  count(): number {
+    if (!this.available) return 0;
+    const row = this.conn!.prepare("SELECT count(*) AS c FROM chunks").get() as { c: number };
+    return row.c;
+  }
+
+  isEmpty(): boolean {
+    return this.count() === 0;
+  }
+
+  close(): void {
+    if (this.conn !== null) {
+      this.conn.close();
+      this.conn = null;
+    }
+  }
+}
+
+// ── process-wide shared index ──────────────────────────────────
+// code_search (dev MCP) and the dev-reload reindex hook must share ONE index so
+// a saved file is immediately searchable. Keyed by resolved db path.
+export const _sharedContexts = new Map<string, Context>();
+
+function dbKey(db?: string): string {
+  return resolve(db ? String(db) : join(process.cwd(), ".tina4", "context.db"));
+}
+
+/**
+ * Get (or create) the process-wide Context at `db` (default
+ * `<cwd>/.tina4/context.db`). If `root` is given and the index is empty, builds
+ * it once. This is what code_search uses so the reload hook can keep the SAME
+ * index fresh.
+ */
+export function defaultContext(root?: string, db?: string): Context {
+  const key = dbKey(db);
+  let ctx = _sharedContexts.get(key);
+  if (ctx === undefined) {
+    ctx = new Context(key);
+    _sharedContexts.set(key, ctx);
+  }
+  if (root != null && ctx.available && ctx.isEmpty()) {
+    ctx.indexRoot(root);
+  }
+  return ctx;
+}
+
+/**
+ * Return the already-created shared Context for `db` (or undefined). Used by the
+ * reload hook so a file change reindexes an EXISTING index but never creates one
+ * on its own (nothing to keep fresh until code_search runs).
+ */
+export function existingContext(db?: string): Context | undefined {
+  return _sharedContexts.get(dbKey(db));
+}

package/packages/core/src/devAdmin.ts

@@ -703,6 +703,21 @@ const handleReload: RouteHandler = async (req, res) => {
     console.error(`  Re-discover on reload failed:`, err);
   }
 
+  // Keep the code Context index LIVE on the same reload trigger: reindex just
+  // the changed file (UPSERT) so the dev-MCP code_search reflects the edit
+  // immediately. existingContext() only touches an already-built index (it never
+  // creates one — nothing to keep fresh until code_search has run), and the
+  // whole block is guarded so a context failure never breaks the reload.
+  try {
+    if (_reloadFile) {
+      const { existingContext } = await import("./context/index.js");
+      const ctx = existingContext();
+      if (ctx) ctx.reindexFile(_reloadFile);
+    }
+  } catch (err) {
+    console.error(`  Context reindex on reload failed:`, err);
+  }
+
   // WebSocket-primary reload: push an instant message to every browser
   // connected on /__dev_reload. The toolbar client (and the dev-admin
   // dashboard) act on this immediately — the mtime poll is only a fallback for

package/packages/core/src/index.ts

@@ -75,6 +75,8 @@ export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete,
 export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
 export { Api } from "./api.js";
 export type { ApiResult } from "./api.js";
+export { Context, defaultContext, existingContext, fts5Supported, _sharedContexts } from "./context/index.js";
+export type { SearchHit } from "./context/index.js";
 export { Events } from "./events.js";
 export { DevAdmin, MessageLog, RequestInspector, ErrorTracker, DevMailboxStore, DevQueue, WsTracker, supervisorBaseUrl, devAdminLanguage } from "./devAdmin.js";
 export {

package/packages/core/src/mcp.ts

@@ -1056,7 +1056,8 @@ function verifyNodeSyntax(absPath: string, relPath: string): string | null {
 let _lastCacheStats: Record<string, unknown> | null = null;
 
 /**
- * Register all 24 built-in dev tools on the given McpServer.
+ * Register all built-in dev tools on the given McpServer (the api_* reflection
+ * tools plus code_search, the fuzzy FTS grounding tool).
  */
 export function registerDevTools(server: McpServer): void {
   const projectRoot = path.resolve(process.cwd());
@@ -2070,6 +2071,48 @@ export function registerDevTools(server: McpServer): void {
       { name: "name", type: "string" },
     ]),
   );
+
+  // ── Code/doc grounding (context subsystem) ──────────────────
+  // Sibling of api_* but the DUAL of it: api_* is exact structural reflection
+  // (class/method signatures); code_search is fuzzy/semantic FTS over the
+  // project's own SOURCE + docs. Use code_search for "where/how is X done in
+  // THIS codebase?" and api_* for "what's the signature of X?". Backed by a
+  // zero-dependency node:sqlite FTS5 index at .tina4/context.db, held as a
+  // PROCESS-WIDE shared Context (context.defaultContext) so the dev-reload hook
+  // (handleReload) can keep the SAME index fresh on every file save.
+  server.registerTool(
+    "code_search",
+    (args) => {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { defaultContext } = req("./context/index.js") as typeof import("./context/index.js");
+        // Index src/ when present (falls back to the project root), mirroring
+        // the Python master's _code_root().
+        const srcDir = path.join(projectRoot, "src");
+        const root = fs.existsSync(srcDir) && fs.statSync(srcDir).isDirectory() ? srcDir : projectRoot;
+        const ctx = defaultContext(root, path.join(projectRoot, ".tina4", "context.db"));
+        if (!ctx.available) {
+          return { error: "SQLite FTS5 is not available in this Node build; code_search is disabled." };
+        }
+        if (args.rebuild) {
+          ctx.reset();
+          ctx.indexRoot(root);
+        }
+        const k = parseInt(String(args.k ?? 5), 10) || 5;
+        return ctx.search((args.query as string) || "", k);
+      } catch (e) {
+        return { error: (e as Error).message };
+      }
+    },
+    "Fuzzy/semantic search over THIS project's own source + docs (node:sqlite FTS5, zero-dep). " +
+      "Ranks definitions above tests that merely mention a symbol. Use for 'where is X done here?'; " +
+      "use api_* for exact signatures. Returns [{path, score, snippet}].",
+    schemaFromParams([
+      { name: "query", type: "string" },
+      { name: "k", type: "integer", default: 5 },
+      { name: "rebuild", type: "boolean", default: false },
+    ]),
+  );
 }
 
 /** Alias for registerDevTools — parity with PHP/Ruby/Python. */

package/packages/orm/src/autoCrud.ts

@@ -14,28 +14,47 @@ import { validate } from "./validation.js";
  *   PUT    /api/{table}/{id}   — update record
  *   DELETE /api/{table}/{id}   — delete record
  */
+/**
+ * Options accepted by the AutoCrud registration API.
+ *
+ * `public` is the cross-backend escape hatch (parity with python's `public=True`
+ * and php's `bool $public`). Write routes (POST/PUT/DELETE) are secure-by-default
+ * — the router gates them unless a def sets `secure: false`. Set `public: true`
+ * to open the generated write routes explicitly. Reads (GET) are always public.
+ */
+export interface AutoCrudOptions {
+  /** When true, the generated write routes (POST/PUT/DELETE) are OPEN (secure:false). Default false → secure. */
+  public?: boolean;
+}
+
 export class AutoCrud {
   private static registered: Map<string, DiscoveredModel> = new Map();
+  /** tableName -> public-writes flag (default secure); mirrors php's `$this->public`. */
+  private static publicWrites: Map<string, boolean> = new Map();
 
   /**
    * Register a model for auto-CRUD.
+   *
+   * @param options.public If true, the generated write routes are OPEN (no auth).
+   *   Default (false) keeps them secure-by-default, matching the framework's write gate.
    */
-  static register(model: DiscoveredModel, prefix: string = "/api"): void {
+  static register(model: DiscoveredModel, prefix: string = "/api", options: AutoCrudOptions = {}): void {
     const tableName = model.definition.tableName;
     if (!tableName) {
       throw new Error(`AutoCrud: model has no tableName set.`);
     }
     AutoCrud.registered.set(tableName, model);
+    AutoCrud.publicWrites.set(tableName, options.public === true);
   }
 
   /**
    * Discover models from the provided array and register them.
    * (In Node.js, models are discovered by the server and passed in.)
    */
-  static discover(discoveredModels: DiscoveredModel[], prefix: string = "/api"): string[] {
+  static discover(discoveredModels: DiscoveredModel[], prefix: string = "/api", options: AutoCrudOptions = {}): string[] {
     const names: string[] = [];
     for (const model of discoveredModels) {
-      AutoCrud.register(model, prefix);
+      AutoCrud.register(model, prefix, options);
       names.push(model.definition.tableName);
     }
     return names;
@@ -53,14 +72,20 @@ export class AutoCrud {
    */
   static clear(): void {
     AutoCrud.registered.clear();
+    AutoCrud.publicWrites.clear();
   }
 
   /**
-   * Generate route definitions for all registered models.
+   * Generate route definitions for all registered models, honouring each
+   * model's per-table `public` flag (set at register/discover time).
    */
   static generateRoutes(): RouteDefinition[] {
-    const models = Array.from(AutoCrud.registered.values());
-    return generateCrudRoutes(models);
+    const routes: RouteDefinition[] = [];
+    for (const [tableName, model] of AutoCrud.registered) {
+      const isPublic = AutoCrud.publicWrites.get(tableName) === true;
+      routes.push(...generateCrudRoutes([model], { public: isPublic }));
+    }
+    return routes;
   }
 }
 
@@ -80,9 +105,18 @@ export function crudEligibleModels(models: DiscoveredModel[]): DiscoveredModel[]
 /**
  * Generate CRUD route definitions for the given models.
  * (Standalone function for backward compatibility.)
+ *
+ * @param options.public When true, the generated write routes (POST/PUT/DELETE)
+ *   opt OUT of the router's secure-by-default write gate (`secure: false`) — the
+ *   cross-backend escape hatch (parity with python `public=True` / php `$public`).
+ *   Default (false) leaves `secure` unset so the router gates writes (secure:true).
+ *   GET routes are unaffected (reads are already public).
  */
-export function generateCrudRoutes(models: DiscoveredModel[]): RouteDefinition[] {
+export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudOptions = {}): RouteDefinition[] {
   const routes: RouteDefinition[] = [];
+  // Only writes are gated; `public` flips them open. Spread this into POST/PUT/
+  // DELETE defs so the default path leaves `secure` unset (router → secure:true).
+  const writeSecurity = options.public === true ? { secure: false as const } : {};
 
   for (const { definition } of models) {
     const { tableName, fields, softDelete, tableFilter, fieldMapping } = definition;
@@ -167,10 +201,11 @@ export function generateCrudRoutes(models: DiscoveredModel[]): RouteDefinition[]
       },
     });
 
-    // POST /api/{table} -- Create
+    // POST /api/{table} -- Create (secure-by-default; secure:false only when public)
     routes.push({
       method: "POST",
       pattern: basePath,
+      ...writeSecurity,
       meta: {
         summary: `Create ${tableName}`,
         tags: [tableName],
@@ -228,10 +263,11 @@ export function generateCrudRoutes(models: DiscoveredModel[]): RouteDefinition[]
       },
     });
 
-    // PUT /api/{table}/:id -- Update
+    // PUT /api/{table}/:id -- Update (secure-by-default; secure:false only when public)
     routes.push({
       method: "PUT",
       pattern: `${basePath}/{id}`,
+      ...writeSecurity,
       meta: {
         summary: `Update ${tableName}`,
         tags: [tableName],
@@ -275,10 +311,11 @@ export function generateCrudRoutes(models: DiscoveredModel[]): RouteDefinition[]
       },
     });
 
-    // DELETE /api/{table}/:id -- Delete (soft or hard)
+    // DELETE /api/{table}/:id -- Delete (secure-by-default; secure:false only when public)
     routes.push({
       method: "DELETE",
       pattern: `${basePath}/{id}`,
+      ...writeSecurity,
       meta: {
         summary: `Delete ${tableName}`,
         tags: [tableName],

package/packages/orm/src/index.ts

@@ -47,6 +47,7 @@ export {
 } from "./migration.js";
 export type { MigrationResult, MigrationStatus } from "./migration.js";
 export { AutoCrud, generateCrudRoutes, crudEligibleModels } from "./autoCrud.js";
+export type { AutoCrudOptions } from "./autoCrud.js";
 export { buildQuery, parseQueryString } from "./query.js";
 export { validate } from "./validation.js";
 export type { ValidationError } from "./validation.js";