tina4-nodejs 3.13.137 → 3.13.138

package/packages/core/public/licenses/tina4-js-MIT.txt

@@ -0,0 +1,20 @@
+MIT License
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/core/src/__feedback/widget.js

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 (function(){"use strict";(()=>{try{const t=window.location.pathname||"";return t.startsWith("/__dev")||t.startsWith("/__feedback")}catch{return!1}})()?console.info("tina4-feedback-widget: skipping on developer path"):window.__tina4FeedbackLoaded?console.warn("tina4-feedback-widget already loaded; skipping"):(window.__tina4FeedbackLoaded=!0,b());function b(){const c=(getComputedStyle(document.documentElement).getPropertyValue("--primary")||"").trim()||"#3b82f6";h(c);const l=m();document.body.appendChild(l);let e=null,u;const r=[];l.addEventListener("click",()=>{if(e){e.remove(),e=null,l.style.display="";return}e=g(),document.body.appendChild(e),l.style.display="none",setTimeout(()=>e?.querySelector("textarea")?.focus(),0)});function g(){const o=document.createElement("div");o.className="tina4-fb-modal",o.innerHTML=`
       <div class="tina4-fb-head">
         <span class="tina4-fb-title">Tell us what's not working</span>

package/packages/core/src/_missing.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Last-resort finder for `@tina4/core/<subpath>` under Node's ESM resolver.
  *

package/packages/core/src/ai.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 AI — Install AI coding assistant context files.
  *

package/packages/core/src/aiClient.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /** Zero-dependency app-facing AI client (ADR-0053 + ADR-0060). */
 import http, { type IncomingMessage } from "node:http";
 import https from "node:https";

package/packages/core/src/api.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 API Client — HTTP client using Node.js built-in modules only.
  *
@@ -667,7 +675,7 @@ export class Api {
             url += (url.includes("?") ? "&" : "?") + qs;
         }
 
-        const { headers, data } = this.buildRequest("GET", "application/json", undefined);
+        const { headers, data } = this.buildRequest("GET", "application/json", undefined, undefined, url);
 
         // An injected transport can't stream (it returns a buffered result), so
         // write its body out; only the real network path streams chunk-by-chunk.
@@ -760,7 +768,7 @@ export class Api {
         const url = this.buildUrl(path);
         const method = (opts.method ?? "GET").toUpperCase();
         const contentType = opts.contentType ?? "application/json";
-        const { headers, data } = this.buildRequest(method, contentType, opts.body, opts.headers);
+        const { headers, data } = this.buildRequest(method, contentType, opts.body, opts.headers, url);
         const totalSec = this.streamSeconds(opts.timeout, "TINA4_API_TIMEOUT", this.timeout);
         const connectSec = this.streamSeconds(opts.connectTimeout, "TINA4_API_CONNECT_TIMEOUT", 10);
         const opened = await this.openStreamRequest(method, url, headers, data, connectSec);
@@ -904,6 +912,7 @@ export class Api {
         contentType: string,
         body: unknown,
         extraHeaders?: Record<string, string>,
+        targetUrl?: string,
     ): { headers: Record<string, string>; data: Buffer | undefined } {
         const headers: Record<string, string> = { "User-Agent": `Tina4/${TINA4_VERSION}`, ...this.headers };
         if (this.authHeader) {
@@ -943,6 +952,9 @@ export class Api {
             Object.assign(headers, extraHeaders);
         }
 
+        if (targetUrl !== undefined && !sameOrigin(targetUrl, this.baseUrl)) {
+            for (const name of STRIP_ON_CROSS_ORIGIN) deleteHeaderCaseInsensitive(headers, name);
+        }
         return { headers, data };
     }
 
@@ -985,7 +997,7 @@ export class Api {
         contentType: string = "application/json",
         extraHeaders?: Record<string, string>,
     ): Promise<ApiResult> {
-        const { headers, data } = this.buildRequest(method, contentType, body, extraHeaders);
+        const { headers, data } = this.buildRequest(method, contentType, body, extraHeaders, url);
 
         // A user-injected transport fully replaces the network call.
         if (this.transportFn) {

package/packages/core/src/auth.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 Auth — Zero-dependency JWT, password hashing, and auth middleware.
  *
@@ -12,7 +20,7 @@
  *   checkPassword("secret123", hash);  // true
  */
 import { createHmac, createSign, createVerify, pbkdf2Sync, randomBytes, timingSafeEqual } from "node:crypto";
-import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, openSync, closeSync, fstatSync, fchmodSync, constants } from "node:fs";
 import { join } from "node:path";
 import type { Middleware, Tina4Request, Tina4Response } from "./types.js";
 import { isTruthy } from "./dotenv.js";
@@ -107,14 +115,19 @@ export function ensureDevSecret(cwd?: string): string | null {
   const baseDir = cwd ?? process.cwd();
   const envLocalPath = join(baseDir, ".env.local");
   try {
-    // If the file exists and its content doesn't end in a newline, prepend one
-    // so the new key lands on its own line.
-    let prefix = "";
-    if (existsSync(envLocalPath)) {
-      const existing = readFileSync(envLocalPath, "utf-8");
-      if (existing.length > 0 && !existing.endsWith("\n")) prefix = "\n";
+    // Read and append through one descriptor so replacing a pathname cannot
+    // redirect either operation to an unrelated file.
+    const fd = openSync(envLocalPath, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0), 0o600);
+    try {
+      const info = fstatSync(fd);
+      if (!info.isFile() || info.nlink !== 1) throw new Error("Refusing a non-regular or multiply-linked configuration file");
+      fchmodSync(fd, 0o600);
+      const existing = readFileSync(fd, "utf-8");
+      const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+      appendFileSync(fd, `${prefix}TINA4_SECRET=${newSecret}\n`);
+    } finally {
+      closeSync(fd);
     }
-    appendFileSync(envLocalPath, `${prefix}TINA4_SECRET=${newSecret}\n`);
     void _logInfo("Auth: generated a development secret, saved to .env.local (gitignored)");
   } catch {
     // Keep the in-memory secret for this run; warn but never crash boot.

package/packages/core/src/authGate.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Secure-by-default route auth gate — shared by the live server dispatch and the
  * in-process TestClient so the test surface enforces the IDENTICAL gate as

package/packages/core/src/background.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Background tasks — periodic callbacks that run alongside the HTTP server.
  *

package/packages/core/src/cache.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Multi-backend response cache for GET requests.
  *
@@ -56,6 +64,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
 import * as net from "node:net";
+import { optionalPackageMissing } from "./optionalPackage.js";
 
 // ── Credential parsing (WHATWG URL or TINA4_CACHE_USERNAME / _PASSWORD) ──
 
@@ -181,6 +190,12 @@ interface CacheBackend {
   /** One-time async connect/probe. Resolves once the backend has decided
    *  availability; createBackend() awaits this before falling back to file. */
   ready?(): Promise<void>;
+  /**
+   * When unavailable because the app has not installed the backend's driver
+   * (an optional peer, ADR-0067): the actionable install message, appended to
+   * the fallback warning. null for every other cause.
+   */
+  missingDriver?(): string | null;
 }
 
 // ── Memory backend ────────────────────────────────────────────────
@@ -1141,6 +1156,7 @@ class MongoBackend implements CacheBackend {
   private misses = 0;
   private maxEntries: number;
   private available = false;
+  private missingDriverMessage: string | null = null;
   private readyPromise: Promise<void>;
   // The mongodb driver types aren't depended on at compile time (optional dep).
   private client: any = null;
@@ -1178,8 +1194,15 @@ class MongoBackend implements CacheBackend {
     try {
       // Dynamic import so @tina4/core has no hard dependency on `mongodb` and an
       // absent driver degrades to file-fallback (never an import-time crash).
-      const mod: any = await import("mongodb").catch(() => null);
-      if (!mod || !mod.MongoClient) { this.available = false; return; }
+      let importError: any = null;
+      const mod: any = await import("mongodb").catch((error) => { importError = error; return null; });
+      if (!mod || !mod.MongoClient) {
+        this.available = false;
+        if (importError?.code === "ERR_MODULE_NOT_FOUND") {
+          this.missingDriverMessage = optionalPackageMissing("the mongodb cache backend", ["mongodb"]).message;
+        }
+        return;
+      }
       const client = new mod.MongoClient(this.url, { serverSelectionTimeoutMS: 4000 });
       await client.connect();
       await client.db(this.dbName).command({ ping: 1 });
@@ -1200,6 +1223,10 @@ class MongoBackend implements CacheBackend {
     return this.readyPromise;
   }
 
+  missingDriver(): string | null {
+    return this.missingDriverMessage;
+  }
+
   async isAvailable(): Promise<boolean> {
     await this.readyPromise;
     return this.available;
@@ -1291,6 +1318,7 @@ class DatabaseBackend implements CacheBackend {
   private misses = 0;
   private maxEntries: number;
   private available = false;
+  private missingDriverMessage: string | null = null;
   private readyPromise: Promise<void>;
   // @tina4/orm Database instance (optional dep, loaded dynamically).
   private db: any = null;
@@ -1324,8 +1352,13 @@ class DatabaseBackend implements CacheBackend {
       try { db.commit(); } catch { /* sqlite autocommits DDL */ }
       this.db = db;
       this.available = true;
-    } catch {
+    } catch (error) {
       this.available = false;
+      // The ORM adapters already phrase a missing driver as the install
+      // command; carry THAT through, and nothing else (a connect error can
+      // name the host and user).
+      const message = error instanceof Error ? error.message : String(error);
+      if (/npm install \S/.test(message)) this.missingDriverMessage = message;
     } finally {
       if (prevAuto === undefined) delete process.env.TINA4_AUTO_CACHING; else process.env.TINA4_AUTO_CACHING = prevAuto;
       if (prevDb === undefined) delete process.env.TINA4_DB_CACHE; else process.env.TINA4_DB_CACHE = prevDb;
@@ -1336,6 +1369,10 @@ class DatabaseBackend implements CacheBackend {
     return this.readyPromise;
   }
 
+  missingDriver(): string | null {
+    return this.missingDriverMessage;
+  }
+
   async isAvailable(): Promise<boolean> {
     await this.readyPromise;
     return this.available;
@@ -1531,9 +1568,11 @@ export async function createBackend(config?: {
   // degrading to a no-op cache. Mirrors the Python master.
   if (typeof backend.isAvailable === "function" && !(await backend.isAvailable())) {
     // eslint-disable-next-line no-console
+    const installHint = backend.missingDriver?.() ?? null;
     console.warn(
       `[tina4] Cache backend '${backendName}' is unavailable ` +
-      `(driver missing or service unreachable) — falling back to 'file'.`,
+      `(driver missing or service unreachable) — falling back to 'file'.` +
+      (installHint ? ` ${installHint}` : ""),
     );
     return new FileBackend(cacheDir(), maxEntries);
   }

package/packages/core/src/constants.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 Constants — HTTP status codes and content types.
  *

package/packages/core/src/container.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Lightweight dependency injection container.
  *

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

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 // Tina4 Node.js
 //
 // Text folding + chunking for the Context subsystem.

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

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 // Tina4 Node.js
 //
 // Context — a native, zero-dependency code/doc grounding index.