cli.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/cli.py
 
"""
Purpose
-------
Provide the main command-line interface for the OCT (Option C Tools) ecosystem.
 
Responsibilities
----------------
- Define top-level commands: oct lint, oct format, oct new, oct scaffold, oct docs,
  oct test, oct export-source, oct clean, oct health.
- Delegate work to the appropriate OCT modules.
- Scaffold new Option C projects with a correct ``oc_diagnostics/debug_config.json``
  pre-configured for use with ``oc_diagnostics``.
- Set up Sphinx documentation templates in ``docs/``.
- Ensure consistent behavior across all projects.
 
Diagnostics
-----------
Domain: OCT-CLI
Levels:
    L2 - lifecycle
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- Must be installed as the console entry point for the OCT package.
- Must not contain business logic; only dispatching.
- Scaffolded ``debug_config.json`` must be a valid ``oc_diagnostics`` configuration.
 
Dependencies
------------
- oct (package version)
- oct.core.project_root (project root detection)
- oct.linter.oct_lint (linter command implementation)
- oct.formatter.oct_format (formatter command implementation)
- oct.health.oct_health (health dashboard command)
- oct.generator.new_python_file (new file scaffolding)
- oct.diag.oct_diag (diagnostics config commands)
- oct.deps.oct_deps (dependency graph command)
- oct.hooks.oct_hooks (pre-commit hooks generator)
- oct.typecheck.oct_typecheck (type-checking wrapper)
- click (CLI framework)
- oct.complexity.command (complexity command)
- oct.mutation.command (mutate command)
- oct.git (git_group - the git command group)
- oct.migrate (migrate_group - the migrate command group)
- oct.audit (audit_group - the audit command)
- oct.install.oct_install (oct_install_cmd - the install command)
- oct.core.diagnostics (_dbg structured logger)
- oc_diagnostics (lazy; init with file-only output before each command)
- oct.timing.ledger (lazy; the timing stage around each command)
- oct.core.compat (lazy; oc_diagnostics compatibility warning for scaffold)
- oct.scaffold (lazy; run_scaffold for the scaffold command)
- oct.scaffold.oct_scaffold (lazy; Claude Code skills copy for scaffold --with-claude)
- oct.core.workspace (lazy; manifest subproject name for the Doxyfile PROJECT_NAME)
- oct.docs.callgraph_command (lazy; docs --callgraph)
- oct.docs.doxyfile_init (lazy; Doxyfile writer for docs --init-doxygen)
- oct.docs.oct_docs (lazy; Sphinx, Doxygen, all-tier and clean docs runs, project name fallback)
- oct.docs.typedoc (lazy; docs --typedoc)
- oct.testing.cache (lazy; pytest cache plugin flags and the cached run's file count)
- oct.core.git (lazy; changed-file discovery for test --changed)
- oct.tools.source_exporter (lazy; export-source, and source export and pycache removal for clean)
- oct.tools.skeleton_exporter (lazy; export-skeleton, and skeleton export removal for clean)
- oct.tools.build_artifacts (lazy; build and dist tree removal for clean)
- oct.git.oct_git (lazy; enhanced hooks template for the deprecated install-hooks)
- oct.tools.install_mcp (lazy; install-mcp command)
- oc_chat.registry (not imported; run as python -m oc_chat.registry by the agent command)
- pytest (not imported; run as python -m pytest by the test command)
"""
 
import json
import os
import sys
import click
from pathlib import Path
 
from oct import __version__
from oct.complexity.command import complexity
from oct.core.project_root import find_project_root, get_project_root
from oct.linter.oct_lint import run_linter
from oct.mutation.command import mutate
from oct.formatter.oct_format import run_formatter
from oct.health.oct_health import run_health
from oct.generator.new_python_file import create_new_file
from oct.diag.oct_diag import (
    list_domains,
    migrate_config,
    restore_config,
    set_level,
    validate_config,
)
from oct.deps.oct_deps import run_deps
from oct.hooks.oct_hooks import install_hooks
from oct.typecheck.oct_typecheck import run_typecheck
 
 
_COMMAND_FLAGS = {
    "lint": [
        ("--fix-headers", "Automatically fix shebang, encoding, and path headers"),
        ("--dry-run", "Preview changes without modifying files"),
        ("--json", "Emit machine-readable JSON to stdout"),
        ("--jobs N, -j N", "Parallel workers (default: 1)"),
        ("--changed", "Lint only git-modified Python files"),
        ("--profile P", "Lint profile: proto, compact, strict"),
        ("--secret-match MODE", "Secret-name matcher: substring (default) | word"),
        ("--code-entropy-threshold N", "Shannon entropy threshold for code strings (default: 4.5)"),
        ("--no-entropy", "Disable entropy-based secret detection"),
        ("--no-cache", "Bypass lint cache reads (still writes)"),
        ("--baseline", "Save current violations as the baseline"),
        ("--against-baseline", "Report only new/resolved vs saved baseline"),
        ("--explain RULE", "Show rule documentation (rationale, pattern, spec ref)"),
        ("PATH ...", "Files or directories to lint (default: entire project)"),
    ],
    "format": [
        ("--fix", "Apply formatting changes (default: dry-run)"),
        ("--dry-run", "Report what would change without modifying"),
        ("--json", "Output machine-readable JSON"),
        ("--verbose", "Show per-file details"),
        ("--changed", "Format only git-modified Python files"),
    ],
    "agent": [
        ("SUBCOMMAND ...", "Forwarded verbatim to 'python -m oc_chat.registry' "
                           "(init, doctor, queue, plan, round, roadmap, "
                           "regenerate, checkpoint, ...)"),
        ("(passthrough)", "The registry JSON envelope, --json flags, and exit "
                          "codes (0/1/2/3/5) are preserved by the child CLI"),
    ],
    "new": [
        ("PATH", "Target file path (required)"),
        ("--force", "Overwrite existing file"),
        ("--test", "Also generate companion test file in tests/"),
        ("--dry-run", "Show what would be created without writing"),
        ("--verbose", "Show generated file content"),
    ],
    "scaffold": [
        ("NAME", "Project name (required)"),
        ("--dry-run", "Show what would be created without writing"),
        ("--no-venv", "Skip .venv/ creation (FS-503: on by default)"),
        ("--with-claude", "Copy bundled Claude Code skills into .claude/skills/"),
    ],
    "docs": [
        ("--sphinx", "Generate Sphinx HTML documentation"),
        ("--doxygen", "Generate Doxygen HTML documentation"),
        ("--typedoc", "Generate TypeDoc HTML documentation (needs typedoc.json)"),
        ("--all", "Generate every declared tier: Sphinx, Doxygen, TypeDoc"),
        ("--clean", "Remove generated documentation artifacts"),
        ("--dry-run", "Preview what --clean would remove"),
        ("--no-workspace", "Force single-project mode at a workspace root (FS-WS-DOCS)"),
        ("--init-doxygen", "Write docs/doxygen_work_dir/Doxyfile from the bundled template"),
        ("--force", "With --init-doxygen: overwrite an existing Doxyfile"),
        ("--callgraph QUALNAME", "Full call graph of one function (DOT + SVG, docs/_build/callgraph/)"),
        ("--depth N", "With --callgraph: stop N calls below the root"),
        ("--trace -- ARGS", "With --callgraph: run 'oct ARGS' for real and compare what ran"),
    ],
    "test": [
        ("--json", "Emit machine-readable JSON summary to stdout"),
        ("--changed", "Run tests for git-modified files only"),
        ("--cached", "Skip test files unchanged since their last green run"),
        ("--oct-cache-clear", "Empty the test cache before running"),
    ],
    "export-source": [
        ("--verbose", "Show per-file statistics"),
        ("--clean", "[DEPRECATED: use 'oct clean'] Remove _source_code-* dirs"),
        ("--single-dir", "Write all output into one root-level directory"),
        ("--diff REF", "Export only files changed since REF"),
        ("--warn-secrets", "Warn on suspected secrets in exported files"),
        ("--block-secrets", "Abort export when secrets are detected"),
        ("--allow-outside-project", "Allow export targets outside the project root"),
    ],
    "export-skeleton": [
        ("--json", "Emit machine-readable JSON summary to stdout"),
        ("--verbose", "Show per-file statistics"),
        ("--single-dir", "Write all output into one root-level directory"),
        ("--no-diagnostics", "Omit Diagnostics section from docstrings"),
        ("--clean", "Remove previously exported skeletons"),
        ("--allow-outside-project", "Allow skeleton targets outside the project root"),
    ],
    "clean": [
        ("--dry-run", "Show what would be deleted without deleting"),
        ("--allow-outside-project", "Allow cleaning paths outside the project root"),
    ],
    "health": [
        ("--tests", "Run the project test suite"),
        ("--timing", "Show only the timing report"),
        ("--timing-last N", "Recent records per stage (default: 20)"),
        ("--write-baseline", "Write this host's timing medians"),
        ("--force-host", "Allow adding another baseline host"),
        ("--session PATH", "Read tool latency and tokens from session events"),
        ("--json", "Machine-readable JSON output"),
        ("--verbose", "Detailed per-file breakdown"),
        ("--timeout N", "Per-check timeout in seconds (default: 300)"),
    ],
    "complexity": [
        ("--coverage-data PATH", "Map an existing coverage.py data file"),
        ("--json", "Emit the full machine-readable report"),
        ("--top N", "Limit human output to the worst N functions"),
        ("--max-cc N", "Exit 2 when a function exceeds CC N (advisory: 15)"),
        ("--max-crap M", "Exit 2 when a function exceeds CRAP M (advisory: 30)"),
        ("--changed", "Measure only git-modified Python files"),
        ("--baseline PATH", "Ratchet against recorded debt; new or worse fails"),
        ("--write-baseline PATH", "Record this run's measurements as a baseline"),
        ("PATH ...", "Python files or directories (default: project root)"),
    ],
    "mutate": [
        ("--target FILE", "Python file to mutate (required)"),
        ("--tests PATH", "Tests run once per mutant (required for a run)"),
        ("--timeout N", "Seconds per test run before a mutant times out"),
        ("--json", "Emit the full machine-readable report"),
        ("--list", "Enumerate the mutants without running anything"),
    ],
    "deps": [
        ("--json", "JSON adjacency list output"),
        ("--mermaid", "Mermaid diagram output"),
        ("--dot", "DOT/Graphviz output"),
    ],
    "install": [
        ("TARGET", "Project root to install (default: current directory)"),
        ("--editable, -e", "Install in editable mode (required)"),
        ("--reinstall", "Allow re-install over an existing shadow"),
        ("--use-active-venv", "Bypass venv-match check"),
        ("--allow-worktree", "Allow installing from a Claude Code worktree"),
        ("--allow-outside-project", "Allow running outside an Option C project"),
        ("--json", "Emit JSON output"),
    ],
    "install-hooks": [
        ("--force", "Overwrite existing .pre-commit-config.yaml"),
    ],
    "git": [
        ("status", "Show git status with Option C compliance annotations"),
        ("check", "Run the unified quality gate (lint + format + secrets)"),
        ("init", "Initialise or enhance a git repo with Option C conventions"),
        ("commit", "Commit with quality gate and secrets enforcement"),
        ("branch", "Create or switch branches with naming validation"),
        ("add", "Stage files for commit (whole-file or interactive)"),
        ("restore", "Restore working-tree edits or unstage paths"),
        ("ignore", "Manage .gitignore patterns within the OCT-managed block"),
        ("commit-msg", "Validate a commit message file (pre-commit stage)"),
        ("hooks", "Manage Option C git hooks"),
        ("changelog", "Generate changelog from Conventional Commits history"),
    ],
    "git status": [
        ("--json", "Emit machine-readable JSON output"),
        ("--no-check", "Skip compliance annotations (plain git status)"),
        ("--scope SCOPE", "Scope: project (default), repo, auto"),
    ],
    "git add": [
        ("PATHS...", "Files or directories to stage"),
        ("--patch, -p", "Interactive hunk-level staging"),
        ("--update, -u", "Stage all already-tracked modified files"),
        ("--all, -A", "Stage all changes within project scope"),
        ("--dry-run", "Show what would be staged without staging"),
        ("--json", "Emit JSON output"),
    ],
    "git ignore": [
        ("PATTERNS...", "Glob patterns to add to .gitignore"),
        ("--remove PATTERN", "Remove a pattern from the OCT-managed block"),
        ("--list", "List currently active ignore patterns"),
        ("--scope SCOPE", "Target .gitignore: workspace, project, nearest (default)"),
        ("--json", "Emit JSON output"),
    ],
    "git restore": [
        ("PATHS...", "Files to restore (default: scope by --all)"),
        ("--staged", "Unstage paths from the index without touching working tree"),
        ("--all, -A", "Restore all in-scope paths"),
        ("--yes", "Skip confirmation prompt for --staged --all"),
        ("--json", "Emit JSON output"),
    ],
    "git init": [
        ("--dry-run", "Show what would be created without writing"),
        ("--github", "Also generate GitHub Actions workflow"),
        ("--no-hooks", "Skip hook installation"),
    ],
    "git branch": [
        ("--create NAME", "Create a new branch from HEAD"),
        ("--switch NAME", "Switch to an existing branch"),
        ("--json", "Emit JSON output"),
    ],
    "git commit": [
        ("-m MESSAGE, --message MESSAGE", "Commit message (Conventional Commits format)"),
        ("--force", "Skip lint/format checks (secrets still checked)"),
        ("--no-verify", "Forward --no-verify to git (hooks skipped)"),
        ("--profile P", "Override lint profile: proto, compact, strict"),
        ("--json", "Emit JSON output"),
        ("--ignore-unstaged-mutation", "Downgrade B1.0 mutation detection to warn for this run"),
    ],
    "git commit-msg": [
        ("MESSAGE_FILE", "Path to the commit message file (required)"),
        ("--json", "Emit machine-readable JSON output"),
    ],
    "git check": [
        ("--staged-only", "Check only staged (index) files"),
        ("--all", "Check every Python file in the project"),
        ("--include-tests", "Also run `oct test` (for pre-push use)"),
        ("--fix", "Attempt auto-fix of violations, then re-check"),
        ("--profile P", "Override lint profile: proto, compact, strict"),
        ("--json", "Emit machine-readable JSON output"),
        ("--sandbox", "Run pytest under the MCP sandbox environment"),
    ],
    "git hooks": [
        ("install", "Generate .pre-commit-config.yaml with all hooks"),
        ("status", "Show installed hook state"),
        ("remove", "Remove Option C hooks (preserves non-OCT hooks)"),
    ],
    "git changelog": [
        ("--release V", "Release version tag (e.g. v0.13.0)"),
        ("--since REF", "Git ref to start from (default: last tag)"),
        ("--dry-run", "Print to stdout without writing"),
        ("--json", "Emit structured JSON"),
    ],
    "git hooks install": [
        ("--force", "Overwrite existing configuration"),
    ],
    "typecheck": [
        ("--json", "Emit machine-readable JSON summary to stdout"),
        ("ARGS ...", "Arguments forwarded to pyright/mypy"),
    ],
    "diag": [
        ("validate-config", "Validate debug_config.json against schema"),
        ("  --strict", "Treat validation warnings as errors"),
        ("list-domains", "List configured domains with levels and colors"),
        ("set-level DOMAIN N", "Set a domain's debug level (0-9)"),
        ("  --dry-run", "Preview edit without writing (use with set-level)"),
        ("restore", "Restore debug_config.json from .bk backup"),
        ("migrate-config [PATH]", "Upgrade legacy v1 schema to v2.0"),
        ("  --dry-run", "Preview migration without writing (use with migrate-config)"),
    ],
    "install-mcp": [
        ("--host HOST", "Target AI host: claude-code, cursor, vscode, auto (default: auto)"),
        ("--dry-run / --no-dry-run", "Preview without writing (default: --dry-run)"),
    ],
    "migrate": [
        ("option-c", "Migrate to canonical .option_c/ dotdir layout (FS-539)"),
    ],
    "migrate option-c": [
        ("--dry-run", "Show plan without writing anything"),
        ("--no-backup", "Skip .bk backup when overwriting"),
    ],
    "audit": [
        ("--json-output", "Emit JSON instead of human-readable text"),
    ],
}
 
 
#: ``ctx.meta`` slot carrying this invocation's timing sample, so a
#: command can add the scope and file count the ledger records (Plan
#: 249 P5). ``Context.meta`` is shared with every subcommand context.
TIMING_SAMPLE_KEY = "oct.timing.sample"
 
 
#: Attribute a command sets to ``True`` to receive its positional arguments
#: verbatim on Windows. See :func:`_resolve_leaf_command` for why this
#: exists; ``oct git ignore`` is the command that needs it.
NO_GLOB_EXPANSION_ATTR: str = "no_glob_expansion"
 
 
def _resolve_leaf_command(
    group: click.Group, args: list[str],
) -> click.Command | None:
    """Return the command *args* would dispatch to, parsing nothing else.
 
    Walks the group tree with ``resilient_parsing`` contexts, so option
    callbacks never run and a malformed command line resolves to ``None``
    rather than raising - the real parse that follows reports the error
    properly. Used before Click's Windows argument expansion to find out
    whether the target command wants that expansion at all.
    """
    cmd: click.Command = group
    remaining = list(args)
    try:
        while isinstance(cmd, click.Group):
            with cmd.make_context(
                cmd.name or "oct", remaining, resilient_parsing=True,
            ) as ctx:
                # Click 8.2 moved protected_args behind an underscore; take
                # whichever this version has, plus the ordinary remainder.
                remaining = [
                    *getattr(ctx, "_protected_args", ()), *ctx.args,
                ]
            if not remaining:
                return cmd
            name, remaining = remaining[0], remaining[1:]
            nxt = cmd.get_command(ctx, name)
            if nxt is None:
                return None
            cmd = nxt
    except click.ClickException:
        return None
    return cmd
 
 
def _expand_windows_args(group: click.Group, args: list[str]) -> list[str]:
    """Apply Click's Windows shell-expansion unless the target opts out.
 
    Click's ``Command.main`` runs ``_expand_args`` over the whole argv on
    Windows - ``~``, ``$VAR`` and globs - because cmd and PowerShell do
    none of that themselves, and ``oct lint oct/*.py`` relies on it. But
    the expansion cannot tell a path from a pattern: ``oct git ignore
    "**/docs/html/"`` had its one argument replaced by the fourteen
    directories it happened to match, every one of which the pattern
    validator then rejected (2026-09-27). A command that takes patterns
    sets :data:`NO_GLOB_EXPANSION_ATTR` and receives its argv verbatim;
    every other command keeps the expansion it always had.
    """
    from click.utils import _expand_args
    leaf = _resolve_leaf_command(group, args)
    if leaf is not None and getattr(leaf, NO_GLOB_EXPANSION_ATTR, False):
        return list(args)
    return _expand_args(args)
 
 
def _start_diagnostics() -> None:
    """Start oc_diagnostics for this process: exception hook, no stream capture.
 
    Output goes to the log file only, so oct's terminal output stays its
    own. The file's FORMAT is left to the config's ``log_format`` (text, or
    ``jsonl`` for machine reading; oc_diagnostics >= 2.2.0 keeps the two
    independent). Idempotent; a no-op without oc_diagnostics.
    """
    try:
        from oc_diagnostics import init, set_global_setting
        init(intercept_streams=False)
        set_global_setting("output_mode", "file")
    except ImportError:
        pass
 
 
class OctGroup(click.Group):
    """Custom group that shows per-command flags in the main --help output."""
 
    def main(self, args: list[str] | None = None, *rest: object,
             windows_expand_args: bool = True, **kwargs: object) -> object:
        """Click's ``main`` with the Windows expansion made command-aware.
 
        Click only expands when it reads ``sys.argv`` itself, so the argv
        is taken here, expanded (or not) per the target command, and
        handed over with expansion switched off so it is not done twice.
        """
        if args is None:
            args = sys.argv[1:]
            if os.name == "nt" and windows_expand_args:
                args = _expand_windows_args(self, args)
        return super().main(args, *rest, windows_expand_args=False, **kwargs)
 
    def invoke(self, ctx: click.Context) -> object:
        """Time the registered command path without recording its arguments."""
        # Diagnostics start HERE, before the timing stage opens: the stage's
        # own ENTER record was the first _dbg call of every command, and it
        # ran before the group callback used to call init(), so every oct
        # invocation printed "_dbg() called before init()" (masked until
        # 2026-09-28 by an earlier offender in oct.migrate; both found by the
        # chart C runtime trace). init() is idempotent.
        _start_diagnostics()
        from oct.timing.ledger import command_stage, timed_stage
        root = ctx.params.get("root_dir")
        if root is None:
            try:
                root = find_project_root(Path.cwd())
            except Exception:
                root = Path.cwd()
        with timed_stage(
            Path(root or Path.cwd()), command_stage(ctx), outcome=0,
        ) as sample:
            # Plan 249 P5: a command that measures something worth
            # recording (``oct test --cached`` counts the files it
            # actually ran) sets ``scope``/``files`` on this sample.
            ctx.meta[TIMING_SAMPLE_KEY] = sample
            return super().invoke(ctx)
 
    def format_help(
        self,
        ctx: click.Context,
        formatter: click.HelpFormatter,
    ) -> None:
        formatter.write(f"oct {__version__}\n")
        formatter.write_paragraph()
        self.format_usage(ctx, formatter)
 
        if self.help:
            formatter.write_paragraph()
            with formatter.indentation():
                formatter.write(self.help)
            formatter.write_paragraph()
 
        # Global options
        opts = []
        for param in self.get_params(ctx):
            rv = param.get_help_record(ctx)
            if rv:
                opts.append(rv)
        if opts:
            with formatter.section("Global Options"):
                formatter.write_dl(opts)
 
        # Commands with inline flags
        commands = []
        for name in self.list_commands(ctx):
            cmd = self.get_command(ctx, name)
            if cmd is None or cmd.hidden:
                continue
            commands.append((name, cmd))
 
        if commands:
            with formatter.section("Commands"):
                for name, cmd in commands:
                    short_help = cmd.get_short_help_str(limit=60)
                    formatter.write(f"  {name:<16} {short_help}\n")
                    flags = _COMMAND_FLAGS.get(name, [])
                    for flag, desc in flags:
                        formatter.write(f"    {flag:<22} {desc}\n")
                    if flags:
                        formatter.write("\n")
 
 
@click.group(cls=OctGroup)
@click.version_option(__version__, "-V", "--version", prog_name="oct",
                      message="%(prog)s %(version)s")
@click.option("--root-dir", default=None, type=click.Path(exists=True, file_okay=False),
              help="Override project root directory (skip auto-detection).")
@click.option("--allow-outside-project", is_flag=True,
              help="Allow operations outside auto-detected project root (OI-405).")
@click.option("--strict-config", is_flag=True,
              help="Fail on malformed .octrc.json or schema errors (OI-411).")
@click.option("--log", "log_output", is_flag=True,
              help="Persist command output as JSON to .option_c/logs/.")
@click.pass_context
def cli(
    ctx: click.Context,
    root_dir: str | None,
    allow_outside_project: bool,
    strict_config: bool,
    log_output: bool,
) -> None:
    """OCT - Option C Tools"""
    # Diagnostics were started by OctGroup.invoke, which Click runs before
    # this callback; a _dbg call here reaches a live logger.
    func = "cli"
    _dbg("OCT-CLI", func,
         f"cli start: root_dir={root_dir} strict_config={strict_config}", 3)
    ctx.ensure_object(dict)
    ctx.obj["root_dir"] = root_dir
    ctx.obj["allow_outside_project"] = allow_outside_project
    ctx.obj["strict_config"] = strict_config
    ctx.obj["log_output"] = log_output
    if strict_config:
        os.environ["OCT_STRICT_CONFIG"] = "1"
 
 
cli.add_command(complexity)
cli.add_command(mutate)
 
 
@cli.command(context_settings=dict(ignore_unknown_options=True))
@click.argument("args", nargs=-1, type=click.UNPROCESSED)
@click.pass_context
def lint(ctx: click.Context, args: tuple[str, ...]) -> None:
    """Run the Option C linter."""
    project_root = get_project_root(ctx)
    exit_code = run_linter(project_root, list(args))
    if exit_code != 0:
        raise SystemExit(exit_code)
 
 
@cli.command(context_settings=dict(ignore_unknown_options=True))
@click.argument("args", nargs=-1, type=click.UNPROCESSED)
@click.pass_context
def format(ctx: click.Context, args: tuple[str, ...]) -> None:
    """Auto-fix Option C compliance violations in Python files."""
    project_root = get_project_root(ctx)
    run_formatter(project_root, list(args))
 
 
@cli.command(name="agent", context_settings=dict(ignore_unknown_options=True))
@click.argument("args", nargs=-1, type=click.UNPROCESSED)
def agent(args: tuple[str, ...]) -> None:
    """Delegate to the OC Chat registry agent CLI.
 
    A thin subprocess facade over ``python -m oc_chat.registry`` (Plan 151
    T6). oct NEVER imports oc_chat - the CLI-boundary rule; all arguments,
    stdin/stdout/stderr, the JSON envelope, and the exit-code contract
    (0 ok, 1 source-validation, 2 build/refusal/scope, 3 not-byte-stable,
    5 stale schema) are preserved verbatim by delegating to the child
    process. Requires oc_chat to be importable on the interpreter running
    the facade (the monorepo workspace install).
    """
    import subprocess
    import sys
 
    # ``-P`` (PYTHONSAFEPATH) keeps the current working directory off the
    # child's import path. From the monorepo root the ``oc_chat/`` directory
    # would otherwise shadow the installed ``oc_chat`` as a namespace package
    # (the Plan 151 §2.7b "chimera" - every monorepo ``python -m oc_chat.*``
    # invocation is pinned to ``-P``), and the registry CLI resolves its
    # store via workspace discovery, not via cwd imports.
    try:
        result = subprocess.run(
            [sys.executable, "-P", "-m", "oc_chat.registry", *args]
        )
    except FileNotFoundError as exc:  # pragma: no cover - interpreter always present
        raise click.ClickException(f"could not launch the registry CLI: {exc}")
    if result.returncode != 0:
        raise SystemExit(result.returncode)
 
 
@cli.command()
@click.argument("path")
@click.option("--force", is_flag=True, help="Overwrite existing file")
@click.option("--test", is_flag=True, help="Also generate companion test file")
@click.option("--dry-run", is_flag=True, help="Show what would be created without writing anything")
@click.option("--verbose", is_flag=True, help="Show generated file content")
@click.pass_context
def new(
    ctx: click.Context,
    path: str,
    force: bool,
    test: bool,
    dry_run: bool,
    verbose: bool,
) -> None:
    """Create a new Option C-compliant Python file."""
    project_root = get_project_root(ctx)
    create_new_file(project_root, path, force, dry_run=dry_run, test=test, verbose=verbose)
 
 
@cli.command()
@click.argument("name")
@click.option("--dry-run", is_flag=True,
              help="Show what would be created without writing anything")
@click.option("--no-venv", is_flag=True, default=False,
              help="Skip .venv/ creation (FS-503: on by default).")
@click.option("--with-claude", is_flag=True, default=False,
              help="Copy bundled Claude Code skills into .claude/skills/.")
def scaffold(
    name: str,
    dry_run: bool,
    no_venv: bool,
    with_claude: bool,
) -> None:
    """Create a new Option C project."""
    from oct.core.compat import check_oc_diagnostics_compat
    from oct.scaffold import run_scaffold
 
    compat_msg = check_oc_diagnostics_compat()
    if compat_msg:
        click.echo(compat_msg, err=True)
 
    result = run_scaffold(
        name,
        Path.cwd(),
        dry_run=dry_run,
        include_venv=not no_venv,
    )
 
    if with_claude:
        from oct.scaffold.oct_scaffold import _copy_claude_skills
        _copy_claude_skills(Path.cwd() / name, result, dry_run=dry_run)
 
    for msg in result.messages:
        click.echo(msg)
    if not dry_run:
        click.echo(f"Created new Option C project: {Path.cwd() / name}")
 
 
def _workspace_subproject_name(project_root: Path) -> str | None:
    """Return the manifest name of the subproject at *project_root*, if any.
 
    ``None`` when *project_root* is not inside a workspace, the manifest
    does not load, or no subproject entry contains it.
    """
    from oct.core.workspace import (
        WorkspaceError, assign_to_subproject, find_workspace_root, load_workspace,
    )
    ws_root = find_workspace_root(project_root)
    if ws_root is None:
        return None
    try:
        workspace = load_workspace(ws_root)
    except WorkspaceError:
        return None
    sp = assign_to_subproject(project_root, workspace)
    return sp.name if sp is not None else None
 
 
@cli.command()
@click.option("--sphinx", "sphinx_mode", is_flag=True,
              help="Generate Sphinx HTML documentation")
@click.option("--doxygen", "doxygen_mode", is_flag=True,
              help="Generate Doxygen HTML documentation")
@click.option("--typedoc", "typedoc_mode", is_flag=True,
              help="Generate TypeDoc HTML documentation (TypeScript projects "
                   "declaring a typedoc.json)")
@click.option("--all", "all_mode", is_flag=True,
              help="Generate every declared tier: Sphinx, Doxygen, TypeDoc")
@click.option("--clean", "clean_mode", is_flag=True,
              help="Remove generated documentation artifacts")
@click.option("--dry-run", "dry_run", is_flag=True,
              help="Preview what --clean would remove")
@click.option("--no-workspace", "no_workspace", is_flag=True,
              help="Force single-project mode even at a workspace root "
                   "(escape hatch for the FS-WS-DOCS workspace fan-out)")
@click.option("--init-doxygen", "init_doxygen", is_flag=True,
              help="Write docs/doxygen_work_dir/Doxyfile from the bundled "
                   "template, declaring this project for Doxygen builds. "
                   "Keeps an existing Doxyfile unless --force is given.")
@click.option("--force", "force", is_flag=True,
              help="With --init-doxygen: overwrite an existing Doxyfile.")
@click.option("--callgraph", "callgraph", metavar="QUALNAME", default=None,
              help="Draw the full call graph of one function (dotted name, or "
                   "a unique suffix) to docs/_build/callgraph/ as DOT and SVG, "
                   "and report what could and could not be resolved.")
@click.option("--depth", "depth", type=click.IntRange(min=0), default=None,
              help="With --callgraph: stop this many calls below the root.")
@click.option("--trace", "trace_mode", is_flag=True,
              help="With --callgraph: run 'oct ARGS' (given after --) in this "
                   "process, FOR REAL, record what ran, and draw it against the "
                   "static graph. Run it in a throwaway project for commands "
                   "with side effects, such as git commit.")
@click.argument("trace_args", nargs=-1, type=click.UNPROCESSED)
@click.pass_context
def docs(
    ctx: click.Context,
    sphinx_mode: bool,
    doxygen_mode: bool,
    typedoc_mode: bool,
    all_mode: bool,
    clean_mode: bool,
    dry_run: bool,
    no_workspace: bool,
    init_doxygen: bool,
    force: bool,
    callgraph: str | None,
    depth: int | None,
    trace_mode: bool,
    trace_args: tuple[str, ...],
) -> None:
    """Validate or build Option C documentation."""
    project_root = get_project_root(ctx)
 
    if callgraph is None and (depth is not None or trace_mode):
        raise click.UsageError("--depth and --trace need --callgraph QUALNAME.")
    if trace_args and not trace_mode:
        raise click.UsageError(
            f"Unexpected arguments {' '.join(trace_args)!r}; arguments after "
            "-- are the oct command that --trace runs.")
    if callgraph is not None:
        from oct.docs.callgraph_command import run_docs_callgraph
        exit_code = run_docs_callgraph(
            project_root, callgraph, depth=depth,
            trace_args=list(trace_args) if trace_mode else None,
        )
        if exit_code != 0:
            raise SystemExit(exit_code)
        return
 
    if init_doxygen:
        from oct.docs.doxyfile_init import DoxyfileTemplateMissing, write_doxyfile
        from oct.docs.oct_docs import _load_project_info
        # PROJECT_NAME is the title Doxygen shows. Prefer the workspace
        # manifest's name for this subproject, because that is what the docs
        # hub card is labelled with; the pyproject name is the distribution
        # name and can differ (oc_chat's is 'oc_chat-workspace').
        name = _workspace_subproject_name(project_root)
        if name is None:
            name = _load_project_info(project_root).get("name") or project_root.name
        try:
            path, written = write_doxyfile(project_root, name, force=force)
        except DoxyfileTemplateMissing as exc:
            click.echo(f"Error: {exc}", err=True)
            raise SystemExit(1)
        if written:
            click.echo(f"Wrote {path} (PROJECT_NAME = {name!r}).")
            click.echo("This project now builds under 'oct docs --doxygen' "
                       "and the workspace fan-out, and gets a Doxygen card "
                       "on the docs hub, unless its workspace manifest entry "
                       "sets html_docs.doxygen to false.")
        else:
            click.echo(f"Kept existing {path}; pass --force to overwrite it.")
        return
 
    if clean_mode:
        from oct.docs.oct_docs import run_docs_clean
        exit_code = run_docs_clean(project_root, dry_run=dry_run, no_workspace=no_workspace)
        if exit_code != 0:
            raise SystemExit(exit_code)
        return
 
    if all_mode:
        from oct.docs.oct_docs import run_docs_all
        exit_code = run_docs_all(project_root, no_workspace=no_workspace)
        if exit_code != 0:
            raise SystemExit(exit_code)
        return
 
    if sphinx_mode:
        from oct.docs.oct_docs import run_docs_sphinx
        exit_code = run_docs_sphinx(project_root, no_workspace=no_workspace)
        if exit_code != 0:
            raise SystemExit(exit_code)
        return
 
    if doxygen_mode:
        from oct.docs.oct_docs import run_docs_doxygen
        exit_code = run_docs_doxygen(project_root, no_workspace=no_workspace)
        if exit_code != 0:
            raise SystemExit(exit_code)
        return
 
    if typedoc_mode:
        from oct.docs.typedoc import run_docs_typedoc
        exit_code = run_docs_typedoc(project_root, no_workspace=no_workspace)
        if exit_code != 0:
            raise SystemExit(exit_code)
        return
 
    _oc_diag = project_root / "oc_diagnostics"
    diag_dir = _oc_diag if _oc_diag.exists() else project_root / "diagnostics"
    # Plan 151 T6 (G7 deprecation-clearance): warn ONLY when a LEGACY
    # ``diagnostics/`` directory actually exists, not whenever
    # ``oc_diagnostics/`` is merely absent.
    if diag_dir.name == "diagnostics" and diag_dir.is_dir():
        click.echo(
            "Warning: 'diagnostics/' is deprecated and will be removed in v1.0.0. "
            "Rename to 'oc_diagnostics/'.",
            err=True,
        )
    required = [
        project_root / "docs" / "ARCHITECTURE.md",
        project_root / "tests" / "Tests_README.md",
        diag_dir / "debug_config.json",
    ]
 
    missing = [p for p in required if not p.exists()]
 
    if missing:
        click.echo("Missing required documentation files:")
        for m in missing:
            click.echo(f"  - {m}")
    else:
        click.echo("All required Option C documentation is present.")
 
# The traced command's arguments (after --) must reach it verbatim, so the
# Windows glob expansion does not touch 'oct docs' argv; docs takes no paths.
setattr(docs, NO_GLOB_EXPANSION_ATTR, True)
 
_PYTEST_INSTALL_HINT = (
    "pytest is not installed. Install it with one of:\n"
    "  pip install oct[test]   # installs OCT's test extras\n"
    "  pip install pytest      # install pytest directly"
)
 
 
def _pytest_missing(combined_output: str) -> bool:
    """Detect the 'No module named pytest' signature in combined output."""
    return "No module named pytest" in combined_output
 
 
def _run_pytest(project_root: Path, args: tuple, json_mode: bool = False) -> None:
    """Run pytest in *project_root* and exit on failure.
 
    When *json_mode* is True, captures pytest output, parses the summary
    line, and emits a machine-readable JSON object to stdout:
    ``{"tool": "test", "passed": N, "failed": N, "errors": N,
       "warnings": N, "output": "...", "exit_code": N}``
 
    OI-511: pytest is now declared in the ``[project.optional-dependencies].test``
    extra rather than as a runtime dependency; if ``python -m pytest`` reports
    it is not importable, emit the install hint above and exit 1.
    """
    import json as _json
    import re as _re
    import subprocess, sys
    if json_mode:
        try:
            result = subprocess.run(
                [sys.executable, "-m", "pytest", "--tb=short", "-q"] + list(args),
                cwd=project_root,
                capture_output=True,
                text=True,
                encoding="utf-8",
                errors="replace",
            )
        except FileNotFoundError:
            click.echo(_json.dumps({
                "tool": "test", "passed": 0, "failed": 0, "errors": 1,
                "warnings": 0, "output": _PYTEST_INSTALL_HINT,
                "exit_code": 1,
            }))
            raise SystemExit(1)
        combined = (result.stdout or "") + (result.stderr or "")
        if result.returncode != 0 and _pytest_missing(combined):
            click.echo(_json.dumps({
                "tool": "test", "passed": 0, "failed": 0, "errors": 1,
                "warnings": 0, "output": _PYTEST_INSTALL_HINT,
                "exit_code": 1,
            }))
            raise SystemExit(1)
        # Parse the pytest summary line: "N passed", "N failed", "N error"
        passed = failed = errors = warnings = 0
        for m in _re.finditer(
            r"(\d+)\s+(passed|failed|error(?:s)?|warning(?:s)?)",
            combined,
        ):
            n, kind = int(m.group(1)), m.group(2)
            if kind == "passed":
                passed = n
            elif kind == "failed":
                failed = n
            elif kind.startswith("error"):
                errors = n
            elif kind.startswith("warning"):
                warnings = n
        click.echo(_json.dumps({
            "tool": "test",
            "passed": passed,
            "failed": failed,
            "errors": errors,
            "warnings": warnings,
            "output": combined,
            "exit_code": result.returncode,
        }))
        if result.returncode != 0:
            raise SystemExit(result.returncode)
        return
    try:
        result = subprocess.run(
            [sys.executable, "-m", "pytest"] + list(args),
            cwd=project_root,
            capture_output=True,
            text=True,
            encoding="utf-8",
            errors="replace",
        )
    except FileNotFoundError:
        raise click.ClickException(_PYTEST_INSTALL_HINT)
    combined = (result.stdout or "") + (result.stderr or "")
    if result.returncode != 0 and _pytest_missing(combined):
        raise click.ClickException(_PYTEST_INSTALL_HINT)
    # Replay captured output so users still see pytest's normal reporting.
    if result.stdout:
        click.echo(result.stdout, nl=False)
    if result.stderr:
        click.echo(result.stderr, nl=False, err=True)
    if result.returncode == 0:
        click.echo("All tests passed.")
    else:
        click.echo("Some tests failed.")
        raise SystemExit(result.returncode)
 
 
def _map_source_to_test(source: Path, project_root: Path) -> Path | None:
    """Heuristic: map a source .py file to its likely test file.
 
    Tries several common patterns and returns the first existing match,
    or ``None`` if no test file is found.
    """
    try:
        rel = source.relative_to(project_root)
    except ValueError:
        return None
 
    parts = list(rel.parts)
    stem = source.stem
 
    # Pattern 1: oct/<pkg>/foo.py → tests/tests_<pkg>/test_foo.py
    if len(parts) >= 3 and parts[0] == "oct":
        pkg = parts[1]
        test_path = project_root / "tests" / f"tests_{pkg}" / f"test_{stem}.py"
        if test_path.is_file():
            return test_path
 
    # Pattern 2: src/foo.py → tests/test_foo.py
    if len(parts) >= 2 and parts[0] == "src":
        test_path = project_root / "tests" / f"test_{stem}.py"
        if test_path.is_file():
            return test_path
 
    # Pattern 3: <any>/foo.py → tests/test_foo.py
    test_path = project_root / "tests" / f"test_{stem}.py"
    if test_path.is_file():
        return test_path
 
    return None
 
 
def _cache_args(cached: bool, cache_clear: bool) -> tuple[str, ...]:
    """Pytest arguments that drive the Plan 249 content-hashed cache.
 
    ``-p oct.testing.cache`` loads the plugin for ANY project, so the
    flags work whether or not the project's root conftest wires the
    seams itself; the plugin registers its options at most once.
    """
    if not (cached or cache_clear):
        return ()
    from oct.testing.cache import CACHE_CLEAR_OPTION, CACHE_OPTION
 
    flags = ["-p", "oct.testing.cache"]
    if cached:
        flags.append(CACHE_OPTION)
    if cache_clear:
        flags.append(CACHE_CLEAR_OPTION)
    return tuple(flags)
 
 
def _record_cached_run(ctx: click.Context, project_root: Path) -> None:
    """Put the cached run's file count in the timing ledger (P5).
 
    ``files`` is the number of files that actually RAN, so the saving
    a cache produced is visible in ``oct health --timing`` beside the
    uncached runs of the same stage.
    """
    from oct.testing.cache import read_last_run
 
    sample = ctx.meta.get(TIMING_SAMPLE_KEY)
    if sample is None:
        return
    sample.scope = "cached"
    last_run = read_last_run(project_root)
    ran = last_run.get("ran")
    if isinstance(ran, int) and ran >= 0:
        sample.files = ran
 
 
@cli.command()
@click.option("--json", "json_mode", is_flag=True,
              help="Emit machine-readable JSON summary to stdout.")
@click.option("--changed", is_flag=True,
              help="Run tests for git-modified files only.")
@click.option("--cached", is_flag=True,
              help="Skip test files unchanged since their last green run.")
@click.option("--oct-cache-clear", "cache_clear", is_flag=True,
              help="Empty the Option C test cache before running.")
@click.argument("args", nargs=-1)
@click.pass_context
def test(
    ctx: click.Context,
    json_mode: bool,
    changed: bool,
    cached: bool,
    cache_clear: bool,
    args: tuple[str, ...],
) -> None:
    """Run the project's test suite."""
    project_root = get_project_root(ctx)
    args = _cache_args(cached, cache_clear) + args
    if cached:
        ctx.call_on_close(
            lambda: _record_cached_run(ctx, project_root),
        )
 
    _PYTEST_CFG_FILES = ("pytest.ini", "pyproject.toml", "setup.cfg", "tox.ini")
 
    # --changed: discover changed source files and map to tests.
    if changed:
        try:
            from oct.core.git import git_changed_files
            changed_py = git_changed_files(project_root, extensions={".py"})
            test_files: list[Path] = []
            for src in changed_py:
                mapped = _map_source_to_test(src, project_root)
                if mapped and mapped not in test_files:
                    test_files.append(mapped)
            if test_files:
                rel_paths = [str(t.relative_to(project_root)) for t in test_files]
                if not json_mode:
                    click.echo(f"Running {len(test_files)} test file(s) for changed sources.")
                _run_pytest(project_root, tuple(rel_paths) + args, json_mode=json_mode)
                return
            else:
                click.echo(
                    "No test files found for changed sources. Running all tests.",
                    err=True,
                )
        except Exception as exc:
            click.echo(
                f"Warning: --changed failed ({exc}). Running all tests.",
                err=True,
            )
 
    has_tests_dir = (project_root / "tests").is_dir()
    has_pytest_cfg = any((project_root / f).is_file() for f in _PYTEST_CFG_FILES)
 
    if has_tests_dir or has_pytest_cfg:
        # Standard single-project test run.
        _run_pytest(project_root, args, json_mode=json_mode)
        return
 
    # Meta-project: discover sub-projects that have tests/ AND a pytest config.
    sub_projects = []
    for child in sorted(project_root.iterdir()):
        if not child.is_dir() or child.name.startswith("."):
            continue
        if (child / "tests").is_dir() and any(
            (child / f).is_file() for f in _PYTEST_CFG_FILES
        ):
            sub_projects.append(child)
 
    if not sub_projects:
        raise click.ClickException(
            f"No tests/ directory or pytest configuration found in {project_root}, "
            f"and no testable sub-projects detected. "
            f"Run 'oct test' from a project that has a test suite."
        )
 
    import subprocess, sys
 
    click.echo(f"No test suite at root -- found {len(sub_projects)} "
               f"sub-project(s) with tests:")
    for sp in sub_projects:
        click.echo(f"  - {sp.name}/")
    click.echo()
 
    failed = []
    for sp in sub_projects:
        click.echo(f"{'=' * 60}")
        click.echo(f"Running tests in {sp.name}/")
        click.echo(f"{'=' * 60}")
        try:
            result = subprocess.run(
                [sys.executable, "-m", "pytest"] + list(args),
                cwd=sp,
            )
            if result.returncode != 0:
                failed.append(sp.name)
        except FileNotFoundError:
            raise click.ClickException(
                "pytest is not installed. Install it with: pip install pytest"
            )
        click.echo()
 
    if failed:
        click.echo(f"Tests failed in: {', '.join(failed)}")
        raise SystemExit(1)
    else:
        click.echo("All sub-project tests passed.")
 
@cli.command(name="export-source")
@click.option("--verbose", is_flag=True, help="Show per-file statistics.")
@click.option("--clean", is_flag=True, help="[DEPRECATED: use 'oct clean'] Remove _source_code-* dirs.")
@click.option("--single-dir", is_flag=True, help="Write all output into one root-level directory.")
@click.option("--allow-outside-project", is_flag=True,
              help="Allow PATH outside the auto-detected project root (OI-405).")
@click.option("--warn-secrets/--no-warn-secrets", default=True,
              help="Scan file contents for potential secrets (OI-416).")
@click.option("--block-secrets", is_flag=True,
              help="Skip files with potential secrets (implies --warn-secrets, OI-416).")
@click.option("--diff", "diff_ref", default=None,
              help="Export only files changed since REF (git ref).")
@click.argument("path", required=False)
@click.pass_context
def export_source(
    ctx: click.Context,
    verbose: bool,
    clean: bool,
    single_dir: bool,
    allow_outside_project: bool,
    warn_secrets: bool,
    block_secrets: bool,
    diff_ref: str | None,
    path: str | None,
) -> None:
    """Export consolidated source-code files for inspection."""
    from oct.core.project_root import validate_path_containment
    from oct.tools.source_exporter import run_exporter
 
    # Merge global and command-level allow_outside_project flags
    global_allow = ctx.obj.get("allow_outside_project", False) if ctx.obj else False
    allow_outside_project = allow_outside_project or global_allow
    
    # Update context for get_project_root to use
    if ctx.obj:
        ctx.obj["allow_outside_project"] = allow_outside_project
 
    if path:
        if allow_outside_project:
            project_root = Path(path).resolve()
        else:
            auto_root = get_project_root(ctx)
            project_root = validate_path_containment(
                Path(path), auto_root, allow_outside=False
            )
    else:
        project_root = get_project_root(ctx)
 
    args = []
    if verbose:
        args.append("--verbose")
    if clean:
        click.echo(
            "Warning: 'export-source --clean' is deprecated. "
            "Use 'oct clean' (with optional --dry-run) instead.",
            err=True,
        )
        args.append("--clean")
    if single_dir:
        args.append("--single-dir")
    if warn_secrets:
        args.append("--warn-secrets")
    if block_secrets:
        args.append("--block-secrets")
    if diff_ref:
        args.append(f"--diff={diff_ref}")
 
    try:
        run_exporter(project_root, args)
    except Exception as e:
        click.echo(f"Error: export-source failed unexpectedly: {e}", err=True)
        raise SystemExit(1)
 
 
@cli.command(name="export-skeleton")
@click.option("--json", "json_mode", is_flag=True,
              help="Emit machine-readable JSON summary to stdout.")
@click.option("--verbose", is_flag=True, help="Show per-file statistics.")
@click.option("--single-dir", is_flag=True, help="Write all output into one root-level directory.")
@click.option("--no-diagnostics", is_flag=True, help="Omit Diagnostics section from docstrings.")
@click.option("--clean", is_flag=True, help="Remove _skeleton_code-* dirs.")
@click.option("--allow-outside-project", is_flag=True,
              help="Allow PATH outside the auto-detected project root (OI-405).")
@click.argument("path", required=False)
@click.pass_context
def export_skeleton(
    ctx: click.Context,
    json_mode: bool,
    verbose: bool,
    single_dir: bool,
    no_diagnostics: bool,
    clean: bool,
    allow_outside_project: bool,
    path: str | None,
) -> None:
    """Export structural skeletons of source files for AI inspection."""
    from oct.core.project_root import validate_path_containment
    from oct.tools.skeleton_exporter import run_skeleton_exporter
 
    if path:
        if allow_outside_project:
            project_root = Path(path).resolve()
        else:
            auto_root = get_project_root(ctx)
            project_root = validate_path_containment(
                Path(path), auto_root, allow_outside=False
            )
    else:
        project_root = get_project_root(ctx)
 
    args = []
    if verbose:
        args.append("--verbose")
    if single_dir:
        args.append("--single-dir")
    if no_diagnostics:
        args.append("--no-diagnostics")
    if clean:
        args.append("--clean")
 
    try:
        run_skeleton_exporter(project_root, args, json_mode=json_mode)
    except Exception as e:
        click.echo(f"Error: export-skeleton failed unexpectedly: {e}", err=True)
        raise SystemExit(1)
 
 
@cli.command()
@click.argument("path", required=False)
@click.option("--dry-run", is_flag=True, help="Show what would be deleted without deleting anything")
@click.option("--allow-outside-project", is_flag=True,
              help="Allow PATH outside the auto-detected project root (OI-405).")
@click.pass_context
def clean(
    ctx: click.Context,
    path: str | None,
    dry_run: bool,
    allow_outside_project: bool,
) -> None:
    """Remove _source_code-*, _skeleton_code-* export dirs, __pycache__ dirs
    and packaging build/ and dist/ trees.
 
    A build/ or dist/ directory is only removed when it sits beside a
    pyproject.toml / setup.py / setup.cfg AND contains nothing but
    packaging output. One that fails either test is kept and the reason
    printed, because both are ordinary words and a project is entitled to
    a source directory called either.
    """
    from oct.core.project_root import validate_path_containment
    from oct.tools.build_artifacts import clean_build_dirs
    from oct.tools.source_exporter import clean_source_dirs, clean_pycache_dirs
    from oct.tools.skeleton_exporter import clean_skeleton_dirs
 
    if path:
        if allow_outside_project:
            target = Path(path).resolve()
        else:
            try:
                auto_root = get_project_root(ctx)
            except click.ClickException:
                auto_root = Path.cwd()
            target = validate_path_containment(
                Path(path), auto_root, allow_outside=False
            )
    else:
        target = Path.cwd()
    failed_total = 0
    for cleaner in (clean_source_dirs, clean_skeleton_dirs, clean_pycache_dirs,
                    clean_build_dirs):
        _removed, failed = cleaner(target, dry_run=dry_run)
        failed_total += len(failed)
    if failed_total:
        click.echo(
            f"oct clean: {failed_total} directories could not be removed; "
            "see the list above.",
            err=True,
        )
        ctx.exit(1)
 
 
@cli.command()
@click.option("--json", "json_mode", is_flag=True, help="Machine-readable JSON output")
@click.option("--verbose", is_flag=True, help="Detailed per-file breakdown")
@click.option("--tests", "run_tests", is_flag=True, help="Run the project test suite")
@click.option(
    "--timeout",
    "test_timeout",
    type=click.IntRange(min=1),
    default=None,
    help="Test execution timeout in seconds (default: 300, or health.test_timeout in .octrc.json).",
)
@click.option("--timing", is_flag=True, help="Show only timing statistics")
@click.option("--timing-last", type=click.IntRange(min=1), default=20, help="Recent records per stage")
@click.option("--write-baseline", is_flag=True, help="Write this host's timing baseline")
@click.option("--force-host", is_flag=True, help="Allow adding a different baseline host")
@click.option("--session", type=click.Path(exists=True, dir_okay=False, path_type=Path), help="Session events JSONL")
@click.pass_context
def health(
    ctx: click.Context,
    json_mode: bool,
    verbose: bool,
    run_tests: bool,
    test_timeout: int | None,
    timing: bool,
    timing_last: int,
    write_baseline: bool,
    force_host: bool,
    session: Path | None,
) -> None:
    """Display project compliance dashboard."""
    project_root = get_project_root(ctx)
    run_health(
        project_root,
        json_mode=json_mode,
        verbose=verbose,
        run_tests=run_tests,
        test_timeout=test_timeout,
        log_output=ctx.obj.get("log_output", False),
        **({"timing": timing, "timing_last": timing_last,
            "write_baseline": write_baseline, "force_host": force_host,
            "session": session} if timing or write_baseline or session or force_host else {}),
    )
 
 
@cli.command(context_settings=dict(ignore_unknown_options=True))
@click.argument("args", nargs=-1, type=click.UNPROCESSED)
@click.pass_context
def deps(ctx: click.Context, args: tuple[str, ...]) -> None:
    """Analyse inter-module dependencies."""
    project_root = get_project_root(ctx)
    exit_code = run_deps(project_root, list(args))
    if exit_code != 0:
        raise SystemExit(exit_code)
 
 
@cli.command(name="install-hooks")
@click.option("--force", is_flag=True, help="Overwrite existing .pre-commit-config.yaml")
@click.pass_context
def install_hooks_cmd(ctx: click.Context, force: bool) -> None:
    """[DEPRECATED] Use 'oct git hooks install' instead."""
    click.echo(
        "Notice: 'oct install-hooks' is deprecated. "
        "Use 'oct git hooks install' instead.",
        err=True,
    )
    project_root = get_project_root(ctx)
    # Delegate to the enhanced hooks installer via the new module.
    from oct.git.oct_git import _ENHANCED_HOOKS_TEMPLATE
    config_path = project_root / ".pre-commit-config.yaml"
    if config_path.exists() and not force:
        click.echo(f"Error: {config_path} already exists. Use --force to overwrite.")
        raise SystemExit(1)
    config_path.write_text(_ENHANCED_HOOKS_TEMPLATE, encoding="utf-8")
    click.echo(f"Created {config_path}")
    click.echo("Run 'pre-commit install' to activate the hooks.")
 
 
@cli.command(context_settings=dict(ignore_unknown_options=True))
@click.option("--json", "json_mode", is_flag=True,
              help="Emit machine-readable JSON summary to stdout.")
@click.argument("args", nargs=-1, type=click.UNPROCESSED)
@click.pass_context
def typecheck(
    ctx: click.Context,
    json_mode: bool,
    args: tuple[str, ...],
) -> None:
    """Run type checking (pyright or mypy)."""
    project_root = get_project_root(ctx)
    exit_code = run_typecheck(project_root, list(args), json_mode=json_mode)
    if exit_code != 0:
        raise SystemExit(exit_code)
 
 
# -- git command group (Phase 4B) ------------------------------------
from oct.git import git_group as _git_group
cli.add_command(_git_group, name="git")
 
# -- migrate command group (FS-539) ----------------------------------
from oct.migrate import migrate_group as _migrate_group
cli.add_command(_migrate_group, name="migrate")
 
# -- audit command (FS-539 / FS-501 stub) ----------------------------
from oct.audit import audit_group as _audit_cmd
cli.add_command(_audit_cmd, name="audit")
 
# -- install command (Phase 4-followup B1.4) -------------------------
from oct.install.oct_install import oct_install_cmd as _oct_install_cmd
from oct.core.diagnostics import _dbg
cli.add_command(_oct_install_cmd, name="install")
 
 
@cli.group()
@click.pass_context
def diag(ctx: click.Context) -> None:
    """oc_diagnostics configuration tools."""
    pass
 
 
@diag.command(name="validate-config")
@click.option(
    "--strict",
    is_flag=True,
    default=False,
    help="OI-534: escalate WARNING to failure; exit 2 on any ERROR or WARNING.",
)
@click.pass_context
def diag_validate_config(ctx: click.Context, strict: bool) -> None:
    """Validate debug_config.json against the expected schema."""
    project_root = get_project_root(ctx)
    issues = validate_config(project_root)
    if not issues:
        click.echo("debug_config.json is valid.")
        return
    for issue in issues:
        click.echo(issue)
    has_error = any(i.startswith("ERROR") for i in issues)
    has_warning = any(i.startswith("WARNING") for i in issues)
    # OI-534 / FS-513: --strict promotes WARNING to failure and uses
    # exit code 2 so CI can distinguish a config audit failure from the
    # generic exit 1 used by the non-strict path.
    if strict and (has_error or has_warning):
        raise SystemExit(2)
    if has_error:
        raise SystemExit(1)
 
 
@diag.command(name="list-domains")
@click.pass_context
def diag_list_domains(ctx: click.Context) -> None:
    """List configured domains with their levels and colors."""
    project_root = get_project_root(ctx)
    try:
        domains = list_domains(project_root)
    except FileNotFoundError as e:
        raise click.ClickException(str(e))
 
    if not domains:
        click.echo("No domains configured.")
        return
 
    click.echo(f"{'Domain':<24} {'Level':<8} {'Color'}")
    click.echo("-" * 44)
    for d in domains:
        click.echo(f"{d['name']:<24} {d['level']:<8} {d['color']}")
 
 
@diag.command(name="set-level")
@click.argument("domain")
@click.argument("level", type=click.IntRange(0, 9))
@click.option(
    "--dry-run",
    is_flag=True,
    default=False,
    help="Preview the edit without writing the config or its .bk backup.",
)
@click.pass_context
def diag_set_level(
    ctx: click.Context,
    domain: str,
    level: int,
    dry_run: bool,
) -> None:
    """Set a domain's debug level (0-9).
 
    OI-528: the write is always preceded by a ``<path>.bk`` backup so
    ``oct diag restore`` can undo a bad edit. ``--dry-run`` prints the
    would-be post-edit config to stdout and skips both writes.
    """
    project_root = get_project_root(ctx)
    try:
        new_config = set_level(project_root, domain, level, dry_run=dry_run)
    except (FileNotFoundError, ValueError, KeyError) as e:
        raise click.ClickException(str(e))
    if dry_run:
        click.echo(json.dumps(new_config, indent=2))
        click.echo(
            f"[DRY RUN] Would set {domain} level to {level} (no write).",
            err=True,
        )
        return
    click.echo(f"Set {domain} level to {level}.")
 
 
@diag.command(name="restore")
@click.pass_context
def diag_restore(ctx: click.Context) -> None:
    """OI-528: restore debug_config.json from its .bk backup."""
    project_root = get_project_root(ctx)
    try:
        restored = restore_config(project_root)
    except FileNotFoundError as e:
        raise click.ClickException(str(e))
    click.echo(f"Restored {restored} from backup.")
 
 
@diag.command(name="migrate-config")
@click.argument(
    "config_path",
    required=False,
    type=click.Path(dir_okay=False, path_type=Path),
)
@click.option(
    "--dry-run",
    is_flag=True,
    default=False,
    help="Show the migrated config on stdout without writing to disk.",
)
@click.pass_context
def diag_migrate_config(
    ctx: click.Context,
    config_path: Path | None,
    dry_run: bool,
) -> None:
    """OI-508 / FS-515: upgrade a legacy v1 debug_config.json to v2.0.
 
    When PATH is omitted, migrates the project's own debug_config.json.
    Writes ``<path>.bk`` before overwriting; idempotent - running twice
    over an already-v2 file is a no-op.
    """
    from oct.diag.oct_diag import _find_config
    if config_path is None:
        project_root = get_project_root(ctx)
        config_path = _find_config(project_root)
    try:
        new_config = migrate_config(config_path, dry_run=dry_run)
    except (FileNotFoundError, ValueError) as e:
        raise click.ClickException(str(e))
    if dry_run:
        click.echo(json.dumps(new_config, indent=2))
        click.echo(f"[DRY RUN] Would write v2 schema to {config_path}", err=True)
        return
    backup_path = config_path.with_suffix(config_path.suffix + ".bk")
    click.echo(f"Migrated {config_path} -> v{new_config.get('_schema_version')} "
               f"(backup: {backup_path.name})")
 
 
@cli.command(name="install-mcp")
@click.option(
    "--host",
    type=click.Choice(["claude-code", "cursor", "vscode", "auto"], case_sensitive=False),
    default="auto",
    help="Target AI host (default: auto-detect).",
)
@click.option(
    "--dry-run/--no-dry-run",
    default=True,
    help="Preview without writing (default: --dry-run).",
)
@click.pass_context
def install_mcp(ctx: click.Context, host: str, dry_run: bool) -> None:
    """Install oct-mcp into an AI host's MCP config (Claude Code, Cursor, VS Code)."""
    from oct.tools.install_mcp import run_install_mcp
    project_root = get_project_root(ctx)
    exit_code = run_install_mcp(host=host, project_root=project_root, dry_run=dry_run)
    if exit_code != 0:
        raise SystemExit(exit_code)
 
 
if __name__ == "__main__":
    cli()