terramend 0.2.0

package/src/prep/installPythonDependencies.test.ts

@@ -0,0 +1,268 @@
+import { join } from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { installPythonDependencies } from "#app/prep/installPythonDependencies";
+import type { PrepOptions } from "#app/prep/types";
+
+vi.mock("node:fs", () => ({
+  existsSync: vi.fn(() => false),
+}));
+
+vi.mock("#app/utils/cli", () => ({
+  log: {
+    info: vi.fn(),
+    debug: vi.fn(),
+    warning: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+    startGroup: vi.fn(),
+    endGroup: vi.fn(),
+  },
+}));
+
+vi.mock("#app/utils/subprocess", () => ({
+  spawn: vi.fn(),
+}));
+
+import { existsSync } from "node:fs";
+import type { PythonPrepResult } from "#app/prep/types";
+import { spawn } from "#app/utils/subprocess";
+
+const existsSyncMock = vi.mocked(existsSync);
+const spawnMock = vi.mocked(spawn);
+
+const options: PrepOptions = { ignoreScripts: false, binDir: "/tmp/run/pm-bin" };
+
+type SpawnArg = Parameters<typeof spawn>[0];
+
+function spawnResult(init: { exitCode?: number; stdout?: string; stderr?: string } = {}) {
+  return {
+    exitCode: init.exitCode ?? 0,
+    stdout: init.stdout ?? "",
+    stderr: init.stderr ?? "",
+    durationMs: 1,
+  };
+}
+
+/** make only the given files exist in cwd */
+function filesPresent(...names: string[]) {
+  const paths = new Set(names.map((name) => join(process.cwd(), name)));
+  existsSyncMock.mockImplementation((path) => paths.has(String(path)));
+}
+
+/** answer `which <name>` probes by availability; everything else by handler */
+function routeSpawn(params: {
+  available?: string[];
+  handlers?: Record<string, (call: SpawnArg) => ReturnType<typeof spawnResult>>;
+}) {
+  const available = new Set(params.available ?? []);
+  spawnMock.mockImplementation(async (call) => {
+    if (call.cmd === "which") {
+      return spawnResult({ exitCode: available.has(call.args[0] ?? "") ? 0 : 1 });
+    }
+    const handler = params.handlers?.[call.cmd];
+    if (!handler) throw new Error(`unexpected spawn: ${call.cmd} ${call.args.join(" ")}`);
+    return handler(call);
+  });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+/** run() is typed as the PrepResult union; narrow to the python shape */
+async function runPython(opts: PrepOptions): Promise<PythonPrepResult> {
+  const result = await installPythonDependencies.run(opts);
+  if (result.language !== "python") {
+    throw new Error(`expected a python prep result, got ${result.language}`);
+  }
+  return result;
+}
+
+describe("installPythonDependencies.shouldRun", () => {
+  it("is false when no python interpreter is available", async () => {
+    routeSpawn({ available: [] });
+    await expect(installPythonDependencies.shouldRun()).resolves.toBe(false);
+    expect(existsSyncMock).not.toHaveBeenCalled();
+  });
+
+  it("is false with python but no config file", async () => {
+    routeSpawn({ available: ["python3"] });
+    filesPresent();
+    await expect(installPythonDependencies.shouldRun()).resolves.toBe(false);
+  });
+
+  it("is true with a fallback `python` binary and a requirements.txt", async () => {
+    routeSpawn({ available: ["python"] });
+    filesPresent("requirements.txt");
+    await expect(installPythonDependencies.shouldRun()).resolves.toBe(true);
+  });
+});
+
+describe("installPythonDependencies.run", () => {
+  it("reports an issue when no config file is found", async () => {
+    filesPresent();
+    const result = await runPython(options);
+    expect(result).toEqual({
+      language: "python",
+      packageManager: "pip",
+      configFile: "unknown",
+      dependenciesInstalled: false,
+      issues: ["no python config file found"],
+    });
+  });
+
+  it("skips installation entirely when shell is disabled", async () => {
+    filesPresent("requirements.txt");
+    const result = await runPython({ ...options, ignoreScripts: true });
+    expect(result.dependenciesInstalled).toBe(false);
+    expect(result.configFile).toBe("requirements.txt");
+    expect(result.issues[0]).toContain("can execute arbitrary code");
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it("installs requirements.txt via pip when pip is available", async () => {
+    filesPresent("requirements.txt");
+    const pipCalls: SpawnArg[] = [];
+    routeSpawn({
+      available: ["pip"],
+      handlers: {
+        pip: (call) => {
+          pipCalls.push(call);
+          return spawnResult({ stdout: "installed" });
+        },
+      },
+    });
+
+    const result = await runPython(options);
+
+    expect(pipCalls[0]?.args).toEqual(["install", "-r", "requirements.txt"]);
+    expect(result).toEqual({
+      language: "python",
+      packageManager: "pip",
+      configFile: "requirements.txt",
+      dependenciesInstalled: true,
+      issues: [],
+    });
+  });
+
+  it("prefers requirements.txt over later configs in priority order", async () => {
+    filesPresent("requirements.txt", "pyproject.toml", "Pipfile");
+    routeSpawn({ available: ["pip"], handlers: { pip: () => spawnResult() } });
+    const result = await runPython(options);
+    expect(result.configFile).toBe("requirements.txt");
+  });
+
+  it("installs a missing tool (pipenv) before running its install command", async () => {
+    filesPresent("Pipfile");
+    const pipCalls: SpawnArg[] = [];
+    const pipenvCalls: SpawnArg[] = [];
+    routeSpawn({
+      available: [],
+      handlers: {
+        pip: (call) => {
+          pipCalls.push(call);
+          return spawnResult();
+        },
+        pipenv: (call) => {
+          pipenvCalls.push(call);
+          return spawnResult();
+        },
+      },
+    });
+
+    const result = await runPython(options);
+
+    expect(pipCalls[0]?.args).toEqual(["install", "pipenv"]);
+    expect(pipenvCalls[0]?.args).toEqual(["install"]);
+    expect(result.packageManager).toBe("pipenv");
+    expect(result.dependenciesInstalled).toBe(true);
+  });
+
+  it("does not attempt to install pip itself when missing", async () => {
+    filesPresent("setup.py");
+    const pipCalls: SpawnArg[] = [];
+    routeSpawn({
+      available: [],
+      handlers: {
+        pip: (call) => {
+          pipCalls.push(call);
+          return spawnResult();
+        },
+      },
+    });
+
+    const result = await runPython(options);
+
+    // only the editable install ran — no `pip install pip` bootstrap
+    expect(pipCalls).toHaveLength(1);
+    expect(pipCalls[0]?.args).toEqual(["install", "-e", "."]);
+    expect(result.dependenciesInstalled).toBe(true);
+  });
+
+  it("surfaces tool installation failures as issues", async () => {
+    filesPresent("poetry.lock");
+    routeSpawn({
+      available: [],
+      handlers: {
+        pip: (call) => {
+          // exercise the stderr-forwarding callback
+          call.onStderr?.("");
+          return spawnResult({ exitCode: 1, stderr: "no network" });
+        },
+      },
+    });
+
+    const result = await runPython(options);
+
+    expect(result).toEqual({
+      language: "python",
+      packageManager: "poetry",
+      configFile: "poetry.lock",
+      dependenciesInstalled: false,
+      issues: ["no network"],
+    });
+  });
+
+  it("falls back to a generic message when tool install fails silently", async () => {
+    filesPresent("Pipfile.lock");
+    routeSpawn({
+      available: [],
+      handlers: {
+        pip: () => spawnResult({ exitCode: 1 }),
+      },
+    });
+
+    const result = await runPython(options);
+
+    expect(result.issues).toEqual(["failed to install pipenv"]);
+  });
+
+  it("reports install command failures with combined output", async () => {
+    filesPresent("pyproject.toml");
+    routeSpawn({
+      available: ["pip"],
+      handlers: {
+        pip: () => spawnResult({ exitCode: 2, stdout: "resolving...", stderr: "conflict" }),
+      },
+    });
+
+    const result = await runPython(options);
+
+    expect(result.dependenciesInstalled).toBe(false);
+    expect(result.issues).toEqual(["resolving...\nconflict"]);
+  });
+
+  it("reports the exit code when a failing install produces no output", async () => {
+    filesPresent("pyproject.toml");
+    routeSpawn({
+      available: ["pip"],
+      handlers: {
+        pip: () => spawnResult({ exitCode: 3 }),
+      },
+    });
+
+    const result = await runPython(options);
+
+    expect(result.issues).toEqual(["pip exited with code 3"]);
+  });
+});

package/src/prep/installPythonDependencies.ts

@@ -0,0 +1,199 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  PrepDefinition,
+  PrepOptions,
+  PythonPackageManager,
+  PythonPrepResult,
+} from "#app/prep/types";
+import { log } from "#app/utils/cli";
+import { spawn } from "#app/utils/subprocess";
+
+interface PythonConfig {
+  file: string;
+  tool: PythonPackageManager;
+  // non-empty: the first element is the executable, the rest are args
+  installCmd: [string, ...string[]];
+}
+
+// python dependency file patterns in priority order
+const PYTHON_CONFIGS: PythonConfig[] = [
+  {
+    file: "requirements.txt",
+    tool: "pip",
+    installCmd: ["pip", "install", "-r", "requirements.txt"],
+  },
+  {
+    file: "pyproject.toml",
+    tool: "pip",
+    installCmd: ["pip", "install", "."],
+  },
+  {
+    file: "Pipfile",
+    tool: "pipenv",
+    installCmd: ["pipenv", "install"],
+  },
+  {
+    file: "Pipfile.lock",
+    tool: "pipenv",
+    installCmd: ["pipenv", "sync"],
+  },
+  {
+    file: "poetry.lock",
+    tool: "poetry",
+    installCmd: ["poetry", "install", "--no-interaction"],
+  },
+  {
+    file: "setup.py",
+    tool: "pip",
+    installCmd: ["pip", "install", "-e", "."],
+  },
+];
+
+// tool install commands (via pip). Each command is non-empty (executable + args).
+const TOOL_INSTALL_COMMANDS: Record<string, [string, ...string[]]> = {
+  pipenv: ["pip", "install", "pipenv"],
+  poetry: ["pip", "install", "poetry"],
+};
+
+async function isCommandAvailable(command: string): Promise<boolean> {
+  const result = await spawn({
+    cmd: "which",
+    args: [command],
+    env: { PATH: process.env.PATH || "" },
+  });
+  return result.exitCode === 0;
+}
+
+async function installTool(name: string): Promise<string | null> {
+  const installCmd = TOOL_INSTALL_COMMANDS[name];
+  if (!installCmd) {
+    // tool doesn't need installation (e.g., pip)
+    return null;
+  }
+
+  log.info(`» installing ${name}...`);
+  const [cmd, ...args] = installCmd;
+  const result = await spawn({
+    cmd,
+    args,
+    env: { PATH: process.env.PATH || "", HOME: process.env.HOME || "" },
+    onStderr: (chunk) => process.stderr.write(chunk),
+  });
+
+  if (result.exitCode !== 0) {
+    return result.stderr || `failed to install ${name}`;
+  }
+
+  log.info(`» installed ${name}`);
+  return null;
+}
+
+export const installPythonDependencies: PrepDefinition = {
+  name: "installPythonDependencies",
+
+  shouldRun: async () => {
+    // check if python is available
+    const hasPython = (await isCommandAvailable("python3")) || (await isCommandAvailable("python"));
+    if (!hasPython) {
+      return false;
+    }
+
+    // check if any python config file exists
+    const cwd = process.cwd();
+    return PYTHON_CONFIGS.some((config) => existsSync(join(cwd, config.file)));
+  },
+
+  run: async (options: PrepOptions): Promise<PythonPrepResult> => {
+    const cwd = process.cwd();
+
+    // find the first matching config
+    const config = PYTHON_CONFIGS.find((c) => existsSync(join(cwd, c.file)));
+    if (!config) {
+      return {
+        language: "python",
+        packageManager: "pip",
+        configFile: "unknown",
+        dependenciesInstalled: false,
+        issues: ["no python config file found"],
+      };
+    }
+
+    log.info(`» detected python config: ${config.file} (using ${config.tool})`);
+
+    // SECURITY: when shell is disabled, skip ALL python dependency installation.
+    // every python install path can potentially execute arbitrary code:
+    //   - setup.py / pyproject.toml: directly execute build backends
+    //   - requirements.txt: can contain "-e ." or local path references that
+    //     trigger setup.py execution
+    //   - Pipfile/poetry.lock: can contain path dependencies pointing to local
+    //     directories with malicious setup.py
+    //   - source distributions from PyPI also execute setup.py
+    // there is no equivalent of npm's --ignore-scripts for pip.
+    if (options.ignoreScripts) {
+      log.info(
+        `» skipping python install (shell disabled, python packages can execute arbitrary code)`,
+      );
+      return {
+        language: "python",
+        packageManager: config.tool,
+        configFile: config.file,
+        dependenciesInstalled: false,
+        issues: [
+          `skipped: python dependency installation can execute arbitrary code (setup.py, build backends, local path references), which is blocked when shell is disabled`,
+        ],
+      };
+    }
+
+    // check if the tool is available, install if needed
+    const isAvailable = await isCommandAvailable(config.tool);
+    if (!isAvailable) {
+      log.info(`» ${config.tool} not found, attempting to install...`);
+      const installError = await installTool(config.tool);
+      if (installError) {
+        return {
+          language: "python",
+          packageManager: config.tool,
+          configFile: config.file,
+          dependenciesInstalled: false,
+          issues: [installError],
+        };
+      }
+    }
+
+    // run the install command
+    const [cmd, ...args] = config.installCmd;
+    const fullCommand = `${cmd} ${args.join(" ")}`;
+    log.info(`» running: ${fullCommand}`);
+    const result = await spawn({
+      cmd,
+      args,
+      env: { PATH: process.env.PATH || "", HOME: process.env.HOME || "" },
+    });
+
+    const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    if (output) {
+      log.startGroup(`${fullCommand} output`);
+      log.info(output);
+      log.endGroup();
+    }
+
+    if (result.exitCode !== 0) {
+      return {
+        language: "python",
+        packageManager: config.tool,
+        configFile: config.file,
+        dependenciesInstalled: false,
+        issues: [output || `${cmd} exited with code ${result.exitCode}`],
+      };
+    }
+
+    return {
+      language: "python",
+      packageManager: config.tool,
+      configFile: config.file,
+      dependenciesInstalled: true,
+      issues: [],
+    };
+  },
+};

package/src/prep/types.ts

@@ -0,0 +1,38 @@
+interface PrepResultBase {
+  dependenciesInstalled: boolean;
+  issues: string[];
+}
+
+export type NodePackageManager = "npm" | "pnpm" | "yarn" | "bun" | "deno";
+
+export interface NodePrepResult extends PrepResultBase {
+  language: "node";
+  packageManager: NodePackageManager;
+}
+
+export type PythonPackageManager = "pip" | "pipenv" | "poetry";
+
+export interface PythonPrepResult extends PrepResultBase {
+  language: "python";
+  packageManager: PythonPackageManager;
+  configFile: string;
+}
+
+export interface UnknownLanguagePrepResult extends PrepResultBase {
+  language: "unknown";
+}
+
+export type PrepResult = NodePrepResult | PythonPrepResult | UnknownLanguagePrepResult;
+
+export type PrepOptions = {
+  /** when true, lifecycle scripts (postinstall, etc.) are suppressed */
+  ignoreScripts: boolean;
+  /** directory the corepack shim is installed into (see `packageManagerBinDir`) */
+  binDir: string;
+};
+
+export interface PrepDefinition {
+  name: string;
+  shouldRun: () => Promise<boolean> | boolean;
+  run: (options: PrepOptions) => Promise<PrepResult>;
+}

package/src/reviewQuality.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import {
+  FINDING_VERIFICATION_PASS,
+  FP_PRECEDENTS_ADDENDUM_HEADING,
+  mergeReviewModeInstructions,
+} from "#app/reviewQuality";
+
+describe("mergeReviewModeInstructions", () => {
+  it("returns the base untouched when neither input is set", () => {
+    const base = { Review: "backend rules", Build: "build rules" };
+    expect(mergeReviewModeInstructions(base, {})).toBe(base);
+    expect(mergeReviewModeInstructions(base, { reviewInstructions: "  " })).toBe(base);
+  });
+
+  it("appends review instructions after backend-provided ones", () => {
+    const merged = mergeReviewModeInstructions(
+      { Review: "backend rules" },
+      { reviewInstructions: "org policy" },
+    );
+    expect(merged.Review).toBe("backend rules\n\norg policy");
+  });
+
+  it("wraps FP instructions under the addendum heading the verification pass names", () => {
+    const merged = mergeReviewModeInstructions(
+      {},
+      { fpFilteringInstructions: "TLS terminates at the ALB" },
+    );
+    expect(merged.Review).toContain(FP_PRECEDENTS_ADDENDUM_HEADING);
+    expect(merged.Review).toContain("TLS terminates at the ALB");
+    expect(merged.Review).toContain("verbatim in every verification dispatch");
+  });
+
+  it("keeps order: backend, review policy, then the FP addendum last", () => {
+    const merged = mergeReviewModeInstructions(
+      { Review: "backend" },
+      { reviewInstructions: "policy", fpFilteringInstructions: "fp" },
+    );
+    const text = merged.Review ?? "";
+    expect(text.indexOf("backend")).toBeLessThan(text.indexOf("policy"));
+    expect(text.indexOf("policy")).toBeLessThan(text.indexOf(FP_PRECEDENTS_ADDENDUM_HEADING));
+  });
+
+  it("does not touch other modes", () => {
+    const merged = mergeReviewModeInstructions(
+      { Build: "build rules" },
+      { reviewInstructions: "org policy" },
+    );
+    expect(merged.Build).toBe("build rules");
+    expect(merged.Review).toBe("org policy");
+  });
+});
+
+describe("addendum heading contract", () => {
+  it("the verification pass names the exact heading the merge produces", () => {
+    // FINDING_VERIFICATION_PASS instructs the orchestrator to include any
+    // "Finding precedents — org addendum" section verbatim in dispatches; the
+    // heading the merge emits must match that pointer or org FP rules never
+    // reach the verification subagents.
+    expect(FINDING_VERIFICATION_PASS).toContain(
+      FP_PRECEDENTS_ADDENDUM_HEADING.replace(/^### /, ""),
+    );
+  });
+});