@crystalplatforms/adm 0.2.3 → 0.3.0

package/src/install/run.js

@@ -0,0 +1,88 @@
+const { loadCatalog } = require('../setup/catalog');
+const { detectEnvironment } = require('../platform');
+const { buildToolPlan } = require('../pkg/builders');
+const { closestMatches } = require('../utils/closest-match');
+const { executeInstall } = require('./executor');
+const { renderResults } = require('./report');
+const { appendInstalled } = require('../setup/registry');
+const { parseToolIds } = require('./plan');
+const { saveReport } = require('../reports');
+const { getVersion } = require('../commands/version');
+
+// Builds plan entries for a validated tool-id list (shared with plan.js).
+function planEntriesFor(requested, { environment } = {}) {
+  const catalog = loadCatalog();
+  const byId = new Map(catalog.flatMap(c => c.tools.map(t => [t.id, { ...t, category: c.id }])));
+  const unknown = requested.filter(id => !byId.has(id));
+  if (unknown.length > 0) {
+    const allIds = [...byId.keys()];
+    const suggestions = [...new Set(unknown.flatMap(id => closestMatches(id, allIds)))].slice(0, 5);
+    const lines = [`Unknown tool id in ADM_TOOLS: ${unknown.join(', ')}`];
+    if (suggestions.length > 0) lines.push(`Did you mean: ${suggestions.join(', ')}?`);
+    lines.push('');
+    lines.push('Valid tool ids:');
+    lines.push(allIds.join(', '));
+    return { unknown: true, message: lines.join('\n') };
+  }
+  const env = environment || detectEnvironment();
+  const entries = requested.map(id => {
+    const tool = byId.get(id);
+    return { id, name: tool.name, category: tool.category, method: tool.installMethod, ...buildToolPlan(tool, env) };
+  });
+  return { unknown: false, entries, environment: env };
+}
+
+// Real install run: ADM_TOOLS=<ids> adm  (no ADM_DRY_RUN).
+// Exit codes: 0 = all installed/skipped · 1 = unknown tool id (usage) ·
+//             2 = at least one install failed (execution failure).
+async function runInstall(toolsSpec, opts = {}) {
+  const log = opts.log || (s => process.stdout.write(s + '\n'));
+  const err = opts.err || (s => process.stderr.write(s + '\n'));
+
+  let requested;
+  try {
+    requested = parseToolIds(toolsSpec);
+  } catch (e) {
+    err(`ADM failed: ${e.message}`);
+    return 2;
+  }
+
+  let plan;
+  try {
+    plan = planEntriesFor(requested);
+  } catch (e) {
+    err(`ADM failed: cannot load the tool catalog: ${e.message}`);
+    return 2;
+  }
+  if (plan.unknown) {
+    err(plan.message);
+    return 1;
+  }
+
+  const outcome = await executeInstall(plan.entries, {
+    ...opts,
+    rcFile: plan.environment.rcFile,
+    onInstalled: opts.onInstalled || (entry => appendInstalled(entry, { configDir: opts.configDir })),
+  });
+
+  const reportText = renderResults(outcome.results, { summary: false });
+  log(reportText);
+  log('');
+  log(`Done: ${outcome.installed} installed, ${outcome.skipped} skipped, ${outcome.failed} failed.`);
+
+  // Persist the report to the global cache (owner decision) — a missing
+  // config dir yields a loud ⚠ on stderr, never a silent skip.
+  const body = [
+    `ADM install report — ${new Date().toISOString()}`,
+    `ADM ${getVersion()} · ADM_TOOLS=${toolsSpec}`,
+    '',
+    reportText,
+    `Done: ${outcome.installed} installed, ${outcome.skipped} skipped, ${outcome.failed} failed.`,
+  ].join('\n') + '\n';
+  const saved = saveReport('install', body, { configDir: opts.configDir });
+  if (saved.error) err(`⚠ ${saved.error}`);
+
+  return outcome.failed > 0 ? 2 : 0;
+}
+
+module.exports = { runInstall, planEntriesFor };

package/src/install/shell-paths.js

@@ -0,0 +1,129 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Idempotent writer of PATH entries into shell rc files (#29, #31).
+//
+// Contract:
+//   - writes to the rc of the CURRENT shell (bash → .bashrc, zsh → .zshrc …)
+//   - double run = zero duplicates (marker is replaced, not appended)
+//   - cleans old ADM markers from any previous version (v0.2 included)
+
+// Every marker string ADM has ever written into rc files. Cleaning removes
+// every line containing any of them; `upsertRcEntry` re-adds only the current
+// marker + entry pair.
+const ADM_RC_MARKERS = ['# adm-cli', 'adm completion', 'adm-cli npm path'];
+
+// Canonical managed entries: marker line + the PATH line appended after it.
+// Keys are purposes; both entries are cleaned from any rc we touch.
+const RC_ENTRIES = {
+  'npm-global': {
+    marker: '# adm-cli npm path',
+    line: 'export PATH="$HOME/.npm-global/bin:$PATH"',
+  },
+  launcher: {
+    marker: '# adm-cli',
+    line: 'export PATH="$HOME/.local/bin:$PATH"',
+  },
+};
+
+function entryFor(entry) {
+  if (typeof entry === 'string') {
+    const def = RC_ENTRIES[entry];
+    if (!def) throw new Error(`unknown rc entry "${entry}" — valid: ${Object.keys(RC_ENTRIES).join(', ')}`);
+    return def;
+  }
+  return entry; // { marker, line } custom pair
+}
+
+// Builds the managed block ("marker\nline") for an entry.
+function entryBlock(entry) {
+  const def = entryFor(entry);
+  return `${def.marker}\n${def.line}`;
+}
+
+// Lines this module considers "managed by ADM" for a given entry: the marker
+// lines of ANY ADM version plus the exact canonical PATH lines. Removing them
+// before appending is what makes old markers disappear on the way.
+function managedLines(entry) {
+  const def = entryFor(entry);
+  const lines = [...ADM_RC_MARKERS];
+  for (const key of Object.keys(RC_ENTRIES)) {
+    if (key !== 'launcher' && key !== 'npm-global') continue;
+    lines.push(RC_ENTRIES[key].line);
+  }
+  // Custom entries carry their own line.
+  if (!def.marker) lines.push(def.line);
+  else lines.push(def.line);
+  return lines;
+}
+
+// Reads an rc file; returns '' when missing (fresh machine).
+function readRc(rcPath, readFile) {
+  try {
+    return readFile(rcPath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+// Upserts the entry block into the rc file.
+//   rcFile — basename in home (".bashrc") or an absolute path; null → no rc
+//            known for this shell → { changed: false, reason: 'no-rc-file' }.
+// Returns { changed, rcFile, removed } (removed = ADM-managed lines cleaned).
+function upsertRcEntry(opts = {}) {
+  const {
+    rcFile,
+    entry,
+    home = os.homedir(),
+    readFile = fs.readFileSync,
+    writeFile = fs.writeFileSync,
+    existsSync = fs.existsSync,
+  } = opts;
+
+  if (!rcFile) return { changed: false, rcFile: null, removed: 0, reason: 'no-rc-file' };
+
+  const rcPath = path.isAbsolute(rcFile) ? rcFile : path.join(home, rcFile);
+  const def = entryFor(entry);
+  const original = readRc(rcPath, readFile);
+  const lines = original.split('\n');
+
+  const strip = managedLines(entry);
+  const kept = lines.filter(line => !strip.some(s => line.trim() === s.trim() || line.includes(s)));
+  const removed = lines.length - kept.length;
+
+  // Drop leading/trailing blank lines left over by removals, keep body intact.
+  const body = kept.join('\n').replace(/\n{3,}$/, '\n\n').replace(/^\n+/, '');
+  const block = entryBlock(entry);
+  const content = body ? `${body.replace(/\n+$/, '')}\n\n${block}\n` : `${block}\n`;
+
+  const unchanged = original === content;
+  if (!unchanged) {
+    if (!existsSync(path.dirname(rcPath))) {
+      return { changed: false, rcFile: rcPath, removed, reason: 'no-home-dir' };
+    }
+    writeFile(rcPath, content, 'utf8');
+  }
+  return { changed: !unchanged, rcFile: rcPath, removed };
+}
+
+// Only removes ADM-managed lines (no re-add). Used by uninstall flows that
+// want a surgical cleanup for a single rc.
+function cleanRcEntry(opts = {}) {
+  const {
+    rcFile,
+    home = os.homedir(),
+    readFile = fs.readFileSync,
+    writeFile = fs.writeFileSync,
+  } = opts;
+  if (!rcFile) return { changed: false, removed: 0 };
+  const rcPath = path.isAbsolute(rcFile) ? rcFile : path.join(home, rcFile);
+  const original = readRc(rcPath, readFile);
+  const lines = original.split('\n');
+  const kept = lines.filter(line => !ADM_RC_MARKERS.some(m => line.includes(m)));
+  const removed = lines.length - kept.length;
+  if (removed > 0) writeFile(rcPath, kept.join('\n'), 'utf8');
+  return { changed: removed > 0, removed };
+}
+
+module.exports = { upsertRcEntry, cleanRcEntry, RC_ENTRIES, ADM_RC_MARKERS, entryBlock };

package/src/legacy-cleanup.js

@@ -0,0 +1,96 @@
+const fs = require('fs');
+const path = require('path');
+const { configDir, readConfig, writeConfig } = require('./config');
+
+// v0.3 removed the AI/GitHub/GitLab features. On the first start of v0.3 we
+// delete everything those features left on disk — tokens must not sit around
+// unread — and remember it with a `cleanedAt` marker in the config.
+//
+// Legacy artifacts:
+//   ~/.adm/tokens.enc        — encrypted GitHub/GitLab tokens
+//   ~/.adm/ai-knowledge.json — AI knowledge cache
+//   macOS keychain entries   — service "adm-cli" (github-token, gitlab-token…)
+//
+// Runs at most once: skipped when config.cleanedAt is set.
+const LEGACY_FILES = ['tokens.enc', 'ai-knowledge.json'];
+const KEYCHAIN_SERVICE = 'adm-cli';
+
+function listKeychainAccounts() {
+  const { execFileSync } = require('child_process');
+  try {
+    const out = execFileSync('security', ['dump-keychain'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const accounts = [];
+    // dump-keychain prints one block per entry; match the service and account
+    // attributes within each block.
+    const svceRe = /"svce"<blob>="([^"]*)"/g;
+    const acctRe = /"acct"<blob>="([^"]+)"/g;
+    for (const entry of out.split(/(?=class:)/g)) {
+      svceRe.lastIndex = 0;
+      acctRe.lastIndex = 0;
+      const svce = svceRe.exec(entry);
+      const acct = acctRe.exec(entry);
+      if (svce && acct && svce[1] === KEYCHAIN_SERVICE) accounts.push(acct[1]);
+    }
+    return accounts;
+  } catch {
+    return [];
+  }
+}
+
+function deleteKeychainAccount(account) {
+  const { execFileSync } = require('child_process');
+  try {
+    execFileSync('security', ['delete-generic-password', '-s', KEYCHAIN_SERVICE, '-a', account],
+      { stdio: ['ignore', 'pipe', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function legacyCleanup({ log, platform, env } = {}) {
+  log = log || (s => process.stdout.write(s + '\n'));
+  platform = platform || process.platform;
+  env = env || process.env;
+
+  const dir = process.env.ADM_CONFIG_DIR || configDir();
+  const config = await readConfig();
+  if (config.cleanedAt) return { skipped: true, removed: [] };
+
+  const removed = [];
+
+  // Files from the old AI/token features
+  for (const name of LEGACY_FILES) {
+    const file = path.join(dir, name);
+    try {
+      fs.unlinkSync(file);
+      removed.push(file);
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+  }
+
+  // macOS keychain tokens
+  if (platform === 'darwin') {
+    for (const account of listKeychainAccounts()) {
+      if (deleteKeychainAccount(account)) removed.push(`keychain:${KEYCHAIN_SERVICE}/${account}`);
+    }
+  }
+
+  const marker = { ...config, cleanedAt: new Date().toISOString() };
+  await writeConfig(marker);
+
+  if (removed.length > 0) {
+    const lines = [
+      'ADM cleanup: removed data from features that were dropped in v0.3 (AI, GitHub/GitLab integrations):',
+      ...removed.map(r => `  - ${r}`),
+      '',
+      'Your secrets were deleted so they do not sit unread on disk.',
+    ];
+    log(lines.join('\n'));
+  }
+
+  return { skipped: false, removed };
+}
+
+module.exports = { legacyCleanup, LEGACY_FILES, KEYCHAIN_SERVICE };

package/src/pkg/builders.js

@@ -0,0 +1,220 @@
+const { resolvePackageName } = require('./package-names');
+const { resolveScript } = require('./script-urls');
+const { installCommand } = require('./managers');
+
+// ── ecosystem package-name overrides ──────────────────────────
+// Only where the install identifier differs from the catalog tool id.
+const GO_PACKAGES = {
+  'golangci-lint': 'github.com/golangci/golangci-lint/v2/cmd/golangci-lint',
+  goreleaser: 'github.com/goreleaser/goreleaser/v2',
+  air: 'github.com/air-verse/air',
+  ginkgo: 'github.com/onsi/ginkgo/v2/ginkgo',
+  delve: 'github.com/go-delve/delve/cmd/dlv',
+  gofumpt: 'mvdan.cc/gofumpt',
+  goimports: 'golang.org/x/tools/cmd/goimports',
+  gomock: 'go.uber.org/mock/mockgen',
+  staticcheck: 'honnef.co/go/tools/cmd/staticcheck',
+  gosec: 'github.com/securego/gosec/v2/cmd/gosec',
+  gotestsum: 'gotest.tools/gotestsum',
+  swag: 'github.com/swaggo/swag/cmd/swag',
+  'protoc-gen-go': 'google.golang.org/protobuf/cmd/protoc-gen-go',
+  grpcurl: 'github.com/fullstorydev/grpcurl/cmd/grpcurl',
+  ghq: 'github.com/x-motemen/ghq',
+  fzf: 'github.com/junegunn/fzf',
+  lazygit: 'github.com/jesseduffield/lazygit',
+  hugo: 'github.com/gohugoio/hugo',
+  temporal: 'github.com/temporalio/cli/cmd/temporal',
+  ko: 'github.com/google/ko',
+  buf: 'github.com/bufbuild/buf/cmd/buf',
+};
+
+const CARGO_PACKAGES = { delta: 'git-delta' };
+const GEM_PACKAGES = { 'factory-bot': 'factory_bot' };
+const COMPOSER_PACKAGES = {
+  'php-cs-fixer': 'friendsofphp/php-cs-fixer',
+  phpunit: 'phpunit/phpunit',
+  pest: 'pestphp/pest',
+  laravel: 'laravel/installer',
+  drush: 'drush/drush',
+  deployer: 'deployer/deployer',
+  phan: 'phan/phan',
+  rector: 'rector/rector',
+  infection: 'infection/infection',
+};
+const DOTNET_PACKAGES = {
+  sonarscanner: 'dotnet-sonarscanner',
+  coverlet: 'coverlet.console',
+  reportgenerator: 'dotnet-reportgenerator-globaltool',
+  roslynator: 'roslynator.commandline',
+  nuke: 'nuke.globaltool',
+};
+
+// Binary produced after install (for `command -v <bin>` status checks) where
+// it differs from the catalog id.
+const NPM_BINS = {
+  '@anthropic-ai/claude-code': 'claude',
+  '@openai/codex': 'codex',
+  '@anthropic-ai/gemini-cli': 'gemini',
+  '@githubnext/github-copilot-cli': 'github-copilot-cli',
+  '@plandex/cli': 'plandex',
+  // npm package name differs from the produced binary — the status probe
+  // must check the REAL command or installed tools look "not installed"
+  // (HITL finding, 0.3.0: picking installed TypeScript kept re-"installing").
+  typescript: 'tsc',
+};
+const GO_BINS = { delve: 'dlv', gomock: 'mockgen' };
+const CARGO_BINS = { delta: 'delta', 'fd-find': 'fd', ripgrep: 'rg', 'du-dust': 'dust', bottom: 'btm' };
+
+const NVM_INSTALL = 'curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | sh';
+
+// Pick the python installer command:
+//   pip available → pip / pip3 available → pip3 / otherwise → python3 -m pip
+// On Windows the fallback MUST be `python -m pip`: python3.exe is commonly a
+// Microsoft Store alias stub that silently opens the Store (installs hang).
+function pipCommand(pkgName, availability = {}, os) {
+  if (availability.pip) return `pip install --upgrade ${pkgName}`;
+  if (availability.pip3) return `pip3 install --upgrade ${pkgName}`;
+  const python = os === 'win32' ? 'python -m pip install --upgrade' : 'python3 -m pip install --upgrade';
+  return `${python} ${pkgName}`;
+}
+
+// Builds the install plan entry for one tool in one environment.
+// Returns:
+//   { status: 'planned', command, manager?, package?, statusSource }
+//   { status: 'manual', reason }
+//   { status: 'link', url }
+function buildToolPlan(tool, env, opts = {}) {
+  const method = tool.installMethod;
+  const id = tool.id;
+
+  const planned = (fields) => ({
+    status: 'planned',
+    ...fields,
+    statusSource: fields.statusSource || `command -v ${statusBin(id, method)}`,
+  });
+
+  switch (method) {
+    case 'nvm':
+      // POSIX nvm installs via the official script. Windows has no `sh` (and
+      // nvm-windows is a different tool entirely) — install Node.js LTS
+      // through the detected manager instead (HITL finding, 0.3.0).
+      if (env.os === 'win32') {
+        const NODE_WIN = { winget: 'OpenJS.NodeJS.LTS', choco: 'nodejs-lts', scoop: 'nodejs-lts' };
+        const nodePkg = NODE_WIN[env.manager];
+        if (!nodePkg) {
+          return { status: 'manual', reason: 'no supported package manager for Node.js — install the LTS from https://nodejs.org' };
+        }
+        return planned({ command: installCommand(env.manager, nodePkg), manager: env.manager, package: nodePkg, statusSource: 'command -v node' });
+      }
+      return planned({ command: NVM_INSTALL, statusSource: 'command -v node' });
+
+    case 'npm':
+    case 'node': {
+      const name = NPM_BINS[id] || id;
+      return planned({ command: `npm install -g ${id}@latest`, statusSource: `command -v ${name}` });
+    }
+
+    case 'pip':
+    case 'python': {
+      const pkgName = id;
+      return planned({ command: pipCommand(pkgName, opts.pipAvailability, env.os) });
+    }
+
+    case 'cargo': {
+      const crate = CARGO_PACKAGES[id] || id;
+      return planned({ command: `cargo install ${crate}`, package: crate, statusSource: `command -v ${CARGO_BINS[id] || id}` });
+    }
+
+    case 'go': {
+      const modulePath = GO_PACKAGES[id] || id;
+      return planned({ command: `go install ${modulePath}@latest`, package: modulePath, statusSource: `command -v ${GO_BINS[id] || id}` });
+    }
+
+    case 'gem': {
+      const gem = GEM_PACKAGES[id];
+      if (!gem) {
+        // dry-rb is a family of gems, not a single installable gem
+        if (id === 'dry-rb') return { status: 'manual', reason: 'dry-rb is a family of gems (dry-validation, dry-rails…) — install the gem you need: https://dry-rb.org' };
+      }
+      return planned({ command: `gem install ${gem || id}`, package: gem || id });
+    }
+
+    case 'composer': {
+      const pkgName = COMPOSER_PACKAGES[id] || id;
+      return planned({ command: `composer global require ${pkgName}`, package: pkgName });
+    }
+
+    case 'dotnet': {
+      const pkgName = DOTNET_PACKAGES[id] || id;
+      return planned({ command: `dotnet tool install -g ${pkgName}`, package: pkgName });
+    }
+
+    case 'rustup': {
+      // rustup itself (the "cargo" catalog entry) and rustup components
+      if (id === 'cargo') {
+        const s = resolveScript('rustup', env.os, env.arch);
+        if (s.manual) return { status: 'manual', reason: s.manual };
+        return planned({ command: s.run, shell: s.shell, statusSource: 'command -v cargo' });
+      }
+      return planned({ command: `rustup component add ${id}` });
+    }
+
+    case 'script': {
+      const resolved = resolveScript(id, env.os, env.arch);
+      if (resolved.manual) return { status: 'manual', reason: resolved.manual };
+      // `shell: 'powershell'` propagates to the executor (Windows-only scripts).
+      return planned({ command: resolved.run, package: resolved.url, shell: resolved.shell });
+    }
+
+    case 'link':
+      return { status: 'link', url: tool.url || `https://marketplace.visualstudio.com/search?term=${id}` };
+
+    default: {
+      // Manager-backed install: brew / apt / dnf / pacman / zypper / apk /
+      // winget / choco / scoop. Manager methods in the catalog all mean
+      // "install via the system manager" — resolved per environment.
+      const resolved = resolvePackageName(id, env.manager);
+      if (resolved.manual) return { status: 'manual', reason: resolved.manual };
+      const command = installCommand(env.manager, resolved.name);
+      if (!command) return { status: 'manual', reason: `no package manager detected on ${env.os} — install ${id} manually` };
+      return planned({ command, manager: env.manager, package: resolved.name });
+    }
+  }
+}
+
+// Best-effort retry route for a tool whose primary plan came back manual
+// (#34: the wizard must try, not silently refuse). The manager route already
+// failed — before giving up, try the script-installer table for the same
+// platform. Returns the original entry when no script route exists either
+// (the executor then reports `failed` with the reason as the hint).
+function withFallbackRoute(entry, env) {
+  if (entry.status !== 'manual') return entry;
+  const resolved = resolveScript(entry.id, env.os, env.arch);
+  if (resolved.manual) return entry;
+  return {
+    ...entry,
+    status: 'planned',
+    command: resolved.run,
+    package: resolved.url,
+    shell: resolved.shell,
+    method: 'script',
+    retryFallback: true,
+    statusSource: entry.statusSource || `command -v ${statusBin(entry.id, 'script')}`,
+  };
+}
+
+function statusBin(id, method) {
+  if (NPM_BINS[id]) return NPM_BINS[id];
+  if (GO_BINS[id]) return GO_BINS[id];
+  if (CARGO_BINS[id]) return CARGO_BINS[id];
+  return id;
+}
+
+// Every install method the builders handle (builder matrix reference).
+const ALL_METHODS = [
+  'nvm', 'npm', 'node', 'pip', 'python', 'cargo', 'go', 'gem', 'composer',
+  'dotnet', 'rustup', 'script', 'link',
+  'brew', 'apt', 'dnf', 'pacman', 'zypper', 'apk', 'winget', 'choco', 'scoop',
+];
+
+module.exports = { buildToolPlan, withFallbackRoute, pipCommand, statusBin, ALL_METHODS, NVM_INSTALL };

package/src/pkg/managers.js

@@ -0,0 +1,59 @@
+const fs = require('fs');
+const path = require('path');
+
+// Package-manager abstraction: which binary to look up and how to build the
+// install command for a package name. All commands are POSIX `sh` compatible —
+// no /bin/bash hardcoding (Alpine, NixOS…).
+const MANAGERS = {
+  brew:   { os: 'darwin', bin: 'brew',   install: pkgName => `brew install ${pkgName}` },
+  apt:    { os: 'linux',  bin: 'apt-get', install: pkgName => `sudo apt-get install -y ${pkgName}` },
+  dnf:    { os: 'linux',  bin: 'dnf',     install: pkgName => `sudo dnf install -y ${pkgName}` },
+  pacman: { os: 'linux',  bin: 'pacman',  install: pkgName => `sudo pacman -S --noconfirm ${pkgName}` },
+  zypper: { os: 'linux',  bin: 'zypper',  install: pkgName => `sudo zypper install -y ${pkgName}` },
+  apk:    { os: 'linux',  bin: 'apk',     install: pkgName => `sudo apk add ${pkgName}` },
+  winget: { os: 'win32',  bin: 'winget',  install: pkgName => `winget install --id ${pkgName} --exact --accept-source-agreements --accept-package-agreements` },
+  choco:  { os: 'win32',  bin: 'choco',   install: pkgName => `choco install ${pkgName} --yes` },
+  scoop:  { os: 'win32',  bin: 'scoop',   install: pkgName => `scoop install ${pkgName}` },
+};
+
+const SUPPORTED_MANAGERS = Object.keys(MANAGERS);
+
+// Checks whether the manager's binary exists in PATH. Pure fs walk — no exec,
+// fast enough for dry-run planning, deterministic and testable via env override.
+function isManagerAvailable(name, opts = {}) {
+  const def = MANAGERS[name];
+  if (!def) return false;
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+  const statSync = opts.statSync || fs.statSync;
+  const accessSync = opts.accessSync || fs.accessSync;
+
+  const sep = platform === 'win32' ? ';' : ':';
+  const dirs = (env.PATH || env.Path || '').split(sep).filter(Boolean);
+  const exts = platform === 'win32'
+    ? ['', '.exe', '.cmd', '.bat', '.ps1']
+    : [''];
+
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = `${dir}${path.sep}${def.bin}${ext}`;
+      try {
+        statSync(candidate);
+        accessSync(candidate);
+        return true;
+      } catch {
+        // next candidate
+      }
+    }
+  }
+  return false;
+}
+
+// Install command for a manager + package name, or null for unknown manager.
+function installCommand(manager, pkgName) {
+  const def = MANAGERS[manager];
+  if (!def) return null;
+  return def.install(pkgName);
+}
+
+module.exports = { MANAGERS, SUPPORTED_MANAGERS, isManagerAvailable, installCommand };