interference-agent 0.1.0 → 0.2.3

package/src/tui/ToolStep.tsx

@@ -1,6 +1,35 @@
-import { Box, Text } from "ink";
-import { Spinner } from "@inkjs/ui";
+import type { ReactNode } from "react";
+import { Box, Text, useStdout } from "ink";
+import { SpinnerInline } from "./Spinner.tsx";
 import type { DiffLine } from "./DiffView.tsx";
+import { BG_PANEL, DIFF_ADD_BG, DIFF_REM_BG, panelWidth } from "./theme.ts";
+
+const fill = (w: number, used: number) => " ".repeat(Math.max(0, w - used));
+
+// Riga di diff: numero riga + marker + testo, su sfondo verde/rosso attenuato (it. 20).
+function DiffLineRow({ d, w }: { d: DiffLine; w: number }) {
+  const bg = d.type === "add" ? DIFF_ADD_BG : d.type === "remove" ? DIFF_REM_BG : BG_PANEL;
+  const fg = d.type === "add" ? "green" : d.type === "remove" ? "red" : undefined;
+  const num = String((d.type === "add" ? d.newNo : d.oldNo) ?? "").padStart(4, " ");
+  const mark = d.type === "add" ? "+ " : d.type === "remove" ? "- " : "  ";
+  const text = d.text.slice(0, Math.max(0, w - 9));
+  const used = 2 + 4 + 1 + 2 + text.length; // barra + numero + spazio + marker + testo
+  return (
+    <Text backgroundColor={bg}>
+      <Text color="gray" bold backgroundColor={bg}>
+        {"▌ "}
+      </Text>
+      <Text dimColor backgroundColor={bg}>
+        {num}{" "}
+      </Text>
+      <Text color={fg} dimColor={d.type === "same"} backgroundColor={bg}>
+        {mark}
+        {text}
+      </Text>
+      <Text backgroundColor={bg}>{fill(w, used)}</Text>
+    </Text>
+  );
+}
 
 // Vista di un tool step (call → result). Allineata a ToolEntry in App.tsx.
 export interface ToolView {
@@ -27,6 +56,21 @@ const ICON: Record<string, string> = {
   task: "│",
 };
 
+// Testo descrittivo durante l'esecuzione (it. 21, stile opencode `~ <verbo>…`).
+const PENDING: Record<string, string> = {
+  bash: "Running command…",
+  read: "Reading file…",
+  ls: "Listing…",
+  glob: "Finding files…",
+  grep: "Searching content…",
+  webfetch: "Fetching…",
+  websearch: "Searching web…",
+  todowrite: "Updating todos…",
+  question: "Asking…",
+  task: "Delegating…",
+};
+const pendingText = (name: string) => PENDING[name] ?? "Working…";
+
 // Tool con output complesso → blocco con bordo sinistro. Gli altri → riga inline.
 const BLOCK = new Set(["bash", "write", "edit"]);
 
@@ -94,26 +138,59 @@ function InlineTool({
   desc: string;
   pending: boolean;
 }) {
-  const iconColor = tool.isError ? "red" : "cyan";
+  const iconColor = tool.isError ? "red" : "white";
   return (
     <Box flexDirection="column" paddingLeft={3}>
       <Box>
-        <Text color={iconColor}>{icon} </Text>
-        <Text color={tool.isError ? "red" : undefined} dimColor={!tool.isError && !pending}>
-          {tool.toolName} {desc}
-        </Text>
-        {pending && <Spinner label="" />}
+        {/* icona a larghezza fissa (2 col) → allineamento tra tool diversi */}
+        <Box width={2}>
+          <Text color={iconColor}>{icon}</Text>
+        </Box>
+        {pending ? (
+          <>
+            <Text dimColor>~ {pendingText(tool.toolName)} </Text>
+            <SpinnerInline />
+          </>
+        ) : (
+          <Text color={tool.isError ? "red" : undefined} dimColor={!tool.isError}>
+            {tool.toolName} {desc}
+          </Text>
+        )}
       </Box>
       {!pending && tool.output && (
-        <Text dimColor color={tool.isError ? "red" : undefined}>
-          {"  "}
-          {oneLine(tool.output)}
-        </Text>
+        <Box paddingLeft={2}>
+          <Text dimColor color={tool.isError ? "red" : undefined}>
+            {oneLine(tool.output)}
+          </Text>
+        </Box>
       )}
     </Box>
   );
 }
 
+// Riga del pannello: barra "▌ " (2 col) + contenuto + riempimento di sfondo a larghezza.
+function PanelLine({
+  w,
+  barColor,
+  used,
+  children,
+}: {
+  w: number;
+  barColor: string;
+  used: number;
+  children: ReactNode;
+}) {
+  return (
+    <Text backgroundColor={BG_PANEL}>
+      <Text color={barColor} bold>
+        {"▌ "}
+      </Text>
+      {children}
+      <Text backgroundColor={BG_PANEL}>{fill(w - 2, used)}</Text>
+    </Text>
+  );
+}
+
 function BlockTool({
   tool,
   icon,
@@ -125,55 +202,55 @@ function BlockTool({
   desc: string;
   pending: boolean;
 }) {
+  const { stdout } = useStdout();
+  const w = panelWidth(stdout?.columns);
+  const barColor = tool.isError ? "red" : "gray";
   const title =
     tool.toolName === "bash" ? oneLine(desc, 160) : `${tool.toolName} ${desc}`;
+  const titleClip = title.slice(0, w - 6);
+
+  const diff = tool.diff && tool.diff.length > 0 ? tool.diff : null;
+  const outLines =
+    !diff && !pending && tool.output ? clip(tool.output).split("\n") : [];
+
   return (
-    <Box
-      flexDirection="column"
-      borderStyle="round"
-      borderColor={tool.isError ? "red" : "gray"}
-      borderTop={false}
-      borderRight={false}
-      borderBottom={false}
-      paddingLeft={1}
-      marginTop={1}
-      marginBottom={1}
-    >
-      <Box>
-        <Text color={tool.isError ? "red" : "cyan"} bold>
+    <Box flexDirection="column" marginTop={1} marginBottom={1}>
+      <PanelLine w={w} barColor={barColor} used={2 + titleClip.length}>
+        <Text color={tool.isError ? "red" : "white"} bold backgroundColor={BG_PANEL}>
           {icon}{" "}
         </Text>
-        <Text bold>{title}</Text>
-        {pending && <Spinner label="" />}
-      </Box>
-      {tool.diff && tool.diff.length > 0 ? (
-        <DiffBody diff={tool.diff} />
-      ) : (
-        !pending &&
-        tool.output && (
-          <Text dimColor color={tool.isError ? "red" : undefined}>
-            {clip(tool.output)}
+        <Text bold backgroundColor={BG_PANEL}>
+          {titleClip}
+        </Text>
+      </PanelLine>
+
+      {pending && (
+        <PanelLine w={w} barColor={barColor} used={2 + pendingText(tool.toolName).length}>
+          <Text dimColor backgroundColor={BG_PANEL}>
+            ~ {pendingText(tool.toolName)}
           </Text>
-        )
+        </PanelLine>
       )}
-    </Box>
-  );
-}
 
-function DiffBody({ diff }: { diff: DiffLine[] }) {
-  return (
-    <Box flexDirection="column">
-      {diff.slice(0, 15).map((d, i) => (
-        <Text
-          key={i}
-          color={d.type === "add" ? "green" : d.type === "remove" ? "red" : undefined}
-          dimColor={d.type === "same"}
-        >
-          {d.type === "add" ? "+ " : d.type === "remove" ? "- " : "  "}
-          {d.text.slice(0, 100)}
-        </Text>
-      ))}
-      {diff.length > 15 && <Text dimColor>… {diff.length - 15} more lines</Text>}
+      {diff && diff.slice(0, 15).map((d, i) => <DiffLineRow key={i} d={d} w={w} />)}
+      {diff && diff.length > 15 && (
+        <PanelLine w={w} barColor={barColor} used={2 + 14}>
+          <Text dimColor backgroundColor={BG_PANEL}>
+            … {diff.length - 15} more
+          </Text>
+        </PanelLine>
+      )}
+
+      {outLines.map((ln, i) => {
+        const t = ln.slice(0, w - 2);
+        return (
+          <PanelLine key={i} w={w} barColor={barColor} used={t.length}>
+            <Text dimColor color={tool.isError ? "red" : undefined} backgroundColor={BG_PANEL}>
+              {t}
+            </Text>
+          </PanelLine>
+        );
+      })}
     </Box>
   );
 }

package/src/tui/Welcome.tsx

@@ -2,6 +2,7 @@ import { Box, Text } from "ink";
 import { currentThinking } from "../config.ts";
 import { WORDMARK } from "./wordmark.ts";
 import { PANEL, padRight } from "./theme.ts";
+import { CURRENT_VERSION } from "../version.ts";
 
 // Larghezza del pannello wordmark = riga più lunga + margini.
 const WM_W = Math.max(...WORDMARK.map((l) => l.length)) + 4;
@@ -19,6 +20,7 @@ interface Props {
   provider: string;
   model: string;
   sessionCount: number;
+  update?: string | null;
 }
 
 function Tip({ cmd, desc }: { cmd: string; desc: string }) {
@@ -34,9 +36,19 @@ function Tip({ cmd, desc }: { cmd: string; desc: string }) {
 
 // Branding-only: l'input è condiviso (gestito da App), così gli slash e
 // l'autocomplete funzionano anche dalla home.
-export function Welcome({ provider, model, sessionCount }: Props) {
+export function Welcome({ provider, model, sessionCount, update }: Props) {
   return (
     <Box flexDirection="column" marginBottom={1}>
+      {/* Banner aggiornamento (it. 28): discreto, solo se c'è una versione più recente */}
+      {update && (
+        <Box justifyContent="center" marginBottom={1}>
+          <Text color={ACCENT}>
+            interference {CURRENT_VERSION} → {update}
+          </Text>
+          <Text color={MUTED}> · run </Text>
+          <Text color={ACCENT}>/update</Text>
+        </Box>
+      )}
       {/* Header centrato: wordmark su pannello (sfondo reale via Text) + tagline */}
       <Box flexDirection="column" alignItems="center" marginBottom={1}>
         <Box flexDirection="column">
@@ -65,13 +77,16 @@ export function Welcome({ provider, model, sessionCount }: Props) {
         </Box>
       )}
 
-      {/* Tips (blocco, centrato) */}
+      {/* Tips (blocco, centrato) — i due comandi fondamentali in cima */}
       <Box flexDirection="column" alignItems="center" marginTop={1}>
+        <Box marginBottom={1}>
+          <Text color={MUTED}>Get started — connect a provider, then pick a model:</Text>
+        </Box>
         <Box flexDirection="column">
-          <Tip cmd="/help" desc="show all commands" />
-          <Tip cmd="/build" desc="switch to full-access mode" />
+          <Tip cmd="/provider" desc="connect a provider (add your API key)" />
+          <Tip cmd="/model" desc="choose the model to use" />
+          <Tip cmd="/help" desc="all commands" />
           <Tip cmd="/thinking" desc="set reasoning level" />
-          <Tip cmd="/init" desc="generate AGENTS.md" />
         </Box>
       </Box>
 

package/src/tui/__tests__/reasoning.test.ts

@@ -0,0 +1,24 @@
+import { describe, test, expect } from "bun:test";
+import { reasoningSummary } from "../reasoning.ts";
+
+describe("reasoningSummary (iter 23)", () => {
+  test("prima frase breve", () => {
+    expect(reasoningSummary("Devo controllare i file. Poi rispondo.")).toBe("Devo controllare i file.");
+  });
+
+  test("strip markdown iniziale e cap a 60", () => {
+    const long = "## " + "x".repeat(80);
+    const out = reasoningSummary(long);
+    expect(out.startsWith("x")).toBe(true);
+    expect(out.length).toBeLessThanOrEqual(61); // 60 + …
+    expect(out.endsWith("…")).toBe(true);
+  });
+
+  test("salta righe vuote, prende la prima significativa", () => {
+    expect(reasoningSummary("\n\n- Analizzo il loop")).toBe("Analizzo il loop");
+  });
+
+  test("testo vuoto → stringa vuota", () => {
+    expect(reasoningSummary("   \n  ")).toBe("");
+  });
+});

package/src/tui/__tests__/syntax.test.ts

@@ -0,0 +1,33 @@
+import { describe, test, expect } from "bun:test";
+import { tokenizeLine, normalizeLang } from "../syntax.ts";
+
+describe("syntax tokenizer (iter 22)", () => {
+  test("classifies keyword / string / number / comment", () => {
+    const toks = tokenizeLine('const x = "a" // c', "ts");
+    const byColor = Object.fromEntries(toks.filter((t) => t.color).map((t) => [t.text, t.color]));
+    expect(byColor["const"]).toBe("cyan");
+    expect(byColor['"a"']).toBe("green");
+    expect(byColor["// c"]).toBe("gray");
+  });
+
+  test("numbers are magenta", () => {
+    const toks = tokenizeLine("const n = 42", "ts");
+    expect(toks.find((t) => t.text === "42")?.color).toBe("magenta");
+  });
+
+  test("python uses # comments", () => {
+    const toks = tokenizeLine("x = 1 # note", "py");
+    expect(toks.find((t) => t.text === "# note")?.color).toBe("gray");
+  });
+
+  test("unknown lang → single plain token", () => {
+    expect(tokenizeLine("anything here", "")).toEqual([{ text: "anything here" }]);
+  });
+
+  test("normalizeLang maps aliases", () => {
+    expect(normalizeLang("typescript")).toBe("ts");
+    expect(normalizeLang("PYTHON")).toBe("py");
+    expect(normalizeLang("bash")).toBe("sh");
+    expect(normalizeLang("rust")).toBe("");
+  });
+});

package/src/tui/__tests__/tui-render.test.tsx

@@ -3,6 +3,7 @@ import React from "react";
 import { render } from "ink-testing-library";
 import { ToolStep } from "../ToolStep.tsx";
 import { MarkdownText } from "../MarkdownText.tsx";
+import { computeDiff } from "../DiffView.tsx";
 
 function frame(el: React.ReactElement): string {
   const { lastFrame, unmount } = render(el);
@@ -19,10 +20,18 @@ describe("ToolStep rendering (iter 18)", () => {
     expect(out).not.toContain("{"); // niente JSON grezzo
   });
 
-  test("bash block: command rendered with $ and output", () => {
+  test("pending tool shows descriptive text (iter 21)", () => {
+    const grep = frame(<ToolStep tool={{ toolName: "grep", input: { pattern: "foo" } }} />);
+    expect(grep).toContain("~ Searching content…");
+    const bash = frame(<ToolStep tool={{ toolName: "bash", input: { command: "ls" } }} />);
+    expect(bash).toContain("~ Running command…");
+  });
+
+  test("bash block: command rendered with $ and output, on a panel (▌ bar)", () => {
     const out = frame(<ToolStep tool={{ toolName: "bash", input: { command: "bun test" }, output: "77 pass" }} />);
     expect(out).toContain("$ bun test");
     expect(out).toContain("77 pass");
+    expect(out).toContain("▌"); // pannello (it. 19): barra laterale su sfondo
   });
 
   test("edit block: diff lines with +/-", () => {
@@ -45,6 +54,26 @@ describe("ToolStep rendering (iter 18)", () => {
   });
 });
 
+describe("diff line numbers (iter 20)", () => {
+  test("computeDiff assigns old/new line numbers", () => {
+    const d = computeDiff(["a", "b", "c"], ["a", "B", "c"]);
+    expect(d).toEqual([
+      { type: "same", text: "a", oldNo: 1, newNo: 1 },
+      { type: "remove", text: "b", oldNo: 2 },
+      { type: "add", text: "B", newNo: 2 },
+      { type: "same", text: "c", oldNo: 3, newNo: 3 },
+    ]);
+  });
+
+  test("edit block renders line numbers in the diff", () => {
+    const d = computeDiff(["x"], ["y"]);
+    const out = frame(<ToolStep tool={{ toolName: "edit", input: { path: "f.ts" }, output: "ok", diff: d }} />);
+    expect(out).toContain("- x");
+    expect(out).toContain("+ y");
+    expect(out).toMatch(/\b1\b/); // numero di riga presente
+  });
+});
+
 describe("MarkdownText rendering (iter 18)", () => {
   test("strips markdown markers, keeps content", () => {
     const out = frame(<MarkdownText content={"# Titolo\nUn **bold** e `code`.\n- item"} />);

package/src/tui/placeholders.ts

@@ -0,0 +1,22 @@
+// Esempi rotanti per il placeholder dell'input (it. 25), per modalità.
+export const PLACEHOLDERS: Record<"plan" | "build", string[]> = {
+  build: [
+    "Fix a TODO in the codebase",
+    "Add a test for the parser",
+    "Refactor this module",
+    "Implement the next iteration",
+  ],
+  plan: [
+    "How does the agent loop work?",
+    "Where is resolveInWorkspace defined?",
+    "Map the tool system",
+    "What does this function return?",
+  ],
+};
+
+export function placeholderFor(mode: string, idx: number): string {
+  const list = mode === "plan" ? PLACEHOLDERS.plan : PLACEHOLDERS.build;
+  const verb = mode === "plan" ? "Explore" : "Ask anything";
+  const ex = list[((idx % list.length) + list.length) % list.length];
+  return `${verb}… "${ex}"`;
+}

package/src/tui/reasoning.ts

@@ -0,0 +1,23 @@
+// Sommario del pensiero (it. 23): ricava un titolo breve dalla prima frase significativa
+// del reasoning, per l'header `✻ Thinking/Thought: <titolo>` (stile opencode).
+
+export function reasoningSummary(text: string): string {
+  const firstLine = text
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+  if (!firstLine) return "";
+
+  let s = firstLine
+    .replace(/^#{1,6}\s+/, "") // heading
+    .replace(/^[-*>]\s+/, "") // bullet/quote
+    .replace(/^\d+\.\s+/, "") // lista numerata
+    .replace(/[*_`]/g, "") // enfasi/code inline
+    .replace(/\s+/g, " ")
+    .trim();
+
+  // Taglia alla prima frase se breve, altrimenti cap a 60 char.
+  const sentence = s.match(/^(.*?[.!?])(\s|$)/);
+  if (sentence && sentence[1] && sentence[1].length <= 60) return sentence[1];
+  return s.length > 60 ? s.slice(0, 60).trimEnd() + "…" : s;
+}

package/src/tui/syntax.ts

@@ -0,0 +1,58 @@
+// Syntax highlighting MINIMALE per i code block (it. 22). Niente parser/dipendenze:
+// un tokenizer a regex per pochi scope (commento/stringa/numero/keyword) — "good enough"
+// come la subtle-syntax di opencode. Colori per il contenuto (i code block sono per natura
+// colorati); la chrome resta B&W.
+
+export interface Tok {
+  text: string;
+  color?: string;
+  dim?: boolean;
+}
+
+const KW: Record<string, string[]> = {
+  ts: ["import","export","from","const","let","var","function","return","if","else","for","while","class","extends","implements","interface","type","enum","new","async","await","try","catch","finally","throw","typeof","instanceof","as","in","of","public","private","protected","readonly","static","void","null","undefined","true","false"],
+  js: ["import","export","from","const","let","var","function","return","if","else","for","while","class","extends","new","async","await","try","catch","finally","throw","typeof","instanceof","in","of","null","undefined","true","false"],
+  py: ["def","class","import","from","return","if","elif","else","for","while","try","except","finally","with","as","in","not","and","or","is","lambda","yield","async","await","pass","raise","None","True","False","self"],
+  sh: ["if","then","else","elif","fi","for","in","do","done","while","case","esac","function","echo","export","local","return","cd","exit"],
+  json: [],
+};
+
+export function normalizeLang(info: string): string {
+  const l = info.toLowerCase().trim();
+  if (l === "ts" || l === "typescript" || l === "tsx") return "ts";
+  if (l === "js" || l === "javascript" || l === "jsx" || l === "mjs") return "js";
+  if (l === "py" || l === "python") return "py";
+  if (l === "sh" || l === "bash" || l === "shell" || l === "zsh") return "sh";
+  if (l === "json") return "json";
+  return "";
+}
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export function tokenizeLine(line: string, lang: string): Tok[] {
+  if (!lang) return [{ text: line }];
+  const kw = KW[lang] ?? [];
+  const commentPat = lang === "py" || lang === "sh" ? "(#[^\\n]*)" : "(\\/\\/[^\\n]*)";
+  const parts = [
+    commentPat,
+    "(\"(?:[^\"\\\\]|\\\\.)*\"|'(?:[^'\\\\]|\\\\.)*'|`(?:[^`\\\\]|\\\\.)*`)",
+    "(\\b\\d+(?:\\.\\d+)?\\b)",
+  ];
+  if (kw.length) parts.push("(\\b(?:" + kw.map(escape).join("|") + ")\\b)");
+  const re = new RegExp(parts.join("|"), "g");
+
+  const out: Tok[] = [];
+  let last = 0;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(line)) !== null) {
+    if (m.index > last) out.push({ text: line.slice(last, m.index) });
+    if (m[1]) out.push({ text: m[0], color: "gray", dim: true }); // commento
+    else if (m[2]) out.push({ text: m[0], color: "green" }); // stringa
+    else if (m[3]) out.push({ text: m[0], color: "magenta" }); // numero
+    else out.push({ text: m[0], color: "cyan" }); // keyword
+    last = m.index + m[0].length;
+    if (m[0].length === 0) re.lastIndex++; // guard anti-loop
+  }
+  if (last < line.length) out.push({ text: line.slice(last) });
+  return out.length ? out : [{ text: line }];
+}

package/src/tui/theme.ts

@@ -1,10 +1,22 @@
 // Palette condivisa della TUI. Brand: bianco/nero (niente colori).
 // Il contrasto nasce dal PANEL (sfondo applicato sui <Text>, non sui <Box>:
 // in Ink il backgroundColor del Box non riempie il padding → si usa il Text).
-export const PANEL = "#262626"; // sfondo pannello (grigio scuro, stacca dal nero)
+// Gerarchia sfondi a 3 livelli (B&W), stile opencode (base < panel < element).
+export const BG_PANEL = "#141414"; // blocchi/dialog (un gradino sopra il nero)
+export const BG_ELEMENT = "#1e1e1e"; // elementi/selezione/pannello utente (un gradino sopra ancora)
+export const PANEL = BG_ELEMENT; // alias storico (messaggio utente, input, welcome)
 export const USER_BAR = "white"; // barra messaggi utente
 export const ASSISTANT_BAR = "gray"; // barra risposte assistant
 
+// Sfondi diff (attenuati, leggibili su terminale scuro) — it. 20.
+export const DIFF_ADD_BG = "#0f2a18"; // riga aggiunta (verde scuro)
+export const DIFF_REM_BG = "#3a1414"; // riga rimossa (rosso scuro)
+
+// Ambra: riservata ESCLUSIVAMENTE al pensiero (reasoning), come opencode.
+// Esecuzione (tool) e risposte restano bianco/nero → le tre fasi si distinguono.
+export const THINKING = "#d79921"; // header pensiero (ambra)
+export const THINKING_BODY = "gray"; // corpo pensiero (attenuato)
+
 // Pad a destra fino a w caratteri (per estendere lo sfondo del Text).
 export function padRight(s: string, w: number): string {
   return s.length >= w ? s : s + " ".repeat(w - s.length);

package/src/version.ts

@@ -0,0 +1,79 @@
+import { readFileSync } from "node:fs";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import * as path from "node:path";
+import { interferenceDir } from "./paths.ts";
+
+// Versione corrente letta dal package.json del pacchetto (sync, funziona anche
+// installato globalmente: version.ts sta in <pkg>/src, package.json in <pkg>/).
+function readVersion(): string {
+  try {
+    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    return (JSON.parse(raw).version as string) ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+export const CURRENT_VERSION: string = readVersion();
+
+const PKG = "interference-agent";
+const TTL = 24 * 60 * 60 * 1000; // 24h
+const REGISTRY = `https://registry.npmjs.org/${PKG}/latest`;
+
+function cachePath(): string {
+  // Reindirizzabile via INTERFERENCE_HOME (isolamento test) — vedi paths.ts.
+  return interferenceDir("update-check.json");
+}
+
+// Confronto semver "x.y.z" (con eventuale prefisso v). true se `latest` > `current`.
+export function isNewer(latest: string, current: string): boolean {
+  const p = (v: string) => v.replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+  const a = p(latest);
+  const b = p(current);
+  for (let i = 0; i < 3; i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+
+// Controlla npm per una versione più recente. Throttled (cache 24h), non bloccante,
+// silenzioso offline. Ritorna la versione latest se più nuova, altrimenti null.
+export async function checkForUpdate(): Promise<string | null> {
+  if (process.env.INTERFERENCE_NO_UPDATE_CHECK) return null;
+  const file = cachePath();
+  try {
+    let latest: string | null = null;
+
+    // 1) cache fresca?
+    try {
+      const c = JSON.parse(await readFile(file, "utf8"));
+      if (typeof c.ts === "number" && Date.now() - c.ts < TTL && typeof c.latest === "string") {
+        latest = c.latest;
+      }
+    } catch {
+      // niente cache valida
+    }
+
+    // 2) altrimenti interroga il registry (timeout breve)
+    if (!latest) {
+      const res = await fetch(REGISTRY, { signal: AbortSignal.timeout(2500) });
+      if (!res.ok) return null;
+      const j = (await res.json()) as { version?: string };
+      latest = j.version ?? null;
+      if (latest) {
+        try {
+          await mkdir(path.dirname(file), { recursive: true });
+          await writeFile(file, JSON.stringify({ ts: Date.now(), latest }));
+        } catch {
+          // cache best-effort
+        }
+      }
+    }
+
+    return latest && isNewer(latest, CURRENT_VERSION) ? latest : null;
+  } catch {
+    return null; // offline / errori → nessun avviso
+  }
+}