pi-jev-guard 0.3.3 → 0.5.0

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,
+        },
+      };
+    },
+  });
+}