@imolko/ultra-agent 0.1.0-beta

package/pi/extensions/qa-guardrail/adapters/cli.ts

@@ -0,0 +1,100 @@
+/**
+ * Base for future CLI adapters (ruff, pylint, …).
+ *
+ * Same contract as the in-process eslint adapter — `lint(file) → Violation[]`,
+ * never failing silently. When linting is impossible (binary missing or the
+ * run/parse fails), the adapter throws and the runner catches, warns, and
+ * skips feedback:
+ *
+ * - Lazy: the binary is resolved from PATH on the *first* lint call, never at
+ *   adapter creation, so loading the extension requires no linter at all.
+ * - Missing binary → throw (message = missingBinaryWarning).
+ * - Run/parse errors → rethrow.
+ */
+
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import type { LintAdapter, LintContext, Violation } from "../types.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Resolve a binary name against PATH. Returns the absolute path, or `null`
+ * when not found. `env` and `exists` are injectable for tests.
+ */
+export function resolveBinary(
+  binary: string,
+  env: NodeJS.ProcessEnv | Record<string, string | undefined> = process.env,
+  exists: (p: string) => boolean = existsSync,
+): string | null {
+  const pathVar = env.PATH ?? env.Path ?? env.path;
+  if (typeof pathVar !== "string" || pathVar === "") {
+    return null;
+  }
+  for (const dir of pathVar.split(delimiter)) {
+    if (dir === "") continue;
+    const candidate = join(dir, binary);
+    if (exists(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/** Message thrown when a future CLI adapter's binary is absent. */
+export function missingBinaryWarning(id: string, binary: string): string {
+  return `qa-guardrail: binario ausente — ${binary} (adaptador ${id}); no se linteará`;
+}
+
+export interface CliAdapterOptions {
+  /** Whitelisted id, e.g. "ruff". */
+  id: string;
+  /** Binary name resolved from PATH. */
+  binary: string;
+  /** Extra args placed before the file argument. */
+  args?: string[];
+  /** Parse stdout/stderr into normalized violations. */
+  parse: (stdout: string, stderr: string, file: string) => Violation[];
+  /** Binary resolver. Defaults to `resolveBinary`. Injectable for tests. */
+  findBinary?: (binary: string) => string | null;
+  /** Runner. Defaults to `execFile`. Injectable for tests. */
+  run?: (
+    binary: string,
+    args: string[],
+    ctx: LintContext,
+  ) => Promise<{ stdout: string; stderr: string }>;
+}
+
+async function defaultRun(
+  binary: string,
+  args: string[],
+  ctx: LintContext,
+): Promise<{ stdout: string; stderr: string }> {
+  const { stdout, stderr } = await execFileAsync(binary, args, { cwd: ctx.cwd });
+  return { stdout: stdout as string, stderr: stderr as string };
+}
+
+export function createCliAdapter(options: CliAdapterOptions): LintAdapter {
+  let binaryPath: string | null | undefined;
+  const findBinary = options.findBinary ?? resolveBinary;
+  const run = options.run ?? defaultRun;
+
+  return {
+    id: options.id,
+    async lint(file, ctx) {
+      if (binaryPath === undefined) {
+        binaryPath = findBinary(options.binary);
+      }
+      if (binaryPath === null) {
+        // Fail-fast: linter missing → throw; the runner warns and skips.
+        throw new Error(missingBinaryWarning(options.id, options.binary));
+      }
+      const absolutePath = resolve(ctx.cwd, file);
+      const args = [...(options.args ?? []), absolutePath];
+      const { stdout, stderr } = await run(binaryPath, args, ctx);
+      return options.parse(stdout, stderr, absolutePath);
+    },
+  };
+}

package/pi/extensions/qa-guardrail/adapters/eslint.ts

@@ -0,0 +1,90 @@
+/**
+ * In-process ESLint adapter (Node API).
+ *
+ * - Lazy: `import("eslint")` only happens on the first lint call, so loading
+ *   the extension never requires eslint to be installed.
+ * - Single instance: one ESLint instance is reused across calls; it is rebuilt
+ *   only if the project root changes or `eslint.config.mjs` changes (mtime),
+ *   so mid-session edits to the rules take effect on the next lint.
+ * - Throws when linting is impossible (missing module or broken config); the
+ *   runner catches, warns, and skips. Returns `[]` for a clean or ignored file.
+ */
+
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import type { LintAdapter, Violation } from "../types.js";
+
+/** Flat-config file whose mtime invalidates the cached ESLint instance. */
+export const ESLINT_CONFIG_FILE = "eslint.config.mjs";
+
+/** Last-modified time of the flat config, or `null` when it does not exist. */
+function configMtimeMs(root: string): number | null {
+  try {
+    return statSync(resolve(root, ESLINT_CONFIG_FILE)).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+interface EslintMessage {
+  ruleId?: string | null;
+  message: string;
+  line?: number;
+  column?: number;
+  severity?: number;
+  endLine?: number;
+  endColumn?: number;
+}
+
+interface EslintLintResult {
+  messages: EslintMessage[];
+}
+
+interface EslintInstance {
+  lintFiles(patterns: string[]): Promise<EslintLintResult[]>;
+}
+
+function toViolation(message: EslintMessage): Violation {
+  return {
+    ruleId: message.ruleId ?? null,
+    message: message.message,
+    line: message.line ?? 0,
+    column: message.column ?? 0,
+    severity: message.severity ?? 2,
+    endLine: message.endLine,
+    endColumn: message.endColumn,
+  };
+}
+
+export function createEslintAdapter(): LintAdapter {
+  let currentRoot: string | null = null;
+  let currentConfigMtime: number | null = null;
+  let current: Promise<EslintInstance> | null = null;
+
+  function getInstance(root: string): Promise<EslintInstance> {
+    const mtime = configMtimeMs(root);
+    if (currentRoot === root && currentConfigMtime === mtime && current) {
+      return current;
+    }
+    currentRoot = root;
+    currentConfigMtime = mtime;
+    current = import("eslint")
+      .then((mod) => mod.loadESLint())
+      .then(
+        (ESLintClass) =>
+          new ESLintClass({ cwd: root, warnIgnored: false }) as EslintInstance,
+      );
+    return current;
+  }
+
+  return {
+    id: "eslint",
+    async lint(file, ctx) {
+      const absolutePath = resolve(ctx.cwd, file);
+      const instance = await getInstance(ctx.root);
+      const results = await instance.lintFiles([absolutePath]);
+      const messages = results[0]?.messages ?? [];
+      return messages.map(toViolation);
+    },
+  };
+}

package/pi/extensions/qa-guardrail/adapters/registry.ts

@@ -0,0 +1,45 @@
+/**
+ * Whitelisted adapter registry: id → adapter.
+ *
+ * Only adapters explicitly registered here can be selected by config. Unknown
+ * ids resolve to `undefined` *and* emit a warning (never a crash): this is the
+ * whitelist that makes the config selection-only.
+ */
+
+import type { LintAdapter } from "../types.js";
+
+const registry = new Map<string, LintAdapter>();
+
+/** Emits the warning for an unknown id. No-op by default; tests override it. */
+let unknownIdWarn: (message: string) => void = () => {};
+
+export function registerAdapter(adapter: LintAdapter): void {
+  registry.set(adapter.id, adapter);
+}
+
+/**
+ * Replace the unknown-id warning sink. The default is a no-op so the registry
+ * stays usable without a UI/logger; the extension wires it to its own warning
+ * channel at startup.
+ */
+export function setUnknownIdWarn(fn: (message: string) => void): void {
+  unknownIdWarn = fn;
+}
+
+export function getAdapter(id: string): LintAdapter | undefined {
+  const adapter = registry.get(id);
+  if (!adapter) {
+    unknownIdWarn(`qa-guardrail: adaptador no registrado — ${id}`);
+  }
+  return adapter;
+}
+
+export function isWhitelisted(id: string): boolean {
+  return registry.has(id);
+}
+
+/** Test helper: empty the registry and restore the warning no-op. */
+export function clearRegistry(): void {
+  registry.clear();
+  unknownIdWarn = () => {};
+}

package/pi/extensions/qa-guardrail/baseline.ts

@@ -0,0 +1,74 @@
+/**
+ * Frozen per-file, per-session baseline for delta scoping.
+ *
+ * The baseline is captured on `tool_call` *before* the first edit: the
+ * violations the file already had when the agent found it. Once captured it is
+ * frozen for the rest of the session — subsequent edits must not re-capture
+ * (that would swallow the agent's own changes into the baseline). New files
+ * (which do not exist yet at capture time) get an empty baseline.
+ */
+
+import { existsSync } from "node:fs";
+import type { Violation } from "./types.js";
+
+export interface BaselineDeps {
+  /** Filesystem probe used to decide whether a file is new. */
+  exists(path: string): boolean;
+}
+
+export interface BaselineStore {
+  /**
+   * Capture the baseline for `file` if it has not been captured yet, and
+   * return it. Existing files are linted via `lint`; new files get `[]`
+   * without linting. Never throws: a lint failure yields `[]`.
+   */
+  capture(file: string, lint: (file: string) => Promise<Violation[]>): Promise<Violation[]>;
+  /** The frozen baseline for `file`, or `undefined` if not yet captured. */
+  get(file: string): Violation[] | undefined;
+  /** Whether a baseline has been captured for `file`. */
+  has(file: string): boolean;
+  /** Forget the baseline for `file` (human reset), so it can be re-captured. */
+  reset(file: string): void;
+  /** Forget every baseline (session teardown / tests). */
+  clear(): void;
+}
+
+export function createBaselineStore(deps: Partial<BaselineDeps> = {}): BaselineStore {
+  const exists = deps.exists ?? existsSync;
+  const store = new Map<string, Violation[]>();
+
+  return {
+    async capture(file, lint) {
+      if (store.has(file)) {
+        return store.get(file)!;
+      }
+
+      let baseline: Violation[] = [];
+      if (exists(file)) {
+        try {
+          baseline = await lint(file);
+        } catch {
+          baseline = [];
+        }
+      }
+      store.set(file, baseline);
+      return baseline;
+    },
+
+    get(file) {
+      return store.get(file);
+    },
+
+    has(file) {
+      return store.has(file);
+    },
+
+    reset(file) {
+      store.delete(file);
+    },
+
+    clear() {
+      store.clear();
+    },
+  };
+}

package/pi/extensions/qa-guardrail/cerco.ts

@@ -0,0 +1,134 @@
+/**
+ * Cerco (fence) for qa-guardrail (#320).
+ *
+ * Two independent guards the agent cannot bypass:
+ *
+ * 1. A hardcoded protected-path list — `eslint.config.mjs`,
+ *    `.pi/qa-guardrail.json`, and this extension's own directory. Writes/edits
+ *    to those paths are blocked at `tool_call`: the rules definition and the
+ *    cerco itself are not editable by the agent (A-045/A-049).
+ * 2. Detection of `eslint-disable*` directives, independent of ESLint (which
+ *    currently lets them pass via the `eslint` exemption of `no-comments`).
+ *    New directives in `write.content` / `edit.newText` are blocked at
+ *    `tool_call`. Inherited ones are out of scope here and only surface in
+ *    `/qa-guardrail check` (#321).
+ */
+
+import { relative, resolve, sep } from "node:path";
+
+/** Hardcoded protected list. Relative to the project root (cwd). */
+export const PROTECTED_PATHS: readonly string[] = [
+  "eslint.config.mjs",
+  ".pi/qa-guardrail.json",
+  ".pi/extensions/qa-guardrail/**",
+];
+
+/** Matches `eslint-disable`, `eslint-disable-line`, `eslint-disable-next-line`. */
+export const ESLINT_DISABLE_PATTERN = /eslint-disable(?:-line|-next-line)?\b/;
+
+/** True when `text` contains an eslint-disable* directive. */
+export function hasEslintDisableDirective(text: string): boolean {
+  return ESLINT_DISABLE_PATTERN.test(text);
+}
+
+/** Every eslint-disable* directive found in `text`, in order of appearance. */
+export function findEslintDisableDirectives(text: string): string[] {
+  return text.match(/eslint-disable(?:-line|-next-line)?\b/g) ?? [];
+}
+
+function toPosix(p: string): string {
+  return p.split(sep).join("/");
+}
+
+/** True when `file` (relative to `cwd`) is in the protected list. */
+export function isProtectedPath(file: string, cwd: string): boolean {
+  return protectedPathReason(file, cwd) !== undefined;
+}
+
+/** Human-readable reason why `file` is protected, or `undefined` if it is not. */
+export function protectedPathReason(file: string, cwd: string): string | undefined {
+  const abs = resolve(cwd, file);
+  const rel = toPosix(relative(resolve(cwd), abs));
+
+  for (const pattern of PROTECTED_PATHS) {
+    if (pattern.endsWith("/**")) {
+      const dir = pattern.slice(0, -"/**".length);
+      if (rel === dir || rel.startsWith(`${dir}/`)) {
+        return `qa-guardrail: ${file} está protegido (${pattern}) — el cerco no es editable por el agente`;
+      }
+    } else if (rel === pattern) {
+      return `qa-guardrail: ${file} está protegido (${pattern}) — el cerco no es editable por el agente`;
+    }
+  }
+  return undefined;
+}
+
+export type CercoCheck = { blocked: true; reason: string } | { blocked: false };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The strings a write/edit is about to introduce (write.content / edit.newText). */
+function extractNewTexts(toolName: string, input: unknown): string[] {
+  if (!isRecord(input)) {
+    return [];
+  }
+
+  if (toolName === "write") {
+    const content = input.content;
+    return typeof content === "string" ? [content] : [];
+  }
+
+  if (toolName === "edit") {
+    const texts: string[] = [];
+    const edits = input.edits;
+    if (Array.isArray(edits)) {
+      for (const edit of edits) {
+        if (isRecord(edit) && typeof edit.newText === "string") {
+          texts.push(edit.newText);
+        }
+      }
+    }
+    // Legacy session format: top-level oldText/newText (see pi extension docs).
+    const newText = input.newText;
+    if (typeof newText === "string") {
+      texts.push(newText);
+    }
+    return texts;
+  }
+
+  return [];
+}
+
+/**
+ * Check both cerco guards for a `tool_call`. Returns the first block, if any.
+ * Non-write/edit tools always pass (the cerco only fences edits).
+ */
+export function checkCerco(
+  toolName: string,
+  input: unknown,
+  file: string,
+  cwd: string,
+): CercoCheck {
+  if (toolName !== "write" && toolName !== "edit") {
+    return { blocked: false };
+  }
+
+  const protectedReason = protectedPathReason(file, cwd);
+  if (protectedReason) {
+    return { blocked: true, reason: protectedReason };
+  }
+
+  for (const text of extractNewTexts(toolName, input)) {
+    const directive = findEslintDisableDirectives(text)[0];
+    if (directive) {
+      return {
+        blocked: true,
+        reason: `qa-guardrail: directiva ${directive} nueva en ${file} bloqueada — el cerco prohíbe desactivar reglas en línea`,
+      };
+    }
+  }
+
+  return { blocked: false };
+}

package/pi/extensions/qa-guardrail/check.ts

@@ -0,0 +1,185 @@
+/**
+ * Full-sweep `/qa-guardrail check`: list every matching file's violations and
+ * inherited `eslint-disable*` directives, without blocking.
+ *
+ * Unlike the tool_result delta feedback, this is a *complete* sweep: it reports
+ * inherited violations too (the migration inventory). Inherited directives are
+ * detected with the same independent regex as the cerco (slice 4) and listed,
+ * never blocked.
+ */
+
+import { readFileSync, readdirSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import type { ConfigLoadResult } from "./config.js";
+import { findProjectRoot, loadConfig } from "./config.js";
+import { findEslintDisableDirectives } from "./cerco.js";
+import { getAdapter } from "./adapters/registry.js";
+import { isFileSelected } from "./selection.js";
+import type { LintAdapter, Violation } from "./types.js";
+
+/** One file with at least one violation or inherited directive. */
+export interface CheckFinding {
+  /** File path relative to `cwd` (posix separators). */
+  file: string;
+  /** Adapter that covered the file. */
+  adapterId: string;
+  violations: Violation[];
+  disableDirectives: string[];
+}
+
+export interface CheckReport {
+  /** False when the config is absent/invalid (gate off). */
+  ok: boolean;
+  /** Gate-off reason when `ok` is false. */
+  reason?: string;
+  findings: CheckFinding[];
+  /** Files assigned to an adapter (selected), whether or not they had findings. */
+  filesScanned: number;
+}
+
+export interface CheckDeps {
+  loadConfig(cwd: string): ConfigLoadResult;
+  getAdapter(id: string): LintAdapter | undefined;
+  findRoot(cwd: string, markers: string[]): string | null;
+  listFiles(root: string): Promise<string[]>;
+  readFile(path: string): string | null;
+  warn(message: string): void;
+}
+
+/** Directories the sweep never descends into (repo hygiene, not config). */
+export const CHECK_SKIP_DIRS: ReadonlySet<string> = new Set(["node_modules", ".git"]);
+
+/** Recursive, cycle-safe file enumeration (absolute paths). */
+export function listFilesSync(root: string): string[] {
+  const out: string[] = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop()!;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const abs = resolve(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (CHECK_SKIP_DIRS.has(entry.name)) continue;
+        stack.push(abs);
+      } else if (entry.isFile()) {
+        out.push(abs);
+      }
+    }
+  }
+  return out;
+}
+
+function toPosix(p: string): string {
+  return p.split("\\").join("/");
+}
+
+/**
+ * Sweep `cwd`: for each enabled tool entry, walk its project root and assign
+ * each selected file to the first entry that covers it (mirrors
+ * `selectAdapterId` first-wins). Then lint each assigned file once and collect
+ * violations plus inherited directives.
+ */
+export async function runCheck(cwd: string, deps: CheckDeps): Promise<CheckReport> {
+  const result = deps.loadConfig(cwd);
+  if (!result.ok) {
+    return { ok: false, reason: result.reason, findings: [], filesScanned: 0 };
+  }
+  const config = result.config;
+
+  const assigned = new Map<string, { adapterId: string; root: string }>();
+
+  for (const entry of config.tools) {
+    if (entry.enabled === false) continue;
+    const root = deps.findRoot(cwd, entry.rootMarkers) ?? cwd;
+    let files: string[];
+    try {
+      files = await deps.listFiles(root);
+    } catch (err) {
+      deps.warn(`qa-guardrail: no se pudo barrer ${root} — ${String(err)}`);
+      continue;
+    }
+    for (const abs of files) {
+      if (assigned.has(abs)) continue;
+      if (isFileSelected(abs, entry, cwd)) {
+        assigned.set(abs, { adapterId: entry.id, root });
+      }
+    }
+  }
+
+  const findings: CheckFinding[] = [];
+
+  for (const [abs, info] of assigned) {
+    const adapter = deps.getAdapter(info.adapterId);
+    if (!adapter) {
+      deps.warn(`qa-guardrail: adaptador no registrado — ${info.adapterId}`);
+      continue;
+    }
+
+    let violations: Violation[] = [];
+    try {
+      violations = await adapter.lint(abs, { root: info.root, cwd });
+    } catch (err) {
+      deps.warn(`qa-guardrail: lint falló para ${abs} — ${String(err)}`);
+    }
+
+    const content = deps.readFile(abs) ?? "";
+    const disableDirectives = findEslintDisableDirectives(content);
+
+    if (violations.length > 0 || disableDirectives.length > 0) {
+      findings.push({
+        file: toPosix(relative(resolve(cwd), abs)),
+        adapterId: info.adapterId,
+        violations,
+        disableDirectives,
+      });
+    }
+  }
+
+  return { ok: true, findings, filesScanned: assigned.size };
+}
+
+/** Compact, human/agent-readable report for the check command. */
+export function formatCheckReport(cwd: string, report: CheckReport): string {
+  if (!report.ok) {
+    return `qa-guardrail: check no disponible — ${report.reason ?? "config ausente"}`;
+  }
+  if (report.findings.length === 0) {
+    return `qa-guardrail: check — ${report.filesScanned} archivos barridos, sin violaciones ni directivas heredadas.`;
+  }
+
+  const header = `qa-guardrail: check — ${report.findings.length} archivo(s) con hallazgos (${report.filesScanned} barridos).`;
+  const lines: string[] = [header];
+  for (const finding of report.findings) {
+    lines.push(`\n${finding.file} (${finding.adapterId}):`);
+    for (const v of finding.violations) {
+      const rule = v.ruleId ?? "parse-error";
+      lines.push(`- ${rule} (${v.line}:${v.column}) ${v.message}`);
+    }
+    for (const directive of finding.disableDirectives) {
+      lines.push(`- directiva heredada: ${directive}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Real dependencies for the extension's own `/qa-guardrail check` command. */
+export const defaultCheckDeps: CheckDeps = {
+  loadConfig,
+  getAdapter,
+  findRoot: (cwd, markers) => findProjectRoot(cwd, markers),
+  listFiles: async (root) => listFilesSync(root),
+  readFile: (path) => {
+    try {
+      return readFileSync(path, "utf8");
+    } catch {
+      return null;
+    }
+  },
+  warn: (message) => console.warn(message),
+};