pi-jev-guard 0.4.0 → 0.5.0

package/src/automatic/guardian.ts

@@ -62,6 +62,8 @@ export interface PostPublishCheckResult {
   holdText?: string;
   /** Dettaglio per il report (publish con nota, hold). */
   grounding?: GateVerdictReport["grounding"];
+  /** Stato deterministico delle verifiche progetto osservate. */
+  verification?: GateVerdictReport["verification"];
 }
 
 /** Esito finale del gate con verdetto, per `/jev last` e diagnostica. */
@@ -76,6 +78,12 @@ export interface GateVerdictReport {
     action: "warned" | "repaired" | "held";
     reasons: string[];
   };
+  /** Mai generato dal modello: file edit/write + check configurati osservati. */
+  verification?: {
+    action: "passed" | "warned" | "repaired" | "held";
+    changedFiles: string[];
+    checks: Array<{ id: string; state: "passed" | "failed" | "pending" }>;
+  };
 }
 
 export class GuardianLimitError extends Error {
@@ -183,6 +191,10 @@ function withNotice(message: AssistantMessage, notice: string): AssistantMessage
   return { ...message, content };
 }
 
+function hasToolCalls(message: AssistantMessage): boolean {
+  return message.content.some((block) => block.type === "toolCall");
+}
+
 function assertCompleteCandidate(message: AssistantMessage): void {
   // Rifiuta terminali non supportati per pubblicazione.
   if (
@@ -284,12 +296,14 @@ export function runGuardedStream(
         const publishCandidate = async (
           notice?: string,
           grounding?: GateVerdictReport["grounding"],
+          verification?: GateVerdictReport["verification"],
         ): Promise<void> => {
           deps.onVerdict?.({
             verdict,
             attempts: attempt + 1,
             outcome: "published",
             ...(grounding ? { grounding } : {}),
+            ...(verification ? { verification } : {}),
           });
           const approved = notice ? withNotice(candidate, notice) : candidate;
           const aggregated = aggregateUsage(usages);
@@ -339,6 +353,15 @@ export function runGuardedStream(
         const runPostCheck = async (
           baseNotice?: string,
         ): Promise<"published" | "held" | undefined> => {
+          // I toolcall devono raggiungere il runtime: un post-check su una
+          // risposta intermedia potrebbe rigenerarla/holdarla e impedire il
+          // check stesso (es. `jev_verify`) prima che venga eseguito. Safety
+          // e tool policy restano già applicate; il post-check corre sul
+          // successivo messaggio finale dopo i tool result.
+          if (hasToolCalls(candidate)) {
+            await publishCandidate(baseNotice);
+            return "published";
+          }
           if (!deps.postPublishCheck) {
             await publishCandidate(baseNotice);
             return "published";
@@ -357,7 +380,7 @@ export function runGuardedStream(
           signal?.throwIfAborted();
           if (check.action === "publish") {
             const notice = [baseNotice, check.notice].filter(Boolean).join("") || undefined;
-            await publishCandidate(notice, check.grounding);
+            await publishCandidate(notice, check.grounding, check.verification);
             return "published";
           }
           if (check.action === "hold") {
@@ -367,6 +390,7 @@ export function runGuardedStream(
               attempts,
               outcome: "held",
               ...(check.grounding ? { grounding: check.grounding } : {}),
+              ...(check.verification ? { verification: check.verification } : {}),
             });
             await publishHoldText(check.holdText ?? "[JEV — OUTPUT NON PUBBLICATO]");
             return "held";
@@ -376,7 +400,7 @@ export function runGuardedStream(
             rejectedText: rawCandidate,
             feedback:
               check.feedback ??
-              "Grounding check failed; only assert session activities supported by evidence.",
+              "Post-publication check failed; correct the draft using the supplied evidence.",
           });
           return undefined;
         };

package/src/commands.ts

@@ -19,6 +19,7 @@ import { reviewWithCoverage } from "./reviewer.ts";
 import type { Metrics } from "./metrics.ts";
 import type { OutputVerdict } from "./output-judge.ts";
 import type { GateVerdictReport } from "./automatic/guardian.ts";
+import type { VerificationMode } from "./verification.ts";
 
 export interface GateStatusView {
   active: boolean;
@@ -79,6 +80,27 @@ export interface JevCommandDeps {
     hasStaleTests: boolean;
   };
   setGrounding: (mode: "off" | "warn" | "repair" | "hold") => JevConfig;
+  verificationStatus?: (cwd: string) => {
+    enabled: boolean;
+    mode: VerificationMode;
+    manifestPath: string;
+    manifestLoaded: boolean;
+    manifestError?: string;
+    changedFiles: string[];
+    checks: Array<{ id: string; state: "passed" | "failed" | "pending" }>;
+  };
+  setVerification?: (mode: "off" | VerificationMode) => JevConfig;
+  reloadVerificationManifest?: (cwd: string) => {
+    ok: boolean;
+    error?: string;
+    path?: string;
+  };
+  runVerification?: (args: {
+    cwd: string;
+    selection: string | undefined;
+    signal?: AbortSignal;
+    trusted: boolean;
+  }) => Promise<{ ok: boolean; message: string; results: unknown[] }>;
 }
 
 export const JEV_SUBCOMMANDS = [
@@ -96,6 +118,8 @@ export const JEV_SUBCOMMANDS = [
   "output",
   "last",
   "grounding",
+  "verification",
+  "verify",
   "backend",
   "save-key",
   "help",
@@ -121,6 +145,10 @@ export const JEV_HELP_TEXT = [
   "  /jev last                Ultimo verdetto del gate (twin): esito e controlli",
   "  /jev grounding off|warn|repair|hold",
   "                           Grounding affermazioni sessione (solo automatic, opt-in)",
+  "  /jev verification off|warn|repair|hold|reload",
+  "                           Footer deterministico + repair dai check progetto (opt-in; reload acquisisce manifest)",
+  "  /jev verify [recommended|all|id]",
+  "                           Esegue solo check dichiarati in .pi/jev-verification.json",
   "  /jev backend             Mostra backend attivo e chiavi rilevate",
   "  /jev backend auto|openrouter|typesafe",
   "                           Cambia backend (salvato in jev-config.json)",
@@ -140,7 +168,7 @@ export const JEV_HELP_TEXT = [
 export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
   pi.registerCommand("jev", {
     description:
-      "Jev guard: verifica con TypeSafe Jev. Sottocomandi: status, mode, models, upstream, off, check, stats, help.",
+      "Jev guard: gate, grounding e verifica progetto. Sottocomandi: status, mode, upstream, check, verification, verify, stats, help.",
     getArgumentCompletions: (argumentPrefix) => {
       const prefix = argumentPrefix.trim().toLowerCase();
       return JEV_SUBCOMMANDS.filter((s) => s.startsWith(prefix)).map(
@@ -188,6 +216,7 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
         const info = deps.reviewerInfo();
         const gate = deps.gateStatus();
         const twinView = deps.twinStatus();
+        const verification = deps.verificationStatus?.(ctx.cwd);
         const authProvider = twinView.primary?.provider ?? cfg.automatic.upstreamProvider;
         let guardedAuth = "—";
         if (gate.active) {
@@ -250,6 +279,11 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
             `Exfil check: ${cfg.exfilCheck.enabled ? "attivo in automatic (confirm in TUI, fail-open)" : "disattivo (config)"}`,
             `Output judge: ${cfg.outputJudge.enabled ? `attivo in automatic (tool: ${cfg.outputJudge.tools.join(",") || "—"}, fail-open)` : "disattivo (config)"}`,
             `Grounding: ${cfg.grounding.enabled ? `attivo in automatic (mode=${cfg.grounding.mode}, evidenza=${deps.groundingStatus().entries}${deps.groundingStatus().hasStaleTests ? ", test stale" : ""})` : "disattivo (opt-in: /jev grounding warn)"}`,
+            verification
+              ? `Verifica progetto: ${verification.enabled
+                ? `attiva (mode=${verification.mode}, manifest=${verification.manifestLoaded ? "OK" : verification.manifestError ?? "assente"}, modifiche=${verification.changedFiles.length}, check=${verification.checks.map((check) => `${check.id}:${check.state}`).join(",") || "—"})`
+                : `disattiva (opt-in: /jev verification warn; manifest=${verification.manifestPath})`}`
+              : "Verifica progetto: non disponibile in questa estensione",
             cfg.mode === "automatic"
               ? "ATTENZIONE: in automatic testo/codice vengono inviati al verificatore. Crea il twin con /jev upstream e seleziona il modello __jev per enforcement."
               : "on-demand: nessuna verifica automatica.",
@@ -465,6 +499,9 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
             last.report.grounding
               ? `grounding: ${last.report.grounding.action} (${last.report.grounding.reasons.join(", ") || "n/a"})`
               : "grounding: non intervenuto",
+            last.report.verification
+              ? `verifica progetto: ${last.report.verification.action} (file=${last.report.verification.changedFiles.join(",") || "—"}; check=${last.report.verification.checks.map((check) => `${check.id}:${check.state}`).join(",") || "—"})`
+              : "verifica progetto: non intervenuta",
             v.errorCode ? `errore: ${v.errorCode}` : `backend: ${v.backend ?? "?"} · modello: ${v.model ?? "?"}`,
             v.truncated ? `troncato: ${JSON.stringify(v.truncated)}` : "copertura intera",
             `tempo verifica: ${Math.round(v.elapsedMs)}ms`,
@@ -521,6 +558,74 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
         return;
       }
 
+      if (sub === "verification") {
+        if (!deps.verificationStatus || !deps.setVerification) {
+          ctx.ui.notify("Verifica progetto non disponibile in questa versione dell'estensione.", "warning");
+          return;
+        }
+        const value = parts[1];
+        if (value === undefined) {
+          const st = deps.verificationStatus(ctx.cwd);
+          ctx.ui.notify(
+            st.enabled
+              ? [
+                  `Verifica progetto attiva in automatic (mode=${st.mode}).`,
+                  `Manifest: ${st.manifestPath} — ${st.manifestLoaded ? "OK" : st.manifestError ?? "non disponibile"}.`,
+                  `Modifiche osservate: ${st.changedFiles.join(", ") || "nessuna"}.`,
+                  `Check: ${st.checks.map((check) => `${check.id}:${check.state}`).join(", ") || "nessuno pertinente"}.`,
+                  "Esegui quelli mancanti con /jev verify recommended. Dopo una modifica manuale del manifest: /jev verification reload.",
+                ].join("\n")
+              : `Verifica progetto disattiva (opt-in). Manifest previsto: ${st.manifestPath}. Attiva con /jev verification warn|repair|hold.`,
+            "info",
+          );
+          return;
+        }
+        if (value === "reload") {
+          if (!deps.reloadVerificationManifest) {
+            ctx.ui.notify("Reload manifest non disponibile in questa versione dell'estensione.", "warning");
+            return;
+          }
+          const reloaded = deps.reloadVerificationManifest(ctx.cwd);
+          ctx.ui.notify(
+            reloaded.ok
+              ? `Manifest verifica acquisito: ${reloaded.path}. I comandi verranno eseguiti solo da questa snapshot.`
+              : `Manifest verifica non acquisito: ${reloaded.error}`,
+            reloaded.ok ? "info" : "warning",
+          );
+          return;
+        }
+        if (value !== "off" && value !== "warn" && value !== "repair" && value !== "hold") {
+          ctx.ui.notify("Uso: /jev verification off|warn|repair|hold|reload", "warning");
+          return;
+        }
+        deps.setVerification(value);
+        ctx.ui.notify(
+          value === "off"
+            ? "Verifica progetto disattivata."
+            : `Verifica progetto attiva (mode=${value}). Crea ${deps.verificationStatus(ctx.cwd).manifestPath} con i soli comandi approvati, poi usa /jev verify recommended.`,
+          "info",
+        );
+        return;
+      }
+
+      if (sub === "verify") {
+        if (!deps.runVerification) {
+          ctx.ui.notify("Verifica progetto non disponibile in questa versione dell'estensione.", "warning");
+          return;
+        }
+        const trusted = typeof (ctx as { isProjectTrusted?: unknown }).isProjectTrusted === "function"
+          ? ctx.isProjectTrusted()
+          : false;
+        const result = await deps.runVerification({
+          cwd: ctx.cwd,
+          selection: parts[1],
+          signal: ctx.signal ?? undefined,
+          trusted,
+        });
+        ctx.ui.notify(result.message, result.ok ? "info" : "warning");
+        return;
+      }
+
       if (sub === "reload") {
         const cfg = deps.reload();
         ctx.ui.notify(`Config ricaricata. mode=${cfg.mode} backend=${cfg.jev.backend}`, "info");

package/src/config.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import type { JevBackend } from "./reviewer.ts";
+import type { VerificationSettings } from "./verification.ts";
 
 export type JevMode = "on-demand" | "automatic";
 export type JevBackendSetting = JevBackend | "auto";
@@ -97,6 +98,7 @@ export interface JevConfig {
     /** Una modifica riuscita invalida i test precedenti (stale). */
     invalidateTestsOnEdit: boolean;
   };
+  verification: VerificationSettings;
   exfilCheck: {
     /** Check semantico sui comandi con tool di rete (solo automatic). */
     enabled: boolean;
@@ -194,6 +196,17 @@ export const DEFAULT_CONFIG: JevConfig = {
     cacheSeconds: 120,
     invalidateTestsOnEdit: true,
   },
+  verification: {
+    // Opt-in: il manifest può eseguire solo comandi esplicitamente approvati
+    // dal progetto; non abilitarlo silenziosamente in installazioni esistenti.
+    enabled: false,
+    mode: "warn",
+    manifestPath: ".pi/jev-verification.json",
+    maxRepairs: 1,
+    commandTimeoutMs: 120000,
+    outputChars: 6000,
+    maxCommands: 3,
+  },
   exfilCheck: {
     enabled: true,
     tools: ["bash", "powershell"],

package/src/verification-runner.ts

@@ -0,0 +1,177 @@
+/** Esecuzione bounded dei soli comandi dichiarati nel manifest di verifica. */
+import { spawn } from "node:child_process";
+import type { VerificationCheck, VerificationSettings } from "./verification.ts";
+
+export interface VerificationExecution {
+  id: string;
+  command: string;
+  ok: boolean;
+  exitCode?: number;
+  timedOut?: boolean;
+  aborted?: boolean;
+  /** Solo output fallito, bounded; il successo non riversa log inutili nel contesto. */
+  output?: string;
+}
+
+function boundedTimeout(value: unknown): number {
+  // Config manuale può essere malformata: mai trasformare NaN in timeout 0.
+  const numeric = typeof value === "number" && Number.isFinite(value) ? value : 120_000;
+  // Non permettere manifest accidentali da ore: per check oltre 10 min l'utente
+  // può aumentare il setting ma resta una scelta esplicita e limitata.
+  return Math.max(1000, Math.min(600_000, Math.floor(numeric)));
+}
+
+function boundedOutputChars(value: unknown): number {
+  const numeric = typeof value === "number" && Number.isFinite(value) ? value : 6_000;
+  return Math.max(0, Math.min(100_000, Math.floor(numeric)));
+}
+
+function appendBounded(state: { text: string; elided: number }, chunk: Buffer, maxChars: number): void {
+  const value = chunk.toString("utf8");
+  const remaining = Math.max(0, maxChars - state.text.length);
+  state.text += value.slice(0, remaining);
+  state.elided += Math.max(0, value.length - remaining);
+}
+
+/**
+ * Esegue un comando scelto dal manifest. `command` non arriva mai dal modello;
+ * il chiamante deve aver già selezionato un VerificationCheck validato.
+ */
+export async function runVerificationCheck(args: {
+  check: VerificationCheck;
+  cwd: string;
+  settings: VerificationSettings;
+  signal?: AbortSignal;
+}): Promise<VerificationExecution> {
+  const { check, cwd, settings, signal } = args;
+  const configuredTimeout = boundedTimeout(settings.commandTimeoutMs);
+  const timeoutMs = Math.min(
+    check.timeoutMs === undefined ? configuredTimeout : boundedTimeout(check.timeoutMs),
+    configuredTimeout,
+  );
+  const outputChars = boundedOutputChars(settings.outputChars);
+  const captured = { text: "", elided: 0 };
+  let timedOut = false;
+  let aborted = false;
+
+  return new Promise<VerificationExecution>((resolveResult) => {
+    let settled = false;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let forceKill: ReturnType<typeof setTimeout> | undefined;
+    let child: ReturnType<typeof spawn> | undefined;
+    const killTree = (signalName: NodeJS.Signals) => {
+      if (!child?.pid) return;
+      try {
+        // Su POSIX il comando shell e i suoi figli sono un process group
+        // dedicato (detached:true): evitare che un npm/test appeso sopravviva
+        // al timeout del guard. Su Windows il fallback uccide almeno shell.
+        if (process.platform !== "win32") process.kill(-child.pid, signalName);
+        else child.kill(signalName);
+      } catch {
+        try {
+          child.kill(signalName);
+        } catch {
+          // Il processo può essere già terminato.
+        }
+      }
+    };
+    const settle = (result: VerificationExecution) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      if (forceKill) clearTimeout(forceKill);
+      signal?.removeEventListener("abort", onAbort);
+      resolveResult(result);
+    };
+    const terminate = () => {
+      killTree("SIGTERM");
+      forceKill ??= setTimeout(() => killTree("SIGKILL"), 1_000);
+    };
+    const output = () => {
+      const base = captured.text.trim();
+      const suffix = captured.elided > 0 ? `\n…[${captured.elided} chars elided]` : "";
+      return `${base}${suffix}`.trim();
+    };
+    const onAbort = () => {
+      aborted = true;
+      terminate();
+    };
+
+    try {
+      // shell è necessario perché il manifest contiene comandi normali come
+      // `npm run typecheck`; la fiducia arriva dal file locale + project trust.
+      child = spawn(check.command, {
+        cwd,
+        shell: true,
+        windowsHide: true,
+        detached: process.platform !== "win32",
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      settle({
+        id: check.id,
+        command: check.command,
+        ok: false,
+        output: error instanceof Error ? error.message : String(error),
+      });
+      return;
+    }
+
+    child.stdout?.on("data", (chunk: Buffer) => appendBounded(captured, chunk, outputChars));
+    child.stderr?.on("data", (chunk: Buffer) => appendBounded(captured, chunk, outputChars));
+    child.on("error", (error) => {
+      settle({
+        id: check.id,
+        command: check.command,
+        ok: false,
+        output: error.message,
+      });
+    });
+    child.on("close", (exitCode) => {
+      const ok = exitCode === 0 && !timedOut && !aborted;
+      settle({
+        id: check.id,
+        command: check.command,
+        ok,
+        ...(typeof exitCode === "number" ? { exitCode } : {}),
+        ...(timedOut ? { timedOut: true } : {}),
+        ...(aborted ? { aborted: true } : {}),
+        ...(!ok ? { output: output() || (timedOut ? `Timeout after ${timeoutMs}ms` : aborted ? "Aborted" : "Command failed without output") } : {}),
+      });
+    });
+
+    timeout = setTimeout(() => {
+      timedOut = true;
+      terminate();
+    }, timeoutMs);
+    // Child può chiudersi molto rapidamente prima dell'assegnazione del timer.
+    if (settled && timeout) clearTimeout(timeout);
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export async function runVerificationChecks(args: {
+  checks: VerificationCheck[];
+  cwd: string;
+  settings: VerificationSettings;
+  signal?: AbortSignal;
+}): Promise<VerificationExecution[]> {
+  const results: VerificationExecution[] = [];
+  for (const check of args.checks) {
+    if (args.signal?.aborted) break;
+    results.push(await runVerificationCheck({ ...args, check }));
+  }
+  return results;
+}
+
+/** Testo destinato al modello: esiti concreti, output diagnostico solo su errore. */
+export function formatVerificationExecutions(results: readonly VerificationExecution[]): string {
+  if (results.length === 0) return "[jev_verify] Nessun check eseguito.";
+  return results.map((result) => {
+    const header = result.ok
+      ? `[jev_verify] ${result.id}: superato${result.exitCode !== undefined ? ` (exit ${result.exitCode})` : ""}.`
+      : `[jev_verify] ${result.id}: fallito${result.exitCode !== undefined ? ` (exit ${result.exitCode})` : ""}${result.timedOut ? " (timeout)" : ""}${result.aborted ? " (annullato)" : ""}.`;
+    return result.output ? `${header}\n${result.output}` : header;
+  }).join("\n\n");
+}

package/src/verification-tool.ts

@@ -0,0 +1,65 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { VerificationExecution } from "./verification-runner.ts";
+
+export interface VerificationToolRunResult {
+  ok: boolean;
+  message: string;
+  results: VerificationExecution[];
+}
+
+/**
+ * Tool ristretto: il modello seleziona solo un id del manifest (o
+ * recommended/all), mai una stringa shell arbitraria.
+ */
+export function registerVerificationTool(
+  pi: ExtensionAPI,
+  deps: {
+    run: (args: {
+      cwd: string;
+      selection: string | undefined;
+      signal?: AbortSignal;
+      trusted: boolean;
+    }) => Promise<VerificationToolRunResult>;
+  },
+): void {
+  pi.registerTool({
+    name: "jev_verify",
+    label: "Jev project verification",
+    description:
+      "Run a project-approved typecheck, lint, or test declared in .pi/jev-verification.json. " +
+      "It never accepts arbitrary shell commands.",
+    promptSnippet: "Run approved project verification checks after code edits.",
+    promptGuidelines: [
+      "After a successful edit/write, call jev_verify with check='recommended' when verification is enabled.",
+      "Use only this tool's declared check ids; never claim code compiles or tests pass without its observed result.",
+      "If a check fails, inspect its actual output, repair the code, then run the check again.",
+    ],
+    parameters: Type.Object({
+      check: Type.Optional(
+        Type.String({
+          minLength: 1,
+          maxLength: 64,
+          description: "Check id, or 'recommended' (default) / 'all'",
+        }),
+      ),
+    }),
+    executionMode: "sequential",
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const result = await deps.run({
+        cwd: ctx.cwd,
+        selection: params.check,
+        signal: signal ?? undefined,
+        trusted: ctx.isProjectTrusted(),
+      });
+      return {
+        content: [{ type: "text", text: result.message }],
+        details: {
+          kind: "jev-verification",
+          ok: result.ok,
+          results: result.results,
+        },
+      };
+    },
+  });
+}