package-registry-manager 0.21.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to the JavaScript package are documented here. The package
+currently shares its release version with the Rust implementation.
+
+## [Unreleased]
+
+### Added
+
+- `setup --registry npm --execute` takes a never-published package to OIDC
+  trusted publishing in one run: web login, a confirmed first publish from a
+  temporary worktree of the default branch, `npm trust github`, and cleanup of
+  a leftover `NPM_TOKEN` secret. It never reads, creates, or asks for an npm
+  token (#3).
+- `inspect` and `plan` look packages up on npm, crates.io, PyPI, and Docker Hub
+  and plan a `bootstrap`, `attach`, or `complete` mode. `--offline` skips the
+  lookups, `--dry-run` prints the whole flow, and `--verify-release` watches the
+  next release for provenance (#3).
+- PyPI bootstraps through a pending publisher and a first OIDC publish from CI;
+  crates.io publishes once with a revocable token and then opens the trusted
+  publisher settings (#3).
+- Docker Hub and GHCR images are detected from a `Dockerfile` and the release
+  workflow, with plans for the repository, a scoped token, `DOCKERHUB_*`
+  variables and secret, `packages: write`, and package linking (#5).
+- `setup --browser default|automated` chooses where sign-in and approval URLs
+  open; `default`, the default, uses the user's default browser (#9).
+
+### Changed
+
+- npm web-auth URLs (`npm login`, `npm publish` 2FA, `npm trust`) open in the
+  user's default browser (`open`, `xdg-open`, or the Windows URL handler),
+  where they are usually already signed in. The automated browser profile is
+  only used to fill the trusted-publisher form (#9).
+- The automation browser profile now defaults to a per-user state directory
+  outside any repository (`~/Library/Application Support` on macOS,
+  `$XDG_STATE_HOME` or `~/.local/state` on Linux, `%LOCALAPPDATA%` on Windows,
+  each followed by `package-registry-manager/browser-profile`) (#8).
+
+### Fixed
+
+- A browser profile inside a Git work tree gets a `.gitignore` containing `*`
+  before the browser starts, and setup refuses to continue if Git still does
+  not ignore it or already tracks files in it. A profile left in
+  `.package-registry-manager/` by an earlier release is protected the same way,
+  with a warning to delete it (#8).
+- When a web login is not completed and npm falls back to its legacy
+  `Username:` prompt, setup stops npm and says to re-run for a fresh login link
+  instead of failing with `npm exited with status 1` (#9).
+
+- `plan` no longer emits setup steps or a trusted publisher for unpublishable
+  packages; they appear with `"steps": []` and a `skipped_reason`, and `setup`
+  picks the only publishable package when a registry also has private ones
+  (#4).
+
+## [0.19.35] - 2026-09-21
+
+### Added
+
+- Initial JavaScript implementation of repository inspection and registry
+  setup planning.

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,21 @@
+# package-registry-manager (JavaScript)
+
+Node.js implementation of
+[package-registry-manager](https://github.com/link-foundation/package-registry-manager).
+It discovers package manifests, emits registry setup plans, validates packages
+with exact argument vectors, and guides authenticated setup in the default
+browser, filling forms in a dedicated visible browser profile.
+
+```bash
+npx package-registry-manager inspect --repository /path/to/repository
+npx package-registry-manager plan --repository /path/to/repository --format json
+npx package-registry-manager setup --repository /path/to/repository --registry npm
+```
+
+The package installs the command as both `package-registry-manager` and
+`package-registry-manager-js`; use the second name when the Rust command of the
+same name is also on your `PATH`.
+
+Setup is a dry run unless `--execute` is present, and it never publishes an
+artifact. See the repository README for all registry walkthroughs and safety
+details.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "package-registry-manager",
+  "version": "0.21.0",
+  "description": "Inspect repositories and guide secure package-registry setup",
+  "type": "module",
+  "bin": {
+    "package-registry-manager": "src/cli.mjs",
+    "package-registry-manager-js": "src/cli.mjs"
+  },
+  "exports": "./src/index.mjs",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/link-foundation/package-registry-manager.git",
+    "directory": "js"
+  },
+  "license": "Unlicense",
+  "files": [
+    "src/",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "syntax": "node --check src/cli.mjs && node --check src/index.mjs && node --check src/browser.mjs && node --check src/browser-options.mjs && node --check src/automation.mjs && node --check src/profile.mjs && node --check src/setup.mjs && node --check src/auth-urls.mjs && node --check src/containers.mjs && node --check src/flows.mjs && node --check src/prerequisites.mjs && node --check src/registry-state.mjs && node --check src/workflows.mjs && node --check src/publishers.mjs && node --check src/skips.mjs && node --check src/tokens.mjs && node --check src/approvals.mjs && node --check src/default-browser.mjs && node --check src/pages.mjs && node --check scripts/publish-to-npm.mjs && node --check scripts/setup-npm.mjs && node --check scripts/sanitize-npm-userconfig.mjs",
+    "lint": "eslint src test scripts --max-warnings 0",
+    "lint:fix": "eslint src test scripts --fix --max-warnings 0",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check:duplication": "jscpd src",
+    "check": "npm run syntax && npm run lint && npm run format:check && npm run check:duplication",
+    "test": "node --test --test-timeout=30000",
+    "pack:check": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "browser-commander": "^0.21.2",
+    "command-stream": "^1.3.0",
+    "playwright": "^1.63.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.11.0",
+    "eslint-config-prettier": "^10.1.8",
+    "jscpd": "^5.4.0",
+    "prettier": "^3.9.9"
+  }
+}

package/src/approvals.mjs

@@ -0,0 +1,72 @@
+/**
+ * npm's browser sign-in and approval links: how long they stay valid, how the
+ * tool recognizes an expired one, and how often it asks npm for a fresh one.
+ */
+
+/** How long npm keeps a web login or approval session open. */
+export const APPROVAL_WINDOW_MS = 5 * 60_000;
+/** How many links the tool requests before it gives up on one step. */
+export const APPROVAL_ATTEMPTS = 3;
+/** npm's error once its approval session expired while it polled for the result. */
+export const EXPIRED_APPROVAL = /Invalid response from web login endpoint/i;
+
+/** Shown with every npm approval link. */
+export const TWO_FACTOR_HINT =
+  "If npm's approval page offers to skip two-factor checks for the next 5 minutes, choose it so the approvals that follow need no new confirmation.";
+
+const pad = (number) => String(number).padStart(2, "0");
+
+/**
+ * The deadline printed with a sign-in or approval link, such as
+ * "Sign in within about 5 minutes (until 19:05).".
+ */
+export function approvalDeadline(kind, now = new Date()) {
+  const until = new Date(now.getTime() + APPROVAL_WINDOW_MS);
+  const action = kind === "login" ? "Sign in" : "Approve";
+  return `${action} within about 5 minutes (until ${pad(until.getHours())}:${pad(until.getMinutes())}).`;
+}
+
+/**
+ * Why an npm run ended on an expired link, or undefined when it did not: a
+ * web login falls back to npm's legacy `Username:` prompt, and a publish or
+ * trust approval fails with npm's web-login error.
+ */
+export function expiredApproval(result) {
+  if (result.legacyLogin) {
+    return "npm fell back to its legacy username prompt";
+  }
+  if (result.code !== 0 && result.approvalExpired) {
+    return "npm's approval session ended";
+  }
+  return undefined;
+}
+
+/**
+ * Runs `attempt()` until it does not end on an expired link, up to
+ * `attempts` times, printing why each fresh link is requested.
+ */
+export async function withFreshLinks(
+  attempt,
+  { attempts = APPROVAL_ATTEMPTS, log = console.log } = {},
+) {
+  for (let number = 1; ; number += 1) {
+    const result = await attempt();
+    const reason = expiredApproval(result);
+    if (!reason) {
+      return result;
+    }
+    if (number >= attempts) {
+      throw new Error(
+        `the browser link expired ${attempts} times (${reason}); re-run the command when you are ready to approve within 5 minutes`,
+      );
+    }
+    log(
+      `\nThe link expired before it was approved (${reason}); requesting a fresh one (attempt ${number + 1} of ${attempts}).`,
+    );
+  }
+}
+
+/** The closing note once a package publishes through trusted publishing. */
+export function oidcReleaseNote(workflow) {
+  return `Future releases publish from ${workflow} through trusted publishing; no login is needed.`;
+}

package/src/auth-urls.mjs

@@ -0,0 +1,149 @@
+import { spawn } from "command-stream";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { EXPIRED_APPROVAL } from "./approvals.mjs";
+
+/**
+ * Preloaded into npm so it treats piped stdout as a terminal. npm only offers
+ * web authentication (`Authenticate your account at:`) on a TTY; the tool
+ * pipes stdout to find those URLs and open them in a browser.
+ */
+export const TTY_SHIM = `for (const stream of [process.stdin, process.stdout]) {
+  if (!stream.isTTY) {
+    Object.defineProperty(stream, "isTTY", { value: true, configurable: true });
+  }
+}
+`;
+
+const PROMPTS = [
+  [/^Login at:?$/i, "login"],
+  [/^Authenticate your account at:?$/i, "approve"],
+];
+const INLINE = /(Login at|Authenticate your account at):?\s+(https?:\/\/\S+)/i;
+const linkKind = (label) => (/^login/i.test(label) ? "login" : "approve");
+// npm falls back to this prompt when a web login is not completed in time.
+const LEGACY_LOGIN = /^Username:/i;
+/** Terminal color and cursor escape sequences. */
+// eslint-disable-next-line no-control-regex
+export const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+
+const clean = (raw) => raw.replace(ANSI, "").trim();
+
+/**
+ * Returns a line scanner that reports web-authentication URLs printed by npm,
+ * with their kind (`login` or `approve`), and, once, npm's legacy `Username:`
+ * prompt, which is printed without a trailing newline.
+ */
+export function authUrlScanner(onUrl, onLegacyLogin) {
+  let pending = "";
+  let expectUrl = null;
+  let legacy = false;
+  const seen = new Set();
+  const detectLegacy = (line) => {
+    if (onLegacyLogin && !legacy && LEGACY_LOGIN.test(line)) {
+      legacy = true;
+      onLegacyLogin();
+    }
+  };
+  const report = (url, kind) => {
+    if (!seen.has(url)) {
+      seen.add(url);
+      onUrl(url, kind);
+    }
+  };
+  const scanLine = (raw) => {
+    const line = clean(raw);
+    detectLegacy(line);
+    const inline = INLINE.exec(line);
+    const prompt = PROMPTS.find(([pattern]) => pattern.test(line));
+    if (inline) {
+      report(inline[2], linkKind(inline[1]));
+      expectUrl = null;
+    } else if (prompt) {
+      expectUrl = prompt[1];
+    } else if (expectUrl && /^https?:\/\/\S+$/.test(line)) {
+      report(line, expectUrl);
+      expectUrl = null;
+    } else if (line) {
+      expectUrl = null;
+    }
+  };
+  return (chunk) => {
+    pending += chunk;
+    const lines = pending.split(/\r?\n/);
+    pending = lines.pop();
+    lines.forEach(scanLine);
+    detectLegacy(clean(pending));
+  };
+}
+
+/** Appends a `--require` of the TTY shim to existing NODE_OPTIONS. */
+export function nodeOptionsWithShim(existing, shimPath) {
+  const quoted = shimPath.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+  return [existing, `--require "${quoted}"`].filter(Boolean).join(" ");
+}
+
+/** Writes the TTY shim to a private temporary directory. */
+export async function writeTtyShim() {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "prm-shim-"));
+  const shim = path.join(directory, "tty-shim.cjs");
+  await writeFile(shim, TTY_SHIM, { mode: 0o600 });
+  return { directory, shim };
+}
+
+/**
+ * Runs an exact argument vector with the terminal's stdin and stderr, while
+ * mirroring and capturing stdout. stdin stays a real terminal so masked
+ * prompts (cargo login, gh secret set) keep working. With
+ * `options.stopOnLegacyLogin` the command is stopped at npm's legacy
+ * `Username:` prompt and the result has `legacyLogin: true`. With
+ * `options.watchStderr` stderr is mirrored too, and the result has
+ * `approvalExpired: true` once npm reports an expired approval session.
+ */
+export function runInteractive(command, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command.program, command.args, {
+      cwd: options.cwd,
+      env: options.env ?? process.env,
+      stdio: ["inherit", "pipe", options.watchStderr ? "pipe" : "inherit"],
+      shell: false,
+    });
+    let legacyLogin = false;
+    const stop = options.stopOnLegacyLogin
+      ? () => {
+          legacyLogin = true;
+          child.kill();
+        }
+      : undefined;
+    const scan =
+      options.onUrl || stop
+        ? authUrlScanner(options.onUrl ?? (() => {}), stop)
+        : null;
+    let stdout = "";
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      if (options.mirror !== false) {
+        process.stdout.write(chunk);
+      }
+      scan?.(chunk);
+    });
+    let approvalExpired = false;
+    let errors = "";
+    if (options.watchStderr) {
+      child.stderr.setEncoding("utf8");
+      child.stderr.on("data", (chunk) => {
+        process.stderr.write(chunk);
+        errors = `${errors}${chunk}`.slice(-4096);
+        approvalExpired ||= EXPIRED_APPROVAL.test(errors.replace(ANSI, ""));
+      });
+    }
+    child.on("error", reject);
+    child.on("close", (code) => {
+      scan?.("\n");
+      resolve({ code: code ?? 1, stdout, legacyLogin, approvalExpired });
+    });
+  });
+}

package/src/automation.mjs

@@ -0,0 +1,124 @@
+import { cp } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  attachViaExtension,
+  EXTENSION_DIRECTORY,
+  launchRealBrowser,
+} from "browser-commander";
+
+import { snapshotBrowser } from "./browser-options.mjs";
+import { defaultBrowserProfile, ensureProfileIgnored } from "./profile.mjs";
+
+/** How long `--browser-attach extension` waits for the extension to connect. */
+export const EXTENSION_TIMEOUT_MS = 300_000;
+
+/** Where the companion extension is written for Chrome's "Load unpacked". */
+export function relayExtensionDirectory() {
+  return path.join(path.dirname(defaultBrowserProfile()), "relay-extension");
+}
+
+/**
+ * The `launchRealBrowser` options for the automated browser: the dedicated
+ * profile by default, optionally seeded from a real profile, or a temporary
+ * snapshot of the user's own profile with `--browser-attach snapshot`.
+ */
+export function launchOptions(browser, profile, verbose = false) {
+  const options = {
+    engine: "playwright",
+    channel: browser.channel,
+    headless: false,
+    verbose,
+  };
+  if (browser.executable) {
+    options.executablePath = browser.executable;
+  }
+  if (browser.restrictions.length > 0) {
+    options.restrictions = browser.restrictions;
+  }
+  if (Object.keys(browser.preferences).length > 0) {
+    options.preferences = browser.preferences;
+  }
+  if (browser.attach?.mode === "snapshot") {
+    options.attach = {
+      mode: "snapshot",
+      browser: snapshotBrowser(browser.channel),
+      profile: browser.attach.profile ?? "Default",
+    };
+    return options;
+  }
+  options.userDataDir = profile;
+  if (browser.import) {
+    options.migrateFrom = {
+      browser: browser.import.browser,
+      ...(browser.import.profile ? { profile: browser.import.profile } : {}),
+    };
+  }
+  return options;
+}
+
+/** The instructions printed while waiting for the companion extension. */
+export function extensionInstructions(directory) {
+  return [
+    `Waiting up to ${EXTENSION_TIMEOUT_MS / 60_000} minutes for the Browser Commander extension in your own browser.`,
+    'If it is not installed, open chrome://extensions, turn on Developer mode, click "Load unpacked", and choose:',
+    `  ${directory}`,
+  ].join("\n");
+}
+
+/**
+ * Connects the browser that fills forms and returns a page with `goto`,
+ * `evaluate`, and `close`.
+ */
+export async function connectAutomation({ browser, profile, verbose = false }) {
+  if (browser.attach?.mode === "extension") {
+    return connectExtension();
+  }
+  if (!browser.attach) {
+    await ensureProfileIgnored(profile, { verbose });
+  }
+  const connection = await launchRealBrowser(
+    launchOptions(browser, profile, verbose),
+  );
+  return {
+    goto: (url) => connection.page.goto(url),
+    evaluate: (script) => connection.page.evaluate(script),
+    close: () => connection.browser.close(),
+  };
+}
+
+async function connectExtension() {
+  const directory = relayExtensionDirectory();
+  await cp(EXTENSION_DIRECTORY, directory, { recursive: true });
+  const relay = await attachViaExtension({
+    timeoutMs: EXTENSION_TIMEOUT_MS,
+    onListening: () => console.log(extensionInstructions(directory)),
+  });
+  let session = null;
+  return {
+    async goto(url) {
+      if (session) {
+        await session.send("Page.navigate", { url });
+      } else {
+        const { tabId } = await relay.newTab(url);
+        session = await relay.session(tabId);
+      }
+    },
+    async evaluate(expression) {
+      const { result, exceptionDetails } = await session.send(
+        "Runtime.evaluate",
+        { expression, returnByValue: true, awaitPromise: true },
+      );
+      if (exceptionDetails) {
+        throw new Error(
+          `the page script failed: ${exceptionDetails.exception?.description ?? exceptionDetails.text}`,
+        );
+      }
+      return result.value;
+    },
+    async close() {
+      await session?.detach().catch(() => {});
+      await relay.close();
+    },
+  };
+}

package/src/browser-options.mjs

@@ -0,0 +1,175 @@
+import path from "node:path";
+
+import {
+  LAUNCH_RESTRICTION_PRESETS,
+  LAUNCH_RESTRICTIONS,
+} from "browser-commander";
+
+/** Browsers whose profile `--browser-import` can migrate. */
+export const IMPORT_BROWSERS = ["chrome", "edge", "brave", "firefox"];
+/** How `--browser-attach` reaches the user's own browser. */
+export const ATTACH_MODES = ["snapshot", "extension"];
+
+/**
+ * Every launch restriction and preset `--browser-restriction` accepts, from
+ * Browser Commander's shared catalogue.
+ */
+export function restrictionNames() {
+  return [
+    ...LAUNCH_RESTRICTIONS.map((restriction) => restriction.id),
+    ...Object.keys(LAUNCH_RESTRICTION_PRESETS),
+  ];
+}
+
+/**
+ * Validates the browser options of the automated profile. Nothing changes by
+ * default: a fresh dedicated profile fills forms. `--browser-import` migrates
+ * a real profile into it, and `--browser-attach` uses the user's own browser
+ * instead, as a temporary snapshot or through the companion extension.
+ */
+export function parseBrowserOptions({
+  channel = "chrome",
+  executable,
+  importFrom,
+  attach,
+  preferences = [],
+  restrictions = [],
+  profileGiven = false,
+} = {}) {
+  const options = {
+    channel,
+    executable: executable ? path.resolve(executable) : null,
+    import: importFrom ? parseImport(importFrom) : null,
+    attach: attach ? parseAttach(attach) : null,
+    preferences: parsePreferences(preferences),
+    restrictions: validateRestrictions(restrictions),
+  };
+  if (options.attach && options.import) {
+    throw new Error(
+      "--browser-attach cannot be combined with --browser-import",
+    );
+  }
+  if (options.attach && profileGiven) {
+    throw new Error(
+      "--browser-attach cannot be combined with --browser-profile",
+    );
+  }
+  if (
+    options.attach?.mode === "extension" &&
+    (options.executable ||
+      options.restrictions.length > 0 ||
+      Object.keys(options.preferences).length > 0)
+  ) {
+    throw new Error(
+      "--browser-attach extension cannot be combined with --browser-executable, --browser-pref, or --browser-restriction",
+    );
+  }
+  return options;
+}
+
+/** Parses `<chrome|edge|brave|firefox>[:profile]`. */
+export function parseImport(spec) {
+  const separator = spec.indexOf(":");
+  const browser = separator === -1 ? spec : spec.slice(0, separator);
+  const profile = separator === -1 ? null : spec.slice(separator + 1);
+  if (!IMPORT_BROWSERS.includes(browser) || profile === "") {
+    throw new Error(
+      "--browser-import must be <chrome|edge|brave|firefox>[:profile]",
+    );
+  }
+  return { browser, profile };
+}
+
+/** Parses `snapshot`, `snapshot:<profile>`, or `extension`. */
+export function parseAttach(spec) {
+  if (spec === "extension") {
+    return { mode: "extension" };
+  }
+  const match = /^snapshot(?::(.+))?$/.exec(spec);
+  if (!match) {
+    throw new Error(
+      "--browser-attach must be 'snapshot', 'snapshot:<profile>', or 'extension'",
+    );
+  }
+  return { mode: "snapshot", profile: match[1] ?? null };
+}
+
+/**
+ * Builds the preferences object from `key=value` pairs. Dotted keys nest, and
+ * a value is JSON when it parses as JSON, otherwise a string.
+ */
+export function parsePreferences(pairs) {
+  const preferences = {};
+  for (const pair of pairs) {
+    const separator = pair.indexOf("=");
+    const key = separator === -1 ? "" : pair.slice(0, separator);
+    if (!/^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/.test(key)) {
+      throw new Error(`--browser-pref must be key=value, got '${pair}'`);
+    }
+    const parts = key.split(".");
+    const last = parts.pop();
+    let target = preferences;
+    for (const part of parts) {
+      if (!isObject(target[part])) {
+        target[part] = {};
+      }
+      target = target[part];
+    }
+    target[last] = preferenceValue(pair.slice(separator + 1));
+  }
+  return preferences;
+}
+
+function preferenceValue(text) {
+  try {
+    const value = JSON.parse(text);
+    return Number.isFinite(value) || typeof value !== "number" ? value : text;
+  } catch {
+    return text;
+  }
+}
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Rejects a restriction or preset that is not in the shared catalogue. */
+export function validateRestrictions(names) {
+  const known = restrictionNames();
+  for (const name of names) {
+    if (!known.includes(name)) {
+      throw new Error(
+        `unknown --browser-restriction '${name}'; choose from ${known.join(", ")}`,
+      );
+    }
+  }
+  return [...new Set(names)];
+}
+
+/** The installed browser a snapshot copies for a launch channel. */
+export function snapshotBrowser(channel) {
+  if (channel.startsWith("msedge")) {
+    return "edge";
+  }
+  return ["brave", "chromium"].includes(channel) ? channel : "chrome";
+}
+
+/** Describes where forms are filled, for the browser prerequisite. */
+export function automatedDescription({
+  channel = "chrome",
+  profile,
+  attach,
+  import: source,
+} = {}) {
+  if (attach?.mode === "extension") {
+    return "your own browser through the Browser Commander extension";
+  }
+  if (attach?.mode === "snapshot") {
+    return `a temporary snapshot of your ${snapshotBrowser(channel)} profile ${attach.profile ?? "Default"}`;
+  }
+  const location = profile ? ` at ${profile}` : "";
+  const imported = source
+    ? ` with data imported from ${source.browser}${source.profile ? `:${source.profile}` : ""}`
+    : "";
+  return `the automated ${channel} profile${location}${imported}`;
+}