tina4-nodejs 3.11.17 → 3.11.19

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

@@ -13,6 +13,7 @@ export type {
 } from "./types.js";
 
 export { startServer, resolvePortAndHost, handle, start, stop } from "./server.js";
+export { background, stopAllBackgroundTasks, backgroundTaskCount } from "./background.js";
 export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares } from "./router.js";
 export { get, post, put, patch, del, any, websocket, del as delete } from "./router.js";
 export type { RouteInfo } from "./router.js";
@@ -115,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

@@ -20,6 +20,7 @@ import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
 import { DevAdmin, RequestInspector } from "./devAdmin.js";
 import { I18n } from "./i18n.js";
+import { stopAllBackgroundTasks } from "./background.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -549,6 +550,7 @@ ${reset}
       // Return a handle that kills all workers
       return {
         close: () => {
+          stopAllBackgroundTasks();
           for (const id in cluster.workers) {
             cluster.workers[id]?.kill();
           }
@@ -713,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> {
@@ -1075,6 +1084,8 @@ ${reset}
       }
       resolvePromise({
         close: () => {
+          // Clear any registered background timers so graceful shutdown actually exits.
+          stopAllBackgroundTasks();
           if (aiServer) aiServer.close();
           server.close();
           // Close database if ORM was initialized