ai-dev-cli-tools 0.5.0a1__py3-none-any.whl

ai_dev_tools/runners/finish.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from ai_dev_tools.config import load_settings
+from ai_dev_tools.git.inspect import inspect_git
+from ai_dev_tools.models.report import Report
+from ai_dev_tools.reporters.writer import write_json, write_markdown
+from ai_dev_tools.runners.check import run_check
+from ai_dev_tools.security.secrets import scan_paths_for_secrets
+
+UNSAFE_REPO_STATES = {"CONFLICT", "DETACHED_HEAD", "DIVERGED"}
+
+
+def run_finish(project_root: Path) -> Report:
+    settings = load_settings(project_root)
+    git_report = inspect_git(settings.project_root, detailed=True)
+    changed = [str(path) for path in git_report.summary.get("changed_files", [])]
+    check_report = run_check(settings.project_root, mode="changed")
+    findings = scan_paths_for_secrets(
+        settings.project_root, [settings.project_root / path for path in changed]
+    )
+    blocking_reasons = _blocking_reasons(git_report, check_report, findings, changed)
+    ready = not blocking_reasons
+    report = Report(
+        command="finish",
+        project_root=settings.project_root,
+        status="success" if ready else "failed",
+    )
+    report.summary = {
+        "ready_to_commit": ready,
+        "blocking_reasons": blocking_reasons,
+        "blocking_reason_codes": [_blocking_reason_code(reason) for reason in blocking_reasons],
+        "changed": _classify_changed(changed),
+        "validation": {
+            "checks": check_report.status,
+            "secrets": "none" if not findings else f"{len(findings)} finding(s)",
+        },
+        "secret_findings": [finding.masked_dict() for finding in findings],
+        "reports": {
+            "git": [artifact.path for artifact in git_report.artifacts],
+            "check": [artifact.path for artifact in check_report.artifacts],
+        },
+    }
+    report.finish()
+    write_markdown(report, settings.reports_directory / "finish-latest.md")
+    write_json(report, settings.reports_directory / "finish-latest.json")
+    return report
+
+
+def _blocking_reasons(
+    git_report: Report,
+    check_report: Report,
+    findings: Sequence[object],
+    changed: list[str],
+) -> list[str]:
+    reasons: list[str] = []
+    states = set(str(item) for item in git_report.summary.get("states", []))
+    conflicts = git_report.summary.get("conflicted_files", [])
+    if not changed:
+        reasons.append("no_changes")
+    if conflicts:
+        reasons.append("repository has merge conflicts")
+    for state in sorted(states & UNSAFE_REPO_STATES):
+        if state != "CONFLICT":
+            reasons.append(f"repository state is {state}")
+    if check_report.status == "failed":
+        checks_failed = check_report.summary.get("checks_failed")
+        if isinstance(checks_failed, int) and checks_failed:
+            reasons.append(f"{checks_failed} check(s) failed")
+        else:
+            reasons.append("required checks failed")
+    if findings:
+        reasons.append(f"{len(findings)} potential secret(s) detected")
+    return reasons
+
+
+def _blocking_reason_code(reason: str) -> str:
+    if reason == "no_changes":
+        return "NO_CHANGES"
+    if "merge conflicts" in reason:
+        return "MERGE_CONFLICTS"
+    if reason.startswith("repository state is "):
+        return f"UNSAFE_REPOSITORY_{reason.rsplit(' ', 1)[-1]}"
+    if "check" in reason and "failed" in reason:
+        return "CHECKS_FAILED"
+    if "secret" in reason:
+        return "POTENTIAL_SECRETS"
+    return "FINISH_BLOCKED"
+
+
+def _classify_changed(paths: list[str]) -> dict[str, int]:
+    result = {"production_files": 0, "test_files": 0, "documentation_files": 0, "other_files": 0}
+    for path in paths:
+        lower = path.lower()
+        if lower.endswith((".md", ".rst", ".txt")) or lower.startswith("docs/"):
+            result["documentation_files"] += 1
+        elif "test" in lower:
+            result["test_files"] += 1
+        elif lower.endswith((".py", ".js", ".ts", ".java", ".rs", ".php")):
+            result["production_files"] += 1
+        else:
+            result["other_files"] += 1
+    return result

ai_dev_tools/runners/focused.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import sys
+
+from ai_dev_tools.runners.check_models import CheckTask
+
+
+def focused_rerun(task: CheckTask, parsed: dict[str, object]) -> list[str] | None:
+    parser = str(parsed.get("parser") or parsed.get("tool") or "").lower()
+    path = _first_project_file(parsed)
+    if not path:
+        return None
+    if "pytest" in parser or path.endswith(".py"):
+        return [sys.executable, "-m", "pytest", path]
+    if any(name in parser for name in ("jest", "vitest")) or path.endswith(
+        (".js", ".jsx", ".ts", ".tsx")
+    ):
+        return ["npm", "test", "--", path]
+    if "phpunit" in parser or path.endswith(".php"):
+        return ["vendor/bin/phpunit", path]
+    if "maven" in parser and task.workspace:
+        return ["mvn", "-pl", task.workspace, "test"]
+    if "gradle" in parser and task.workspace:
+        return ["gradle", f":{task.workspace.replace('/', ':')}:test"]
+    return None
+
+
+def _first_project_file(parsed: dict[str, object]) -> str | None:
+    frames = parsed.get("project_frames")
+    if not isinstance(frames, list):
+        return None
+    for frame in frames:
+        if isinstance(frame, dict) and isinstance(frame.get("file"), str):
+            return str(frame["file"])
+        if isinstance(frame, str) and frame:
+            return frame.split(":", 1)[0]
+    return None

ai_dev_tools/runners/index.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ai_dev_tools.cache.repository import (
+    INDEX_RELATIVE_PATH,
+    read_repository_index,
+    update_repository_index,
+)
+from ai_dev_tools.models.report import Artifact, Report
+
+
+def run_index(project_root: Path, action: str) -> Report:
+    root = project_root.resolve()
+    report = Report(command=f"index {action}", project_root=root)
+    if action == "status":
+        index = read_repository_index(root)
+        if not index:
+            report.status = "partial"
+            report.summary = {
+                "indexed": False,
+                "message": "Repository index does not exist. Run `ai-dev index update`.",
+                "reason_code": "INDEX_MISSING",
+            }
+            return report
+    else:
+        index = update_repository_index(root, rebuild=action == "rebuild")
+
+    index_path = root / INDEX_RELATIVE_PATH
+    report.summary = {
+        "indexed": True,
+        "schema_version": index.get("schema_version"),
+        "generated_at": index.get("generated_at"),
+        **_summary(index.get("summary")),
+    }
+    report.artifacts.append(Artifact(str(index_path), "repository-index", "Repository file index"))
+    return report
+
+
+def _summary(value: object) -> dict[str, object]:
+    if not isinstance(value, dict):
+        return {}
+    allowed = {"files", "hashed", "reused", "removed"}
+    return {str(key): item for key, item in value.items() if key in allowed}

ai_dev_tools/runtime/__init__.py

@@ -0,0 +1,3 @@
+from ai_dev_tools.runtime.runner import RunOptions, run_application, stop_application
+
+__all__ = ["RunOptions", "run_application", "stop_application"]

ai_dev_tools/runtime/runner.py

@@ -0,0 +1,380 @@
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import socket
+import subprocess
+import sys
+import time
+from contextlib import suppress
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from urllib import error as urllib_error
+from urllib import request as urllib_request
+
+from ai_dev_tools.config import Settings, load_settings
+from ai_dev_tools.models.report import Artifact, Issue, Report
+from ai_dev_tools.reporters.writer import write_json, write_markdown
+from ai_dev_tools.security.secrets import mask_text
+from ai_dev_tools.utils.subprocess import run_command, split_command
+
+
+@dataclass(frozen=True, slots=True)
+class RunOptions:
+    explain: bool = False
+    dry_run: bool = False
+    foreground: bool = False
+    timeout_seconds: int = 300
+    readiness_http: str | None = None
+    readiness_tcp: str | None = None
+    startup_timeout_seconds: int = 10
+    startup_log_lines: int = 50
+
+
+@dataclass(frozen=True, slots=True)
+class RunPlan:
+    command: list[str]
+    source: str
+    cwd: str = ""
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def run_application(project_root: Path, options: RunOptions) -> Report:
+    settings = load_settings(project_root)
+    report = Report(command="run", project_root=settings.project_root)
+    plan = resolve_run_plan(settings)
+    paths = _runtime_paths(settings.project_root)
+    current = _read_json(paths["metadata"])
+    if current.get("status") in {"running", "stopping"} and _heartbeat_is_fresh(current):
+        report.status = "blocked"
+        report.issues.append(
+            Issue("error", "A managed project process is already running.", code="ALREADY_RUNNING")
+        )
+    elif plan is None:
+        report.status = "blocked"
+        report.issues.append(
+            Issue(
+                "error",
+                "No safe run command detected. Configure [commands].run.",
+                code="NO_RUN_COMMAND",
+            )
+        )
+    elif options.explain or options.dry_run:
+        report.summary = {
+            "plan": plan.to_dict(),
+            "explain": options.explain,
+            "dry_run": options.dry_run,
+            "modifications": "NONE",
+            "readiness": _readiness_config(options),
+        }
+    elif options.foreground:
+        result = run_command(
+            plan.command,
+            settings.project_root / plan.cwd,
+            timeout_seconds=options.timeout_seconds,
+        )
+        report.status = "success" if result.exit_code == 0 else "failed"
+        report.exit_code = result.exit_code
+        paths["log"].parent.mkdir(parents=True, exist_ok=True)
+        paths["log"].write_text(mask_text(result.combined_output) + "\n", encoding="utf-8")
+        report.artifacts.append(Artifact(str(paths["log"]), "log", "Application output"))
+        report.summary = {
+            "plan": plan.to_dict(),
+            "mode": "foreground",
+            "exit_code": result.exit_code,
+            "timed_out": result.timed_out,
+        }
+    else:
+        token = secrets.token_urlsafe(24)
+        _remove_stale_request(paths["request"])
+        supervisor_command = [
+            sys.executable,
+            str(Path(__file__).with_name("supervisor.py")),
+            "--metadata",
+            str(paths["metadata"]),
+            "--request",
+            str(paths["request"]),
+            "--token",
+            token,
+            "--cwd",
+            str(settings.project_root / plan.cwd),
+            "--log",
+            str(paths["log"]),
+            "--",
+            *plan.command,
+        ]
+        _spawn_supervisor(supervisor_command, settings.project_root)
+        state = _wait_for_state(paths["metadata"], {"running", "exited"}, 10.0)
+        readiness: dict[str, object] = {"status": "not_configured"}
+        if state.get("status") != "running":
+            report.status = "failed"
+            report.issues.append(
+                Issue("error", "Managed process failed to start.", code="START_FAILED")
+            )
+        else:
+            readiness = _wait_for_readiness(options)
+            if readiness["status"] == "ready":
+                report.status = "success"
+            else:
+                report.status = "failed"
+                report.issues.append(
+                    Issue(
+                        "error",
+                        "Managed process did not pass its readiness check in time.",
+                        code="READINESS_TIMEOUT",
+                    )
+                )
+                _request_managed_stop(paths, token, 5)
+        report.summary = {
+            "plan": plan.to_dict(),
+            "mode": "background",
+            "status": state.get("status", "unknown"),
+            "supervisor_pid": state.get("supervisor_pid"),
+            "child_pid": state.get("child_pid"),
+            "readiness": readiness,
+            "startup_log": _tail_log(paths["log"], options.startup_log_lines),
+            "stale_metadata_recovered": bool(current) and not _heartbeat_is_fresh(current),
+        }
+        report.artifacts.extend(
+            [
+                Artifact(str(paths["log"]), "log", "Application output"),
+                Artifact(str(paths["metadata"]), "runtime-state", "Managed process state"),
+            ]
+        )
+    if not report.summary:
+        report.summary = {
+            "plan": plan.to_dict() if plan else None,
+            "explain": options.explain,
+            "dry_run": options.dry_run,
+        }
+    report.finish()
+    write_markdown(report, settings.reports_directory / "run-latest.md")
+    write_json(report, settings.reports_directory / "run-latest.json")
+    return report
+
+
+def stop_application(
+    project_root: Path, *, explain: bool = False, timeout_seconds: int = 10
+) -> Report:
+    settings = load_settings(project_root)
+    report = Report(command="stop", project_root=settings.project_root)
+    paths = _runtime_paths(settings.project_root)
+    state = _read_json(paths["metadata"])
+    public_state = _public_state(state)
+    if not state:
+        report.status = "partial"
+        report.summary = {"status": "not_running", "state": {}}
+    elif state.get("status") not in {"running", "stopping"}:
+        report.status = "partial"
+        report.summary = {"status": "not_running", "state": public_state}
+    elif not isinstance(state.get("token"), str):
+        report.status = "blocked"
+        report.issues.append(
+            Issue(
+                "error", "Runtime state has no valid control token.", code="INVALID_RUNTIME_STATE"
+            )
+        )
+        report.summary = {"status": "unknown", "state": public_state}
+    elif explain:
+        report.summary = {
+            "status": "would_request_stop",
+            "state": public_state,
+            "modifications": "NONE",
+        }
+    else:
+        paths["request"].parent.mkdir(parents=True, exist_ok=True)
+        paths["request"].write_text(str(state["token"]), encoding="utf-8")
+        stopped = _wait_for_state(paths["metadata"], {"stopped", "exited"}, timeout_seconds)
+        if stopped.get("status") not in {"stopped", "exited"}:
+            report.status = "failed"
+            report.issues.append(
+                Issue(
+                    "error",
+                    "Supervisor did not acknowledge the stop request; no arbitrary PID was killed.",
+                    code="STOP_TIMEOUT",
+                )
+            )
+        else:
+            report.status = "success"
+        report.summary = {
+            "status": stopped.get("status", "unknown"),
+            "state": _public_state(stopped),
+        }
+    if paths["metadata"].exists():
+        report.artifacts.append(
+            Artifact(str(paths["metadata"]), "runtime-state", "Managed process state")
+        )
+    report.finish()
+    write_markdown(report, settings.reports_directory / "stop-latest.md")
+    write_json(report, settings.reports_directory / "stop-latest.json")
+    return report
+
+
+def resolve_run_plan(settings: Settings) -> RunPlan | None:
+    configured = settings.commands.get("run")
+    if configured:
+        command = split_command(configured)
+        return RunPlan(command, "configured") if command else None
+    package_path = settings.project_root / "package.json"
+    if package_path.exists():
+        try:
+            package = json.loads(package_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            return None
+        scripts = package.get("scripts", {}) if isinstance(package, dict) else {}
+        if isinstance(scripts, dict):
+            for name in ("dev", "start", "serve"):
+                if isinstance(scripts.get(name), str):
+                    manager = _node_manager(settings.project_root)
+                    return RunPlan([manager, "run", name], f"package.json#scripts.{name}")
+    return None
+
+
+def _node_manager(root: Path) -> str:
+    if (root / "pnpm-lock.yaml").exists():
+        return "pnpm"
+    if (root / "yarn.lock").exists():
+        return "yarn"
+    return "npm"
+
+
+def _spawn_supervisor(command: list[str], cwd: Path) -> None:
+    flags = 0
+    start_new_session = os.name != "nt"
+    if os.name == "nt":
+        flags = (
+            getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+            | getattr(subprocess, "DETACHED_PROCESS", 0)
+            | getattr(subprocess, "CREATE_NO_WINDOW", 0)
+        )
+    subprocess.Popen(
+        command,
+        cwd=cwd,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        close_fds=True,
+        shell=False,
+        start_new_session=start_new_session,
+        creationflags=flags,
+    )
+
+
+def _readiness_config(options: RunOptions) -> dict[str, object]:
+    return {
+        "http": options.readiness_http,
+        "tcp": options.readiness_tcp,
+        "timeout_seconds": options.startup_timeout_seconds,
+    }
+
+
+def _wait_for_readiness(options: RunOptions) -> dict[str, object]:
+    if options.readiness_http is None and options.readiness_tcp is None:
+        return {"status": "ready", "check": "process_started", "attempts": 0}
+    deadline = time.monotonic() + max(options.startup_timeout_seconds, 0)
+    attempts = 0
+    last_error = ""
+    while True:
+        attempts += 1
+        try:
+            if options.readiness_http is not None:
+                with urllib_request.urlopen(options.readiness_http, timeout=0.5) as response:
+                    if response.status >= 500:
+                        raise OSError(f"HTTP {response.status}")
+            if options.readiness_tcp is not None:
+                host, port = _parse_tcp_endpoint(options.readiness_tcp)
+                with socket.create_connection((host, port), timeout=0.5):
+                    pass
+            return {"status": "ready", "check": _readiness_config(options), "attempts": attempts}
+        except (OSError, ValueError, urllib_error.URLError) as exc:
+            last_error = mask_text(str(exc))
+            if time.monotonic() >= deadline:
+                break
+            time.sleep(0.1)
+    return {
+        "status": "timeout",
+        "check": _readiness_config(options),
+        "attempts": attempts,
+        "last_error": last_error,
+    }
+
+
+def _parse_tcp_endpoint(value: str) -> tuple[str, int]:
+    host, separator, port_text = value.rpartition(":")
+    if not separator or not host:
+        raise ValueError("TCP readiness must use host:port")
+    port = int(port_text)
+    if not 1 <= port <= 65535:
+        raise ValueError("TCP readiness port must be between 1 and 65535")
+    return host, port
+
+
+def _tail_log(path: Path, max_lines: int) -> list[str]:
+    if max_lines <= 0:
+        return []
+    try:
+        return path.read_text(encoding="utf-8", errors="replace").splitlines()[-max_lines:]
+    except OSError:
+        return []
+
+
+def _request_managed_stop(paths: dict[str, Path], token: str, timeout: int) -> None:
+    paths["request"].parent.mkdir(parents=True, exist_ok=True)
+    paths["request"].write_text(token, encoding="utf-8")
+    _wait_for_state(paths["metadata"], {"stopped", "exited"}, timeout)
+
+
+def _runtime_paths(root: Path) -> dict[str, Path]:
+    directory = root / ".ai" / "runtime"
+    return {
+        "metadata": directory / "process.json",
+        "request": directory / "stop.request",
+        "log": root / ".ai" / "logs" / "run-latest.log",
+    }
+
+
+def _wait_for_state(path: Path, statuses: set[str], timeout: float) -> dict[str, object]:
+    deadline = time.monotonic() + max(timeout, 0)
+    latest: dict[str, object] = {}
+    while time.monotonic() <= deadline:
+        latest = _read_json(path)
+        if latest.get("status") in statuses:
+            return latest
+        pending = _read_json(path.with_suffix(path.suffix + ".tmp"))
+        if pending.get("status") in statuses:
+            return pending
+        time.sleep(0.05)
+    return latest
+
+
+def _read_json(path: Path) -> dict[str, object]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        return value if isinstance(value, dict) else {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _heartbeat_is_fresh(state: dict[str, object]) -> bool:
+    heartbeat = state.get("heartbeat_at")
+    if not isinstance(heartbeat, str):
+        return False
+    try:
+        from datetime import datetime
+
+        age = datetime.now().astimezone() - datetime.fromisoformat(heartbeat).astimezone()
+        return age.total_seconds() < 5
+    except ValueError:
+        return False
+
+
+def _public_state(state: dict[str, object]) -> dict[str, object]:
+    return {key: value for key, value in state.items() if key != "token"}
+
+
+def _remove_stale_request(path: Path) -> None:
+    with suppress(FileNotFoundError):
+        path.unlink()