oct.install.oct_install module

oct.install.oct_install module#

Purpose#

Wrap pip install -e <target> with safety preflight checks that catch the most common operator-error patterns: running the install from the wrong terminal window with the wrong venv active, in the wrong CWD, or against a worktree that would shadow a sibling worktree.

Responsibilities#

  • Define the oct_install_cmd() Click command, mounted on the top-level cli group.

  • Resolve and validate the install target (an Option C project root).

  • Verify the active venv matches the target’s expected venv.

  • Detect existing-shadow installs from another worktree.

  • Refuse to install from inside a Claude Code worktree without an explicit override.

  • Delegate to pip install -e <target> via subprocess after preflights succeed; print post-install diagnostics so the user sees exactly which oct binary will be invoked next.

Diagnostics#

Domain: INSTALL Levels:

L1 — errors (pip failure, preflight refusal) L2 — lifecycle (preflight start/end, install start/end) L3 — details (venv path, target path, shadow location) L4 — deep trace (each preflight check)

Contracts#

  • All subprocess calls use shell=False and explicit argv lists.

  • No filesystem writes are performed by this command itself; only pip (the delegated subprocess) writes to the venv’s site-packages.

  • Audit trail via the existing oct.git.audit.audited() decorator is intentionally NOT applied here, because the audit module emits to logs/git-audit-*.jsonl which lives under the project root — but oct install may run before any project root exists. A lightweight _dbg trace is kept instead.

Dependencies#

  • oct.core.diagnostics (_dbg structured logger)

  • click (CLI framework)