Remove the SOCKET_FORCE env binding; --force is flag-only (#615)

[Mikola Lysenko (mikolalysenko)]

What and why

Removes the SOCKET_FORCE environment variable. --force stays on apply, vendor and --update (self-update) as a flag only.

The maintainer asked on #615 whether we still need SOCKET_FORCE. The answer was no, and the decision was: no per-command force variables, remove SOCKET_FORCE in v5, keep --force as a flag. Reasons:

• Only three clap bindings read it (apply --force, vendor --force, --update --force). Core never reads it.
• Nothing sets it: the npm wrapper, install.sh, CI workflows, scripts/ and depscan have no reference to it. An org-wide search finds it only in this repo.
• Its one real effect was the cross-command leak Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615 describes: one export forced every command that has --force.

Removal fails closed. A stale SOCKET_FORCE=1 export now does nothing, so hash checks and the managed-install refusal stay on. Nothing warns when the variable is set.

User-visible changes

• SOCKET_FORCE is ignored by apply, vendor and --update. Pass --force to the command that needs it.
• No change to flags, defaults or JSON output.

Code

• Dropped env = "SOCKET_FORCE" from the force arg in commands/apply.rs, commands/vendor.rs and commands/update.rs.
• args.rs: removed SOCKET_FORCE from LOCAL_ARG_ENV_VARS and its three rows from BOOL_BINDINGS. New unit test socket_force_env_is_ignored_and_force_flag_still_works (env set to 1/true/yes leaves force=false on apply, vendor, self-update and --update; --force still sets it).
• tests/cli_parse_vendor.rs: the four env-wiring tests are replaced by env_socket_force_is_ignored ("1", "true", "yes", ""). The scrub-list entries stay for hermeticity.

Docs updated

• crates/socket-patch-cli/CLI_CONTRACT.md: apply/vendor --force rows have no env var; --update --force is "Flag only"; the env-var table row is removed; SOCKET_FORCE is listed under "Removed env vars" and in the env-var section intro.
• docs/migrating-to-v5.md: new row in "Retired spellings".
• CHANGELOG.md is not touched (written at release time).

Tests run

• cargo test -p socket-patch-cli --lib args::: 43 passed.
• cargo test -p socket-patch-cli --test cli_parse_vendor --test cli_parse_vex --test cli_parse_apply --test cli_parse_main --test help_text_hygiene: all passed.
• cargo clippy -p socket-patch-cli --all-targets: no new warnings in changed files.

Review findings fixed

• The CLI_CONTRACT env-var intro still said only the three v3/v4 aliases were removed in v5. It now names SOCKET_FORCE too (436149f).
• Left as is: value_parser = parse_bool_flag on the three --force flags is now redundant but harmless; kept to keep the diff small.

Coordination

• vendor --force documents a missing-file tolerance and a mismatch warning that no vendored backend implements #923 rewrites the vendor --force help text and edits the same contract row. That rewrite is not in this PR.
• Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966 also edits the "Retired spellings" table and the args.rs tables. Whichever lands second needs a rebase.

Closes #615

🤖 Generated with Claude Code

---

Generated by Claude Code

---

Note

Low Risk
Intentional v5 contract change with migration docs; behavior fails closed when the env var is set, and flags are unchanged.

Overview
v5 removes SOCKET_FORCE: --force on apply, vendor, and --update is flag-only; the env var is ignored with no warning, so a stale export no longer bypasses beforeHash checks or managed-install refusal on unrelated commands.

Implementation drops env = "SOCKET_FORCE" from the three clap force args, removes the var from LOCAL_ARG_ENV_VARS, and replaces env-wiring tests with coverage that SOCKET_FORCE is ignored while --force still parses. CLI_CONTRACT.md and migrating-to-v5.md document the retirement.

^{Reviewed by Cursor Bugbot for commit 436149f. Configure here.}

[Mikola Lysenko (mikolalysenko)]

bugbot run

---

Generated by Claude Code

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 436149f. Configure here.}