@crystalplatforms/adm 0.2.3 → 0.3.0

package/src/engines.js

@@ -0,0 +1,38 @@
+// Node-version gate (#33): the only module bin/adm may require on OLD Node.
+// bin/adm itself and this file stay old-Node-parseable (no optional chaining,
+// no ??) — src/ elsewhere is allowed modern syntax because this check runs
+// BEFORE any other require, turning an opaque SyntaxError into a friendly,
+// enumerated fix list (story 4), exit 1.
+
+var NODE_MAJOR_MIN = 20;
+var NPM_PACKAGE = '@crystalplatforms/adm';
+var REPO = 'CrystalPlatforms/ADM-CLI';
+
+function nodeCheck(versions, majorMin) {
+  var min = majorMin || NODE_MAJOR_MIN;
+  var v = (versions && versions.node) || '0';
+  var major = Number(String(v).split('.')[0]);
+  var ok = major >= min;
+  var message = '';
+  if (!ok) {
+    var lines = [
+      '',
+      'ADM needs Node.js ' + min + ' or newer (you have v' + v + ').',
+      '',
+      'Fix it any of these ways:',
+      '  1. Install the Node.js LTS from https://nodejs.org',
+      '  2. nvm:      nvm install ' + min + ' && nvm use ' + min,
+      '  3. fnm:      fnm install ' + min + ' && fnm use ' + min,
+      '  4. Windows:  winget install OpenJS.NodeJS.LTS',
+      '',
+      'Or skip Node entirely — install the portable bundle (recommended):',
+      '  macOS / Linux:  curl -fsSL https://raw.githubusercontent.com/' + REPO + '/main/scripts/installer.sh | sh',
+      '  Windows:        irm https://raw.githubusercontent.com/' + REPO + '/main/scripts/install.ps1 | iex',
+      '',
+    ];
+    message = lines.join('\n') + '\n';
+  }
+  return { ok: ok, version: v, major: major, min: min, message: message };
+}
+
+module.exports = { nodeCheck, NODE_MAJOR_MIN, NPM_PACKAGE };

package/src/install/executor.js

@@ -0,0 +1,263 @@
+const { hintFor } = require('./hints');
+const { repairNpmPrefix, npmBinDir } = require('./npm-prefix');
+
+// Executes install-plan entries produced by buildToolPlan (#28) for real
+// (#29). Per tool it returns one of:
+//   { status: 'installed', command, binDirs? }
+//   { status: 'skipped',   reason: 'already installed' }
+//   { status: 'failed',    command, error, hint }   ← hint = copyable fix
+//
+// Contract details the acceptance criteria pin down:
+//   - every command runs through POSIX `sh` (the shell option literally says
+//     "sh") — no /bin/bash hardcode, Alpine/NixOS keep working (story 13)
+//   - after a successful install the tool's bin dir is prepended to THIS
+//     process' PATH, so later installs in the same run see the new binary
+//   - an npm EACCES triggers the no-sudo prefix repair (~/.npm-global) and
+//     exactly one retry; a second failure returns `failed` + hint
+
+const EXEC_TIMEOUT_MS = 20 * 60 * 1000; // generous: heavy deps (aider-chat, torch…) build for a long time
+
+// Default executor shell per platform: POSIX `sh` everywhere (story 13 — no
+// /bin/bash hardcode), cmd.exe on Windows (sh.exe is not part of the OS;
+// winget/choco/scoop commands are cmd-compatible).
+function defaultShell(platform) {
+  return platform === 'win32' ? true : 'sh';
+}
+
+// The status probe text (`command -v <bin>`) is POSIX; cmd.exe needs `where`.
+function probeCommand(statusSource, platform) {
+  if (platform === 'win32') return String(statusSource).replace(/^command -v\s+/, 'where ');
+  return statusSource;
+}
+
+// Runs a command. execFunc injectable for tests (they assert the shell option
+// is 'sh' on POSIX). Resolves { code, stdout, stderr }.
+function shExec(command, opts = {}) {
+  const execFunc = opts.execFunc || require('child_process').exec;
+  const shell = opts.shell === undefined ? defaultShell(opts.platform || process.platform) : opts.shell;
+  return new Promise(resolve => {
+    execFunc(command, {
+      shell,
+      timeout: opts.timeoutMs || EXEC_TIMEOUT_MS,
+      maxBuffer: 16 * 1024 * 1024,
+      env: opts.env,
+    }, (err, stdout, stderr) => {
+      resolve({
+        code: err ? (err.code === undefined ? 1 : err.code) : 0,
+        stdout: String(stdout || ''),
+        stderr: String(stderr || ''),
+        err,
+      });
+    });
+  });
+}
+
+// Status probe: runs the entry's statusSource (`command -v <bin>` / `where`
+// on Windows). Unix probes always run in sh.
+async function isInstalled(entry, opts = {}) {
+  const platform = opts.platform || process.platform;
+  const source = entry.statusSource || `command -v ${entry.id}`;
+  const res = await shExec(probeCommand(source, platform), {
+    execFunc: opts.execFunc,
+    shell: platform === 'win32' ? true : 'sh',
+    platform,
+  });
+  return res.code === 0;
+}
+
+// Well-known bin dirs per install method — used for the in-process PATH
+// refresh. Candidates that don't exist on disk are skipped by refreshPath.
+const METHOD_BIN_CANDIDATES = {
+  npm: (entry, ctx) => (ctx.npmBin ? [ctx.npmBin] : []),
+  node: (entry, ctx) => (ctx.npmBin ? [ctx.npmBin] : []),
+  nvm: () => [], // resolved dynamically via `nvm which current`
+  cargo: () => ['~/.cargo/bin'],
+  go: () => ['~/go/bin'],
+  gem: () => ['~/.gem/ruby/bin'],
+  composer: () => ['~/.composer/vendor/bin', '~/.config/composer/vendor/bin'],
+  dotnet: () => ['~/.dotnet/tools'],
+  pip: () => ['~/.local/bin'],
+  python: () => ['~/.local/bin'],
+  script: () => ['~/.local/bin'],
+  rustup: () => ['~/.cargo/bin'],
+};
+
+// Resolves bin dirs for a freshly installed entry (exec for dynamic ones).
+async function resolveBinDirs(entry, opts = {}) {
+  const home = opts.home || require('os').homedir();
+  const platform = opts.platform || process.platform;
+  const expand = p => p.replace(/^~(?=\/|$)/, home);
+  const dirs = [];
+  const fs = opts.fs || require('fs');
+
+  const push = d => { if (!dirs.includes(d)) dirs.push(d); };
+
+  const candidates = (METHOD_BIN_CANDIDATES[entry.method] || (() => []))(entry, opts) || [];
+  for (const c of candidates) {
+    const dir = expand(c);
+    try { fs.accessSync(dir); push(dir); } catch { /* not created — skip */ }
+  }
+
+  if (entry.method === 'nvm') {
+    const res = await shExec('. "$HOME/.nvm/nvm.sh" && nvm which current', {
+      execFunc: opts.execFunc, shell: 'sh',
+    });
+    if (res.code === 0 && res.stdout.trim()) {
+      const nodeBin = require('path').dirname(res.stdout.trim().split('\n').pop().trim());
+      try { fs.accessSync(nodeBin); push(nodeBin); } catch { /* skip */ }
+    }
+  }
+
+  if (entry.method === 'npm' || entry.method === 'node') {
+    // A repaired prefix means the bin dir is ~/.npm-global/bin, not the
+    // system prefix the process started with.
+    const { getNpmPrefix } = require('./npm-prefix');
+    const prefix = opts.npmPrefix || await getNpmPrefix({ execFunc: opts.execFunc, platform });
+    const bin = npmBinDir(prefix, platform);
+    if (bin) {
+      try { fs.accessSync(expand(bin)); push(expand(bin)); } catch { /* skip */ }
+    }
+  }
+
+  return dirs;
+}
+
+// Prepends dirs to THIS process' PATH so later installs see new binaries.
+// Returns the dirs actually added (dedup, existence-checked upstream).
+function refreshProcessPath(dirs, { env, platform } = {}) {
+  env = env || process.env;
+  platform = platform || process.platform;
+  const key = platform === 'win32' ? 'Path' in env ? 'Path' : 'PATH' : 'PATH';
+  const sep = platform === 'win32' ? ';' : ':';
+  const current = (env[key] || '').split(sep).filter(Boolean);
+  const added = dirs.filter(d => !current.includes(d));
+  if (added.length > 0) {
+    env[key] = [...added, ...current].join(sep);
+  }
+  return added;
+}
+
+function isEaccsFailure(res) {
+  const text = `${res.stderr}\n${res.stdout}\n${res.err && res.err.message || ''}`;
+  return /EACCES|EPERM|permission denied/i.test(text);
+}
+
+// Installs ONE entry. Returns the per-tool result (see module doc).
+// opts.force (or entry.force — set per-entry by the wizard's reinstall, #34)
+// skips the "already installed" probe: the install command runs regardless.
+async function installEntry(entry, opts = {}) {
+  const platform = opts.platform || process.platform;
+  const base = { id: entry.id, name: entry.name, category: entry.category, method: entry.method };
+
+  if (entry.status === 'manual') {
+    return { ...base, status: 'failed', error: entry.reason, hint: entry.reason };
+  }
+  if (entry.status === 'link') {
+    return { ...base, status: 'skipped', reason: 'manual extension — install from the link', url: entry.url };
+  }
+
+  // Already present → skipped (AC: rerun → all skipped) — unless the caller
+  // explicitly forces a reinstall (#34: wizard picks of installed tools).
+  if (!opts.force && !entry.force && await isInstalled(entry, opts)) {
+    return { ...base, status: 'skipped', reason: 'already installed', statusSource: entry.statusSource };
+  }
+
+  // Reinstall semantics (HITL finding, 0.3.0): winget refuses a plain
+  // `install` when the package already exists ("No applicable upgrade
+  // found", exit ≠ 0) — a forced reinstall needs `--force`. choco likewise
+  // needs `--force` to actually reinstall instead of no-op-ing. npm/brew/
+  // apt & friends reinstall (or no-op with exit 0) out of the box.
+  const command = entry.force && (entry.manager === 'winget' || entry.manager === 'choco')
+    ? `${entry.command} --force`
+    : entry.command;
+  // shell: 'powershell' only for Windows script-tools that need it; otherwise
+  // the per-platform default (sh on unix, cmd on Windows).
+  const shell = platform === 'win32' && entry.shell ? entry.shell : undefined;
+
+  const run = () => shExec(command, { execFunc: opts.execFunc, shell, timeoutMs: opts.timeoutMs, platform });
+
+  let res = await run();
+
+  // npm global EACCES → no-sudo prefix repair + one retry.
+  if (res.code !== 0 && isEaccsFailure(res) &&
+      (entry.method === 'npm' || entry.method === 'node') && platform !== 'win32' &&
+      opts.npmPrefixRepair !== false) {
+    const repairFn = opts.repairNpmPrefix || repairNpmPrefix;
+    const repair = await repairFn({
+      home: opts.home, platform, execFunc: opts.execFunc, rcFile: opts.rcFile,
+    });
+    if (repair.repaired) {
+      res = await run();
+      if (res.code === 0) {
+        const binDirs = await resolveBinDirs(entry, { ...opts, npmPrefix: repair.prefix });
+        return {
+          ...base, status: 'installed', command, binDirs,
+          note: 'npm prefix repaired (~/.npm-global); future installs need no sudo',
+        };
+      }
+    }
+  }
+
+  if (res.code !== 0) {
+    const error = (res.stderr || res.stdout || '').trim().split('\n').slice(-6).join('\n')
+      || (res.err && res.err.message) || `exit code ${res.code}`;
+    return {
+      ...base,
+      status: 'failed',
+      command,
+      error,
+      hint: hintFor(`${res.stderr}\n${res.stdout}\n${res.err && res.err.message || ''}`, {
+        method: entry.method, command, manager: entry.manager, rcFile: opts.rcFile, platform,
+      }),
+    };
+  }
+
+  const binDirs = await resolveBinDirs(entry, opts);
+  return { ...base, status: 'installed', command, binDirs };
+}
+
+// Installs a list of entries sequentially, refreshing the in-process PATH
+// after each success. onProgress({ tool, result }) fires per finished tool
+// (the wizard drives its spinner from it); onInstalled fires per successful
+// install (the wizard/router hook the registry up to it).
+async function executeInstall(entries, opts = {}) {
+  const onProgress = opts.onProgress || (() => {});
+  const onStart = opts.onStart || (() => {});
+  const onInstalled = opts.onInstalled || null;
+  const results = [];
+
+  for (const entry of entries) {
+    onStart({ tool: entry });
+    const result = await installEntry(entry, opts);
+    if (result.status === 'installed' && result.binDirs && result.binDirs.length > 0) {
+      result.pathAdded = refreshProcessPath(result.binDirs, { env: opts.env, platform: opts.platform });
+    }
+    if (result.status === 'installed' && onInstalled) {
+      try {
+        await onInstalled({ id: entry.id, name: entry.name, method: entry.method });
+      } catch { /* registry must never break an install */ }
+    }
+    onProgress({ tool: entry, result });
+    results.push(result);
+  }
+
+  return {
+    results,
+    installed: results.filter(r => r.status === 'installed').length,
+    skipped: results.filter(r => r.status === 'skipped').length,
+    failed: results.filter(r => r.status === 'failed').length,
+  };
+}
+
+module.exports = {
+  executeInstall,
+  installEntry,
+  isInstalled,
+  refreshProcessPath,
+  resolveBinDirs,
+  shExec,
+  probeCommand,
+  defaultShell,
+  METHOD_BIN_CANDIDATES,
+  EXEC_TIMEOUT_MS,
+};

package/src/install/hints.js

@@ -0,0 +1,94 @@
+// Hint catalog (#29): a failed install must always end with a hint holding a
+// ready-to-copy command. `hintFor` is pure — no I/O — so tests assert on the
+// exact strings.
+
+const NPM_PREFIX_FIX = 'mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global';
+
+const HOMEBREW_INSTALL = '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"';
+
+// errorText: combined stdout+stderr of the failed command (or its message).
+// ctx: { tool, method, command, manager, rcFile, platform }
+// Returns a multi-line hint string. Always non-empty (generic fallback).
+function hintFor(errorText, ctx = {}) {
+  const text = String(errorText || '');
+  const command = ctx.command || '';
+  const lines = [];
+
+  const isNpm = ctx.method === 'npm' || ctx.method === 'node' ||
+    (typeof command === 'string' && command.startsWith('npm install'));
+
+  if (/EACCES|EPERM|permission denied/i.test(text)) {
+    if (isNpm && ctx.platform !== 'win32') {
+      lines.push('npm cannot write to its global prefix (permission denied).');
+      lines.push('Fix it without sudo — copy & run:');
+      lines.push(`  ${NPM_PREFIX_FIX}`);
+      if (ctx.rcFile) {
+        lines.push('Then make sure the prefix is on PATH (ADM adds this automatically on the next run):');
+        lines.push(`  echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/${ctx.rcFile}`);
+      }
+      return lines.join('\n');
+    }
+    if (command.includes('sudo')) {
+      lines.push('This install needs your password — run it manually in a terminal where you can type it:');
+      lines.push(`  ${command}`);
+      return lines.join('\n');
+    }
+    lines.push('Permission denied. Run the command with elevated permissions or fix ownership, e.g.:');
+    lines.push(`  sudo ${command}`);
+    return lines.join('\n');
+  }
+
+  if (/command not found|ENOENT|not recognized/i.test(text)) {
+    // Missing prerequisite binaries get targeted hints.
+    if (/^brew\b|\/brew\b/.test(command)) {
+      lines.push('Homebrew is not installed. Install it first:');
+      lines.push(`  ${HOMEBREW_INSTALL}`);
+      return lines.join('\n');
+    }
+    if (/\bpip\b/.test(command)) {
+      lines.push('pip is not available — use python3 -m pip instead (copy & run):');
+      lines.push(`  ${command.replace(/^pip\b/, 'python3 -m pip')}`);
+      return lines.join('\n');
+    }
+    if (isNpm || /npm\b/.test(command)) {
+      lines.push('npm was not found — install Node.js first: ADM_TOOLS=node adm');
+      return lines.join('\n');
+    }
+    lines.push('A required command was not found in PATH. Install it first, then retry.');
+    if (command) lines.push(`Command that failed: ${command}`);
+    return lines.join('\n');
+  }
+
+  // Package genuinely missing from the manager's repositories
+  // (winget: "No package found matching input criteria", apt: "Unable to
+  // locate package", dnf/pacman/apk/zypper variants).
+  if (/no package found matching input criteria|unable to locate package|no matching (packages|package)|target not found|unable to select packages|not found in (the )?repositories/i.test(text)) {
+    const SEARCH = {
+      winget: 'winget search', choco: 'choco search', scoop: 'scoop search',
+      apt: 'apt-cache search', dnf: 'dnf search', pacman: 'pacman -Ss',
+      zypper: 'zypper search', apk: 'apk search', brew: 'brew search',
+    };
+    lines.push(`This package is not in the ${ctx.manager || 'package manager'} repositories (or the id is different there).`);
+    if (ctx.manager && SEARCH[ctx.manager]) {
+      lines.push('Find the exact id, then retry — copy & run:');
+      lines.push(`  ${SEARCH[ctx.manager]} <term>`);
+    }
+    if (command) lines.push(`Command that failed: ${command}`);
+    return lines.join('\n');
+  }
+
+  // winget manifests that drifted from the actual installer file
+  if (/installer hash does not match/i.test(text)) {
+    lines.push("This winget package's manifest is outdated (the installer hash changed upstream) — it is a winget repository issue, not a broken setup.");
+    lines.push('Retry later, search a different version, or install it manually.');
+    if (command) lines.push(`Command that failed: ${command}`);
+    return lines.join('\n');
+  }
+
+  // Generic fallback: always points at the exact command to inspect.
+  lines.push('Install failed. Run the command manually to see the full error:');
+  if (command) lines.push(`  ${command}`);
+  return lines.join('\n');
+}
+
+module.exports = { hintFor, NPM_PREFIX_FIX, HOMEBREW_INSTALL };

package/src/install/npm-prefix.js

@@ -0,0 +1,110 @@
+const path = require('path');
+const { upsertRcEntry } = require('./shell-paths');
+
+// npm global-prefix repair without sudo (#29, story 16).
+//
+// When npm's global prefix is a system directory (/usr, /usr/local) that the
+// user cannot write to, `npm install -g` fails with EACCES. The fix:
+//   1. `npm config set prefix ~/.npm-global`
+//   2. PATH entry for ~/.npm-global/bin in the current shell's rc (marker)
+// Both steps are idempotent; step 2 goes through shell-paths.
+
+// System prefixes where a plain `npm install -g` needs root.
+const SYSTEM_PREFIXES = ['/usr', '/usr/local', '/usr/lib'];
+
+function defaultTarget(home) {
+  return `${home}${path.sep}.npm-global`;
+}
+
+// Checks whether a prefix directory is writable by the current user.
+// Injectable fs for tests; missing dir counts as "not writable".
+function isWritable(dir, { accessSync, constants } = {}) {
+  accessSync = accessSync || require('fs').accessSync;
+  constants = constants || require('fs').constants;
+  try {
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Runs `npm config get prefix` (exec injectable for tests).
+async function getNpmPrefix({ execFunc, platform } = {}) {
+  execFunc = execFunc || require('child_process').exec;
+  const res = await new Promise((resolve) => {
+    execFunc('npm config get prefix', { shell: platform === 'win32' ? undefined : 'sh' }, (err, stdout) => {
+      resolve({ err, out: String(stdout || '').trim() });
+    });
+  });
+  return res.out || '';
+}
+
+// True when the prefix needs repair: it is a known system prefix AND not
+// writable by the current user. Windows prefixes (%APPDATA%\npm) are
+// user-writable — never needs repair there.
+function prefixNeedsRepair(prefix, { home, platform, accessSync, constants } = {}) {
+  if (platform === 'win32') return false;
+  if (!prefix) return false;
+  const normalized = String(prefix).replace(/\/+$/, '');
+  const system = SYSTEM_PREFIXES.some(p => normalized === p || normalized.startsWith(`${p}/`));
+  if (!system) return false;
+  return !isWritable(normalized, { accessSync, constants });
+}
+
+// Applies the repair. Returns:
+//   { repaired, prefix, target, rcFile, hint }
+//   { repaired: false, reason } when nothing needed doing or a step failed.
+async function repairNpmPrefix(opts = {}) {
+  const {
+    home = require('os').homedir(),
+    platform = process.platform,
+    execFunc,
+    rcFile,
+    shellPaths = upsertRcEntry,
+  } = opts;
+
+  if (platform === 'win32') {
+    return { repaired: false, reason: 'windows — npm prefix is user-writable by default' };
+  }
+
+  const target = defaultTarget(home);
+  const exec = execFunc || require('child_process').exec;
+
+  // 1. point npm's global prefix at ~/.npm-global
+  const set = await new Promise((resolve) => {
+    exec(`npm config set prefix "${target}"`, { shell: 'sh' }, (err) => resolve({ err }));
+  });
+  if (set.err) {
+    return { repaired: false, reason: `npm config set prefix failed: ${set.err.message}`, hint: `  ${'mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global'}` };
+  }
+
+  // 2. PATH entry (idempotent, marker-managed)
+  let rc = null;
+  try {
+    const res = shellPaths({ rcFile, entry: 'npm-global', home });
+    rc = res.rcFile;
+  } catch {
+    rc = null;
+  }
+
+  return {
+    repaired: true,
+    prefix: target,
+    target,
+    rcFile: rc,
+    hint: [
+      'npm prefix repaired — future global installs go to ~/.npm-global (no sudo).',
+      'Open a new shell or copy & run to use it right now:',
+      '  export PATH="$HOME/.npm-global/bin:$PATH"',
+    ].join('\n'),
+  };
+}
+
+// Binary dir for a given npm prefix (unix appends /bin; windows is flat).
+function npmBinDir(prefix, platform = process.platform) {
+  if (!prefix) return null;
+  return platform === 'win32' ? prefix : `${prefix.replace(/\/+$/, '')}/bin`;
+}
+
+module.exports = { repairNpmPrefix, prefixNeedsRepair, getNpmPrefix, npmBinDir, SYSTEM_PREFIXES, isWritable, defaultTarget };

package/src/install/plan.js

@@ -0,0 +1,75 @@
+const { loadCatalog } = require('../setup/catalog');
+const { detectEnvironment, formatEnvironment } = require('../platform');
+const { buildToolPlan } = require('../pkg/builders');
+const { closestMatches } = require('../utils/closest-match');
+
+// Parses the ADM_TOOLS spec ("id,id id") into tool ids.
+function parseToolIds(spec) {
+  return String(spec)
+    .split(/[\s,]+/)
+    .map(s => s.trim())
+    .filter(Boolean);
+}
+
+// Non-interactive install planning: ADM_TOOLS=<ids> adm
+// Prints the plan for the current environment, changes nothing, exits 0.
+// Unknown ids → usage error (1) enumerating the valid ids with closest
+// matches. Execution errors → 2.
+function runPlan(toolsSpec, { log, err } = {}) {
+  log = log || (s => process.stdout.write(s + '\n'));
+  err = err || (s => process.stderr.write(s + '\n'));
+
+  let catalog;
+  try {
+    catalog = loadCatalog();
+  } catch (e) {
+    err(`ADM failed: cannot load the tool catalog: ${e.message}`);
+    return 2;
+  }
+  const byId = new Map(catalog.flatMap(c => c.tools.map(t => [t.id, { ...t, category: c.id }])));
+
+  const requested = parseToolIds(toolsSpec);
+  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(', '));
+    err(lines.join('\n'));
+    return 1;
+  }
+
+  const env = detectEnvironment();
+  const entries = requested.map(id => {
+    const tool = byId.get(id);
+    return { id, name: tool.name, category: tool.category, ...buildToolPlan(tool, env) };
+  });
+
+  log(`ADM install plan — ${entries.length} tool${entries.length === 1 ? '' : 's'} (dry run, nothing was installed)`);
+  log('');
+  log(`Environment:\n${formatEnvironment(env)}`);
+  log('');
+  for (const e of entries) {
+    const head = `${e.id} (${e.category}) — ${e.status}`;
+    log(head);
+    if (e.status === 'planned') {
+      log(`  command:  ${e.command}`);
+      if (e.manager) log(`  manager:  ${e.manager} · package: ${e.package}`);
+      log(`  check:    ${e.statusSource}`);
+    } else if (e.status === 'manual') {
+      log(`  why:      ${e.reason}`);
+    } else if (e.status === 'link') {
+      log(`  url:      ${e.url}`);
+    }
+    log('');
+  }
+
+  return 0;
+}
+
+module.exports = { runPlan, parseToolIds };

package/src/install/report.js

@@ -0,0 +1,46 @@
+// Per-tool result rendering shared by the ADM_TOOLS runner (#29) and the
+// wizard's final report (#30). Plain text, no colors — readable in logs/CI.
+
+const STATUS_MARKS = { installed: '✓', skipped: '✓', failed: '✗', reinstalled: '✓', manual: 'i' };
+
+const STATUS_LABELS = {
+  installed: 'installed',
+  reinstalled: 'reinstalled',
+  skipped: 'skipped',
+  failed: 'failed',
+  manual: 'manual',
+};
+
+// Renders the final report lines for a list of results
+// (as produced by executeInstall).
+function renderResults(results, { summary = true } = {}) {
+  const lines = [];
+  for (const r of results) {
+    const mark = STATUS_MARKS[r.status] || ' ';
+    const label = STATUS_LABELS[r.status] || r.status;
+    lines.push(`${mark} ${r.name || r.id} — ${label}`);
+    if (r.status === 'skipped' && r.reason) lines.push(`    ${r.reason}${r.url ? `: ${r.url}` : ''}`);
+    if (r.status === 'manual' && (r.hint || r.reason)) lines.push(`    ${r.hint || r.reason}`);
+    if (r.note) lines.push(`    ${r.note}`);
+    if (r.status === 'failed') {
+      lines.push(`    command: ${r.command || '(none)'}`);
+      if (r.error) lines.push(`    error: ${String(r.error).trim()}`);
+      if (r.hint) {
+        lines.push('    hint:');
+        for (const hl of String(r.hint).split('\n')) lines.push(`      ${hl}`);
+      }
+    }
+  }
+  if (summary) {
+    const installed = results.filter(r => r.status === 'installed').length;
+    const reinstalled = results.filter(r => r.status === 'reinstalled').length;
+    const skipped = results.filter(r => r.status === 'skipped').length;
+    const manual = results.filter(r => r.status === 'manual').length;
+    const failed = results.filter(r => r.status === 'failed').length;
+    lines.push('');
+    lines.push(`Done: ${installed} installed${reinstalled ? `, ${reinstalled} reinstalled` : ''}, ${skipped} skipped${manual ? `, ${manual} manual` : ''}, ${failed} failed.`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = { renderResults, STATUS_MARKS };