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)
"""
 
import json
import os
import click
from pathlib import Path
 
from oct import __version__
from oct.core.project_root import find_project_root, get_project_root
from oct.linter.oct_lint import run_linter
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"),
    ],
    "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"),
        ("--all", "Generate both Sphinx and Doxygen documentation"),
        ("--clean", "Remove generated documentation artifacts"),
        ("--dry-run", "Preview what --clean would remove"),
    ],
    "test": [
        ("--json", "Emit machine-readable JSON summary to stdout"),
        ("--changed", "Run tests for git-modified files only"),
    ],
    "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": [
        ("--json", "Machine-readable JSON output"),
        ("--verbose", "Detailed per-file breakdown"),
        ("--timeout N", "Per-check timeout in seconds (default: 300)"),
    ],
    "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-4)"),
        ("  --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"),
    ],
}
 
 
class OctGroup(click.Group):
    """Custom group that shows per-command flags in the main --help output."""
 
    def format_help(self, ctx, formatter):
        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, root_dir, allow_outside_project, strict_config, log_output):
    """OCT — Option C Tools"""
    try:
        from oc_diagnostics import init, set_global_setting
        init(intercept_streams=False)
        set_global_setting("output_mode", "file")
    except ImportError:
        pass
    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.command(context_settings=dict(ignore_unknown_options=True))
@click.argument("args", nargs=-1, type=click.UNPROCESSED)
@click.pass_context
def lint(ctx, args):
    """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, args):
    """Auto-fix Option C compliance violations in Python files."""
    project_root = get_project_root(ctx)
    run_formatter(project_root, list(args))
 
 
@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, path, force, test, dry_run, verbose):
    """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, dry_run, no_venv, with_claude):
    """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}")
 
 
@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("--all", "all_mode", is_flag=True,
              help="Generate both Sphinx and Doxygen documentation")
@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.pass_context
def docs(ctx, sphinx_mode, doxygen_mode, all_mode, clean_mode, dry_run):
    """Validate or build Option C documentation."""
    project_root = get_project_root(ctx)
 
    if clean_mode:
        from oct.docs.oct_docs import run_docs_clean
        exit_code = run_docs_clean(project_root, dry_run=dry_run)
        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)
        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)
        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)
        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"
    if diag_dir.name == "diagnostics":
        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.")
 
_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
 
 
@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.argument("args", nargs=-1)
@click.pass_context
def test(ctx, json_mode, changed, args):
    """Run the project's test suite."""
    project_root = get_project_root(ctx)
 
    _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, verbose, clean, single_dir, allow_outside_project,
                  warn_secrets, block_secrets, diff_ref, path):
    """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, json_mode, verbose, single_dir, no_diagnostics, clean,
                    allow_outside_project, path):
    """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, path, dry_run, allow_outside_project):
    """Remove _source_code-*, _skeleton_code-* export dirs and __pycache__ dirs."""
    from oct.core.project_root import validate_path_containment
    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()
    clean_source_dirs(target, dry_run=dry_run)
    clean_skeleton_dirs(target, dry_run=dry_run)
    clean_pycache_dirs(target, dry_run=dry_run)
 
 
@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(
    "--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.pass_context
def health(ctx, json_mode, verbose, test_timeout):
    """Display project compliance dashboard."""
    project_root = get_project_root(ctx)
    run_health(
        project_root,
        json_mode=json_mode,
        verbose=verbose,
        test_timeout=test_timeout,
        log_output=ctx.obj.get("log_output", False),
    )
 
 
@cli.command(context_settings=dict(ignore_unknown_options=True))
@click.argument("args", nargs=-1, type=click.UNPROCESSED)
@click.pass_context
def deps(ctx, args):
    """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, force):
    """[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, json_mode, args):
    """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
cli.add_command(_oct_install_cmd, name="install")
 
 
@cli.group()
@click.pass_context
def diag(ctx):
    """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, strict: bool):
    """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):
    """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, domain, level, dry_run: bool):
    """Set a domain's debug level (0-4).
 
    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):
    """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, config_path: Path | None, dry_run: bool):
    """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, host, dry_run):
    """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()