terramend 0.2.0

package/src/prep/index.ts

@@ -0,0 +1,43 @@
+import { performance } from "node:perf_hooks";
+import { installNodeDependencies } from "#app/prep/installNodeDependencies";
+import { installPythonDependencies } from "#app/prep/installPythonDependencies";
+import type { PrepDefinition, PrepOptions, PrepResult } from "#app/prep/types";
+import { log } from "#app/utils/cli";
+
+export type { PrepOptions, PrepResult } from "#app/prep/types";
+
+// register all prep steps here
+const prepSteps: PrepDefinition[] = [installNodeDependencies, installPythonDependencies];
+
+/**
+ * run all prep steps sequentially.
+ * failures are logged as warnings but don't stop the run.
+ */
+export async function runPrepPhase(options: PrepOptions): Promise<PrepResult[]> {
+  log.debug("» starting prep phase...");
+  const startTime = performance.now();
+  const results: PrepResult[] = [];
+
+  for (const step of prepSteps) {
+    const shouldRun = await step.shouldRun();
+    if (!shouldRun) {
+      log.debug(`» skipping ${step.name} (not applicable)`);
+      continue;
+    }
+
+    log.debug(`» running ${step.name}...`);
+    const result = await step.run(options);
+    results.push(result);
+
+    if (result.dependenciesInstalled) {
+      log.debug(`» ${step.name}: dependencies installed`);
+    } else if (result.issues.length > 0) {
+      log.warning(`» ${step.name}: ${result.issues[0]}`);
+    }
+  }
+
+  const totalDurationMs = performance.now() - startTime;
+  log.debug(`» prep phase completed (${Math.round(totalDurationMs)}ms)`);
+
+  return results;
+}

package/src/prep/installNodeDependencies.test.ts

@@ -0,0 +1,298 @@
+import { join } from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { installNodeDependencies } from "#app/prep/installNodeDependencies";
+import type { PrepOptions } from "#app/prep/types";
+
+vi.mock("node:fs", () => ({
+  existsSync: vi.fn(() => false),
+}));
+
+vi.mock("package-manager-detector", () => ({
+  detect: vi.fn(async () => null),
+}));
+
+vi.mock("package-manager-detector/commands", () => ({
+  resolveCommand: vi.fn(),
+}));
+
+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/packageManager", () => ({
+  ensurePackageManager: vi.fn(async () => false),
+  resolvePackageManagerSpec: vi.fn(async () => null),
+}));
+
+vi.mock("#app/utils/subprocess", () => ({
+  spawn: vi.fn(),
+}));
+
+import { existsSync } from "node:fs";
+import { detect } from "package-manager-detector";
+import { resolveCommand } from "package-manager-detector/commands";
+import { ensurePackageManager, resolvePackageManagerSpec } from "#app/utils/packageManager";
+import { spawn } from "#app/utils/subprocess";
+
+const existsSyncMock = vi.mocked(existsSync);
+const detectMock = vi.mocked(detect);
+const resolveCommandMock = vi.mocked(resolveCommand);
+const ensurePackageManagerMock = vi.mocked(ensurePackageManager);
+const resolveSpecMock = vi.mocked(resolvePackageManagerSpec);
+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,
+  };
+}
+
+/** route spawn calls by command so test setup reads as a behavior table */
+function routeSpawn(handlers: Record<string, (call: SpawnArg) => ReturnType<typeof spawnResult>>) {
+  spawnMock.mockImplementation(async (call) => {
+    const handler = handlers[call.cmd];
+    if (!handler) throw new Error(`unexpected spawn: ${call.cmd} ${call.args.join(" ")}`);
+    return handler(call);
+  });
+}
+
+function whichAvailable(available: boolean) {
+  return () => spawnResult({ exitCode: available ? 0 : 1 });
+}
+
+function declaredSpec(overrides: Partial<{ name: string; version: string }> = {}) {
+  return {
+    name: "pnpm",
+    version: "11.1.1",
+    concrete: true,
+    source: "packageManager",
+    ...overrides,
+  } as NonNullable<Awaited<ReturnType<typeof resolvePackageManagerSpec>>>;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  detectMock.mockResolvedValue(null);
+  resolveSpecMock.mockResolvedValue(null);
+  ensurePackageManagerMock.mockResolvedValue(false);
+});
+
+describe("installNodeDependencies.shouldRun", () => {
+  it("runs only when package.json exists in cwd", () => {
+    existsSyncMock.mockReturnValueOnce(true);
+    expect(installNodeDependencies.shouldRun()).toBe(true);
+    existsSyncMock.mockReturnValueOnce(false);
+    expect(installNodeDependencies.shouldRun()).toBe(false);
+  });
+});
+
+describe("installNodeDependencies.run", () => {
+  it("skips install when no lockfile is detected (default npm path)", async () => {
+    routeSpawn({ which: whichAvailable(true) });
+
+    const result = await installNodeDependencies.run(options);
+
+    expect(result).toEqual({
+      language: "node",
+      packageManager: "npm",
+      dependenciesInstalled: false,
+      issues: [],
+    });
+    // only the availability probe ran — no installer
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails fast when the manager is missing and shell is disabled", async () => {
+    detectMock.mockResolvedValue({ name: "pnpm", agent: "pnpm" });
+    routeSpawn({ which: whichAvailable(false) });
+
+    const result = await installNodeDependencies.run({ ...options, ignoreScripts: true });
+
+    expect(result.dependenciesInstalled).toBe(false);
+    expect(result.issues[0]).toContain("cannot be installed when shell is disabled");
+  });
+
+  it("provisions a declared manager via corepack and runs the frozen install", async () => {
+    resolveSpecMock.mockResolvedValue(declaredSpec());
+    detectMock.mockResolvedValue({ name: "pnpm", agent: "pnpm" });
+    ensurePackageManagerMock.mockResolvedValue(true);
+    resolveCommandMock.mockReturnValue({ command: "pnpm", args: ["install", "--frozen-lockfile"] });
+    routeSpawn({
+      which: whichAvailable(false),
+      pnpm: () => spawnResult({ stdout: "done" }),
+    });
+
+    const result = await installNodeDependencies.run(options);
+
+    expect(ensurePackageManagerMock).toHaveBeenCalledWith({
+      spec: declaredSpec(),
+      binDir: options.binDir,
+    });
+    expect(result).toEqual({
+      language: "node",
+      packageManager: "pnpm",
+      dependenciesInstalled: true,
+      issues: [],
+    });
+  });
+
+  it("re-pins an already-available declared manager before installing", async () => {
+    resolveSpecMock.mockResolvedValue(declaredSpec());
+    detectMock.mockResolvedValue({ name: "pnpm", agent: "pnpm" });
+    resolveCommandMock.mockReturnValue({ command: "pnpm", args: ["install", "--frozen-lockfile"] });
+    routeSpawn({
+      which: whichAvailable(true),
+      pnpm: () => spawnResult(),
+    });
+
+    const result = await installNodeDependencies.run(options);
+
+    expect(ensurePackageManagerMock).toHaveBeenCalledTimes(1);
+    expect(result.dependenciesInstalled).toBe(true);
+  });
+
+  it("falls back to npm install -g when corepack cannot provision", async () => {
+    resolveSpecMock.mockResolvedValue(declaredSpec({ name: "bun", version: "1.3.0" }));
+    detectMock.mockResolvedValue({ name: "bun", agent: "bun" });
+    ensurePackageManagerMock.mockResolvedValue(false);
+    resolveCommandMock.mockReturnValue({ command: "bun", args: ["install", "--frozen-lockfile"] });
+    const npmCalls: SpawnArg[] = [];
+    routeSpawn({
+      which: whichAvailable(false),
+      npm: (call) => {
+        npmCalls.push(call);
+        return spawnResult();
+      },
+      bun: () => spawnResult(),
+    });
+
+    const result = await installNodeDependencies.run(options);
+
+    expect(npmCalls[0]?.args).toEqual(["install", "-g", "bun@1.3.0"]);
+    expect(result.dependenciesInstalled).toBe(true);
+  });
+
+  it("surfaces fallback installer failures as issues", async () => {
+    detectMock.mockResolvedValue({ name: "yarn", agent: "yarn" });
+    routeSpawn({
+      which: whichAvailable(false),
+      npm: (call) => {
+        // exercise the stderr-forwarding callback
+        call.onStderr?.("");
+        return spawnResult({ exitCode: 1, stderr: "registry down" });
+      },
+    });
+
+    const result = await installNodeDependencies.run(options);
+
+    expect(result).toEqual({
+      language: "node",
+      packageManager: "yarn",
+      dependenciesInstalled: false,
+      issues: ["registry down"],
+    });
+  });
+
+  it("installs deno via curl and prepends its bin dir to PATH", async () => {
+    const originalPath = process.env.PATH;
+    const originalHome = process.env.HOME;
+    vi.stubEnv("HOME", "/home/runner");
+    vi.stubEnv("PATH", "/usr/bin");
+    try {
+      detectMock.mockResolvedValue({ name: "deno", agent: "deno" });
+      resolveCommandMock.mockReturnValue({ command: "deno", args: ["install", "--frozen"] });
+      const shCalls: SpawnArg[] = [];
+      routeSpawn({
+        which: whichAvailable(false),
+        sh: (call) => {
+          shCalls.push(call);
+          return spawnResult();
+        },
+        deno: () => spawnResult(),
+      });
+
+      const result = await installNodeDependencies.run(options);
+
+      expect(shCalls[0]?.args).toEqual(["-c", "curl -fsSL https://deno.land/install.sh | sh"]);
+      const denoBin = join("/home/runner", ".deno", "bin");
+      expect(process.env.PATH?.startsWith(`${denoBin}:`)).toBe(true);
+      expect(result.dependenciesInstalled).toBe(true);
+    } finally {
+      vi.unstubAllEnvs();
+      process.env.PATH = originalPath;
+      process.env.HOME = originalHome;
+    }
+  });
+
+  it("reports an issue when no frozen-install command exists for the agent", async () => {
+    detectMock.mockResolvedValue({ name: "npm", agent: "npm" });
+    resolveCommandMock.mockReturnValue(null);
+    routeSpawn({ which: whichAvailable(true) });
+
+    const result = await installNodeDependencies.run(options);
+
+    expect(result.issues).toEqual(["no frozen-install command available for npm"]);
+  });
+
+  it("appends --ignore-scripts when shell is disabled", async () => {
+    detectMock.mockResolvedValue({ name: "npm", agent: "npm" });
+    resolveCommandMock.mockReturnValue({ command: "npm", args: ["ci"] });
+    const npmCalls: SpawnArg[] = [];
+    routeSpawn({
+      which: whichAvailable(true),
+      npm: (call) => {
+        npmCalls.push(call);
+        return spawnResult();
+      },
+    });
+
+    const result = await installNodeDependencies.run({ ...options, ignoreScripts: true });
+
+    expect(npmCalls[0]?.args).toEqual(["ci", "--ignore-scripts"]);
+    expect(result.dependenciesInstalled).toBe(true);
+  });
+
+  it("returns the command output as an issue when the install fails", async () => {
+    detectMock.mockResolvedValue({ name: "npm", agent: "npm" });
+    resolveCommandMock.mockReturnValue({ command: "npm", args: ["ci"] });
+    routeSpawn({
+      which: whichAvailable(true),
+      npm: () => spawnResult({ exitCode: 1, stdout: "npm ERR!", stderr: "lockfile out of sync" }),
+    });
+
+    const result = await installNodeDependencies.run(options);
+
+    expect(result.dependenciesInstalled).toBe(false);
+    expect(result.issues[0]).toContain("`npm ci` failed:");
+    expect(result.issues[0]).toContain("npm ERR!");
+    expect(result.issues[0]).toContain("lockfile out of sync");
+  });
+
+  it("reports the exit code when a failing install produces no output", async () => {
+    detectMock.mockResolvedValue({ name: "npm", agent: "npm" });
+    resolveCommandMock.mockReturnValue({ command: "npm", args: ["ci"] });
+    routeSpawn({
+      which: whichAvailable(true),
+      npm: () => spawnResult({ exitCode: 7 }),
+    });
+
+    const result = await installNodeDependencies.run(options);
+
+    expect(result.issues[0]).toContain("exited with code 7");
+  });
+});

package/src/prep/installNodeDependencies.ts

@@ -0,0 +1,196 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { detect } from "package-manager-detector";
+import { resolveCommand } from "package-manager-detector/commands";
+import type {
+  NodePackageManager,
+  NodePrepResult,
+  PrepDefinition,
+  PrepOptions,
+} from "#app/prep/types";
+import { log } from "#app/utils/cli";
+import { ensurePackageManager, resolvePackageManagerSpec } from "#app/utils/packageManager";
+import { spawn } from "#app/utils/subprocess";
+
+async function isCommandAvailable(command: string): Promise<boolean> {
+  const result = await spawn({
+    cmd: "which",
+    args: [command],
+    env: { PATH: process.env.PATH || "" },
+  });
+  return result.exitCode === 0;
+}
+
+// fallback installers for managers corepack doesn't ship shims for.
+// pnpm and yarn are handled by `ensurePackageManager` (corepack); bun and
+// deno fall through to here because corepack ignores them.
+async function installFallback(
+  name: NodePackageManager,
+  installSpec: string,
+): Promise<string | null> {
+  if (name === "npm") return null;
+  log.info(`» installing ${installSpec} via npm install -g (corepack does not manage ${name})`);
+  const args =
+    name === "deno"
+      ? ["-c", "curl -fsSL https://deno.land/install.sh | sh"]
+      : ["install", "-g", installSpec];
+  const cmd = name === "deno" ? "sh" : "npm";
+  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}`;
+  }
+  if (name === "deno") {
+    const denoPath = join(process.env.HOME || "", ".deno", "bin");
+    process.env.PATH = `${denoPath}:${process.env.PATH}`;
+  }
+  log.info(`» installed ${name}`);
+  return null;
+}
+
+export const installNodeDependencies: PrepDefinition = {
+  name: "installNodeDependencies",
+
+  shouldRun: () => {
+    const packageJsonPath = join(process.cwd(), "package.json");
+    return existsSync(packageJsonPath);
+  },
+
+  run: async (options: PrepOptions): Promise<NodePrepResult> => {
+    // prefer the project's declared spec (devEngines.packageManager wins over
+    // packageManager). fall back to lockfile detection when nothing is declared.
+    // restrict detect() to the lockfile strategy: `detected` here doubles as
+    // the lockfile-presence gate below, and the default strategy set also
+    // returns positives off `packageManager`/`devEngines` fields (which would
+    // mask the very case we're trying to detect — declared manager but no
+    // lockfile committed).
+    const declared = await resolvePackageManagerSpec(process.cwd());
+    const detected = await detect({ cwd: process.cwd(), strategies: ["lockfile"] });
+
+    const packageManager: NodePackageManager =
+      declared?.name ?? (detected?.name as NodePackageManager) ?? "npm";
+    const agent = detected?.agent ?? packageManager;
+
+    if (declared) {
+      log.info(
+        `» using ${packageManager}@${declared.version} from package.json (${declared.source})`,
+      );
+    } else if (detected) {
+      log.info(`» detected package manager: ${packageManager} (${agent})`);
+    } else {
+      log.info(`» no package manager declared, defaulting to npm`);
+    }
+
+    // provisioning: corepack for pnpm/yarn, legacy npm-install-g for bun/deno.
+    // when shell is disabled we can't run installers (they execute code), so
+    // we require the binary to already be on PATH.
+    if (!(await isCommandAvailable(packageManager))) {
+      if (options.ignoreScripts) {
+        return {
+          language: "node",
+          packageManager,
+          dependenciesInstalled: false,
+          issues: [
+            `${packageManager} is not available and cannot be installed when shell is disabled (would execute code)`,
+          ],
+        };
+      }
+
+      let provisioned = false;
+      if (declared)
+        provisioned = await ensurePackageManager({ spec: declared, binDir: options.binDir });
+      if (!provisioned) {
+        const fallbackSpec = declared ? `${declared.name}@${declared.version}` : packageManager;
+        const installError = await installFallback(packageManager, fallbackSpec);
+        if (installError) {
+          return {
+            language: "node",
+            packageManager,
+            dependenciesInstalled: false,
+            issues: [installError],
+          };
+        }
+      }
+    } else if (declared) {
+      // PATH already has the binary — but it may be the wrong version.
+      // ensurePackageManager is idempotent (caches on `--version` match) so
+      // this is cheap when main.ts already activated it.
+      await ensurePackageManager({ spec: declared, binDir: options.binDir });
+    }
+
+    // frozen-lockfile install only. eager prep is non-mutating by contract:
+    // we run it before the agent starts and any artifact it leaves in the
+    // tree (e.g. a generated `package-lock.json`) trips the dirty-tree
+    // post-run gate and produces a spurious PR. `frozen` commands
+    // (`npm ci`, `pnpm install --frozen-lockfile`, etc.) were assumed to
+    // fail cleanly without a lockfile — that assumption is false for
+    // pnpm 11.1.1 against a no-deps `package.json` (it silently writes an
+    // empty `pnpm-lock.yaml` despite the flag). gate on `detect()` having
+    // found a lockfile; it walks up the tree (so monorepo subpackages
+    // resolve to the workspace-root lockfile) and recognizes every
+    // manager's accepted lockfile variants (`bun.lockb` + `bun.lock`,
+    // `npm-shrinkwrap.json` + `package-lock.json`, etc.). when none is
+    // present, the project either has no installable dependencies or
+    // opts into install via a `setup` lifecycle hook
+    // (`action/utils/lifecycle.ts`); either way, eager prep should skip.
+    if (!detected) {
+      log.info(
+        `» skipping ${packageManager} install: no lockfile found (would otherwise risk lockfile drift)`,
+      );
+      return { language: "node", packageManager, dependenciesInstalled: false, issues: [] };
+    }
+
+    const resolved = resolveCommand(agent, "frozen", []);
+    if (!resolved) {
+      return {
+        language: "node",
+        packageManager,
+        dependenciesInstalled: false,
+        issues: [`no frozen-install command available for ${agent}`],
+      };
+    }
+
+    // SECURITY: when shell is disabled, suppress lifecycle scripts to prevent
+    // agents from injecting arbitrary code execution via package.json scripts
+    if (options.ignoreScripts) {
+      resolved.args.push("--ignore-scripts");
+      log.info("» --ignore-scripts enabled (shell disabled)");
+    }
+
+    const fullCommand = `${resolved.command} ${resolved.args.join(" ")}`;
+    log.info(`» running: ${fullCommand}`);
+    const result = await spawn({
+      cmd: resolved.command,
+      args: resolved.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) {
+      const errorMessage = output || `exited with code ${result.exitCode}`;
+      return {
+        language: "node",
+        packageManager,
+        dependenciesInstalled: false,
+        issues: [`\`${fullCommand}\` failed:\n${errorMessage}`],
+      };
+    }
+
+    return {
+      language: "node",
+      packageManager,
+      dependenciesInstalled: true,
+      issues: [],
+    };
+  },
+};