tina4-nodejs 3.10.50 → 3.10.60

package/CLAUDE.md

@@ -4,7 +4,7 @@
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.10.42 — a convention-over-configuration structural paradigm. **Not a framework.** The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.10.42 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/README.md

@@ -2,7 +2,7 @@
   <img src="https://tina4.com/logo.svg" alt="Tina4" width="200">
 </p>
 <h1 align="center">Tina4 Node.js</h1>
-<h3 align="center">This Is Now A 4Framework</h3>
+<h3 align="center">The Intelligent Native Application 4ramework</h3>
 <p align="center">54 built-in features. Zero dependencies. One import, everything works.</p>
 <p align="center">
   <a href="https://www.npmjs.com/package/tina4-nodejs"><img src="https://img.shields.io/npm/v/tina4-nodejs?color=7b1fa2&label=npm" alt="npm"></a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.50",
+  "version": "3.10.60",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",
   "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],

package/packages/cli/src/bin.ts

@@ -14,7 +14,7 @@ const args = process.argv.slice(2);
 const command = args[0];
 
 const HELP = `
-  tina4nodejs — This is not a framework.
+  tina4nodejs — The Intelligent Native Application 4ramework
 
   Usage:
     tina4nodejs init [dir]            Create a new Tina4 project (default: current directory)
@@ -26,6 +26,7 @@ const HELP = `
     tina4nodejs routes                List all registered routes
     tina4nodejs test [file]           Run project tests
     tina4nodejs seed [file]           Run database seed files from src/seeds/
+    tina4nodejs console               Open an interactive REPL with the framework loaded
     tina4nodejs ai                    Install AI coding assistant context files
     tina4nodejs help                  Show this help message
 
@@ -46,6 +47,7 @@ const HELP = `
   Options:
     --port <number>      Server port (default: 7148)
     --no-browser         Don't open the browser on serve
+    --no-reload          Disable file watcher / live-reload on serve
     --all                Install AI context for all tools (with ai command)
     --force              Overwrite existing AI context files (with ai command)
     --help               Show this help message
@@ -85,11 +87,12 @@ async function main(): Promise<void> {
       const portIndex = args.indexOf("--port");
       const port = portIndex !== -1 ? parseInt(args[portIndex + 1], 10) : 7148;
       const noBrowser = args.includes("--no-browser");
+      const noReload = args.includes("--no-reload");
 
       // Kill any existing process on the port
       killProcessOnPort(port);
 
-      await serveProject({ port, noBrowser });
+      await serveProject({ port, noBrowser, noReload });
       break;
     }
     case "migrate": {
@@ -128,6 +131,40 @@ async function main(): Promise<void> {
       await runSeeds(args[1]);
       break;
     }
+    case "console": {
+      const repl = await import("node:repl");
+      const { loadEnv } = await import("@tina4/core");
+      const { Router } = await import("@tina4/core");
+      const { initDatabase, Database } = await import("@tina4/orm");
+      const { Log } = await import("@tina4/core");
+
+      loadEnv();
+
+      const dbUrl = process.env.DATABASE_URL;
+      let db: unknown = null;
+      if (dbUrl) {
+        try {
+          db = await initDatabase({ url: dbUrl });
+        } catch {
+          console.warn("  Warning: could not connect to database — db will be null");
+        }
+      }
+
+      console.log("\n  Tina4 Node.js Console");
+      console.log("  Type JavaScript. Framework is loaded.");
+      console.log("  Available: db, Router, Database, Log");
+      console.log("  Exit: Ctrl+D or .exit\n");
+
+      const r = repl.start({ prompt: "tina4> " });
+
+      r.context.Router = Router;
+      r.context.Database = Database;
+      r.context.Log = Log;
+      r.context.db = db;
+
+      await new Promise<void>((resolve) => r.on("exit", resolve));
+      break;
+    }
     case "ai": {
       const { showMenu, installSelected, installAll } = await import("../../core/src/ai.js");
       const root = args[1] || ".";

package/packages/cli/src/commands/init.ts

@@ -196,7 +196,7 @@ export default async function (req: Tina4Request, res: Tina4Response): Promise<v
 </head>
 <body>
   <h1>Welcome to {{ name }}</h1>
-  <p>This is not a framework.</p>
+  <p>The Intelligent Native Application 4ramework</p>
 </body>
 </html>
 `
@@ -219,7 +219,7 @@ export default async function (req: Tina4Request, res: Tina4Response): Promise<v
 </head>
 <body>
   <h1>tina4</h1>
-  <p><em>This is not a framework.</em></p>
+  <p><em>The Intelligent Native Application 4ramework</em></p>
   <p>Your API is running. Try:</p>
   <ul>
     <li><a href="/api/hello">GET /api/hello</a></li>

package/packages/cli/src/commands/serve.ts

@@ -4,9 +4,14 @@ import { existsSync } from "node:fs";
 export interface ServeOptions {
   port?: number;
   noBrowser?: boolean;
+  noReload?: boolean;
 }
 
 export async function serveProject(options: ServeOptions): Promise<void> {
+  if (options.noReload) {
+    process.env.TINA4_NO_RELOAD = "true";
+  }
+
   const port = options.port ?? 7148;
   const cwd = process.cwd();
 
@@ -33,26 +38,30 @@ export async function serveProject(options: ServeOptions): Promise<void> {
   });
 
   // Watch for file changes and reload routes
+  const noReload = ["true", "1", "yes"].includes((process.env.TINA4_NO_RELOAD ?? "").toLowerCase());
   const watchDirs = [routesDir, ormDir, modelsDir, templatesDir].filter((d) => existsSync(d));
-  const watcher = watchForChanges(watchDirs, async () => {
-    try {
-      const { discoverRoutes } = await import("../../../core/src/index.js");
-      // Clear routes BEFORE re-discovery to avoid stale duplicates
-      server.router.clear();
-      const routes = await discoverRoutes(routesDir);
-      for (const route of routes) {
-        server.router.addRoute(route);
+  let watcher: { close: () => void } | null = null;
+  if (!noReload) {
+    watcher = watchForChanges(watchDirs, async () => {
+      try {
+        const { discoverRoutes } = await import("../../../core/src/index.js");
+        // Clear routes BEFORE re-discovery to avoid stale duplicates
+        server.router.clear();
+        const routes = await discoverRoutes(routesDir);
+        for (const route of routes) {
+          server.router.addRoute(route);
+        }
+        console.log(`  Reloaded ${routes.length} route(s)`);
+      } catch (err) {
+        console.error("  Error reloading routes:", err);
       }
-      console.log(`  Reloaded ${routes.length} route(s)`);
-    } catch (err) {
-      console.error("  Error reloading routes:", err);
-    }
-  });
+    });
+  }
 
   // Graceful shutdown
   const shutdown = () => {
     console.log("\n  Shutting down...");
-    watcher.close();
+    watcher?.close();
     server.close();
     process.exit(0);
   };

package/packages/core/src/devAdmin.ts

@@ -21,7 +21,21 @@ import { quickMetrics, fullAnalysis, fileDetail } from "./metrics.js";
 
 const cpuCount = osCpus().length;
 
-const TINA4_VERSION = "3.10.34";
+// Read version from root package.json dynamically
+const TINA4_VERSION = (() => {
+  try {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    // Try root package.json first, then core package.json
+    for (const rel of ["../../../package.json", "../../package.json"]) {
+      const p = resolve(__dirname, rel);
+      if (existsSync(p)) {
+        const pkg = JSON.parse(readFileSync(p, "utf-8"));
+        if (pkg.version) return pkg.version;
+      }
+    }
+  } catch {}
+  return "0.0.0";
+})();
 
 // ---------------------------------------------------------------------------
 // Types
@@ -2467,7 +2481,7 @@ function renderBubbleChart(files,depGraph,scanMode){
         bubbles.forEach(function(b,i){if(b.f.path===src)srcIdx=i;});
         if(srcIdx===null)return;
         (depGraph[src]||[]).forEach(function(tgt){
-            var tgtName=tgt.split('.').pop().toLowerCase();
+            var tgtName=basename(tgt);
             var tgtIdx=nameIdx[tgtName];
             if(tgtIdx!==undefined&&srcIdx!==tgtIdx)edges.push([srcIdx,tgtIdx]);
         });

package/packages/core/src/metrics.ts

@@ -60,8 +60,10 @@ function hasMatchingTest(relPath: string): boolean {
   const name = relPath.split('/').pop()?.replace('.ts', '').replace('.js', '') || '';
   const patterns = [
     `test/${name}.test.ts`,
+    `test/${name}.test.js`,
     `${relPath.replace('.ts', '.test.ts').replace('.js', '.test.js')}`,
     `tests/${name}.test.ts`,
+    `spec/${name}.spec.ts`,
   ];
   return patterns.some(p => fs.existsSync(p));
 }

package/packages/core/src/server.ts

@@ -46,23 +46,62 @@ const TINA4_VERSION = readPackageVersion();
 const frondCache = new Map<string, InstanceType<any>>();
 
 /**
- * Test-bind each port in a subprocess to find one that is available.
- * Falls back to `start` if none of the candidates work.
+ * Kill whatever process is listening on *port*.
+ * Uses lsof on macOS/Linux and netstat + taskkill on Windows.
+ * Throws if the port cannot be freed.
  */
-function findAvailablePort(start: number, maxTries = 10): number {
-  // execFileSync imported at top of file (ESM)
-  for (let offset = 0; offset < maxTries; offset++) {
-    const port = start + offset;
-    try {
-      execFileSync(process.execPath, ["-e", `
-        const s = require("net").createServer();
-        s.listen(${port}, "127.0.0.1", () => { s.close(); process.exit(0); });
-        s.on("error", () => process.exit(1));
-      `], { timeout: 1000 });
-      return port;
-    } catch { continue; }
+function killPort(port: number): void {
+  // execFileSync is imported at the top of the file
+  console.log(`  Port ${port} in use — killing existing process...`);
+  try {
+    if (process.platform === "win32") {
+      const out = execFileSync("netstat", ["-ano"], { encoding: "utf-8", timeout: 5000 });
+      for (const line of out.split("\n")) {
+        if (line.includes(`:${port}`) && (line.includes("LISTENING") || line.includes("ESTABLISHED"))) {
+          const parts = line.trim().split(/\s+/);
+          const pid = parts[parts.length - 1];
+          if (/^\d+$/.test(pid)) {
+            execFileSync("taskkill", ["/PID", pid, "/F"], { timeout: 5000 });
+            break;
+          }
+        }
+      }
+    } else {
+      const pids = execFileSync("lsof", ["-ti", `:${port}`], { encoding: "utf-8", timeout: 5000 })
+        .trim()
+        .split("\n")
+        .filter(Boolean);
+      for (const pid of pids) {
+        if (/^\d+$/.test(pid.trim())) {
+          process.kill(parseInt(pid.trim(), 10), "SIGTERM");
+        }
+      }
+    }
+    // Brief pause for the OS to reclaim the port
+    execFileSync(process.execPath, ["-e", "setTimeout(() => {}, 500)"], { timeout: 2000 });
+    console.log(`  Port ${port} freed`);
+  } catch (err) {
+    throw new Error(`Could not free port ${port}: ${err}`);
+  }
+}
+
+/**
+ * Check if *port* is available; if not, kill the process on it and return *port*.
+ * The auto-increment behaviour is intentionally removed — the server always
+ * claims the requested port.
+ */
+function findAvailablePort(start: number): number {
+  try {
+    execFileSync(process.execPath, ["-e", `
+      const s = require("net").createServer();
+      s.listen(${start}, "0.0.0.0", () => { s.close(); process.exit(0); });
+      s.on("error", () => process.exit(1));
+    `], { timeout: 1000 });
+    return start;
+  } catch {
+    killPort(start);
+    return start;
   }
-  return start;
 }
 
 /**
@@ -322,7 +361,7 @@ h1{font-size:3rem;font-weight:700;margin-bottom:0.25rem;letter-spacing:-1px}
 <div class="hero">
     <img src="/images/tina4-logo-icon.webp" class="logo" alt="Tina4">
     <h1>Tina4NodeJs</h1>
-    <p class="tagline">This is not a framework</p>
+    <p class="tagline">The Intelligent Native Application 4ramework</p>
     <div class="actions">
         <a href="https://tina4.com/nodejs" class="btn" target="_blank">Website</a>
         <a href="/__dev" class="btn">Dev Admin</a>
@@ -422,12 +461,8 @@ export async function startServer(config?: Tina4Config): Promise<{
   const host = resolved.host;
   let port = resolved.port;
 
-  // Auto-increment port if the requested one is already in use
-  const availablePort = findAvailablePort(port);
-  if (availablePort !== port) {
-    console.log(`  Port ${port} in use, using ${availablePort} instead`);
-    port = availablePort;
-  }
+  // Claim the requested port — kill whatever is on it if needed
+  port = findAvailablePort(port);
 
   // Cluster mode for production: fork workers based on CPU count
   // Only when --production is explicitly set (via TINA4_PRODUCTION env var)
@@ -448,7 +483,7 @@ export async function startServer(config?: Tina4Config): Promise<{
  / /  / / / / / /_/ /__  __/
 /_/  /_/_/ /_/\\__,_/  /_/
 ${reset}
-  Tina4 Node.js v${TINA4_VERSION} — This is not a framework
+  Tina4 Node.js v${TINA4_VERSION} — The Intelligent Native Application 4ramework
 
   Server:    http://${displayHost}:${port} (cluster, ${numCPUs} workers)
   Swagger:   http://localhost:${port}/swagger
@@ -673,7 +708,17 @@ ${reset}
       const requestId = Date.now().toString(36);
 
       // Wrap res.raw.end to inject dev toolbar and capture requests
-      if (isDevMode() && !pathname.startsWith("/__dev")) {
+      // Skip toolbar injection on the AI port (no-reload behaviour)
+      const isAiPortRequest = !!(rawReq as any)._tina4AiPort;
+
+      // AI port: block /__dev_reload so AI tools never trigger a browser reload
+      if (isAiPortRequest && pathname === "/__dev_reload") {
+        res.raw.writeHead(404, { "Content-Type": "application/json" });
+        res.raw.end(JSON.stringify({ error: "Not available on AI port" }));
+        return;
+      }
+
+      if (isDevMode() && !pathname.startsWith("/__dev") && !isAiPortRequest) {
         const originalEnd = res.raw.end.bind(res.raw);
 
         const wrappedEnd: typeof res.raw.end = function (
@@ -857,7 +902,17 @@ ${reset}
   // Assign to module-level so handle() can dispatch without a server reference
   _dispatchFn = dispatch;
 
-  const server = createServer(dispatch);
+  // When dual-port is active (debug mode + no TINA4_NO_AI_PORT), tag main port requests
+  // as AI port to suppress reload/toolbar injection. Test port (port+1000) gets full reload.
+  const _dualPortActive = isTruthy(process.env.TINA4_DEBUG ?? "") &&
+    !isTruthy(process.env.TINA4_NO_AI_PORT ?? "");
+  const mainPortDispatch = _dualPortActive
+    ? async (req: IncomingMessage, res: ServerResponse) => {
+        (req as any)._tina4AiPort = true;
+        await dispatch(req, res);
+      }
+    : dispatch;
+  const server = createServer(mainPortDispatch);
 
   return new Promise((resolvePromise) => {
     server.listen(port, host, () => {
@@ -873,7 +928,34 @@ ${reset}
       // Determine server mode label
       const serverMode = isDebug ? "single" : (cluster.isWorker ? "cluster-worker" : "single");
 
+      // AI dual-port: main port = AI dev port (no reload), port+1000 = user testing port (hot-reload)
+      // When TINA4_DEBUG=true and TINA4_NO_AI_PORT is not set, main server suppresses reload/toolbar
+      // and a second server on port+1000 provides the normal hot-reload experience.
+      const noAiPort = isTruthy(process.env.TINA4_NO_AI_PORT ?? "");
+      let aiServer: ReturnType<typeof createServer> | null = null;
+      let testPort = port + 1000;
+
+      if (isDebug && !noAiPort) {
+        // Test port (port+1000): normal dispatch with full hot-reload
+        aiServer = createServer(async (req, res) => {
+          await dispatch(req, res);
+        });
+
+        aiServer.on("error", (err: any) => {
+          if (err.code === "EADDRINUSE") {
+            Log.warn(`Test port ${testPort} in use — skipping`);
+            aiServer = null;
+          }
+        });
+
+        aiServer.listen(testPort, host);
+      }
+
       // Banner goes to stdout via console.log — NOT through the framework logger
+      const dualPortLines = (isDebug && !noAiPort)
+        ? `\n  Test Port: http://localhost:${testPort} (stable — no hot-reload)`
+        : "";
+
       console.log(`${color}
   ______ _             __ __
  /_  __/(_)___  ____ _/ // /
@@ -881,19 +963,24 @@ ${reset}
  / /  / / / / / /_/ /__  __/
 /_/  /_/_/ /_/\\__,_/  /_/
 ${reset}
-  Tina4 Node.js v${TINA4_VERSION} — This is not a framework
+  Tina4 Node.js v${TINA4_VERSION} — The Intelligent Native Application 4ramework
 
   Server:    http://${displayHost}:${port} (${serverMode})
   Swagger:   http://localhost:${port}/swagger
   Dashboard: http://localhost:${port}/__dev
-  Debug:     ${isDebug ? "ON" : "OFF"} (Log level: ${logLevel})
+  Debug:     ${isDebug ? "ON" : "OFF"} (Log level: ${logLevel})${dualPortLines}
 `);
       const noBrowser = isTruthy(process.env.TINA4_NO_BROWSER);
       if (!noBrowser) {
-        openBrowser(`http://${displayHost}:${port}`);
+        // Open browser on test port (hot-reload) if available, otherwise main port
+        const browserTarget = (isDebug && !noAiPort && aiServer)
+          ? `http://${displayHost}:${testPort}`
+          : `http://${displayHost}:${port}`;
+        openBrowser(browserTarget);
       }
       resolvePromise({
         close: () => {
+          if (aiServer) aiServer.close();
           server.close();
           // Close database if ORM was initialized
           import("../../orm/src/index.js").then((orm) => orm.closeDatabase()).catch(() => {});