[schmitch]

Since #835, the Connect sidebar of every npm repository shows npm config set replace-registry-host <package-lock.json-host>. This makes the line optional. A proxy or a group shows it only after an administrator turns on Show npm's replace-registry-host setting in the repository's settings (Admin → Repositories, create or edit). It is off by default, and hosted repositories don't offer it.

No issue asks for this, so the pull request fixes none, following AGENTS.md. It also updates the unreleased fragment docs/changes/2.2.0/npm-replace-registry-host.feature.md so that the 2.2.0 notes describe the optional behaviour.

How

• A format option can be a switch. FormatOption in the plugin API gets an input field: OptionInput::Text, which is the existing line of text, or OptionInput::Switch.
  • For a switch, the host keeps "true" (SWITCH_ON) and treats "false" or null as off, clearing the option. It accepts nothing else and doesn't call the plugin's check_option.
  • Descriptor checks refuse a required switch.
  • GET /admin/formats lists each option's input as text or switch.
• npm declares the switch. The new option is show_replace_registry_host, for proxies and groups. Nothing in the plugin reads it.
• Admin screen. RepositoryForm shows a switch option as a Switch and a text option as a text field, as before. When the kind changes on create, the form drops options that the new kind doesn't take, because the server refuses them. Example: the switch turned on for a group, then the kind changed to hosted.
• Connect sidebar. connectSnippets adds the replace-registry-host line only when the repository's option is "true". The browse API already returns the options.
• Docs.
  • docs/npm.md, Connecting a client: the switch, and how to set it through the admin API.
  • docs/format-plugins.md, Format options: switch options.

Testing

• Web:
  • pnpm run tsc is clean.
  • pnpm exec vitest run: all 43 files and 593 tests pass, including new tests for the Connect panel and the form's switch.
• Rust:
  • cargo fmt --check is clean.
  • cargo clippy --workspace --all-targets -- -D warnings is clean.
  • Unit tests of forge-plugin-api, forge-plugin, forge-format-npm and forge-format-apt pass, including a new case that a required switch is refused.
  • the_builtin_formats_describe_themselves_well passes.
• Integration (Docker): the new npm::proxies_and_groups_switch_the_replace_registry_host_command_on, npm::routes_only_npm_repositories and apt::options_are_checked pass. The new test covers off by default, " true " stored as "true", hosted refused, "yes" refused, and switching off with "false" or null. It also checks the formats listing.

---

Generated by Claude Code