infraweaver 0.1.0

package/src/utils/normalizeEnv.ts

@@ -0,0 +1,106 @@
+import * as core from "@actions/core";
+import { log } from "#app/utils/cli";
+import { isSensitiveEnvName } from "#app/utils/secrets";
+
+/**
+ * Trim surrounding whitespace from a sensitive value and register it as a
+ * GitHub Actions log mask. Trailing newlines from terminal-copy paste are a
+ * common footgun: the value travels through GH Actions logs and any tool
+ * that re-emits parts of it leaks the unmasked tail. Trimming canonicalises
+ * the value so the mask matches exactly what downstream tools will print.
+ *
+ * Masking is delegated to `core.setSecret` (not raw `console.log`) so the
+ * toolkit percent-encodes `\r`/`\n`; the runner V2 parser decodes them and
+ * registers the full value plus every non-empty line as separate masks. That
+ * keeps us safe for embedded-newline values (PEMs, kubeconfigs, JSON blobs)
+ * even though they aren't currently used.
+ *
+ * Returns the trimmed value, or `null` when the input was whitespace-only —
+ * callers must leave `process.env` untouched in that case so a misconfigured
+ * value surfaces as a clear "missing key" downstream rather than silently
+ * mutating to the empty string.
+ */
+export function sanitizeSecret(key: string, value: string): string | null {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    log.warning(
+      `» ${key} is whitespace-only — leaving env var unchanged. check your secret value.`,
+    );
+    return null;
+  }
+  if (trimmed !== value) {
+    log.warning(
+      `» stripped whitespace from ${key} (whitespace in secret values breaks GitHub Actions log masking)`,
+    );
+  }
+  core.setSecret(trimmed);
+  return trimmed;
+}
+
+/**
+ * Normalize environment variables to uppercase.
+ * This handles case-insensitive env var names (e.g., `anthropic_api_key` -> `ANTHROPIC_API_KEY`).
+ *
+ * If there are conflicts (same key with different capitalizations but different values),
+ * logs a warning and keeps the uppercase version.
+ *
+ * Also trims and masks sensitive values so accidental trailing whitespace
+ * doesn't defeat GitHub Actions log masking.
+ */
+export function normalizeEnv(): void {
+  const upperKeys = new Map<string, string[]>();
+
+  // group keys by their uppercase form
+  for (const key of Object.keys(process.env)) {
+    const upper = key.toUpperCase();
+    const existing = upperKeys.get(upper) || [];
+    existing.push(key);
+    upperKeys.set(upper, existing);
+  }
+
+  // process each group
+  for (const [upperKey, keys] of upperKeys) {
+    if (keys.length === 1) {
+      const key = keys[0]!;
+      if (key !== upperKey) {
+        // single key, just needs uppercasing
+        process.env[upperKey] = process.env[key];
+        delete process.env[key];
+      }
+      continue;
+    }
+
+    // multiple keys with different capitalizations
+    const values = keys.map((k) => process.env[k]);
+    const uniqueValues = new Set(values);
+
+    if (uniqueValues.size > 1) {
+      // conflict: different values for different capitalizations
+      log.warning(
+        `env var conflict: ${keys.join(", ")} have different values. using uppercase ${upperKey}.`,
+      );
+    }
+
+    // prefer the uppercase version if it exists, otherwise use the first one
+    const preferredKey = keys.find((k) => k === upperKey) || keys[0]!;
+    const preferredValue = process.env[preferredKey];
+
+    // delete all variants
+    for (const key of keys) {
+      delete process.env[key];
+    }
+
+    // set the uppercase version
+    process.env[upperKey] = preferredValue;
+  }
+
+  // trim + mask sensitive values after case normalisation so each key is
+  // visited exactly once with its final, canonical value
+  for (const key of Object.keys(process.env)) {
+    if (!isSensitiveEnvName(key)) continue;
+    const value = process.env[key];
+    if (typeof value !== "string" || value.length === 0) continue;
+    const sanitized = sanitizeSecret(key, value);
+    if (sanitized !== null) process.env[key] = sanitized;
+  }
+}

package/src/utils/openCodeModels.ts

@@ -0,0 +1,86 @@
+// OpenCode-as-source-of-truth for BYOK detection.
+//
+// `opencode models` returns the `provider/model` specifiers that OpenCode
+// can actually route given the current env (workflow env block + GH Actions
+// secrets) and `auth.json` (Codex / future managed credentials). This is
+// authoritative — strictly more accurate than the static
+// `provider.envVars + provider.managedCredentials` catalog in `models.ts`
+// for the "do we have BYOK auth?" gate. The catalog can (and will) miss
+// new auth shapes; OpenCode itself can't.
+//
+// Two captures per run:
+//   1. `captureBaselineModels` — called BEFORE Codex `auth.json` is
+//      materialized. The set OpenCode can serve from the runner's pre-existing
+//      environment alone (workflow `env:` block + GH Actions secrets).
+//   2. `captureAuthorizedModels` — called AFTER Codex `auth.json`
+//      materialization. The authoritative set for BYOK decisions (fallback +
+//      validateAgentApiKey).
+//
+// The set difference (`authorized - baseline`) is the contribution of the
+// Codex OAuth credential to this run — logged once for operator visibility.
+//
+// Memoized at module scope so the two consumers
+// (`selectFallbackModelIfNeeded` + `autoSelectModel`) share one shell-out.
+
+import { execFileSync } from "node:child_process";
+import { log } from "#app/utils/cli";
+
+let baseline: Set<string> | undefined;
+let authorized: Set<string> | undefined;
+
+function readModels(cliPath: string): Set<string> {
+  try {
+    const output = execFileSync(cliPath, ["models"], {
+      encoding: "utf-8",
+      timeout: 30_000,
+      env: process.env,
+    });
+    return new Set(
+      output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean),
+    );
+  } catch (error) {
+    log.debug(
+      `» \`opencode models\` failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return new Set();
+  }
+}
+
+/** Snapshot the set of models OpenCode can serve from the current env, BEFORE
+ * Infraweaver-stored credentials are merged in. Call once early in `main.ts`. */
+export function captureBaselineModels(cliPath: string): void {
+  baseline = readModels(cliPath);
+  log.debug(`» opencode baseline: ${baseline.size} models`);
+}
+
+/** Snapshot the set of models OpenCode can serve AFTER dbSecrets +
+ * Codex auth.json are in place. Logs the diff against the baseline as
+ * `» BYOK auth enabled N model(s): …`. */
+export function captureAuthorizedModels(cliPath: string): void {
+  authorized = readModels(cliPath);
+  const base = baseline;
+  if (base) {
+    const diff = [...authorized].filter((m) => !base.has(m));
+    if (diff.length > 0) {
+      log.info(
+        `» BYOK auth enabled ${diff.length} model(s): ${diff.join(", ")}`,
+      );
+    }
+  }
+  log.debug(`» opencode authorized: ${authorized.size} models`);
+}
+
+/** Authorized set captured after Infraweaver-stored auth is applied. Throws if
+ * called before `captureAuthorizedModels` — the call sites (fallback gate,
+ * api-key validation, auto-select) all run strictly after capture. */
+export function getAuthorizedModels(): Set<string> {
+  if (!authorized) {
+    throw new Error(
+      "getAuthorizedModels called before captureAuthorizedModels",
+    );
+  }
+  return authorized;
+}

package/src/utils/openaiCompatible.ts

@@ -0,0 +1,52 @@
+import { OPENAI_COMPATIBLE_MODEL_ID_ENV } from "#app/models";
+import { readEnv } from "#app/utils/env";
+
+/** endpoint base URL for the `openai-compatible/byok` route (e.g. an Ollama, vLLM,
+ *  TGI, HuggingFace Inference Endpoint, or Azure OpenAI base URL). */
+export const OPENAI_COMPATIBLE_BASE_URL_ENV = "OPENAI_COMPATIBLE_BASE_URL";
+
+/** API key for the endpoint. Optional — keyless self-hosted servers (a local
+ *  Ollama) omit it and the adapter is handed a placeholder instead. */
+export const OPENAI_COMPATIBLE_API_KEY_ENV = "OPENAI_COMPATIBLE_API_KEY";
+
+/** opencode provider name for the injected custom endpoint. */
+export const OPENAI_COMPATIBLE_PROVIDER = "openai-compatible";
+
+/**
+ * Is `model` the resolved id for the `openai-compatible/byok` route? Detected by
+ * the env sentinel — after `resolveModel`, a routing slug becomes its raw backing
+ * id (here `OPENAI_COMPATIBLE_MODEL_ID`), so this is how the harness re-identifies
+ * the route downstream (same pattern as `isVertexRoute` / the Bedrock sentinel).
+ * A HuggingFace model id can itself contain a `/`, so callers must NOT rely on the
+ * slash heuristic that distinguishes raw Bedrock/Vertex ids — use this instead.
+ */
+export function isOpenAiCompatibleRoute(model: string | undefined): boolean {
+  const id = readEnv(OPENAI_COMPATIBLE_MODEL_ID_ENV);
+  return model !== undefined && id !== undefined && id === model;
+}
+
+/** When the route is active, the opencode model string is `openai-compatible/<id>`. */
+export function resolveOpenAiCompatibleOpenCodeModel(model: string | undefined): string | undefined {
+  return isOpenAiCompatibleRoute(model) && model ? `${OPENAI_COMPATIBLE_PROVIDER}/${model}` : undefined;
+}
+
+/**
+ * The opencode `provider` block that registers the user's OpenAI-compatible
+ * endpoint via the AI SDK's `@ai-sdk/openai-compatible` adapter. Returns undefined
+ * unless both the model id and base URL are set. `apiKey` falls back to a non-empty
+ * placeholder so keyless self-hosted endpoints still satisfy the adapter.
+ */
+export function openAiCompatibleProviderBlock(): Record<string, unknown> | undefined {
+  const id = readEnv(OPENAI_COMPATIBLE_MODEL_ID_ENV);
+  const baseURL = readEnv(OPENAI_COMPATIBLE_BASE_URL_ENV);
+  if (!id || !baseURL) return undefined;
+  const apiKey = readEnv(OPENAI_COMPATIBLE_API_KEY_ENV) ?? "sk-no-key-required";
+  return {
+    [OPENAI_COMPATIBLE_PROVIDER]: {
+      npm: "@ai-sdk/openai-compatible",
+      name: "OpenAI-compatible endpoint",
+      options: { baseURL, apiKey },
+      models: { [id]: { name: id } },
+    },
+  };
+}

package/src/utils/opentofuMcp.ts

@@ -0,0 +1,61 @@
+/**
+ * OpenTofu MCP server integration — the permissively-licensed sibling to
+ * [[terraformMcp]].
+ *
+ * When the `opentofu_mcp` input is on, the agent harness registers the OpenTofu
+ * project's registry MCP server next to infraweaver's. It gives the fixing agent
+ * live OpenTofu Registry knowledge — provider/resource docs, module details,
+ * current versions — which powers module-source-aware fixes and generation on an
+ * OpenTofu repo, the same way `terraform_mcp` does for the Terraform Registry.
+ * It's the natural pairing for the OpenTofu-first stance the engine already takes
+ * (the scanners fall back to the `tofu` CLI; the licence posture prefers OpenTofu's
+ * MPL fork over BUSL Terraform).
+ *
+ * Why the HOSTED endpoint (not a Docker image like terraform_mcp):
+ *   - the OpenTofu MCP server has NO official Docker image; it's published as a
+ *     hosted streamable-HTTP endpoint (OpenTofu's own first-party infrastructure)
+ *     plus an npx package. The hosted endpoint is the zero-install path — no
+ *     docker on the runner, no npm supply-chain surface to pin.
+ *   - it serves PUBLIC registry data and needs NO credentials, so pointing the
+ *     agent at it exposes no repo content or secrets — the queries are the same
+ *     class of public lookups a `tofu init` already makes.
+ *
+ * Security posture:
+ *   - opt-in + licence-gated (MPL-2.0): on only via the `opentofu_mcp` input or by
+ *     naming "opentofu_mcp" in tools_enabled — the explicit, licence-aware
+ *     acknowledgement (an external network surface the operator chooses).
+ *   - read-only registry knowledge only; the server exposes no state/apply/deploy
+ *     tools, so there is nothing mutating for the agent to reach.
+ */
+
+import {
+  resolveToolSelection,
+  type ToolSelectionFlags,
+} from "#app/utils/toolSelection";
+
+/** OpenTofu's hosted streamable-HTTP MCP endpoint (first-party; public registry
+ *  data; no credentials). The zero-install path — no docker, no npm pin. */
+export const OPENTOFU_MCP_URL = "https://mcp.opentofu.org/mcp";
+
+/** the registry name the server is registered under in agent MCP configs —
+ *  matches the OpenTofu docs' own client-config examples, so agent guidance
+ *  written against "the opentofu MCP server" finds it under the expected key. */
+export const OPENTOFU_MCP_SERVER_NAME = "opentofu";
+
+export type OpenTofuMcpResolution =
+  | { kind: "disabled" }
+  | { kind: "available"; url: string };
+
+/**
+ * Decide whether the run gets the OpenTofu registry MCP server. Unlike
+ * `resolveTerraformMcp` there is no docker probe: the server is a hosted HTTP
+ * endpoint, so it's either opted-in (available) or off. A discriminated union so
+ * every harness handles both outcomes explicitly.
+ */
+export function resolveOpenTofuMcp(
+  payload: ToolSelectionFlags,
+): OpenTofuMcpResolution {
+  if (!resolveToolSelection(payload).enabled("opentofu_mcp"))
+    return { kind: "disabled" };
+  return { kind: "available", url: OPENTOFU_MCP_URL };
+}

package/src/utils/overrides.ts

@@ -0,0 +1,100 @@
+/**
+ * Parse + apply the action's `unsafe_overrides` input — a JSON object of env
+ * var overrides that mutate `process.env` at the start of a run. Designed for
+ * e2e testing / debugging from `workflow_dispatch`; only callers with
+ * `actions:write` on the repo can supply it.
+ *
+ * The `unsafe` prefix is load-bearing: GH Actions echoes the value verbatim
+ * in the runner's step-header log, so the raw JSON (including any values
+ * passed in) is visible to anyone with `actions:read` on the calling repo.
+ * Treat the run log as compromised for any value placed in `unsafe_overrides`.
+ */
+
+import * as core from "@actions/core";
+
+/**
+ * Names refused even when present in the input. Overriding these would let a
+ * caller escape infraweaver's scope (GITHUB_TOKEN), break runner internals
+ * (ACTIONS_RUNTIME_*), forge OIDC tokens (ACTIONS_ID_TOKEN_REQUEST_*), or
+ * substitute our server-side auth (INFRAWEAVER_API_SECRET). Customer-facing
+ * provider keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, CLAUDE_CODE_OAUTH_TOKEN,
+ * etc.) are intentionally NOT denied — overriding those is the use case.
+ */
+export const DENIED_OVERRIDE_NAMES: ReadonlySet<string> = new Set([
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "ACTIONS_RUNTIME_TOKEN",
+  "ACTIONS_RUNTIME_URL",
+  "ACTIONS_ID_TOKEN_REQUEST_URL",
+  "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+  "ACTIONS_CACHE_URL",
+  "INFRAWEAVER_API_SECRET",
+  "VERCEL_AUTOMATION_BYPASS_SECRET",
+]);
+
+export interface ApplyOverridesResult {
+  applied: string[];
+  denied: string[];
+}
+
+/** Parse the JSON input. Returns `{}` for empty/whitespace. Throws on shape errors. */
+export function parseOverrides(raw: string): Record<string, string> {
+  const trimmed = raw.trim();
+  if (!trimmed) return {};
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (err) {
+    throw new Error(
+      `invalid UNSAFE_OVERRIDES: not valid JSON (${err instanceof Error ? err.message : String(err)})`,
+    );
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`invalid UNSAFE_OVERRIDES: must be a JSON object`);
+  }
+
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(
+    parsed as Record<string, unknown>,
+  )) {
+    if (typeof value !== "string") {
+      throw new Error(
+        `invalid UNSAFE_OVERRIDES: key "${key}" must have a string value (got ${typeof value})`,
+      );
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Mutate `params.env` in place with the supplied JSON overrides, skipping any
+ * names in `DENIED_OVERRIDE_NAMES`. Each applied value is registered with
+ * `core.setSecret` so the runner masks it in subsequent log output, and the
+ * raw `UNSAFE_OVERRIDES` env var is deleted so spawned subprocesses don't
+ * inherit the original JSON (which would defeat both the deny-list and the
+ * masking by exposing the values verbatim).
+ *
+ * Returns the applied/denied breakdown so the caller can render an audit log.
+ */
+export function applyOverrides(params: {
+  raw: string;
+  env: NodeJS.ProcessEnv;
+}): ApplyOverridesResult {
+  const overrides = parseOverrides(params.raw);
+  const applied: string[] = [];
+  const denied: string[] = [];
+  for (const [key, value] of Object.entries(overrides)) {
+    if (DENIED_OVERRIDE_NAMES.has(key)) {
+      denied.push(key);
+      continue;
+    }
+    if (value.length > 0) core.setSecret(value);
+    params.env[key] = value;
+    applied.push(key);
+  }
+  delete params.env.UNSAFE_OVERRIDES;
+  return { applied, denied };
+}

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