@visulima/vis 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/packem_shared/toolchain-BdZd9eBi.js

@@ -0,0 +1,975 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  execFileSync
+} = __cjs_getBuiltinModule("node:child_process");
+const {
+  writeFileSync,
+  renameSync,
+  unlinkSync
+} = __cjs_getBuiltinModule("node:fs");
+import { isAccessibleSync, readFileSync, readJsonSync } from '@visulima/fs';
+import { join, delimiter, sep } from '@visulima/path';
+
+const SUPPORTED_MANAGERS = ["proto", "mise", "fnm", "volta", "asdf", "nvm", "corepack"];
+const MANAGER_CAPABILITIES = {
+  // npm / pnpm / yarn are available via community asdf plugins; users
+  // who haven't installed those plugins won't have asdf reach for
+  // them in resolveManagerFor (the manager just won't have a config
+  // file referencing them), so listing them here is safe and matches
+  // the "asdf is catch-all" docstring above.
+  asdf: ["bun", "deno", "go", "node", "npm", "pnpm", "python", "ruby", "rust", "yarn"],
+  corepack: ["npm", "pnpm", "yarn"],
+  fnm: ["node"],
+  mise: ["bun", "deno", "go", "node", "npm", "pnpm", "python", "ruby", "rust", "yarn"],
+  nvm: ["node"],
+  proto: ["bun", "deno", "go", "node", "npm", "pnpm", "python", "ruby", "rust", "yarn"],
+  volta: ["node", "npm", "pnpm", "yarn"]
+};
+const MANAGER_ORDER = ["proto", "mise", "fnm", "volta", "asdf", "nvm", "corepack"];
+const MANAGER_CONFIG_FILES = {
+  asdf: [".tool-versions"],
+  // Corepack's config is the `packageManager` field in package.json; we
+  // detect that separately in `corepackConfigFiles`.
+  corepack: [],
+  fnm: [".nvmrc", ".node-version"],
+  mise: [".mise.toml", ".config/mise.toml", "mise.toml"],
+  nvm: [".nvmrc"],
+  proto: [".prototools"],
+  volta: []
+};
+const onPathCache = /* @__PURE__ */ new Map();
+const isOnPath = (binary) => {
+  const cached = onPathCache.get(binary);
+  if (cached !== void 0 || onPathCache.has(binary)) {
+    return cached;
+  }
+  const pathEnv = process.env["PATH"];
+  if (!pathEnv) {
+    onPathCache.set(binary, void 0);
+    return void 0;
+  }
+  const isWindows = process.platform === "win32";
+  const exts = isWindows ? ["", ...(process.env["PATHEXT"] ?? ".COM;.EXE;.BAT;.CMD").split(";")] : [""];
+  for (const rawDir of pathEnv.split(delimiter)) {
+    const dir = rawDir.replaceAll(/^["']|["']$/g, "").trim();
+    if (dir === "") {
+      continue;
+    }
+    for (const ext of exts) {
+      const candidate = `${dir}${sep}${binary}${ext}`;
+      if (isAccessibleSync(candidate)) {
+        onPathCache.set(binary, candidate);
+        return candidate;
+      }
+    }
+  }
+  onPathCache.set(binary, void 0);
+  return void 0;
+};
+const queryManagerVersion = (binary, args = ["--version"]) => {
+  try {
+    const output = execFileSync(binary, args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2e3
+    });
+    const match = /\d+\.\d+(\.\d+)?/.exec(output);
+    return match ? match[0] : output.trim() || void 0;
+  } catch {
+    return void 0;
+  }
+};
+const pkgFieldConfigFiles = (workspaceRoot, field) => {
+  const pkgPath = join(workspaceRoot, "package.json");
+  if (!isAccessibleSync(pkgPath)) {
+    return [];
+  }
+  try {
+    const pkg = readJsonSync(pkgPath);
+    const value = pkg[field];
+    if (field === "volta" && typeof value === "object" && value !== null && Object.keys(value).length > 0) {
+      return ["package.json"];
+    }
+    if (field === "packageManager" && typeof value === "string" && value.length > 0) {
+      return ["package.json"];
+    }
+  } catch {
+  }
+  return [];
+};
+const configFilesFor = (name, workspaceRoot) => {
+  if (name === "volta") {
+    return pkgFieldConfigFiles(workspaceRoot, "volta");
+  }
+  if (name === "corepack") {
+    return pkgFieldConfigFiles(workspaceRoot, "packageManager");
+  }
+  return MANAGER_CONFIG_FILES[name].filter((file) => isAccessibleSync(join(workspaceRoot, file)));
+};
+const detectionCache = /* @__PURE__ */ new Map();
+const clearToolchainCache = () => {
+  detectionCache.clear();
+  onPathCache.clear();
+};
+const findInstalledManagers = (workspaceRoot, options) => {
+  {
+    const cached = detectionCache.get(workspaceRoot);
+    if (cached) {
+      return cached;
+    }
+  }
+  const results = [];
+  const pnpmOrYarnOnPath = Boolean(isOnPath("pnpm")) || Boolean(isOnPath("yarn"));
+  for (const name of MANAGER_ORDER) {
+    const binary = name === "nvm" ? void 0 : isOnPath(name);
+    const nvmInstalled = name === "nvm" && Boolean(process.env["NVM_DIR"]);
+    const configFiles = configFilesFor(name, workspaceRoot);
+    const installed = Boolean(binary) || nvmInstalled;
+    if (name === "corepack" && !installed) {
+      const hasPackageManagerPin = configFiles.length > 0;
+      if (!hasPackageManagerPin || pnpmOrYarnOnPath) {
+        continue;
+      }
+    }
+    if (!installed && configFiles.length === 0) {
+      continue;
+    }
+    results.push({
+      binPath: binary,
+      configFiles,
+      installed,
+      name,
+      version: binary ? queryManagerVersion(binary) : void 0
+    });
+  }
+  const frozen = Object.freeze(results);
+  detectionCache.set(workspaceRoot, frozen);
+  return frozen;
+};
+const pickPrimaryManager = (workspaceRoot, config, detected) => {
+  const found = findInstalledManagers(workspaceRoot);
+  if (config?.preferredManager && config.preferredManager !== "none") {
+    return found.find((d) => d.name === config.preferredManager) ?? { configFiles: [], installed: false, name: config.preferredManager };
+  }
+  return found.find((d) => d.installed && d.configFiles.length > 0) ?? found.find((d) => d.installed) ?? found.find((d) => d.configFiles.length > 0) ?? { configFiles: [], installed: false, name: "none" };
+};
+const readVersionFile = (workspaceRoot, names) => {
+  for (const name of names) {
+    const path = join(workspaceRoot, name);
+    if (!isAccessibleSync(path)) {
+      continue;
+    }
+    try {
+      const content = readFileSync(path).trim();
+      if (content !== "") {
+        return { name, value: content.replace(/^v/, "") };
+      }
+    } catch {
+    }
+  }
+  return void 0;
+};
+const PROTO_LINE_RE = /^([a-z][\w-]*)\s*=\s*"?([^"\n#]+?)"?\s*(?:#.*)?$/i;
+const parsePrototools = (workspaceRoot) => {
+  const path = join(workspaceRoot, ".prototools");
+  if (!isAccessibleSync(path)) {
+    return [];
+  }
+  const content = readFileSync(path);
+  const specs = [];
+  let inSection = false;
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) {
+      continue;
+    }
+    if (line.startsWith("[")) {
+      inSection = true;
+      continue;
+    }
+    if (inSection) {
+      continue;
+    }
+    const match = PROTO_LINE_RE.exec(line);
+    if (!match) {
+      continue;
+    }
+    const [, rawTool, version] = match;
+    const normalizedTool = normalizeToolName(rawTool);
+    if (normalizedTool) {
+      specs.push({ source: ".prototools", tool: normalizedTool, version: version.trim() });
+    }
+  }
+  return specs;
+};
+const MISE_TOOL_HEADER_RE = /^\[tools\]\s*$/i;
+const MISE_LINE_RE = /^([a-z][\w-]*)\s*=\s*"?([^"\n#]+?)"?\s*(?:#.*)?$/i;
+const parseMiseToml = (workspaceRoot) => {
+  for (const candidate of MANAGER_CONFIG_FILES.mise) {
+    const path = join(workspaceRoot, candidate);
+    if (!isAccessibleSync(path)) {
+      continue;
+    }
+    const specs = [];
+    const content = readFileSync(path);
+    let inToolsSection = false;
+    for (const rawLine of content.split(/\r?\n/)) {
+      const line = rawLine.trim();
+      if (line === "" || line.startsWith("#")) {
+        continue;
+      }
+      if (line.startsWith("[")) {
+        inToolsSection = MISE_TOOL_HEADER_RE.test(line);
+        continue;
+      }
+      if (!inToolsSection) {
+        continue;
+      }
+      const match = MISE_LINE_RE.exec(line);
+      if (!match) {
+        continue;
+      }
+      const [, rawTool, version] = match;
+      const normalizedTool = normalizeToolName(rawTool);
+      if (normalizedTool) {
+        specs.push({ source: ".mise.toml", tool: normalizedTool, version: version.trim() });
+      }
+    }
+    if (specs.length > 0) {
+      return specs;
+    }
+  }
+  return [];
+};
+const parseToolVersions = (workspaceRoot) => {
+  const path = join(workspaceRoot, ".tool-versions");
+  if (!isAccessibleSync(path)) {
+    return [];
+  }
+  const content = readFileSync(path);
+  const specs = [];
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) {
+      continue;
+    }
+    const parts = line.split(/\s+/);
+    if (parts.length < 2) {
+      continue;
+    }
+    const [rawTool, ...versions] = parts;
+    const normalizedTool = normalizeToolName(rawTool);
+    if (normalizedTool && versions[0]) {
+      specs.push({ source: ".tool-versions", tool: normalizedTool, version: versions[0] });
+    }
+  }
+  return specs;
+};
+const normalizeToolName = (raw) => {
+  const lower = raw.toLowerCase();
+  switch (lower) {
+    case "bun": {
+      return "bun";
+    }
+    case "deno": {
+      return "deno";
+    }
+    case "go":
+    case "golang": {
+      return "go";
+    }
+    case "node":
+    case "nodejs": {
+      return "node";
+    }
+    case "npm": {
+      return "npm";
+    }
+    case "pnpm": {
+      return "pnpm";
+    }
+    case "python":
+    case "python3": {
+      return "python";
+    }
+    case "ruby": {
+      return "ruby";
+    }
+    case "rust":
+    case "rustc": {
+      return "rust";
+    }
+    case "yarn": {
+      return "yarn";
+    }
+    default: {
+      return void 0;
+    }
+  }
+};
+const parsePackageManagerField = (field) => {
+  const [nameAndVersion] = field.split("+", 1);
+  const match = /^(pnpm|yarn|npm|bun)@(.+)$/.exec(nameAndVersion ?? "");
+  if (!match) {
+    return void 0;
+  }
+  const normalizedTool = normalizeToolName(match[1]);
+  if (!normalizedTool) {
+    return void 0;
+  }
+  return { source: "packageManager", tool: normalizedTool, version: match[2] };
+};
+const parseExpectedTools = (workspaceRoot, config) => {
+  const merged = /* @__PURE__ */ new Map();
+  const add = (spec) => {
+    merged.set(spec.tool, spec);
+  };
+  const pkgPath = join(workspaceRoot, "package.json");
+  let rootPkg = {};
+  try {
+    if (isAccessibleSync(pkgPath)) {
+      rootPkg = readJsonSync(pkgPath);
+    }
+  } catch {
+  }
+  if (rootPkg.engines) {
+    for (const [rawTool, version] of Object.entries(rootPkg.engines)) {
+      const normalizedTool = normalizeToolName(rawTool);
+      if (normalizedTool && typeof version === "string") {
+        add({ source: "engines", tool: normalizedTool, version });
+      }
+    }
+  }
+  if (rootPkg.packageManager) {
+    const pmSpec = parsePackageManagerField(rootPkg.packageManager);
+    if (pmSpec) {
+      add(pmSpec);
+    }
+  }
+  if (rootPkg.volta) {
+    for (const [rawTool, version] of Object.entries(rootPkg.volta)) {
+      const normalizedTool = normalizeToolName(rawTool);
+      if (normalizedTool && typeof version === "string") {
+        add({ source: "volta", tool: normalizedTool, version });
+      }
+    }
+  }
+  const nodeFile = readVersionFile(workspaceRoot, [".nvmrc", ".node-version"]);
+  if (nodeFile) {
+    add({
+      source: nodeFile.name === ".nvmrc" ? ".nvmrc" : ".node-version",
+      tool: "node",
+      version: nodeFile.value
+    });
+  }
+  for (const spec of parseToolVersions(workspaceRoot)) {
+    add(spec);
+  }
+  for (const spec of parseMiseToml(workspaceRoot)) {
+    add(spec);
+  }
+  for (const spec of parsePrototools(workspaceRoot)) {
+    add(spec);
+  }
+  if (config?.tools) {
+    for (const [rawTool, version] of Object.entries(config.tools)) {
+      const normalizedTool = normalizeToolName(rawTool);
+      if (normalizedTool && typeof version === "string") {
+        add({ source: "vis.config.ts", tool: normalizedTool, version });
+      }
+    }
+  }
+  return [...merged.values()];
+};
+const TOOL_VERSION_QUERY = {
+  bun: { args: ["--version"], binaries: ["bun"] },
+  deno: { args: ["--version"], binaries: ["deno"] },
+  go: { args: ["version"], binaries: ["go"] },
+  node: { args: ["--version"], binaries: ["node"] },
+  npm: { args: ["--version"], binaries: ["npm"] },
+  pnpm: { args: ["--version"], binaries: ["pnpm"] },
+  python: { args: ["--version"], binaries: ["python", "python3"] },
+  ruby: { args: ["--version"], binaries: ["ruby"] },
+  rust: { args: ["--version"], binaries: ["rustc"] },
+  yarn: { args: ["--version"], binaries: ["yarn"] }
+};
+const queryToolVersion = (tool) => {
+  const lookup = TOOL_VERSION_QUERY[tool];
+  for (const candidate of lookup.binaries) {
+    const binary = isOnPath(candidate);
+    if (binary) {
+      return queryManagerVersion(binary, lookup.args);
+    }
+  }
+  if (tool === "node") {
+    return process.versions.node;
+  }
+  return void 0;
+};
+const satisfies = (actual, range) => {
+  const normalized = range.trim();
+  if (normalized === "" || normalized === "*" || normalized === "latest") {
+    return true;
+  }
+  if (/^\d[\d.]*$/.test(normalized)) {
+    return actual === normalized || actual.startsWith(`${normalized}.`);
+  }
+  const parse = (version) => version.split(/[.\-+]/).map((part) => Number.parseInt(part, 10) || 0);
+  const compare = (a, b) => {
+    const aParts = parse(a);
+    const bParts = parse(b);
+    const len = Math.max(aParts.length, bParts.length);
+    for (let index = 0; index < len; index++) {
+      const ai = aParts[index] ?? 0;
+      const bi = bParts[index] ?? 0;
+      if (ai !== bi) {
+        return ai - bi;
+      }
+    }
+    return 0;
+  };
+  const matchesAll = (clauses) => {
+    for (const clause of clauses) {
+      if (clause.startsWith(">=")) {
+        if (compare(actual, clause.slice(2).trim()) < 0) {
+          return false;
+        }
+      } else if (clause.startsWith("<=")) {
+        if (compare(actual, clause.slice(2).trim()) > 0) {
+          return false;
+        }
+      } else if (clause.startsWith(">")) {
+        if (compare(actual, clause.slice(1).trim()) <= 0) {
+          return false;
+        }
+      } else if (clause.startsWith("<")) {
+        if (compare(actual, clause.slice(1).trim()) >= 0) {
+          return false;
+        }
+      } else if (clause.startsWith("^") || clause.startsWith("~")) {
+        const target = clause.slice(1).trim();
+        const [targetMajor, targetMinor] = parse(target);
+        const [actualMajor, actualMinor] = parse(actual);
+        if (actualMajor !== targetMajor) {
+          return false;
+        }
+        if (clause.startsWith("~") && actualMinor !== targetMinor) {
+          return false;
+        }
+        if (compare(actual, target) < 0) {
+          return false;
+        }
+      }
+    }
+    return true;
+  };
+  const alternatives = normalized.split("||").map((alternative) => alternative.trim().split(/\s+/).filter(Boolean)).filter((clauses) => clauses.length > 0);
+  if (alternatives.length === 0) {
+    return true;
+  }
+  return alternatives.some((clauses) => matchesAll(clauses));
+};
+const preferenceFor = (source, tool) => {
+  switch (source) {
+    case ".mise.toml": {
+      return ["mise"];
+    }
+    case ".node-version":
+    case ".nvmrc": {
+      return ["fnm", "nvm", "volta", "proto", "mise", "asdf"];
+    }
+    case ".prototools": {
+      return ["proto"];
+    }
+    case ".tool-versions": {
+      return ["asdf", "mise"];
+    }
+    case "packageManager": {
+      if (tool === "pnpm" || tool === "yarn") {
+        return ["self-activate", "volta", "proto", "mise", "corepack"];
+      }
+      if (tool === "npm") {
+        return ["volta", "proto", "mise", "asdf", "corepack"];
+      }
+      if (tool === "bun") {
+        return ["proto", "mise", "asdf"];
+      }
+      return ["volta", "proto", "mise"];
+    }
+    case "volta": {
+      return ["volta"];
+    }
+    // Catch-all pins (`engines`, `vis.config.ts`, anything else) —
+    // walk every capable manager.
+    default: {
+      return ["proto", "mise", "fnm", "volta", "asdf", "nvm", "corepack"];
+    }
+  }
+};
+const resolveManagerFor = (spec, detected, config) => {
+  if (config?.preferredManager && config.preferredManager !== "none" && canHandle(config.preferredManager, spec.tool)) {
+    const override = detected.find((d) => d.name === config.preferredManager);
+    return override ? { installed: override.installed, name: override.name } : {
+      installed: false,
+      name: config.preferredManager,
+      note: `${config.preferredManager} is the preferred manager but isn't on PATH`
+    };
+  }
+  const preference = preferenceFor(spec.source, spec.tool);
+  for (const name of preference) {
+    if (name === "self-activate") {
+      if ((spec.tool === "pnpm" || spec.tool === "yarn") && isOnPath(spec.tool)) {
+        return {
+          installed: true,
+          name: "self-activate",
+          note: `${spec.tool} will activate ${spec.version} from the packageManager field on next invocation`
+        };
+      }
+      continue;
+    }
+    if (!canHandle(name, spec.tool)) {
+      continue;
+    }
+    const match = detected.find((d) => d.name === name);
+    if (match?.installed) {
+      return { installed: true, name };
+    }
+  }
+  for (const name of preference) {
+    if (name === "self-activate" || !canHandle(name, spec.tool)) {
+      continue;
+    }
+    return { installed: false, name, note: `${name} can install ${spec.tool} — run \`vis toolchain install\` after adding it to PATH` };
+  }
+  return { installed: false, name: "none", note: "No manager knows how to install this tool" };
+};
+const canHandle = (name, tool) => {
+  if (name === "none") {
+    return false;
+  }
+  if (name === "self-activate") {
+    return tool === "pnpm" || tool === "yarn";
+  }
+  return MANAGER_CAPABILITIES[name].includes(tool);
+};
+const getToolchainStatus = (workspaceRoot, config) => {
+  const detected = findInstalledManagers(workspaceRoot);
+  const expectedTools = parseExpectedTools(workspaceRoot, config);
+  const tools = expectedTools.map((expected) => {
+    const actual = queryToolVersion(expected.tool);
+    const matches = actual !== void 0 && satisfies(actual, expected.version);
+    const manager = resolveManagerFor(expected, detected, config);
+    return { actual, expected, manager, matches };
+  });
+  return { detected, tools };
+};
+const buildInstallInvocation = (manager, spec) => {
+  switch (manager) {
+    case "asdf": {
+      if (!spec) {
+        return void 0;
+      }
+      return { args: ["install", spec.tool, spec.version], bin: "asdf" };
+    }
+    case "corepack": {
+      if (!spec) {
+        return { args: ["prepare", "--activate"], bin: "corepack", hint: "reads the packageManager field in package.json" };
+      }
+      return {
+        args: ["prepare", `${spec.tool}@${spec.version}`, "--activate"],
+        bin: "corepack"
+      };
+    }
+    case "fnm": {
+      if (spec?.tool !== "node") {
+        return void 0;
+      }
+      return { args: ["install", spec.version], bin: "fnm" };
+    }
+    case "mise": {
+      if (!spec) {
+        return void 0;
+      }
+      return { args: ["install", `${spec.tool}@${spec.version}`], bin: "mise" };
+    }
+    case "none": {
+      return void 0;
+    }
+    case "nvm": {
+      return {
+        args: [],
+        bin: "nvm",
+        hint: "nvm is a shell function — run `nvm install` / `nvm use` from your shell"
+      };
+    }
+    case "proto": {
+      if (!spec) {
+        return void 0;
+      }
+      return { args: ["install", spec.tool, spec.version], bin: "proto" };
+    }
+    case "self-activate": {
+      return {
+        args: [],
+        bin: spec?.tool ?? "pnpm",
+        hint: `${spec?.tool ?? "pnpm"} will self-activate on next invocation — no install needed`
+      };
+    }
+    case "volta": {
+      if (!spec) {
+        return { args: ["install", "node@lts"], bin: "volta", hint: "volta pins per-tool; specify <tool>@<version>" };
+      }
+      return { args: ["install", `${spec.tool}@${spec.version}`], bin: "volta" };
+    }
+    default: {
+      const exhaustive = manager;
+      throw new Error(`Unknown manager: ${exhaustive}`);
+    }
+  }
+};
+const buildUseInvocation = (manager, spec) => {
+  switch (manager) {
+    case "asdf": {
+      return {
+        args: ["local", spec.tool, spec.version],
+        bin: "asdf",
+        configChange: { file: ".tool-versions", hint: `Pins ${spec.tool} ${spec.version}` }
+      };
+    }
+    case "corepack": {
+      if (spec.tool !== "npm" && spec.tool !== "pnpm" && spec.tool !== "yarn") {
+        return void 0;
+      }
+      return {
+        args: ["use", `${spec.tool}@${spec.version}`],
+        bin: "corepack",
+        configChange: { file: "package.json", hint: `Writes packageManager: "${spec.tool}@${spec.version}"` }
+      };
+    }
+    case "fnm": {
+      if (spec.tool === "node") {
+        return { args: ["use", spec.version], bin: "fnm" };
+      }
+      return void 0;
+    }
+    case "mise": {
+      return {
+        args: ["use", "--", `${spec.tool}@${spec.version}`],
+        bin: "mise",
+        configChange: { file: ".mise.toml", hint: `Pins ${spec.tool} ${spec.version}` }
+      };
+    }
+    case "none": {
+      return void 0;
+    }
+    case "nvm": {
+      if (spec.tool === "node") {
+        return {
+          args: [],
+          bin: "nvm",
+          configChange: { file: ".nvmrc", hint: "Write version to .nvmrc manually (nvm doesn't persist)." }
+        };
+      }
+      return void 0;
+    }
+    case "proto": {
+      return {
+        args: ["pin", spec.tool, spec.version],
+        bin: "proto",
+        configChange: { file: ".prototools", hint: `Pins ${spec.tool} ${spec.version}` }
+      };
+    }
+    case "self-activate": {
+      return {
+        args: [],
+        bin: spec.tool,
+        configChange: {
+          file: "package.json",
+          hint: `Set packageManager: "${spec.tool}@${spec.version}" — ${spec.tool} will self-activate on next invocation`
+        }
+      };
+    }
+    case "volta": {
+      return {
+        args: ["pin", `${spec.tool}@${spec.version}`],
+        bin: "volta",
+        configChange: { file: "package.json", hint: `Writes volta.${spec.tool}` }
+      };
+    }
+    default: {
+      const exhaustive = manager;
+      throw new Error(`Unknown manager: ${exhaustive}`);
+    }
+  }
+};
+const findOnPathByAlias = (tool) => {
+  for (const alias of TOOL_VERSION_QUERY[tool].binaries) {
+    const binary = isOnPath(alias);
+    if (binary) {
+      return binary;
+    }
+  }
+  return void 0;
+};
+const resolveToolBinary = (manager, tool) => {
+  const aliases = TOOL_VERSION_QUERY[tool].binaries;
+  if (manager.installed && manager.binPath && // proto/mise/asdf expose `which`; volta has `volta which`; fnm
+  // prints to stdout from `fnm which`. Try each alias in order so
+  // `mise which rust` (which doesn't know "rust") falls back to
+  // `mise which rustc`.
+  (manager.name === "proto" || manager.name === "mise" || manager.name === "asdf" || manager.name === "volta" || manager.name === "fnm")) {
+    for (const alias of aliases) {
+      try {
+        const output = execFileSync(manager.binPath, ["which", alias], {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+          timeout: 2e3
+        });
+        const trimmed = output.trim();
+        if (trimmed) {
+          return trimmed;
+        }
+      } catch {
+      }
+    }
+  }
+  for (const alias of aliases) {
+    const binary = isOnPath(alias);
+    if (binary) {
+      return binary;
+    }
+  }
+  return void 0;
+};
+const atomicWrite = (path, body) => {
+  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  writeFileSync(tmp, body);
+  try {
+    renameSync(tmp, path);
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw error;
+  }
+};
+const insertPackageManagerKey = (pkg, value) => {
+  if ("packageManager" in pkg) {
+    pkg.packageManager = value;
+    return pkg;
+  }
+  const ordered = {};
+  let inserted = false;
+  for (const [key, fieldValue] of Object.entries(pkg)) {
+    if (!inserted && (key === "dependencies" || key === "devDependencies" || key === "peerDependencies" || key === "optionalDependencies")) {
+      ordered.packageManager = value;
+      inserted = true;
+    }
+    ordered[key] = fieldValue;
+  }
+  if (!inserted) {
+    ordered.packageManager = value;
+  }
+  return ordered;
+};
+const writePackageManagerField = (workspaceRoot, spec) => {
+  if (spec.tool !== "pnpm" && spec.tool !== "yarn" && spec.tool !== "npm" && spec.tool !== "bun") {
+    return void 0;
+  }
+  const pkgPath = join(workspaceRoot, "package.json");
+  if (!isAccessibleSync(pkgPath)) {
+    throw new Error(`Cannot pin ${spec.tool}: ${pkgPath} does not exist.`);
+  }
+  const raw = readFileSync(pkgPath);
+  const indentMatch = /\n([ \t]+)/.exec(raw);
+  const indent = indentMatch?.[1] ?? "  ";
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${pkgPath} is not valid JSON — fix it before running \`vis toolchain use\`. Underlying error: ${error.message}`);
+  }
+  const value = `${spec.tool}@${spec.version}`;
+  const updated = insertPackageManagerKey(pkg, value);
+  const trailingNewline = raw.endsWith("\n") ? "\n" : "";
+  atomicWrite(pkgPath, `${JSON.stringify(updated, void 0, indent)}${trailingNewline}`);
+  return value;
+};
+const updateEnginesField = (workspaceRoot, spec) => {
+  const pkgPath = join(workspaceRoot, "package.json");
+  if (!isAccessibleSync(pkgPath)) {
+    return void 0;
+  }
+  const raw = readFileSync(pkgPath);
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${pkgPath} is not valid JSON — fix it before running \`vis toolchain use\`. Underlying error: ${error.message}`);
+  }
+  if (pkg.engines?.[spec.tool] === void 0) {
+    return void 0;
+  }
+  if (pkg.engines[spec.tool] === spec.version) {
+    return void 0;
+  }
+  pkg.engines[spec.tool] = spec.version;
+  const indentMatch = /\n([ \t]+)/.exec(raw);
+  const indent = indentMatch?.[1] ?? "  ";
+  const trailingNewline = raw.endsWith("\n") ? "\n" : "";
+  atomicWrite(pkgPath, `${JSON.stringify(pkg, void 0, indent)}${trailingNewline}`);
+  return spec.version;
+};
+const parseUseArgument = (raw) => {
+  const match = /^([a-z][\w-]*)@(.+)$/i.exec(raw.trim());
+  if (!match) {
+    return void 0;
+  }
+  const normalizedTool = normalizeToolName(match[1]);
+  if (!normalizedTool) {
+    return void 0;
+  }
+  return { source: "vis.config.ts", tool: normalizedTool, version: match[2] };
+};
+const ensureToolchain = async (workspaceRoot, config, logger) => {
+  const status = getToolchainStatus(workspaceRoot, config);
+  const mismatches = status.tools.filter((t) => !t.matches);
+  if (mismatches.length === 0) {
+    return { attempted: [], failed: [], upToDate: true };
+  }
+  const hasManager = status.detected.some((d) => d.installed);
+  const autoInstall = config?.autoInstall ?? hasManager;
+  if (!autoInstall) {
+    return { attempted: [], failed: [], upToDate: false };
+  }
+  const attempted = [];
+  const failed = [];
+  const byManager = /* @__PURE__ */ new Map();
+  for (const tool of mismatches) {
+    const bucket = byManager.get(tool.manager.name);
+    if (bucket) {
+      bucket.push(tool);
+    } else {
+      byManager.set(tool.manager.name, [tool]);
+    }
+  }
+  for (const [managerName, tools] of byManager) {
+    if (managerName === "self-activate") {
+      for (const { expected } of tools) {
+        logger.info(`toolchain: ${expected.tool} ${expected.version} will self-activate on next ${expected.tool} invocation`);
+        attempted.push(expected);
+      }
+      continue;
+    }
+    if (managerName === "none") {
+      for (const { expected } of tools) {
+        failed.push({
+          error: `no manager can install ${expected.tool} — install one of ${SUPPORTED_MANAGERS.join(", ")}`,
+          spec: expected
+        });
+      }
+      continue;
+    }
+    const manager = status.detected.find((d) => d.name === managerName);
+    if (!manager?.installed) {
+      for (const { expected } of tools) {
+        failed.push({ error: `${managerName} is not on PATH`, spec: expected });
+      }
+      continue;
+    }
+    const pairs = tools.map((tool) => {
+      return { invocation: buildInstallInvocation(managerName, tool.expected), tool };
+    }).filter((pair) => pair.invocation !== void 0);
+    for (const { invocation, tool } of pairs) {
+      const { expected } = tool;
+      if (invocation.bin === "nvm" && invocation.args.length === 0) {
+        logger.warn(
+          `toolchain: nvm requires a shell-side activation for ${expected.tool} ${expected.version}. Run \`nvm install\` / \`nvm use\` manually.`
+        );
+        failed.push({ error: "nvm requires shell-side activation", spec: expected });
+        continue;
+      }
+      logger.info(`toolchain: $ ${invocation.bin} ${invocation.args.join(" ")}`);
+      try {
+        execFileSync(invocation.bin, invocation.args, {
+          cwd: workspaceRoot,
+          stdio: "inherit"
+        });
+        attempted.push(expected);
+        if (managerName === "fnm") {
+          activateFnmEnv(invocation.bin, logger);
+        }
+      } catch (error) {
+        failed.push({ error: error.message, spec: expected });
+        break;
+      }
+    }
+  }
+  clearToolchainCache();
+  return { attempted, failed, upToDate: false };
+};
+const runToolchainPreflight = async (workspaceRoot, config, logger, skip = false) => {
+  if (skip) {
+    return;
+  }
+  const result = await ensureToolchain(workspaceRoot, config, logger);
+  for (const failure of result.failed) {
+    logger.warn(`toolchain: ${failure.spec.tool} ${failure.spec.version} — ${failure.error}`);
+  }
+};
+const activateFnmEnv = (fnmBin, logger) => {
+  const shell = process.platform === "win32" ? "powershell" : "bash";
+  try {
+    const output = execFileSync(fnmBin, ["env", "--shell", shell], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2e3
+    });
+    for (const line of output.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (trimmed === "") {
+        continue;
+      }
+      const psMatch = /^\$env:([A-Z_]\w*)\s*=\s*(.+)$/i.exec(trimmed);
+      if (psMatch) {
+        const [, name, rawValue] = psMatch;
+        process.env[name] = rawValue.replaceAll(/^["']|["']$/g, "");
+        continue;
+      }
+      const cmdMatch = /^set\s+"?([A-Z_]\w*)=(.*?)"?$/i.exec(trimmed);
+      if (cmdMatch) {
+        const [, name, value] = cmdMatch;
+        process.env[name] = value;
+        continue;
+      }
+      const bashMatch = /^(?:export\s+)?([A-Z_]\w*)=(.+)$/i.exec(trimmed);
+      if (bashMatch) {
+        const [, name, rawValue] = bashMatch;
+        process.env[name] = rawValue.replaceAll(/^["']|["']$/g, "");
+      }
+    }
+  } catch (error) {
+    logger.warn(`toolchain: could not activate fnm env (${error.message}). Subsequent tasks may use the previous Node version.`);
+  }
+};
+
+export { SUPPORTED_MANAGERS as S, resolveManagerFor as a, resolveToolBinary as b, findOnPathByAlias as c, buildUseInvocation as d, buildInstallInvocation as e, findInstalledManagers as f, getToolchainStatus as g, pickPrimaryManager as h, parseUseArgument as p, runToolchainPreflight as r, updateEnginesField as u, writePackageManagerField as w };