terramend 0.2.0

package/src/utils/packageManager.ts

@@ -0,0 +1,257 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { delimiter, join } from "node:path";
+import semver from "semver";
+import { log } from "#app/utils/cli";
+import { spawn } from "#app/utils/subprocess";
+
+export type SupportedPackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+const SUPPORTED_NAMES: readonly SupportedPackageManager[] = ["npm", "pnpm", "yarn", "bun"];
+
+// corepack ships pnpm + yarn shims out of the box. it does not ship bun or
+// npm (npm comes with node). callers fall back to the legacy npm-install-g
+// path for managers outside this set.
+const COREPACK_MANAGED: readonly SupportedPackageManager[] = ["pnpm", "yarn"];
+
+export interface PackageManagerSpec {
+  name: SupportedPackageManager;
+  /**
+   * either a concrete semver (e.g. "11.1.1") or a range (e.g. "^11.0.0").
+   * `concrete` distinguishes — corepack only accepts concrete versions.
+   */
+  version: string;
+  concrete: boolean;
+  /** which package.json field this came from */
+  source: "devEngines" | "packageManager";
+}
+
+interface PackageJson {
+  packageManager?: string;
+  devEngines?: {
+    packageManager?: {
+      name?: string;
+      version?: string;
+      onFail?: string;
+    };
+  };
+}
+
+function isSupported(name: string): name is SupportedPackageManager {
+  return (SUPPORTED_NAMES as readonly string[]).includes(name);
+}
+
+function parsePackageManagerField(value: string): PackageManagerSpec | null {
+  // npm spec form is "name@version[+integrity]" — corepack adds the integrity
+  // suffix; we strip it because it's not a semver.
+  const withoutHash = value.split("+")[0]!;
+  const at = withoutHash.lastIndexOf("@");
+  if (at <= 0) return null;
+  const name = withoutHash.slice(0, at);
+  const version = withoutHash.slice(at + 1);
+  if (!isSupported(name)) {
+    log.warning(`» unknown packageManager in package.json: ${value}`);
+    return null;
+  }
+  return {
+    name,
+    version,
+    concrete: semver.valid(version) !== null,
+    source: "packageManager",
+  };
+}
+
+function parseDevEnginesField(
+  field: NonNullable<NonNullable<PackageJson["devEngines"]>["packageManager"]>,
+): PackageManagerSpec | null {
+  if (!field.name || !field.version) return null;
+  if (!isSupported(field.name)) {
+    log.warning(`» unknown devEngines.packageManager.name in package.json: ${field.name}`);
+    return null;
+  }
+  const version = field.version.trim();
+  return {
+    name: field.name,
+    version,
+    concrete: semver.valid(version) !== null,
+    source: "devEngines",
+  };
+}
+
+/**
+ * resolve the project's intended package manager from package.json. precedence
+ * matches pnpm 11+: `devEngines.packageManager` wins over `packageManager`.
+ * when both are present, a concrete `packageManager` that satisfies a
+ * `devEngines` range is preferred (we can pin it via corepack); otherwise
+ * we warn on disagreement and stick with `devEngines`.
+ */
+export async function resolvePackageManagerSpec(cwd: string): Promise<PackageManagerSpec | null> {
+  const pkgPath = join(cwd, "package.json");
+  if (!existsSync(pkgPath)) return null;
+
+  let pkg: PackageJson;
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, "utf-8")) as PackageJson;
+  } catch (err) {
+    log.warning(
+      `» failed to parse package.json for package manager resolution: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return null;
+  }
+
+  const devSpec = pkg.devEngines?.packageManager
+    ? parseDevEnginesField(pkg.devEngines.packageManager)
+    : null;
+  const pmSpec = pkg.packageManager?.trim()
+    ? parsePackageManagerField(pkg.packageManager.trim())
+    : null;
+
+  if (!devSpec) return pmSpec;
+  if (!pmSpec) return devSpec;
+
+  if (devSpec.name !== pmSpec.name) {
+    log.warning(
+      `» devEngines.packageManager (${devSpec.name}) disagrees with packageManager (${pmSpec.name}); using devEngines per pnpm 11 precedence`,
+    );
+    return devSpec;
+  }
+
+  // same manager — try to land on a concrete version we can pin via corepack.
+  if (devSpec.concrete) {
+    if (pmSpec.concrete && devSpec.version !== pmSpec.version) {
+      log.warning(
+        `» devEngines.packageManager (${devSpec.version}) disagrees with packageManager (${pmSpec.version}); using devEngines per pnpm 11 precedence`,
+      );
+    }
+    return devSpec;
+  }
+
+  if (pmSpec.concrete && semver.satisfies(pmSpec.version, devSpec.version)) {
+    return pmSpec;
+  }
+
+  if (pmSpec.concrete) {
+    log.warning(
+      `» packageManager (${pmSpec.version}) does not satisfy devEngines range (${devSpec.version}); using devEngines`,
+    );
+  }
+  return devSpec;
+}
+
+interface CorepackResult {
+  exitCode: number;
+  stderr: string;
+}
+
+async function runCorepack(args: string[]): Promise<CorepackResult> {
+  const result = await spawn({
+    cmd: "corepack",
+    args,
+    env: {
+      PATH: process.env.PATH || "",
+      HOME: process.env.HOME || "",
+      COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
+    },
+    onStdout: (chunk) => process.stdout.write(chunk),
+    onStderr: (chunk) => process.stderr.write(chunk),
+  });
+  return { exitCode: result.exitCode, stderr: result.stderr };
+}
+
+async function currentVersion(name: SupportedPackageManager): Promise<string | null> {
+  const result = await spawn({
+    cmd: name,
+    args: ["--version"],
+    env: { PATH: process.env.PATH || "" },
+  });
+  if (result.exitCode !== 0) return null;
+  return result.stdout.trim();
+}
+
+/** the per-run directory the corepack shim is installed into. deliberately
+ * NOT the node bin dir: that's npm's `-g` target, and a corepack shim sitting
+ * there makes a customer setup script's `npm i -g pnpm` abort with EEXIST
+ * (npm refuses to clobber a binary it doesn't own). lives under the run
+ * tmpdir so it's cleaned up with everything else. */
+export function packageManagerBinDir(tmpdir: string): string {
+  return join(tmpdir, "pm-bin");
+}
+
+export interface EnsurePackageManagerParams {
+  spec: PackageManagerSpec;
+  /** directory to install the corepack shim into (see `packageManagerBinDir`).
+   * prepended to PATH so the pinned binary resolves by name. */
+  binDir: string;
+}
+
+/**
+ * ensure the requested package manager is on PATH at the declared version,
+ * provisioning via corepack when applicable. returns true if PATH now
+ * resolves to that version, false if we couldn't pin it (in which case
+ * the caller should treat PATH as untrusted and may fall back to its
+ * legacy install path).
+ *
+ * the corepack shim is installed into `params.binDir` (prepended to PATH),
+ * not the node bin dir, so a later `npm i -g pnpm` in a setup hook can't
+ * collide with it. our dir wins the PATH lookup, so the pinned version is
+ * also what resolves even if that `npm i -g` succeeds into the node bin dir.
+ *
+ * never throws: network failure, missing corepack, range-only versions —
+ * all degrade to "log warning, return false". the existing PATH binary
+ * still works; we just don't get our version guarantee.
+ */
+export async function ensurePackageManager(params: EnsurePackageManagerParams): Promise<boolean> {
+  const spec = params.spec;
+  if (spec.name === "npm") return true;
+
+  if (!(COREPACK_MANAGED as readonly string[]).includes(spec.name)) {
+    return false;
+  }
+
+  if (!spec.concrete) {
+    log.warning(
+      `» ${spec.name} ${spec.source} version is a range (${spec.version}); corepack requires a concrete pin. leaving PATH unchanged.`,
+    );
+    return false;
+  }
+
+  const existing = await currentVersion(spec.name);
+  if (existing === spec.version) {
+    log.info(`» ${spec.name}@${spec.version} already active`);
+    return true;
+  }
+
+  log.info(
+    `» corepack prepare ${spec.name}@${spec.version} --activate (shim dir: ${params.binDir})`,
+  );
+
+  await mkdir(params.binDir, { recursive: true });
+  const enable = await runCorepack(["enable", "--install-directory", params.binDir, spec.name]);
+  if (enable.exitCode !== 0) {
+    log.warning(
+      `» corepack enable failed (exit ${enable.exitCode}); leaving ${spec.name} from PATH. stderr: ${enable.stderr.trim() || "(empty)"}`,
+    );
+    return false;
+  }
+
+  // shim dir first so `pnpm` resolves to the pinned binary and shadows any
+  // `pnpm` a later `npm i -g pnpm` drops into the node bin dir.
+  process.env.PATH = `${params.binDir}${delimiter}${process.env.PATH ?? ""}`;
+
+  const prepare = await runCorepack(["prepare", `${spec.name}@${spec.version}`, "--activate"]);
+  if (prepare.exitCode !== 0) {
+    log.warning(
+      `» corepack prepare ${spec.name}@${spec.version} failed (exit ${prepare.exitCode}); leaving ${spec.name} from PATH. stderr: ${prepare.stderr.trim() || "(empty)"}`,
+    );
+    return false;
+  }
+
+  const after = await currentVersion(spec.name);
+  if (after !== spec.version) {
+    log.warning(
+      `» corepack activated ${spec.name}@${spec.version} but PATH still resolves to ${after ?? "(missing)"}; continuing anyway`,
+    );
+  }
+
+  return true;
+}

package/src/utils/patchWorkflowRunFields.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import type { AgentUsage } from "#app/agents/shared";
+import { aggregateUsage } from "#app/utils/patchWorkflowRunFields";
+
+const entry = (overrides: Partial<AgentUsage>): AgentUsage => ({
+  agent: "terramend",
+  inputTokens: 0,
+  outputTokens: 0,
+  ...overrides,
+});
+
+describe("aggregateUsage", () => {
+  it("returns empty object for empty input", () => {
+    expect(aggregateUsage([])).toEqual({});
+  });
+
+  it("drops fields that sum to zero so NULL stays 'not reported'", () => {
+    // a run that only recorded input tokens shouldn't write zero into output/cache/cost —
+    // those columns stay NULL so dashboards can tell 'zero' from 'never reported'.
+    expect(aggregateUsage([entry({ inputTokens: 42 })])).toEqual({ inputTokens: 42 });
+  });
+
+  it("sums a single entry with all fields present", () => {
+    expect(
+      aggregateUsage([
+        entry({
+          inputTokens: 100,
+          outputTokens: 50,
+          cacheReadTokens: 1000,
+          cacheWriteTokens: 200,
+          costUsd: 0.12,
+        }),
+      ]),
+    ).toEqual({
+      inputTokens: 100,
+      outputTokens: 50,
+      cacheReadTokens: 1000,
+      cacheWriteTokens: 200,
+      costUsd: 0.12,
+    });
+  });
+
+  it("sums multiple entries across agents", () => {
+    expect(
+      aggregateUsage([
+        entry({
+          agent: "claude",
+          inputTokens: 100,
+          outputTokens: 50,
+          cacheReadTokens: 1000,
+          costUsd: 0.1,
+        }),
+        entry({
+          agent: "terramend",
+          inputTokens: 200,
+          outputTokens: 80,
+          cacheReadTokens: 2000,
+          cacheWriteTokens: 300,
+          costUsd: 0.25,
+        }),
+      ]),
+    ).toEqual({
+      inputTokens: 300,
+      outputTokens: 130,
+      cacheReadTokens: 3000,
+      cacheWriteTokens: 300,
+      // floating-point sum — specifying exact value documents expected precision
+      costUsd: 0.35,
+    });
+  });
+
+  it("treats undefined cache/cost as zero and drops when the sum is still zero", () => {
+    expect(
+      aggregateUsage([
+        entry({ inputTokens: 10, outputTokens: 5 }),
+        entry({ inputTokens: 20, outputTokens: 15 }),
+      ]),
+    ).toEqual({ inputTokens: 30, outputTokens: 20 });
+  });
+
+  it("clamps individual INT fields at INT4_MAX so partial-persist cannot happen", () => {
+    // server-side per-field rejection would silently drop the huge column and
+    // keep the small ones, producing a row with a NULL for the missing metric.
+    // clamping client-side guarantees the wire payload is self-consistent.
+    const result = aggregateUsage([
+      entry({ inputTokens: 3_000_000_000, outputTokens: 42, cacheReadTokens: 5 }),
+    ]);
+    expect(result.inputTokens).toBe(2_147_483_647);
+    expect(result.outputTokens).toBe(42);
+    expect(result.cacheReadTokens).toBe(5);
+  });
+});

package/src/utils/patchWorkflowRunFields.ts

@@ -0,0 +1,150 @@
+import type { AgentUsage } from "#app/agents/shared";
+import type { ToolContext } from "#app/mcp/server";
+import { apiFetch } from "#app/utils/apiFetch";
+import { log } from "#app/utils/cli";
+import { retry } from "#app/utils/retry";
+
+/**
+ * Artifact tracking fields — one-off PATCHes from MCP tools as GitHub entities
+ * are created during the run. Strings only (GraphQL node IDs).
+ * Keep in sync with `STRING_FIELDS` in `app/api/workflow-run/[runId]/route.ts`.
+ */
+export type WorkflowRunArtifactPatchKey =
+  | "prNodeId"
+  | "issueNodeId"
+  | "reviewNodeId"
+  | "planCommentNodeId"
+  | "summarySnapshot";
+
+/**
+ * Usage fields — aggregated across all agent calls and PATCHed once at
+ * end-of-run. Token counts are Int4 on the DB side (ample for any realistic
+ * run); `costUsd` is a Decimal populated by provider-reported dollar amounts.
+ * Keep in sync with `INT_FIELDS` + `DECIMAL_FIELDS` in the server route.
+ */
+export type WorkflowRunUsagePatchKey =
+  | "inputTokens"
+  | "outputTokens"
+  | "cacheReadTokens"
+  | "cacheWriteTokens"
+  | "costUsd";
+
+export type WorkflowRunPatch = Partial<Record<WorkflowRunArtifactPatchKey, string>> &
+  Partial<Record<WorkflowRunUsagePatchKey, number>>;
+
+const STRING_KEYS: WorkflowRunArtifactPatchKey[] = [
+  "prNodeId",
+  "issueNodeId",
+  "reviewNodeId",
+  "planCommentNodeId",
+  "summarySnapshot",
+];
+
+const NUMBER_KEYS: WorkflowRunUsagePatchKey[] = [
+  "inputTokens",
+  "outputTokens",
+  "cacheReadTokens",
+  "cacheWriteTokens",
+  "costUsd",
+];
+
+/** PATCH workflow-run fields (Terramend JWT, not GitHub). */
+export async function patchWorkflowRunFields(
+  ctx: ToolContext,
+  fields: WorkflowRunPatch,
+): Promise<void> {
+  if (ctx.runId === undefined || !ctx.apiToken) return;
+  const body: Record<string, string | number> = {};
+  for (const key of STRING_KEYS) {
+    const value = fields[key];
+    if (typeof value === "string" && value.length > 0) {
+      body[key] = value;
+    }
+  }
+  for (const key of NUMBER_KEYS) {
+    const value = fields[key];
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+      body[key] = value;
+    }
+  }
+  if (Object.keys(body).length === 0) return;
+  try {
+    await retry(
+      async () => {
+        const response = await apiFetch({
+          path: `/api/workflow-run/${ctx.runId}`,
+          method: "PATCH",
+          headers: {
+            authorization: `Bearer ${ctx.apiToken}`,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) throw new Error(`PATCH workflow-run: ${response.status}`);
+      },
+      {
+        maxAttempts: 3,
+        delayMs: 2000,
+        label: "patchWorkflowRunFields",
+      },
+    );
+  } catch (error) {
+    log.warning(`patchWorkflowRunFields exhausted retries: ${error}`);
+  }
+}
+
+/**
+ * Postgres INTEGER / Prisma Int4 is signed 32-bit. Aggregated usage won't
+ * realistically hit this in a single run (2.1B tokens ≈ $6000+ of input on
+ * Claude Opus), but clamping here keeps the wire payload self-consistent:
+ * the server rejects out-of-range INT fields individually, so without a
+ * client-side clamp a single overflow would write a partial row where
+ * some columns land and others silently don't.
+ */
+const INT4_MAX = 2_147_483_647;
+
+function clampInt(value: number, field: WorkflowRunUsagePatchKey): number {
+  if (value > INT4_MAX) {
+    log.warning(
+      `aggregateUsage: ${field}=${value} exceeds INT4_MAX (${INT4_MAX}) — clamping so the rest of the usage row still persists.`,
+    );
+    return INT4_MAX;
+  }
+  return value;
+}
+
+/**
+ * Sum per-agent usage entries into a single WorkflowRunPatch payload.
+ * Returns an empty object when there's nothing to report, which causes
+ * `patchWorkflowRunFields` to no-op — safe to call unconditionally from
+ * end-of-run paths. Zero-valued fields are dropped so the DB only stores
+ * positive sums (and NULL means "not reported").
+ *
+ * Token sums are clamped to INT4_MAX to guarantee the payload the server
+ * sees is always self-consistent across all numeric columns.
+ */
+export function aggregateUsage(entries: AgentUsage[]): WorkflowRunPatch {
+  if (entries.length === 0) return {};
+
+  const sum = entries.reduce(
+    (acc, e) => ({
+      inputTokens: acc.inputTokens + e.inputTokens,
+      outputTokens: acc.outputTokens + e.outputTokens,
+      cacheReadTokens: acc.cacheReadTokens + (e.cacheReadTokens ?? 0),
+      cacheWriteTokens: acc.cacheWriteTokens + (e.cacheWriteTokens ?? 0),
+      costUsd: acc.costUsd + (e.costUsd ?? 0),
+    }),
+    { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, costUsd: 0 },
+  );
+
+  const out: WorkflowRunPatch = {};
+  if (sum.inputTokens > 0) out.inputTokens = clampInt(sum.inputTokens, "inputTokens");
+  if (sum.outputTokens > 0) out.outputTokens = clampInt(sum.outputTokens, "outputTokens");
+  if (sum.cacheReadTokens > 0)
+    out.cacheReadTokens = clampInt(sum.cacheReadTokens, "cacheReadTokens");
+  if (sum.cacheWriteTokens > 0)
+    out.cacheWriteTokens = clampInt(sum.cacheWriteTokens, "cacheWriteTokens");
+  if (sum.costUsd > 0) out.costUsd = sum.costUsd;
+  return out;
+}