oct.install.oct_install Namespace Reference

Functions
bool	_is_option_c_project (Path target)
str|None	_read_project_name (Path target)
Path|None	_active_venv_root ()
Path|None	_expected_venv_under (Path target)
bool	_is_under (Path child, Path parent)
Path|None	_pip_show_location (str pkg, Path|None venv)
Path	_venv_python (Path venv)
Path|None	_which_oct (Path|None venv)
bool	_is_inside_worktree (Path target)
	oct_install_cmd (ctx, target, editable, reinstall, use_active_venv, allow_worktree, allow_outside_project, json_mode)

Variables
tuple	_LOCAL_VENV_NAMES = (".venv", "venv")
int	_PIP_TIMEOUT = 600

Detailed Description

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 :func:`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 :mod:`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 :func:`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)

Function Documentation

_active_venv_root()

Path | None oct.install.oct_install._active_venv_root ( )

protected

Return the root of the currently active venv, or ``None``.

``sys.prefix`` is the venv root for an active virtual environment,
``sys.base_prefix`` is the system Python. When they differ, a venv
is active. If they match, no venv is active.

Definition at line 117 of file oct_install.py.

Here is the caller graph for this function:

_expected_venv_under()

Path | None oct.install.oct_install._expected_venv_under ( Path target )

protected

Return the first existing local venv directory under *target*.

Definition at line 129 of file oct_install.py.

Here is the caller graph for this function:

_is_inside_worktree()

bool oct.install.oct_install._is_inside_worktree ( Path target )

protected

Return True if *target* lives under any ``.claude/worktrees/`` ancestor.

Definition at line 197 of file oct_install.py.

Here is the caller graph for this function:

_is_option_c_project()

bool oct.install.oct_install._is_option_c_project ( Path target )

protected

Return True if *target* looks like an Option C project root.

Accept both legacy (``.octrc.json`` at root) and migrated
(``.option_c/`` directory) layouts. ``pyproject.toml`` must also
be present so ``pip install -e`` has something to install.

Definition at line 85 of file oct_install.py.

Here is the caller graph for this function:

_is_under()

bool oct.install.oct_install._is_under ( Path child, Path parent )

protected

Return True if *child* is at or below *parent*.

Definition at line 139 of file oct_install.py.

Here is the caller graph for this function:

_pip_show_location()

Path | None oct.install.oct_install._pip_show_location ( str pkg, Path | None venv )

protected

Return the ``Location:`` from ``pip show <pkg>`` or ``None``.

Runs ``<venv>/Scripts/python -m pip show <pkg>`` (Windows) or
``<venv>/bin/python -m pip show <pkg>`` (Unix) when *venv* is
given; falls back to ``sys.executable`` otherwise.

Definition at line 148 of file oct_install.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_read_project_name()

str | None oct.install.oct_install._read_project_name ( Path target )

protected

Return the ``[project] name`` from *target*'s pyproject.toml.

Definition at line 98 of file oct_install.py.

Here is the caller graph for this function:

_venv_python()

Path oct.install.oct_install._venv_python ( Path venv )

protected

Return the python executable path inside *venv*.

Definition at line 175 of file oct_install.py.

Here is the caller graph for this function:

_which_oct()

Path | None oct.install.oct_install._which_oct ( Path | None venv )

protected

Return the path to the ``oct`` script, preferring *venv*'s bin.

Definition at line 184 of file oct_install.py.

Here is the caller graph for this function:

oct_install_cmd()

oct.install.oct_install.oct_install_cmd	(		ctx,
			target,
			editable,
			reinstall,
			use_active_venv,
			allow_worktree,
			allow_outside_project,
			json_mode )

Install an Option C project as an editable package, with safety checks.

Wraps ``pip install -e <target>`` after verifying:

1. The target is an Option C project (pyproject.toml + .octrc.json
   or .option_c/).
2. The active venv matches the target's expected venv (refuse with
   a precise diagnostic otherwise).
3. No existing shadow install from a different worktree is about
   to be silently overwritten.
4. The target is not inside a Claude Code worktree (refusable
   with --allow-worktree).

Definition at line 240 of file oct_install.py.

Here is the call graph for this function:

Variable Documentation

_LOCAL_VENV_NAMES

tuple oct.install.oct_install._LOCAL_VENV_NAMES = (".venv", "venv")

protected

Definition at line 73 of file oct_install.py.

_PIP_TIMEOUT

int oct.install.oct_install._PIP_TIMEOUT = 600

protected

Definition at line 77 of file oct_install.py.