tina4-nodejs 3.12.9 → 3.13.0

package/packages/core/src/errorOverlay.ts

@@ -19,7 +19,7 @@
  * In production, call renderProductionError() instead.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { isTruthy } from "./dotenv.js";
 
@@ -111,8 +111,38 @@ function formatSourceBlock(filename: string, lineno: number): string {
     + rows + `</div>`;
 }
 
-function formatFrame(frame: StackFrame): string {
+/**
+ * Render one stack frame.
+ *
+ * When the file was modified AFTER `capturedAt`, append a peach
+ * "FILE MODIFIED" badge so a stale browser-cached overlay can't lie
+ * about what the source looks like now. The AI coder often rewrites
+ * files in place between page loads, leaving the overlay's source
+ * view showing different code than what raised the error.
+ *
+ * `capturedAt` is in seconds (Date.now() / 1000) for parity with
+ * Python's time.time().
+ */
+function formatFrame(frame: StackFrame, capturedAt = 0): string {
   const source = frame.file && frame.line > 0 ? formatSourceBlock(frame.file, frame.line) : "";
+  let staleBadge = "";
+  if (capturedAt && frame.file) {
+    try {
+      const absPath = resolve(frame.file);
+      const mtime = statSync(absPath).mtimeMs / 1000;
+      if (mtime > capturedAt + 0.5) {  // 0.5s margin for fs noise
+        const d = new Date(mtime * 1000);
+        const mtimeIso = `${String(d.getUTCHours()).padStart(2, "0")}:`
+          + `${String(d.getUTCMinutes()).padStart(2, "0")}:`
+          + `${String(d.getUTCSeconds()).padStart(2, "0")}`;
+        staleBadge = ` <span style="background:${PEACH};color:${BG};padding:1px 8px;`
+          + `border-radius:3px;font-size:11px;font-weight:700;margin-left:6px;">`
+          + `FILE MODIFIED @ ${mtimeIso} UTC &mdash; source may not match what failed</span>`;
+      }
+    } catch {
+      // best-effort — ignore missing files / permission errors
+    }
+  }
   return `<div style="margin-bottom:16px;">`
     + `<div style="margin-bottom:4px;">`
     + `<span style="color:${BLUE};">${esc(frame.file)}</span>`
@@ -120,6 +150,7 @@ function formatFrame(frame: StackFrame): string {
     + `<span style="color:${YELLOW};">${frame.line}</span>`
     + `<span style="color:${SUBTEXT};"> in </span>`
     + `<span style="color:${GREEN};">${esc(frame.func)}</span>`
+    + staleBadge
     + `</div>`
     + source
     + `</div>`;
@@ -153,14 +184,21 @@ function table(pairs: Array<[string, string]>): string {
  * @returns Complete HTML page string.
  */
 export function renderErrorOverlay(error: Error, request?: any): string {
+  // Stamp ONCE per render — every frame compares against this. Seconds-since-epoch
+  // matches Python's time.time() so frames stale by < 0.5s of fs noise don't trip.
+  const capturedAt = Date.now() / 1000;
   const excType = error.constructor?.name ?? "Error";
   const excMsg = error.message ?? String(error);
   const frames = error.stack ? parseStack(error.stack) : [];
 
   // ── Stack trace ──
+  // Each frame compares its source file's mtime to capturedAt and flags itself
+  // if the file has been modified since — protects against the "browser cached
+  // an old overlay, then the AI rewrote the file" confusion where displayed
+  // source no longer matches what actually raised the error.
   let framesHtml = "";
   for (const frame of frames) {
-    framesHtml += formatFrame(frame);
+    framesHtml += formatFrame(frame, capturedAt);
   }
 
   // ── Request info ──

package/packages/core/src/feedback.ts

@@ -0,0 +1,277 @@
+/**
+ * Customer feedback widget — Tier 4 port from tina4-python.
+ *
+ * End-users of a shipped Tina4 app give UX feedback via a floating bubble
+ * widget. Widget visibility + API are gated by TWO env flags:
+ *
+ *   - TINA4_ENABLE_FEEDBACK   master switch (explicit opt-in)
+ *   - TINA4_FEEDBACK_WHITELIST comma-separated emails / user IDs
+ *
+ * Architecture (mirrors Python `tina4_python/dev_admin/__init__.py`
+ * lines 1440-1645):
+ *
+ *   1. Framework middleware injects <script src="/__feedback/widget.js">
+ *      into HTML responses for whitelisted users only.
+ *   2. Widget POSTs to /__feedback/api/turn for each conversational turn.
+ *   3. That handler verifies whitelist + rate-limit, stamps the user
+ *      identity server-side (client cannot fake `sender`), then forwards
+ *      to the Rust agent's /feedback/intake.
+ *
+ * The widget is for END USERS of a shipped app — the /__dev paths get
+ * skipped so the dev admin's own chat bubble doesn't sit on top of the
+ * customer feedback bubble.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { authenticateRequest } from "./auth.js";
+import { supervisorBaseUrl } from "./devAdmin.js";
+import type { RouteHandler, Tina4Request } from "./types.js";
+import type { Router } from "./router.js";
+
+// ── Module-level rate-limit state ──────────────────────────────
+// 5 turns/hour per identified user. Stored in-memory only; this is
+// per-process — for multi-instance deployments a shared backend would
+// be needed, but the python reference is the same shape.
+const RATE_LIMIT_WINDOW_SEC = 3600;
+const RATE_LIMIT_MAX = 5;
+const _rateLimitHits = new Map<string, number[]>();
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+/**
+ * Master switch — both this AND a non-empty whitelist must be set for
+ * the widget to render or the API to accept submissions. Mirrors
+ * Python's `_feedback_enabled()`.
+ */
+export function feedbackEnabled(): boolean {
+  const raw = (process.env.TINA4_ENABLE_FEEDBACK ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+
+/**
+ * Comma-separated emails / user IDs in env, lowercased + trimmed.
+ * Returns [] when the master switch is off so callers can short-circuit
+ * with a single check. Mirrors Python's `_feedback_whitelist()`.
+ */
+export function feedbackWhitelist(): string[] {
+  if (!feedbackEnabled()) return [];
+  const raw = (process.env.TINA4_FEEDBACK_WHITELIST ?? "").trim();
+  if (!raw) return [];
+  return raw
+    .split(",")
+    .map((e) => e.trim().toLowerCase())
+    .filter((e) => e.length > 0);
+}
+
+/**
+ * Best-effort user identity from JWT/Bearer auth. Falls back to
+ * TINA4_FEEDBACK_DEV_USER (local dev convenience — lets the framework
+ * owner test the widget without a full auth setup). Mirrors Python's
+ * `_feedback_identify_user()`.
+ */
+export function feedbackIdentifyUser(request: Tina4Request): string | null {
+  try {
+    const payload = authenticateRequest(
+      (request.headers ?? {}) as Record<string, string | string[] | undefined>,
+    );
+    if (payload && typeof payload === "object") {
+      for (const key of ["email", "sub", "user_id"]) {
+        const v = (payload as Record<string, unknown>)[key];
+        if (v) return String(v).trim().toLowerCase();
+      }
+    }
+  } catch {
+    /* ignore — fall through to dev override */
+  }
+  const dev = (process.env.TINA4_FEEDBACK_DEV_USER ?? "").trim();
+  if (dev) return dev.toLowerCase();
+  return null;
+}
+
+/**
+ * Returns [allowed, userId]. Both halves are required — feature off when
+ * either is falsy. Mirrors Python's `_feedback_is_whitelisted()`.
+ */
+export function feedbackIsWhitelisted(
+  request: Tina4Request,
+): [boolean, string | null] {
+  const wl = feedbackWhitelist();
+  if (wl.length === 0) return [false, null];
+  const user = feedbackIdentifyUser(request);
+  if (!user) return [false, null];
+  return [wl.includes(user), user];
+}
+
+/**
+ * 5 turns/hour per user, sliding window. Prunes old timestamps lazily on
+ * every call (no background task needed). Mirrors Python's
+ * `_feedback_rate_limit_ok()`.
+ */
+export function feedbackRateLimitOk(user: string): boolean {
+  const now = Date.now() / 1000;
+  const prior = _rateLimitHits.get(user) ?? [];
+  const fresh = prior.filter((t) => now - t < RATE_LIMIT_WINDOW_SEC);
+  if (fresh.length >= RATE_LIMIT_MAX) {
+    _rateLimitHits.set(user, fresh);
+    return false;
+  }
+  fresh.push(now);
+  _rateLimitHits.set(user, fresh);
+  return true;
+}
+
+/** Test-only: clear rate-limit state between cases. Not part of public API. */
+export function _resetFeedbackRateLimit(): void {
+  _rateLimitHits.clear();
+}
+
+/**
+ * Insert the widget <script> into HTML for whitelisted users. Called
+ * from the response pipeline right before the body is flushed. No-op if:
+ *   - request path starts with /__dev or /__feedback (developer
+ *     pages have their own chat trigger)
+ *   - master switch / whitelist not set
+ *   - user not in whitelist
+ *   - html lacks </body>
+ * Idempotent — looks for the `data-tina4-feedback` marker and bails.
+ * Mirrors Python's `inject_feedback_widget()`.
+ */
+export function injectFeedbackWidget(
+  request: Tina4Request,
+  html: string,
+): string {
+  if (!html) return html;
+  const path = (request.path ?? "") || "";
+  if (path.startsWith("/__dev") || path.startsWith("/__feedback")) return html;
+  if (html.includes("data-tina4-feedback")) return html;
+  const [allowed] = feedbackIsWhitelisted(request);
+  if (!allowed) return html;
+  const lastBody = html.lastIndexOf("</body>");
+  if (lastBody < 0) return html;
+  const snippet =
+    '<script src="/__feedback/widget.js" data-tina4-feedback></script>';
+  return html.slice(0, lastBody) + snippet + html.slice(lastBody);
+}
+
+// ── Route handlers ──────────────────────────────────────────────
+
+/**
+ * POST /__feedback/api/turn — proxy one conversational turn to the Rust
+ * agent's `/feedback/intake`. Server stamps `sender` from the verified
+ * identity so the client cannot inject who they are. Mirrors Python's
+ * `_api_feedback_turn()`.
+ */
+export const handleFeedbackTurn: RouteHandler = async (req, res) => {
+  const [allowed, user] = feedbackIsWhitelisted(req);
+  if (!allowed || !user) {
+    res.json({ error: "not authorised for feedback" }, 403);
+    return;
+  }
+  if (!feedbackRateLimitOk(user)) {
+    res.json(
+      {
+        error: "rate limit exceeded",
+        hint: `max ${RATE_LIMIT_MAX} turns per hour`,
+      },
+      429,
+    );
+    return;
+  }
+
+  const body = (req as Tina4Request).body;
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    res.json({ error: "expected JSON body" }, 400);
+    return;
+  }
+
+  // Stamp sender server-side — client cannot override identity.
+  const forwardBody = { ...(body as Record<string, unknown>), sender: user };
+  const base = supervisorBaseUrl();
+  const target = `${base}/feedback/intake`;
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 60_000);
+
+  let upstream: Response;
+  try {
+    upstream = await fetch(target, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(forwardBody),
+      signal: ctrl.signal,
+    });
+  } catch (e) {
+    clearTimeout(timer);
+    res.json(
+      { error: "agent unreachable", detail: (e as Error).message },
+      502,
+    );
+    return;
+  }
+  clearTimeout(timer);
+
+  const raw = await upstream.text();
+  const status = upstream.status || 200;
+  try {
+    res.json(JSON.parse(raw), status);
+  } catch {
+    res.raw.writeHead(status, {
+      "Content-Type":
+        upstream.headers.get("content-type") ?? "text/plain; charset=utf-8",
+    });
+    res.raw.end(raw);
+  }
+};
+
+// Widget bundle lives at packages/core/src/__feedback/widget.js so that
+// it isn't auto-served by the static-file handler (which would skip the
+// no-cache headers below).
+const __feedbackDirname = dirname(fileURLToPath(import.meta.url));
+const WIDGET_BUNDLE_PATH = resolve(__feedbackDirname, "__feedback", "widget.js");
+
+/**
+ * GET /__feedback/widget.js — serve the widget bundle with no-cache
+ * headers so a broken bundle doesn't get stuck in browser caches.
+ * Mirrors Python's `_api_feedback_widget_js()`.
+ */
+export const handleFeedbackWidgetJs: RouteHandler = (_req, res) => {
+  let body: Buffer | string;
+  if (existsSync(WIDGET_BUNDLE_PATH)) {
+    body = readFileSync(WIDGET_BUNDLE_PATH);
+  } else {
+    body = "console.warn('tina4-feedback-widget bundle not built yet');";
+  }
+  res.raw.writeHead(200, {
+    "Content-Type": "application/javascript; charset=utf-8",
+    "Cache-Control": "no-cache, must-revalidate",
+    Pragma: "no-cache",
+  });
+  res.raw.end(body);
+};
+
+/**
+ * Register the two feedback routes on a Router. Called from the dev
+ * admin setup so the routes only exist when the dev surface is
+ * enabled — production deployments without TINA4_DEBUG also skip them.
+ */
+export function registerFeedbackRoutes(router: Router): void {
+  router.addRoute({
+    method: "POST",
+    pattern: "/__feedback/api/turn",
+    handler: handleFeedbackTurn,
+  });
+  router.addRoute({
+    method: "GET",
+    pattern: "/__feedback/widget.js",
+    handler: handleFeedbackWidgetJs,
+  });
+}
+
+// Re-export the bundle path so other tools (e.g. CLI builds) can find it.
+export { WIDGET_BUNDLE_PATH };
+// Silence unused-import lint where the helpers are imported but `join` isn't
+// used in this file's current code path. (Kept available for future tweaks.)
+void join;

package/packages/core/src/index.ts

@@ -71,7 +71,18 @@ export type { ResponseCacheConfig } from "./cache.js";
 export { Api } from "./api.js";
 export type { ApiResult } from "./api.js";
 export { Events } from "./events.js";
-export { DevAdmin, MessageLog, RequestInspector, ErrorTracker, DevMailboxStore, DevQueue, WsTracker } from "./devAdmin.js";
+export { DevAdmin, MessageLog, RequestInspector, ErrorTracker, DevMailboxStore, DevQueue, WsTracker, supervisorBaseUrl } from "./devAdmin.js";
+export {
+  feedbackEnabled,
+  feedbackWhitelist,
+  feedbackIdentifyUser,
+  feedbackIsWhitelisted,
+  feedbackRateLimitOk,
+  injectFeedbackWidget,
+  handleFeedbackTurn,
+  handleFeedbackWidgetJs,
+  registerFeedbackRoutes,
+} from "./feedback.js";
 export { Messenger } from "./messenger.js";
 export type { SendResult, EmailMessage } from "./messenger.js";
 export { DevMailbox, createMessenger } from "./devMailbox.js";
@@ -99,6 +110,8 @@ export { RedisNpmSessionHandler } from "./sessionHandlers/redisHandler.js";
 export type { RedisNpmSessionConfig } from "./sessionHandlers/redisHandler.js";
 export { tests, assertEqual, assertRaises, assertTrue, assertFalse, runAll, reset } from "./testing.js";
 export { TestClient, TestResponse } from "./testClient.js";
+export { Tina4Test, AssertionError as Tina4AssertionError } from "./test.js";
+export type { TestRunResults } from "./test.js";
 export { Container, container } from "./container.js";
 export { Validator } from "./validator.js";
 export type { ValidationError } from "./validator.js";

package/packages/core/src/mcp.test.ts

@@ -390,6 +390,307 @@ console.log("\nInstance Registry");
   assert("instances — cleared", McpServer._instances.length === 0);
 }
 
+// ── Defensive Write Helpers (Tier 1 parity port from Python) ─
+
+console.log("\nDefensive Write Helpers");
+
+/**
+ * Invoke an MCP tool and unwrap the JSON-RPC + tools/call envelope.
+ * The MCP `tools/call` response shape is:
+ *   { jsonrpc, id, result: { content: [{ type: "text", text: "<json>" }] } }
+ * For string returns the inner text is the raw string; for object returns
+ * it is JSON-encoded — try to parse it back, fall through to the raw text.
+ */
+function callTool(server: McpServer, name: string, args: Record<string, unknown>): {
+  rpc: { jsonrpc?: string; id?: unknown; result?: unknown; error?: { code: number; message: string } };
+  result: Record<string, unknown> | string | null;
+} {
+  const rpc = JSON.parse(server.handleMessage({
+    jsonrpc: "2.0", id: 1, method: "tools/call",
+    params: { name, arguments: args },
+  }));
+  let result: Record<string, unknown> | string | null = null;
+  const content = (rpc.result as { content?: Array<{ text?: string }> } | undefined)?.content;
+  if (content && content.length > 0 && typeof content[0].text === "string") {
+    const raw = content[0].text;
+    try {
+      result = JSON.parse(raw);
+    } catch {
+      result = raw;
+    }
+  }
+  return { rpc, result };
+}
+
+// refuses prose paths in file_write
+{
+  McpServer._instances = [];
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tina4-mcp-test-"));
+  const oldCwd = process.cwd();
+  process.chdir(tmpDir);
+  try {
+    const server = new McpServer("/test-prose", "Prose Test");
+    registerDevTools(server);
+    const { result } = callTool(server, "file_write", {
+      path: "The plan requires implementing a new feature for users.ts",
+      content: "x",
+    });
+    assert(
+      "refuses prose paths in file_write",
+      typeof result === "object" && result !== null && typeof (result as Record<string, unknown>).error === "string",
+      `Got: ${JSON.stringify(result)}`,
+    );
+  } finally {
+    process.chdir(oldCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// normalizes bare routes/ to src/routes/
+{
+  McpServer._instances = [];
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tina4-mcp-test-"));
+  const oldCwd = process.cwd();
+  process.chdir(tmpDir);
+  try {
+    const server = new McpServer("/test-normalize", "Normalize Test");
+    registerDevTools(server);
+    const { result } = callTool(server, "file_write", {
+      path: "routes/foo.ts",
+      content: "export default async function (req, res) {}\n",
+    });
+    const landedAt = path.join(tmpDir, "src", "routes", "foo.ts");
+    const written = (result as { written?: string } | null)?.written;
+    assert(
+      "normalizes bare routes/ to src/routes/ — file lands at src/routes/foo.ts",
+      fs.existsSync(landedAt) && (written ?? "").replace(/\\/g, "/") === "src/routes/foo.ts",
+      `Got: ${JSON.stringify(result)}; exists=${fs.existsSync(landedAt)}`,
+    );
+    const logPath = path.join(tmpDir, ".tina4", "agent.log");
+    const logContent = fs.existsSync(logPath) ? fs.readFileSync(logPath, "utf-8") : "";
+    assert(
+      "normalizes bare routes/ to src/routes/ — agent.log has path_normalized entry",
+      logContent.includes("write.path_normalized") && logContent.includes("routes/foo.ts"),
+      `Log content: ${logContent.slice(0, 300)}`,
+    );
+  } finally {
+    process.chdir(oldCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// backs up existing file before overwrite
+{
+  McpServer._instances = [];
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tina4-mcp-test-"));
+  const oldCwd = process.cwd();
+  process.chdir(tmpDir);
+  try {
+    const server = new McpServer("/test-backup", "Backup Test");
+    registerDevTools(server);
+    const target = path.join(tmpDir, "src", "routes", "foo.ts");
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, "original content\n", "utf-8");
+
+    const { result } = callTool(server, "file_write", {
+      path: "src/routes/foo.ts",
+      content: "new content that is reasonably similar in length to the old one\n",
+    });
+    const backup = (result as { backup?: string } | null)?.backup ?? "";
+    const backupDir = path.join(tmpDir, ".tina4", "backups");
+    const backups = fs.existsSync(backupDir) ? fs.readdirSync(backupDir) : [];
+    assert(
+      "backs up existing file before overwrite — backup in .tina4/backups/",
+      backups.length === 1 && backup.startsWith(".tina4/backups/"),
+      `Got: ${JSON.stringify(result)}; backups=${JSON.stringify(backups)}`,
+    );
+    assert(
+      "backs up existing file before overwrite — backup contains original",
+      backups.length === 1 &&
+        fs.readFileSync(path.join(backupDir, backups[0]), "utf-8") === "original content\n",
+    );
+  } finally {
+    process.chdir(oldCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// refuses suspicious truncation
+{
+  McpServer._instances = [];
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tina4-mcp-test-"));
+  const oldCwd = process.cwd();
+  process.chdir(tmpDir);
+  try {
+    const server = new McpServer("/test-truncation", "Truncation Test");
+    registerDevTools(server);
+    const target = path.join(tmpDir, "src", "routes", "big.ts");
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    // 500-byte original
+    const original = "x".repeat(500);
+    fs.writeFileSync(target, original, "utf-8");
+
+    // Overwrite with 50 bytes — should be REFUSED (50/500 = 10% < 30%)
+    const { result } = callTool(server, "file_write", {
+      path: "src/routes/big.ts",
+      content: "y".repeat(50),
+    });
+    const r = result as { error?: string; refused?: boolean } | null;
+    assert(
+      "refuses suspicious truncation — returns error with refused flag",
+      r !== null && r.refused === true && typeof r.error === "string" && r.error.includes("REFUSED"),
+      `Got: ${JSON.stringify(result)}`,
+    );
+    const stillThere = fs.readFileSync(target, "utf-8");
+    assert(
+      "refuses suspicious truncation — original file intact",
+      stillThere === original,
+      `Original was modified: length=${stillThere.length}`,
+    );
+  } finally {
+    process.chdir(oldCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// lets canonical src/ paths pass through (no rewrite)
+{
+  McpServer._instances = [];
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tina4-mcp-test-"));
+  const oldCwd = process.cwd();
+  process.chdir(tmpDir);
+  try {
+    const server = new McpServer("/test-passthrough", "Passthrough Test");
+    registerDevTools(server);
+    const { result } = callTool(server, "file_write", {
+      path: "src/routes/foo.ts",
+      content: "export default async function (req, res) {}\n",
+    });
+    const landedAt = path.join(tmpDir, "src", "routes", "foo.ts");
+    const written = (result as { written?: string } | null)?.written;
+    assert(
+      "lets canonical src/ paths pass through — file lands at src/routes/foo.ts",
+      fs.existsSync(landedAt) && (written ?? "").replace(/\\/g, "/") === "src/routes/foo.ts",
+      `Got: ${JSON.stringify(result)}`,
+    );
+    // Path should NOT have been double-prefixed to src/src/routes/foo.ts
+    const doublyPrefixed = path.join(tmpDir, "src", "src", "routes", "foo.ts");
+    assert(
+      "lets canonical src/ paths pass through — no double-prefix",
+      !fs.existsSync(doublyPrefixed),
+    );
+    // agent.log should NOT contain a path_normalized entry for this write
+    const logPath = path.join(tmpDir, ".tina4", "agent.log");
+    const logContent = fs.existsSync(logPath) ? fs.readFileSync(logPath, "utf-8") : "";
+    assert(
+      "lets canonical src/ paths pass through — no path_normalized log entry",
+      !logContent.includes("write.path_normalized"),
+      `Log content: ${logContent.slice(0, 300)}`,
+    );
+  } finally {
+    process.chdir(oldCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// catches JS syntax errors via node --check
+{
+  McpServer._instances = [];
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tina4-mcp-test-"));
+  const oldCwd = process.cwd();
+  process.chdir(tmpDir);
+  try {
+    const server = new McpServer("/test-verify-js", "Verify JS");
+    registerDevTools(server);
+    const { result } = callTool(server, "file_write", {
+      path: "src/routes/broken.js",
+      content: "const x = ;\n",
+    });
+    const r = result as { written?: string; import_error?: string } | null;
+    assert(
+      "catches JS syntax errors via node --check — result has import_error",
+      r !== null && typeof r.import_error === "string" && r.import_error.length > 0,
+      `Got: ${JSON.stringify(result)}`,
+    );
+    const logPath = path.join(tmpDir, ".tina4", "agent.log");
+    const logContent = fs.existsSync(logPath) ? fs.readFileSync(logPath, "utf-8") : "";
+    assert(
+      "catches JS syntax errors via node --check — agent.log has write.import_failed",
+      logContent.includes("write.import_failed") && logContent.includes("src/routes/broken.js"),
+      `Log content: ${logContent.slice(0, 400)}`,
+    );
+  } finally {
+    process.chdir(oldCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// skips non-code files (no syntax check attempted)
+{
+  McpServer._instances = [];
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tina4-mcp-test-"));
+  const oldCwd = process.cwd();
+  process.chdir(tmpDir);
+  try {
+    const server = new McpServer("/test-verify-skip-ext", "Verify Skip Ext");
+    registerDevTools(server);
+    // .twig content that would obviously fail any JS parser
+    const { result } = callTool(server, "file_write", {
+      path: "src/templates/page.twig",
+      content: "{% if not valid js %}<h1>Hi</h1>{% endif %}\n",
+    });
+    const r = result as { written?: string; import_error?: string } | null;
+    assert(
+      "skips non-code files — no import_error attached",
+      r !== null && r.import_error === undefined && typeof r.written === "string",
+      `Got: ${JSON.stringify(result)}`,
+    );
+    const logPath = path.join(tmpDir, ".tina4", "agent.log");
+    const logContent = fs.existsSync(logPath) ? fs.readFileSync(logPath, "utf-8") : "";
+    assert(
+      "skips non-code files — no write.import_failed in agent.log",
+      !logContent.includes("write.import_failed"),
+      `Log content: ${logContent.slice(0, 400)}`,
+    );
+  } finally {
+    process.chdir(oldCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// skips files outside src/
+{
+  McpServer._instances = [];
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tina4-mcp-test-"));
+  const oldCwd = process.cwd();
+  process.chdir(tmpDir);
+  try {
+    const server = new McpServer("/test-verify-skip-outside", "Verify Skip Outside");
+    registerDevTools(server);
+    // Broken JS placed under tests/ — must NOT be checked
+    const { result } = callTool(server, "file_write", {
+      path: "tests/foo.js",
+      content: "const x = ;\n",
+    });
+    const r = result as { written?: string; import_error?: string } | null;
+    assert(
+      "skips files outside src/ — no import_error attached",
+      r !== null && r.import_error === undefined && typeof r.written === "string",
+      `Got: ${JSON.stringify(result)}`,
+    );
+    const logPath = path.join(tmpDir, ".tina4", "agent.log");
+    const logContent = fs.existsSync(logPath) ? fs.readFileSync(logPath, "utf-8") : "";
+    assert(
+      "skips files outside src/ — no write.import_failed in agent.log",
+      !logContent.includes("write.import_failed"),
+      `Log content: ${logContent.slice(0, 400)}`,
+    );
+  } finally {
+    process.chdir(oldCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
 // ── Summary ──────────────────────────────────────────────────
 
 console.log(`\nMCP Tests: ${pass} passed, ${fail} failed`);