clean-room-skill 0.1.12 → 0.1.13

package/lib/install-operations.cjs

@@ -0,0 +1,376 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline/promises');
+const { spawnSync } = require('node:child_process');
+
+const { withDirectoryLock } = require('./dir-lock.cjs');
+const { assertManagedPath, removeEmptyParents } = require('./fs-utils.cjs');
+const {
+  buildHookEntries,
+  configPathForRuntime,
+  hasManagedOpenCodePlugin,
+  mergeHookEntries,
+  pluginPathForRuntime,
+  removeHookEntries,
+} = require('./hooks.cjs');
+const { buildDesiredFiles } = require('./install-artifacts.cjs');
+const {
+  applyInstall,
+  applyUninstall,
+  planInstall,
+  planUninstall,
+  readManifest,
+  writeInstallManifest,
+} = require('./install-plan.cjs');
+const {
+  ensureClaudeGlobalPlugin,
+  removeClaudeGlobalPlugin,
+} = require('./install-claude-plugin.cjs');
+const { resolveRuntimeLayout } = require('./runtime-layout.cjs');
+
+const INSTALL_LOCK_NAME = '.clean-room-install.lock';
+const INSTALL_LOCK_WAIT_MS = envPositiveInteger('CLEAN_ROOM_INSTALL_LOCK_WAIT_MS', 30_000);
+const INSTALL_LOCK_POLL_MS = 100;
+const PYTHON_PROBE_TIMEOUT_MS = envPositiveInteger('CLEAN_ROOM_INSTALL_PYTHON_TIMEOUT_MS', 10_000);
+
+function envPositiveInteger(name, fallback) {
+  const value = process.env[name];
+  if (value === undefined || value === '') {
+    return fallback;
+  }
+  return /^[1-9][0-9]*$/.test(value) ? Number(value) : fallback;
+}
+
+async function withTargetInstallLock(targetRoot, dryRun, fn) {
+  if (dryRun) {
+    return fn();
+  }
+
+  fs.mkdirSync(targetRoot, { recursive: true });
+  const lockPath = assertManagedPath(targetRoot, INSTALL_LOCK_NAME);
+  return withDirectoryLock({
+    lockPath,
+    waitMs: INSTALL_LOCK_WAIT_MS,
+    pollMs: INSTALL_LOCK_POLL_MS,
+    label: 'install lock',
+  }, fn);
+}
+
+async function confirmUnknownConflicts(conflicts, options) {
+  if (conflicts.length === 0) return false;
+  if (options.dryRun) return false;
+  if (options.yes || !process.stdin.isTTY) {
+    throw new Error(
+      `unknown existing file(s) would be overwritten: ${conflicts.join(', ')}. ` +
+      'Run interactively to confirm or remove the conflict.'
+    );
+  }
+  console.log('Unknown existing files would be overwritten:');
+  for (const conflict of conflicts) {
+    console.log(`  ${conflict}`);
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question('Overwrite these files? Type yes to continue: ');
+    if (answer.trim() !== 'yes') {
+      throw new Error('aborted by user');
+    }
+    return true;
+  } finally {
+    rl.close();
+  }
+}
+
+function resolvePython3() {
+  const result = spawnSync('python3', ['-c', 'import sys; print(sys.executable)'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: PYTHON_PROBE_TIMEOUT_MS,
+  });
+  if (result.status !== 0) {
+    throw new Error('python3 is required to install clean-room hooks');
+  }
+  const pythonPath = String(result.stdout || '').trim();
+  if (!path.isAbsolute(pythonPath)) {
+    throw new Error('python3 did not resolve to an absolute executable path');
+  }
+  return pythonPath;
+}
+
+function prepareHookRegistration(layout, hookMode, options = {}) {
+  if (hookMode === 'copy-only') {
+    return { status: 'copy-only' };
+  }
+  if (!layout.supportsHookRegistration) {
+    return { status: 'unsupported' };
+  }
+  if (layout.hookRegistration === 'local-plugin') {
+    const pluginPath = pluginPathForRuntime(layout.runtime, layout.targetRoot);
+    if (!pluginPath) return { status: 'unsupported' };
+    return {
+      status: options.dryRun ? 'planned' : 'local-plugin',
+      kind: 'local-plugin',
+      pluginPath,
+    };
+  }
+  if (layout.hookRegistration !== 'json-config') {
+    return { status: 'unsupported' };
+  }
+  const configPath = configPathForRuntime(layout.runtime, layout.targetRoot);
+  if (!configPath) return { status: 'unsupported' };
+  if (options.dryRun) {
+    return { status: 'planned', kind: 'json-config', configPath };
+  }
+  const pythonPath = resolvePython3();
+  const wrapperPath = path.join(layout.targetRoot, 'hooks', 'clean-room', 'clean-room-hook.py');
+  const entries = buildHookEntries({ pythonPath, wrapperPath, mode: hookMode });
+  return { status: 'registered', kind: 'json-config', configPath, entries };
+}
+
+function hookRegistrationFailureState(hookResult, err) {
+  return {
+    hook_registration: {
+      status: 'failed',
+      config_path: hookResult.configPath,
+      error: err.message,
+      recorded_at: new Date().toISOString(),
+    },
+  };
+}
+
+function partialInstallMessage(targetRoot, state, cause) {
+  const causeMessage = cause && cause.message ? cause.message : String(cause);
+  const parts = [
+    `partial install state for ${targetRoot}`,
+    state.files,
+    state.hooks,
+    state.manifest,
+    state.recovery,
+  ].filter(Boolean);
+  return `${parts.join('; ')}. Cause: ${causeMessage}`;
+}
+
+async function installRuntime(runtime, options) {
+  const layout = resolveRuntimeLayout(runtime, options.scope, { configDir: options.configDir });
+  const targetRoot = layout.targetRoot;
+  await withTargetInstallLock(targetRoot, options.dryRun, async () => {
+    const manifest = readManifest(targetRoot);
+    const desired = buildDesiredFiles(layout, options.hookMode);
+    const plan = planInstall(targetRoot, desired, manifest);
+    const adoptedUnknowns = await confirmUnknownConflicts(plan.unknownConflicts, options);
+
+    const verb = options.operation === 'update' ? 'update' : 'install';
+    console.log(`${options.dryRun ? `Would ${verb}` : activeVerb(verb)} ${runtime} to ${targetRoot}`);
+    console.log(`  files: ${plan.writes.length}`);
+    if (plan.removals.length) console.log(`  stale managed removals: ${plan.removals.length}`);
+    if (plan.backups.length || adoptedUnknowns) {
+      console.log(`  backups: ${plan.backups.length + (adoptedUnknowns ? plan.unknownConflicts.length : 0)}`);
+    }
+    if (options.dryRun && plan.unknownConflicts.length) {
+      console.log(`  unknown conflicts: ${plan.unknownConflicts.length}`);
+    }
+
+    const hookResult = prepareHookRegistration(layout, options.hookMode, { dryRun: options.dryRun });
+    const pluginState = ensureClaudeGlobalPlugin(layout, manifest, options, verb);
+    const installState = pluginState ? { claude_plugin: pluginState } : {};
+    // Install order is files, installing manifest, hook config, then complete manifest.
+    // The installing manifest gives repair/uninstall a durable handle if hook config write fails.
+    let result;
+    try {
+      result = applyInstall(targetRoot, desired, manifest, plan, options);
+    } catch (err) {
+      throw new Error(partialInstallMessage(targetRoot, {
+        files: 'managed files may be partially written',
+        hooks: 'hook config was not updated',
+        manifest: 'install manifest was not written',
+        recovery: 're-run the same install command after fixing the filesystem error',
+      }, err));
+    }
+    if (result) {
+      try {
+        writeInstallManifest(targetRoot, result.manifest, runtime, options.scope, options.hookMode, options.dryRun, {
+          phase: 'installing',
+          ...installState,
+        });
+      } catch (err) {
+        throw new Error(partialInstallMessage(targetRoot, {
+          files: 'managed files were written',
+          hooks: 'hook config was not updated',
+          manifest: 'install manifest was not written',
+          recovery: 're-run the same install command to repair manifest tracking before uninstalling',
+        }, err));
+      }
+    }
+
+    let hookConfigWritten = false;
+    if (!options.dryRun && hookResult.status === 'registered') {
+      try {
+        mergeHookEntries(hookResult.configPath, hookResult.entries);
+        hookConfigWritten = true;
+      } catch (err) {
+        let manifestStatus = 'install manifest records phase installing';
+        if (result) {
+          try {
+            writeInstallManifest(
+              targetRoot,
+              result.manifest,
+              runtime,
+              options.scope,
+              options.hookMode,
+              false,
+              {
+                phase: 'installing',
+                ...installState,
+                ...hookRegistrationFailureState(hookResult, err),
+              }
+            );
+            manifestStatus = 'install manifest records the failed hook registration';
+          } catch {
+            manifestStatus = 'install manifest could not record the failed hook registration';
+          }
+        }
+        throw new Error(partialInstallMessage(targetRoot, {
+          files: 'managed files were written',
+          hooks: 'hook config write failed',
+          manifest: manifestStatus,
+          recovery: 're-run the same install command to repair hook registration',
+        }, err));
+      }
+    }
+    if (hookResult.status === 'unsupported' && options.hookMode === 'safe') {
+      console.log('  hook registration unsupported for this runtime; copied hooks only');
+    }
+    if (hookResult.status === 'planned' && hookResult.kind === 'json-config') {
+      console.log(`  hook registration: would update ${hookResult.configPath}`);
+      console.log('  hook registration: python3 required when applying the install');
+    }
+    if (hookResult.status === 'planned' && hookResult.kind === 'local-plugin') {
+      console.log(`  hook registration: would install local plugin ${hookResult.pluginPath}`);
+    }
+    if (hookResult.status === 'local-plugin') {
+      hookConfigWritten = true;
+    }
+    if (options.hookMode === 'safe') {
+      console.log('  WARNING: safe hooks are installed; clean-room init/onboarding must set role environment variables before enforcement starts');
+    }
+    if (result) {
+      try {
+        writeInstallManifest(targetRoot, result.manifest, runtime, options.scope, options.hookMode, options.dryRun, {
+          phase: 'complete',
+          ...installState,
+        });
+      } catch (err) {
+        throw new Error(partialInstallMessage(targetRoot, {
+          files: 'managed files were written',
+          hooks: hookConfigWritten ? 'hook config was updated' : 'hook config was not updated',
+          manifest: hookConfigWritten ? 'install manifest was not completed' : 'install manifest was not written',
+          recovery: 're-run the same install command to repair manifest tracking before uninstalling',
+        }, err));
+      }
+      if (result.backupRoot) {
+        console.log(`  backed up modified files to ${result.backupRoot}`);
+      }
+    }
+  });
+}
+
+function activeVerb(verb) {
+  if (verb === 'update') return 'Updating';
+  return 'Installing';
+}
+
+async function updateRuntime(runtime, options) {
+  const layout = resolveRuntimeLayout(runtime, options.scope, { configDir: options.configDir });
+  const manifest = readManifest(layout.targetRoot);
+  if (!manifest) {
+    console.log(`${options.dryRun ? 'Would skip update' : 'Skipping update'} ${runtime} from ${layout.targetRoot}`);
+    console.log('  no install manifest found');
+    return;
+  }
+  const hookMode = options.hookModeSpecified ? options.hookMode : (manifest.hooks_mode || options.hookMode);
+  await installRuntime(runtime, {
+    ...options,
+    operation: 'update',
+    hookMode,
+    hookModeSpecified: true,
+  });
+}
+
+function removeHookRegistrations(layout, dryRun) {
+  if (!layout.supportsHookRegistration) return null;
+  if (layout.hookRegistration === 'local-plugin') {
+    const pluginPath = pluginPathForRuntime(layout.runtime, layout.targetRoot);
+    if (!hasManagedOpenCodePlugin(pluginPath)) return null;
+    if (!dryRun) {
+      fs.rmSync(assertManagedPath(layout.targetRoot, path.relative(layout.targetRoot, pluginPath)), { force: true });
+      removeEmptyParents(path.dirname(pluginPath), layout.targetRoot);
+    }
+    return { removed: pluginPath };
+  }
+  const configPath = configPathForRuntime(layout.runtime, layout.targetRoot);
+  if (!configPath) return null;
+  return removeHookEntries(configPath, { dryRun });
+}
+
+function desiredFilesForUninstall(layout, hookMode) {
+  try {
+    return buildDesiredFiles(layout, hookMode);
+  } catch (err) {
+    console.log(`  untracked file scan skipped: ${err.message}`);
+    return new Map();
+  }
+}
+
+async function uninstallRuntime(runtime, options) {
+  const layout = resolveRuntimeLayout(runtime, options.scope, { configDir: options.configDir });
+  const targetRoot = layout.targetRoot;
+  if (!options.dryRun && !fs.existsSync(targetRoot)) {
+    console.log(`Uninstalling ${runtime} from ${targetRoot}`);
+    console.log('  no install manifest found');
+    return;
+  }
+  await withTargetInstallLock(targetRoot, options.dryRun, async () => {
+    const manifest = readManifest(targetRoot);
+    console.log(`${options.dryRun ? 'Would uninstall' : 'Uninstalling'} ${runtime} from ${targetRoot}`);
+    if (!manifest) {
+      console.log('  no install manifest found');
+      removeHookRegistrations(layout, options.dryRun);
+      return;
+    }
+    const desired = desiredFilesForUninstall(layout, manifest.hooks_mode || options.hookMode);
+    const plan = planUninstall(targetRoot, manifest, desired);
+    console.log(`  managed removals: ${plan.removals.length}`);
+    if (plan.backups.length) {
+      console.log(`  backups: ${plan.backups.length}`);
+    }
+    if (plan.untracked.length) {
+      console.log(`  untracked package-path files left in place: ${plan.untracked.length}`);
+    }
+
+    removeClaudeGlobalPlugin(layout, manifest, options);
+    const result = applyUninstall(targetRoot, plan, options.dryRun);
+    if (!options.dryRun) {
+      removeHookRegistrations(layout, false);
+    }
+    if (result?.backupRoot) {
+      console.log(`  backed up modified files to ${result.backupRoot}`);
+    }
+  });
+}
+
+module.exports = {
+  activeVerb,
+  confirmUnknownConflicts,
+  desiredFilesForUninstall,
+  hookRegistrationFailureState,
+  installRuntime,
+  partialInstallMessage,
+  prepareHookRegistration,
+  removeHookRegistrations,
+  resolvePython3,
+  uninstallRuntime,
+  updateRuntime,
+  withTargetInstallLock,
+};

package/lib/install-options.cjs

@@ -0,0 +1,149 @@
+'use strict';
+
+const {
+  RUNTIMES,
+  RUNTIME_FLAGS,
+  resolveRuntimeLayout,
+} = require('./runtime-layout.cjs');
+
+const HOOK_MODES = new Set(['safe', 'copy-only', 'strict']);
+
+function parseArgs(argv) {
+  const options = {
+    runtimes: [],
+    scope: null,
+    dryRun: false,
+    yes: false,
+    uninstall: false,
+    operation: null,
+    hookMode: 'safe',
+    hookModeSpecified: false,
+    configDir: null,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (RUNTIME_FLAGS[arg]) options.runtimes.push(RUNTIME_FLAGS[arg]);
+    else if (arg === '--all') options.runtimes = [...RUNTIMES];
+    else if (arg === '--global') options.scope = setExclusive(options.scope, 'global', '--global');
+    else if (arg === '--local') options.scope = setExclusive(options.scope, 'local', '--local');
+    else if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--yes') options.yes = true;
+    else if (arg === '--uninstall') options.uninstall = true;
+    else if (arg === '--no-hooks') {
+      options.hookMode = 'copy-only';
+      options.hookModeSpecified = true;
+    } else if (arg === '--config-dir') {
+      i += 1;
+      if (i >= argv.length) throw new Error('--config-dir requires a path');
+      options.configDir = argv[i];
+    } else if (arg.startsWith('--config-dir=')) {
+      options.configDir = arg.slice('--config-dir='.length);
+    } else if (arg === '--hooks') {
+      i += 1;
+      if (i >= argv.length) throw new Error('--hooks requires safe, copy-only, or strict');
+      options.hookMode = argv[i];
+      options.hookModeSpecified = true;
+    } else if (arg.startsWith('--hooks=')) {
+      options.hookMode = arg.slice('--hooks='.length);
+      options.hookModeSpecified = true;
+    } else if (arg === '-h' || arg === '--help') {
+      printHelp();
+      process.exit(0);
+    } else {
+      throw new Error(`unknown option: ${arg}`);
+    }
+  }
+
+  options.runtimes = [...new Set(options.runtimes)];
+  if (!HOOK_MODES.has(options.hookMode)) {
+    throw new Error('--hooks must be one of safe, copy-only, or strict');
+  }
+  if (options.configDir && options.runtimes.length > 1) {
+    throw new Error('--config-dir can only be used with one runtime');
+  }
+  return options;
+}
+
+function setExclusive(current, next, flag) {
+  if (current && current !== next) {
+    throw new Error(`${flag} conflicts with --${current}`);
+  }
+  return next;
+}
+
+function printHelp() {
+  console.log(`Usage: clean-room-skill [runtime] [scope] [options]
+       clean-room-skill init [options]
+       clean-room-skill status [runtime] [scope] [options]
+       clean-room-skill update [runtime] [scope] [options]
+       clean-room-skill preflight [options]
+       clean-room-skill run [options]
+
+Commands:
+  init                Create clean-room bootstrap folders and repo guidance
+  status              Report installed runtime version, drift, and hook state
+  update              Update installed runtime files without onboarding
+  preflight           Create or validate a preflight goal contract
+  doctor              Smoke test generated Codex, Claude, or OpenCode hook registration
+  run                 Execute the bounded inner clean-room controller loop
+
+Runtime:
+  --codex              Install for Codex
+  --claude             Install for Claude Code
+  --antigravity        Install for Antigravity
+  --gemini             Install for Gemini CLI
+  --opencode           Install for OpenCode
+  --kilo               Install for Kilo
+  --cursor             Install for Cursor
+  --copilot            Install for GitHub Copilot
+  --windsurf           Install for Windsurf
+  --augment            Install for Augment
+  --trae               Install for Trae
+  --qwen               Install for Qwen Code
+  --hermes             Install for Hermes Agent
+  --codebuddy          Install for CodeBuddy
+  --all                Install for all known runtime layouts
+
+Scope:
+  --global             Install to the runtime user config
+  --local              Install to the current project config
+
+Options:
+  --hooks=<mode>       safe, copy-only, or strict (default: safe)
+  --no-hooks           Alias for --hooks=copy-only
+  --config-dir <path>  Override the target root for one runtime
+  --dry-run            Print actions without writing files
+  --yes                Non-interactive mode; unknown conflicts still abort
+  --uninstall          Remove manifest-managed files and clean-room hook entries
+
+Run without runtime and scope flags for interactive install or uninstall.
+Interactive runtime selection accepts names, numbers, ranges, all, or installed.
+`);
+}
+
+function operationForOptions(options) {
+  if (options.operation) return options.operation;
+  return options.uninstall ? 'uninstall' : 'install';
+}
+
+function validateRuntimeOptions(options) {
+  if (options.configDir && options.runtimes.length > 1) {
+    throw new Error('--config-dir can only be used with one runtime');
+  }
+  for (const runtime of options.runtimes) {
+    const layout = resolveRuntimeLayout(runtime, options.scope, { configDir: options.configDir });
+    if (options.hookMode === 'strict' && !layout.supportsHookRegistration) {
+      throw new Error(`--hooks=strict is not supported for ${runtime}; hook registration is verified only for codex, claude, and opencode`);
+    }
+  }
+}
+
+module.exports = {
+  HOOK_MODES,
+  operationForOptions,
+  parseArgs,
+  printHelp,
+  setExclusive,
+  validateRuntimeOptions,
+};

package/lib/install-runtime-selection.cjs

@@ -0,0 +1,180 @@
+'use strict';
+
+const path = require('node:path');
+
+const { RUNTIMES } = require('./runtime-layout.cjs');
+
+function displayPath(filePath) {
+  const home = process.env.HOME;
+  if (home && filePath === home) {
+    return '~';
+  }
+  if (home && filePath.startsWith(`${home}${path.sep}`)) {
+    return `~/${path.relative(home, filePath)}`;
+  }
+  return filePath;
+}
+
+function printRuntimeChoices(statuses) {
+  console.log('Runtime choices:');
+  statuses.forEach((status, index) => {
+    const number = String(index + 1).padStart(2, ' ');
+    const runtime = status.runtime.padEnd(12, ' ');
+    console.log(`  ${number}. ${runtime} ${status.detail} (${displayPath(status.targetRoot)})`);
+  });
+}
+
+function defaultRuntimeSelectionLabel(statuses, action) {
+  if ((action === 'uninstall' || action === 'update') && defaultRuntimeSelections(statuses, action).length > 0) {
+    return 'installed';
+  }
+  return 'codex';
+}
+
+function defaultRuntimeSelections(statuses, action = 'install') {
+  if (action === 'uninstall') {
+    return statuses.filter((status) => isInstalledStatus(status)).map((status) => status.runtime);
+  }
+  if (action === 'update') {
+    return selectableRuntimeSelections(statuses, action);
+  }
+  if (action === 'status') {
+    return statuses.map((status) => status.runtime);
+  }
+  return ['codex'];
+}
+
+function detectedRuntimeSelections(statuses, action = 'install') {
+  if (action === 'update') {
+    return selectableRuntimeSelections(statuses, action);
+  }
+  return statuses.filter((status) => isInstalledStatus(status)).map((status) => status.runtime);
+}
+
+function isUpdateTargetStatus(status) {
+  return status?.state === 'installed' || status?.state === 'update-available';
+}
+
+function isSelectableRuntimeStatus(status, action = 'install') {
+  if (action === 'update') {
+    return isUpdateTargetStatus(status);
+  }
+  return true;
+}
+
+function selectableRuntimeSelections(statuses, action = 'install') {
+  return statuses
+    .filter((status) => isSelectableRuntimeStatus(status, action))
+    .map((status) => status.runtime);
+}
+
+function statusForRuntime(statuses, runtime) {
+  return statuses.find((status) => status.runtime === runtime) || {
+    runtime,
+    state: 'not-installed',
+  };
+}
+
+function unavailableRuntimeSelectionMessage(status, action) {
+  if (action === 'update') {
+    return `${status.runtime} is not installed in this scope; choose Install to add it.`;
+  }
+  return `${status.runtime} cannot be selected for ${action}.`;
+}
+
+function emptyRuntimeSelectionMessage(statuses, action) {
+  if (action === 'update' && selectableRuntimeSelections(statuses, action).length === 0) {
+    return 'No installed runtimes detected for update. Choose Install instead.';
+  }
+  return 'Select at least one runtime.';
+}
+
+function addRuntimeSelection(selected, runtime, statuses, action) {
+  const status = statusForRuntime(statuses, runtime);
+  if (!isSelectableRuntimeStatus(status, action)) {
+    throw new Error(unavailableRuntimeSelectionMessage(status, action));
+  }
+  selected.push(runtime);
+}
+
+function parseRuntimeSelection(answer, statuses, action = 'install') {
+  const text = answer.trim().toLowerCase();
+  if (text === '') {
+    if (action === 'uninstall' || action === 'update') {
+      const installed = defaultRuntimeSelections(statuses, action);
+      if (installed.length === 0) {
+        throw new Error('no installed runtimes detected; select a runtime explicitly');
+      }
+      return installed;
+    }
+    return ['codex'];
+  }
+
+  const selected = [];
+  const tokens = text.split(/[,\s]+/).filter(Boolean);
+  for (const token of tokens) {
+    if (token === 'all') {
+      selected.push(...(action === 'update' ? selectableRuntimeSelections(statuses, action) : RUNTIMES));
+      continue;
+    }
+    if (token === 'installed') {
+      selected.push(...detectedRuntimeSelections(statuses, action));
+      continue;
+    }
+    const rangeMatch = token.match(/^(\d+)-(\d+)$/);
+    if (rangeMatch) {
+      const start = Number(rangeMatch[1]);
+      const end = Number(rangeMatch[2]);
+      if (start > end) {
+        throw new Error(`invalid runtime range: ${token}`);
+      }
+      for (let index = start; index <= end; index += 1) {
+        addRuntimeSelection(selected, runtimeForSelectionIndex(statuses, index), statuses, action);
+      }
+      continue;
+    }
+    if (/^\d+$/.test(token)) {
+      addRuntimeSelection(selected, runtimeForSelectionIndex(statuses, Number(token)), statuses, action);
+      continue;
+    }
+    if (RUNTIMES.includes(token)) {
+      addRuntimeSelection(selected, token, statuses, action);
+      continue;
+    }
+    throw new Error(`unsupported runtime selection: ${token}`);
+  }
+  const unique = [...new Set(selected)];
+  if (unique.length === 0) {
+    throw new Error('no runtimes selected');
+  }
+  return unique;
+}
+
+function runtimeForSelectionIndex(statuses, index) {
+  if (!Number.isInteger(index) || index < 1 || index > statuses.length) {
+    throw new Error(`runtime selection out of range: ${index}`);
+  }
+  return statuses[index - 1].runtime;
+}
+
+function isInstalledStatus(status) {
+  return status.state === 'installed' || status.state === 'hooks-only';
+}
+
+module.exports = {
+  addRuntimeSelection,
+  defaultRuntimeSelectionLabel,
+  defaultRuntimeSelections,
+  detectedRuntimeSelections,
+  displayPath,
+  emptyRuntimeSelectionMessage,
+  isInstalledStatus,
+  isSelectableRuntimeStatus,
+  isUpdateTargetStatus,
+  parseRuntimeSelection,
+  printRuntimeChoices,
+  runtimeForSelectionIndex,
+  selectableRuntimeSelections,
+  statusForRuntime,
+  unavailableRuntimeSelectionMessage,
+};