feat(cli): offer an opt-in sp shorthand for session-peer #242

Motivation

Offer an optional short command for frequent interactive use: both session-peer [OPTION] and sp [OPTION] should invoke the same installed Python CLI, including subcommands. Keep session-peer as the canonical, unambiguous command.

This is a convenience feature proposed for v1.1.0, not part of the v1.0.3 maintenance scope.

Alternatives considered

• Users can already define a shell alias manually, but setup and lifecycle handling vary across shells and platforms.
• Shipping an unconditional second console-script entry point would be simple, but sp is a short, collision-prone name and should not be installed over another command automatically.
• A separate implementation or parser for sp would introduce avoidable behavioral drift.

Searched existing issues (all states) for sp/alias titles and short command/shortcut/shorthand references; no matching feature issue was found.

Proposed behaviour

• Keep session-peer as the canonical command and make sp an explicit opt-in alias or thin launcher to the same installed entry point.
• Examples: sp --version, sp list, and sp send ... --dry-run, with the same options, output, exit codes, defaults, and safety/approval behavior as the corresponding session-peer invocation.
• Preserve arguments exactly, including spaces, Unicode, stdin messages, and option separators. Do not use shell evaluation.
• Installation must not silently replace an existing executable, alias, function, or another installation manager's command. Document any shell-local collisions that an installer cannot automatically inspect.
• Continue using session-peer in primary documentation, scripts, SSH/internal transport calls, and generated reply instructions; present sp as optional interactive convenience.
• Respect pipx/uv/pip/standalone ownership and supported platform constraints. Choose and document a feasible opt-in approach before implementation; do not silently switch installation managers.
• User-confirmed installation contract: Python and TypeScript/npm versions are not installed simultaneously. Both projects should support the identical command names session-peer and sp; sp invokes the installed implementation, not a cross-runtime selector. Supporting simultaneous Python/TS installations or automatic runtime dispatch is out of scope. Still preserve unrelated tools named sp, respect manager ownership when switching implementations, and do not assume Python/TS feature parity.

Current source reference: pyproject.toml maps session-peer to session_peer:main; install.sh manages the standalone command. This issue does not prescribe an unconditional additional package entry point.

Acceptance criteria

• sp is opt-in and canonical session-peer behavior remains unchanged.
• Both commands use one implementation/parser and preserve options, JSON/text output, errors, and exit codes; no separate feature set.
• Collision checks refuse or clearly warn without overwriting an existing unrelated command, with shell/platform detection limits documented.
• Upgrade/uninstall preserve other tools and remove only an alias/launcher owned by this installation. Repeated setup is safe and idempotent.
• Document opt-in setup/removal for the chosen supported installation methods/platforms, the no-simultaneous-Python/TS-installation prerequisite, safe implementation switching, and use of the original installation manager.
• Tests cover version/help, list and dry-run behavior, malformed arguments, quoting/Unicode/stdin, pre-existing sp, repeated setup, update, removal, and implementation selection. No delivery/approval/retry semantics change.
• No automatic remote-host configuration, production rollout, or release publication is included in this issue.