GeezerVison

Sets up the foundation for a comprehensive unit-test campaign on the
socket-patch CLI. No behavior change to the binary.

Two changes:

1. Expose the clap parser as a library so integration tests can verify
   the public CLI contract without spawning the binary:
   - new crates/socket-patch-cli/src/lib.rs hosting Cli, Commands,
     looks_like_uuid, and parse_with_uuid_fallback (extracted from main.rs)
   - Cargo.toml gains [lib] entry alongside the existing [[bin]]
   - main.rs is now a thin wrapper that delegates to the lib

2. De-duplicate the manifest-path resolution block that was copy-pasted
   into 5 commands (apply, rollback, list, remove, repair). New helper
   socket_patch_core::manifest::operations::resolve_manifest_path
   handles the absolute-vs-relative join in one place, with 3 unit tests.

3. New CLI_CONTRACT.md next to the crate documenting every subcommand,
   flag, default, alias, JSON shape, and exit code as semver-significant
   surface. Adds a comment block above pub enum Commands pointing to it
   so anyone editing the parser sees the contract reminder.

Verified: cargo build/clippy/test --workspace --all-features all clean
(415 unit tests pass, including 3 new resolve_manifest_path tests).

Foundation for follow-up PRs that add the per-command parser snapshot
tests and helper unit tests.

Assisted-by: Claude Code:claude-opus-4-7

Lock in the public CLI contract for the `apply` subcommand and add
unit tests for its pure JSON-output helpers. No behavior change.

`tests/cli_parse_apply.rs` (25 tests) drives `Cli::try_parse_from`
to pin every flag in the `apply` row of `CLI_CONTRACT.md`:

  - Defaults asserted in one block (every field at its documented
    default value, plus separate dedicated tests for `download_mode`
    = "diff" and `manifest_path` = ".socket/manifest.json" since
    these are the values wrappers hard-code).
  - Both long and short forms exercised for `-d/--dry-run`,
    `-s/--silent`, `-m/--manifest-path`, `-g/--global`,
    `-f/--force`, `-v/--verbose`.
  - Long-only flags (`--cwd`, `--offline`, `--json`,
    `--global-prefix`) each get a test.
  - `--ecosystems npm,pypi,cargo` CSV split pinned (contract — a
    single flag, not repeated). Single-value form also tested.
  - `--download-mode` accepts `diff`, `package`, `file` (each
    asserted explicitly so changes to the accepted token set fail
    here loudly).
  - Failure path: `--unknown-flag` returns `Err` with
    `clap::error::ErrorKind::UnknownArgument`.

Inline `#[cfg(test)] mod tests` in `apply.rs` (8 tests) covers
the two pure helpers used by the JSON code path:

  - `verify_status_str`: all four `VerifyStatus` variants map to
    their documented lowercase tags (`ready`, `already_patched`,
    `hash_mismatch`, `not_found`).
  - `result_to_json`: top-level key set is exactly {purl, path,
    success, error, filesPatched, appliedVia, filesVerified};
    `filesVerified[0]` keys are exactly {file, status, message,
    currentHash, expectedHash, targetHash}; a `HashMismatch`
    entry serializes its `status` to `"hash_mismatch"`; `appliedVia`
    uses camelCase (NOT snake_case `applied_via`) and serializes
    as a map of `path -> tag`.

Verified: `cargo build --workspace --all-features`, `cargo clippy
--workspace --all-features -- -D warnings`, and `cargo test
--workspace --all-features --lib --tests` all clean. 33 new tests
total (448 in workspace, all passing).

Assisted-by: Claude Code:claude-opus-4-7