tina4-nodejs 3.11.18 → 3.11.32

package/packages/core/src/docsAutoDiscovery.ts

@@ -0,0 +1,73 @@
+/**
+ * Live Docs MCP discovery — writes `.tina4/mcp.json` so MCP-aware AI tools
+ * (Claude Code, Cursor, etc.) auto-discover this server's docs MCP endpoint.
+ *
+ * Idempotent — only writes if content has changed.
+ *
+ * Spec: plan/v3/22-LIVE-API-RAG.md (Auto-discovery section)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+interface McpDiscovery {
+  mcpServers: Record<string, { url: string; description: string }>;
+}
+
+const TINA4_DIR = ".tina4";
+const MCP_FILE = "mcp.json";
+const GITIGNORE_LINE = ".tina4/";
+
+/**
+ * Write `.tina4/mcp.json` and (if `.git/` exists) append `.tina4/` to .gitignore.
+ *
+ * Returns true if the discovery file was written or updated.
+ */
+export function writeMcpDiscovery(projectRoot: string, port: number): boolean {
+  const root = path.resolve(projectRoot);
+  const tinaDir = path.join(root, TINA4_DIR);
+  const mcpPath = path.join(tinaDir, MCP_FILE);
+
+  const portStr = String(
+    port || Number(process.env.TINA4_PORT) || Number(process.env.PORT) || 7148,
+  );
+
+  const desired: McpDiscovery = {
+    mcpServers: {
+      "tina4-live-docs": {
+        url: `http://localhost:${portStr}/__dev/api/mcp`,
+        description: "Live API docs for this Tina4 project (framework + user code)",
+      },
+    },
+  };
+
+  // Idempotent write — compare before overwriting.
+  let existing: string | null = null;
+  if (fs.existsSync(mcpPath)) {
+    try { existing = fs.readFileSync(mcpPath, "utf-8"); } catch { /* fall through */ }
+  }
+  const desiredJson = JSON.stringify(desired, null, 2) + "\n";
+  let wrote = false;
+  if (existing !== desiredJson) {
+    fs.mkdirSync(tinaDir, { recursive: true });
+    fs.writeFileSync(mcpPath, desiredJson, "utf-8");
+    wrote = true;
+  }
+
+  // Only append .gitignore entry inside a real git repo.
+  const gitDir = path.join(root, ".git");
+  if (fs.existsSync(gitDir)) {
+    const gitignorePath = path.join(root, ".gitignore");
+    let contents = "";
+    if (fs.existsSync(gitignorePath)) {
+      try { contents = fs.readFileSync(gitignorePath, "utf-8"); } catch { /* leave empty */ }
+    }
+    const lines = contents.split(/\r?\n/);
+    const already = lines.some((l) => l.trim() === GITIGNORE_LINE || l.trim() === ".tina4");
+    if (!already) {
+      const sep = contents.endsWith("\n") || contents === "" ? "" : "\n";
+      fs.writeFileSync(gitignorePath, `${contents}${sep}${GITIGNORE_LINE}\n`, "utf-8");
+    }
+  }
+
+  return wrote;
+}

package/packages/core/src/index.ts

@@ -116,3 +116,6 @@ export { Plan } from "./plan.js";
 export type { PlanStep, ParsedPlan, PlanSummary, ExecutionSummary, CurrentPlan } from "./plan.js";
 export { ProjectIndex } from "./projectIndex.js";
 export type { FileEntry, FileRoute } from "./projectIndex.js";
+export { Docs } from "./docs.js";
+export type { DocsHit, ClassSpec, MethodSpec, IndexEntry, DriftHit } from "./docs.js";
+export { writeMcpDiscovery } from "./docsAutoDiscovery.js";

package/packages/core/src/mcp.ts

@@ -1332,6 +1332,73 @@ export function registerDevTools(server: McpServer): void {
     "List this project's declared Node.js dependencies",
     schemaFromParams([]),
   );
+
+  // ── Live API RAG (Docs) — plan/v3/22-LIVE-API-RAG.md ──────────
+
+  server.registerTool(
+    "api_search",
+    (args) => {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { Docs } = require("./docs.js") as typeof import("./docs.js");
+        return Docs.mcpSearch(
+          (args.query as string) || "",
+          parseInt(String(args.k ?? 5), 10) || 5,
+          undefined,
+          (args.source as string) || "all",
+          Boolean(args.include_private),
+        );
+      } catch (e) {
+        return { error: (e as Error).message };
+      }
+    },
+    "Search the live API index (framework + user code) for matching classes/methods",
+    schemaFromParams([
+      { name: "query", type: "string" },
+      { name: "k", type: "integer", default: 5 },
+      { name: "source", type: "string", default: "all" },
+      { name: "include_private", type: "boolean", default: false },
+    ]),
+  );
+
+  server.registerTool(
+    "api_class",
+    (args) => {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { Docs } = require("./docs.js") as typeof import("./docs.js");
+        const spec = Docs.mcpClass((args.name as string) || "");
+        return spec ?? { error: `class not found: ${args.name}` };
+      } catch (e) {
+        return { error: (e as Error).message };
+      }
+    },
+    "Return the full class spec (methods + properties) for a single class FQN",
+    schemaFromParams([{ name: "name", type: "string" }]),
+  );
+
+  server.registerTool(
+    "api_method",
+    (args) => {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { Docs } = require("./docs.js") as typeof import("./docs.js");
+        // PHP names the param `class`, Python names it `class_` — Node.js MCP
+        // accepts the raw `class` field from the JSON-RPC payload.
+        const cls = (args.class as string) || (args.class_name as string) || "";
+        const name = (args.name as string) || "";
+        const spec = Docs.mcpMethod(cls, name);
+        return spec ?? { error: `method not found: ${cls}.${name}` };
+      } catch (e) {
+        return { error: (e as Error).message };
+      }
+    },
+    "Return the full spec for a single method (signature, file, line, visibility)",
+    schemaFromParams([
+      { name: "class", type: "string" },
+      { name: "name", type: "string" },
+    ]),
+  );
 }
 
 /** Alias for registerDevTools — parity with PHP/Ruby/Python. */

package/packages/core/src/server.ts

@@ -715,6 +715,13 @@ ${reset}
   if (DevAdmin.isEnabled()) {
     DevAdmin.register(router);
     console.log(`  Dev dashboard at  \x1b[36mhttp://localhost:${port}/__dev\x1b[0m`);
+    // Live Docs MCP discovery — write .tina4/mcp.json so AI tools find this server.
+    try {
+      const { writeMcpDiscovery } = await import("./docsAutoDiscovery.js");
+      writeMcpDiscovery(process.cwd(), Number(port));
+    } catch (e) {
+      console.log(`  (mcp discovery skipped: ${(e as Error).message})`);
+    }
   }
 
   async function dispatch(rawReq: IncomingMessage, rawRes: ServerResponse): Promise<void> {

package/packages/orm/src/database.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { DatabaseAdapter, DatabaseResult as DatabaseWriteResult } from "./types.js";
 import { DatabaseResult } from "./databaseResult.js";
 
@@ -256,6 +257,23 @@ export class Database {
   /** Database engine type (sqlite, postgres, mysql, mssql, firebird) */
   private dbType: string = "sqlite";
 
+  /**
+   * Async-local storage for the adapter pinned to the current transaction.
+   *
+   * With pooling enabled, ordinary calls round-robin through the pool. Inside
+   * a transaction, however, all calls must land on the SAME adapter — otherwise
+   * startTransaction(), execute() and commit() each rotate to a different
+   * connection and the transaction is meaningless (executes autocommit on
+   * whatever adapter they hit; the final commit lands on yet another adapter
+   * that has nothing to commit; rollback() is silently no-op'd).
+   *
+   * AsyncLocalStorage is the Node analog of Python's threading.local. It pins
+   * the adapter to the current async task tree so concurrent transactions on
+   * the same Database don't clobber each other. startTransaction() sets the
+   * pin via .enterWith(); commit()/rollback() clear it.
+   */
+  private txStore: AsyncLocalStorage<{ adapter: DatabaseAdapter | null }> = new AsyncLocalStorage();
+
   /**
    * Create a Database wrapping an existing adapter.
    * For creating a Database from a URL, use the async static factories:
@@ -320,8 +338,15 @@ export class Database {
 
   /**
    * Get the next adapter — from pool (round-robin) or single connection.
+   *
+   * If a transaction is active (an adapter is pinned in async-local storage),
+   * that adapter is returned for every call so the whole transaction is
+   * atomic on one connection. Otherwise pooled mode round-robins.
    */
   private getNextAdapter(): DatabaseAdapter {
+    const pinned = this.txStore.getStore()?.adapter;
+    if (pinned) return pinned;
+
     if (this._poolSize > 0) {
       const idx = this.poolIndex;
       this.poolIndex = (this.poolIndex + 1) % this._poolSize;
@@ -457,19 +482,37 @@ export class Database {
     }
   }
 
-  /** Start a transaction. */
+  /**
+   * Start a transaction. Pins the adapter to the current async context for
+   * the whole transaction so executes and the final commit/rollback all run
+   * on the same connection (critical when pool > 0).
+   */
   startTransaction(): void {
-    this.getNextAdapter().startTransaction();
+    // Pick an adapter using the normal selection logic, then pin it.
+    const adapter = this.getNextAdapter();
+    let store = this.txStore.getStore();
+    if (store) {
+      store.adapter = adapter;
+    } else {
+      this.txStore.enterWith({ adapter });
+    }
+    adapter.startTransaction();
   }
 
-  /** Commit the current transaction. */
+  /** Commit the current transaction and release the adapter pin. */
   commit(): void {
-    this.getNextAdapter().commit();
+    const adapter = this.getNextAdapter();
+    adapter.commit();
+    const store = this.txStore.getStore();
+    if (store) store.adapter = null;
   }
 
-  /** Rollback the current transaction. */
+  /** Rollback the current transaction and release the adapter pin. */
   rollback(): void {
-    this.getNextAdapter().rollback();
+    const adapter = this.getNextAdapter();
+    adapter.rollback();
+    const store = this.txStore.getStore();
+    if (store) store.adapter = null;
   }
 
   /** Check if a table exists. */