kctl-api 0.2.0__py3-none-any.whl

kctl_api/commands/doctor_cmd.py

@@ -0,0 +1,286 @@
+"""Environment validation (doctor) commands for kctl-api.
+
+Check, fix, and report on the development environment.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+import subprocess
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+from kctl_api.core.utils import find_project_root
+
+app = typer.Typer(name="doctor", help="Environment validation — check, fix, report.", no_args_is_help=True)
+
+
+def _check_binary(name: str, version_flag: str = "--version") -> dict:
+    """Check if a binary is available and get its version."""
+    path = shutil.which(name)
+    if not path:
+        return {"name": name, "ok": False, "version": None, "path": None, "issue": f"{name} not found in PATH"}
+    try:
+        result = subprocess.run([name, version_flag], capture_output=True, text=True, timeout=5)
+        version = (result.stdout or result.stderr).strip().splitlines()[0][:80]
+        return {"name": name, "ok": True, "version": version, "path": path}
+    except Exception as e:
+        return {"name": name, "ok": False, "version": None, "path": path, "issue": str(e)}
+
+
+def _check_python() -> dict:
+    """Check Python version."""
+    import sys
+
+    version = sys.version.split()[0]
+    major, minor = sys.version_info[:2]
+    ok = (major, minor) >= (3, 12)
+    return {
+        "name": "python",
+        "ok": ok,
+        "version": version,
+        "path": sys.executable,
+        "issue": None if ok else f"Python 3.12+ required, got {version}",
+    }
+
+
+def _check_env_file() -> dict:
+    """Check .env file exists and has required keys."""
+    root = find_project_root()
+    env_file = root / ".env"
+    example_file = root / ".env.example"
+
+    if not env_file.exists():
+        return {"name": ".env", "ok": False, "issue": f"{env_file} not found. Copy .env.example"}
+    if not example_file.exists():
+        return {"name": ".env", "ok": True, "version": "exists (no .env.example to compare)"}
+
+    # Find keys in example but missing in .env
+    example_keys = set()
+    env_keys = set()
+
+    for line in example_file.read_text().splitlines():
+        line = line.strip()
+        if line and not line.startswith("#") and "=" in line:
+            example_keys.add(line.split("=")[0].strip())
+
+    for line in env_file.read_text().splitlines():
+        line = line.strip()
+        if line and not line.startswith("#") and "=" in line:
+            env_keys.add(line.split("=")[0].strip())
+
+    missing = example_keys - env_keys
+    if missing:
+        return {
+            "name": ".env",
+            "ok": False,
+            "issue": f"Missing keys: {', '.join(sorted(missing)[:5])}{'...' if len(missing) > 5 else ''}",
+        }
+
+    return {"name": ".env", "ok": True, "version": f"{len(env_keys)} keys configured"}
+
+
+async def _check_postgres_async(actx: AppContext) -> dict:
+    """Check PostgreSQL connectivity."""
+    db_url = actx.database_url
+    if not db_url:
+        return {"name": "postgresql", "ok": False, "issue": "No database_url configured"}
+
+    try:
+        from kctl_api.core.db import dispose_engine, execute_query
+
+        rows = await execute_query(db_url, "SELECT version()")
+        await dispose_engine()
+        version = rows[0].get("version", "")[:60] if rows else "unknown"
+        return {"name": "postgresql", "ok": True, "version": version}
+    except Exception as e:
+        return {"name": "postgresql", "ok": False, "issue": str(e)}
+
+
+async def _check_redis_async(actx: AppContext) -> dict:
+    """Check Redis connectivity."""
+    redis_url = actx.redis_url
+    if not redis_url:
+        return {"name": "redis", "ok": False, "issue": "No redis_url configured"}
+
+    try:
+        from kctl_api.core.redis import close_redis, get_redis
+
+        client = get_redis(redis_url)
+        info = await client.info("server")
+        await close_redis()
+        version = info.get("redis_version", "unknown") if info else "unknown"
+        return {"name": "redis", "ok": True, "version": f"redis {version}"}
+    except Exception as e:
+        return {"name": "redis", "ok": False, "issue": str(e)}
+
+
+def _run_all_checks(actx: AppContext) -> list[dict]:
+    checks: list[dict] = []
+
+    # Binaries
+    checks.append(_check_python())
+    checks.append(_check_binary("uv", "--version"))
+    checks.append(_check_binary("docker", "--version"))
+    checks.append(_check_binary("git", "--version"))
+
+    # Env file
+    checks.append(_check_env_file())
+
+    # Services (async)
+    checks.append(asyncio.run(_check_postgres_async(actx)))
+    checks.append(asyncio.run(_check_redis_async(actx)))
+
+    return checks
+
+
+# ---------------------------------------------------------------------------
+# check
+# ---------------------------------------------------------------------------
+@app.command()
+def check(ctx: typer.Context) -> None:
+    """Check Python, uv, Docker, PostgreSQL, Redis, and .env configuration."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    out.info("Running environment checks ...")
+    checks = _run_all_checks(actx)
+
+    rows = [
+        [
+            c["name"],
+            "[green]ok[/green]" if c.get("ok") else "[red]fail[/red]",
+            c.get("version", ""),
+            c.get("issue", ""),
+        ]
+        for c in checks
+    ]
+
+    out.table(
+        title="Environment Check",
+        columns=[("Check", "bold"), ("Status", ""), ("Version", ""), ("Issue", "red")],
+        rows=rows,
+        data_for_json=checks,
+    )
+
+    failed = [c for c in checks if not c.get("ok")]
+    if failed:
+        out.warn(f"{len(failed)} check(s) failed. Run: kctl-api doctor fix")
+        raise typer.Exit(1)
+    else:
+        out.success("All checks passed.")
+
+
+# ---------------------------------------------------------------------------
+# fix
+# ---------------------------------------------------------------------------
+@app.command()
+def fix(ctx: typer.Context) -> None:
+    """Auto-fix common environment issues."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    root = find_project_root()
+    checks = _run_all_checks(actx)
+    failed = [c for c in checks if not c.get("ok")]
+
+    if not failed:
+        out.success("Nothing to fix — all checks passed.")
+        return
+
+    for check_item in failed:
+        name = check_item["name"]
+        issue = check_item.get("issue", "")
+        out.info(f"Fixing: {name} — {issue}")
+
+        if name == ".env":
+            env_example = root / ".env.example"
+            env_file = root / ".env"
+            if not env_file.exists() and env_example.exists():
+                import shutil as sh
+
+                sh.copy(env_example, env_file)
+                out.success("Copied .env.example → .env")
+            else:
+                out.warn(f"Manual fix required for .env: {issue}")
+
+        elif name == "uv":
+            out.info("Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh")
+
+        elif name == "docker":
+            out.info("Install Docker: https://docs.docker.com/engine/install/")
+
+        elif name == "python":
+            out.info("Install Python 3.12+: https://www.python.org/downloads/")
+
+        elif name in ("postgresql", "redis"):
+            out.info("Start services: kctl-api dev up")
+
+        else:
+            out.warn(f"No automated fix for {name}. Issue: {issue}")
+
+
+# ---------------------------------------------------------------------------
+# report
+# ---------------------------------------------------------------------------
+@app.command()
+def report(ctx: typer.Context) -> None:
+    """Generate a full diagnostic report."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    import datetime
+    import platform
+    import sys
+
+    out.header("Diagnostic Report")
+    out.text(f"  Generated: {datetime.datetime.now(tz=datetime.UTC).isoformat()}")
+    out.text(f"  Platform:  {platform.platform()}")
+    out.text(f"  Python:    {sys.version}")
+    out.text("")
+
+    checks = _run_all_checks(actx)
+    passed = [c for c in checks if c.get("ok")]
+    failed = [c for c in checks if not c.get("ok")]
+
+    out.text(f"  Checks:    {len(checks)} total, {len(passed)} passed, {len(failed)} failed")
+    out.text("")
+
+    for c in checks:
+        status = "[green]PASS[/green]" if c.get("ok") else "[red]FAIL[/red]"
+        line = f"  {status}  {c['name']}"
+        if c.get("version"):
+            line += f" ({c['version']})"
+        if c.get("issue"):
+            line += f" — {c['issue']}"
+        out.text(line)
+
+    out.text("")
+
+    # Project info
+    root = find_project_root()
+    pyproject = root / "pyproject.toml"
+    if pyproject.exists():
+        try:
+            import tomllib
+
+            data = tomllib.loads(pyproject.read_text())
+            version = data.get("tool", {}).get("commitizen", {}).get("version", "unknown")
+            out.text(f"  Project version: {version}")
+        except Exception:
+            pass
+
+    out.text(f"  Project root: {root}")
+
+    if actx.json_mode:
+        out.raw_json(
+            {
+                "platform": platform.platform(),
+                "python": sys.version,
+                "checks": checks,
+                "passed": len(passed),
+                "failed": len(failed),
+            }
+        )

kctl_api/commands/env.py

@@ -0,0 +1,289 @@
+"""Environment management commands for kctl-api.
+
+Validate, diff, template, and sync .env files across the monorepo.
+"""
+
+from __future__ import annotations
+
+import pathlib
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+from kctl_api.core.utils import find_project_root
+
+app = typer.Typer(name="env", help="Environment management — validate, diff, template, sync.", no_args_is_help=True)
+
+
+def _parse_env_file(path: pathlib.Path) -> dict[str, str]:
+    """Parse a .env file into a key-value dict, ignoring comments."""
+    result: dict[str, str] = {}
+    if not path.exists():
+        return result
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" in line:
+            key, _, value = line.partition("=")
+            result[key.strip()] = value.strip()
+    return result
+
+
+def _find_env_files(root: pathlib.Path) -> list[pathlib.Path]:
+    """Find all .env files in the monorepo (apps/)."""
+    found = []
+    for env_file in root.rglob(".env"):
+        # Skip .env inside .venv, node_modules, etc.
+        parts = env_file.parts
+        if any(p in parts for p in (".venv", "node_modules", "__pycache__", ".git")):
+            continue
+        found.append(env_file)
+    return sorted(found)
+
+
+# ---------------------------------------------------------------------------
+# validate
+# ---------------------------------------------------------------------------
+@app.command()
+def validate(
+    ctx: typer.Context,
+    env_file: Annotated[str | None, typer.Option("--file", "-f", help="Path to .env file.")] = None,
+) -> None:
+    """Validate .env against .env.example — show missing and extra keys."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    root = find_project_root()
+    env_path = pathlib.Path(env_file) if env_file else root / ".env"
+    example_path = env_path.parent / ".env.example"
+
+    if not env_path.exists():
+        out.error(f".env not found: {env_path}")
+        raise typer.Exit(1)
+
+    if not example_path.exists():
+        out.warn(f"No .env.example found at {example_path} — cannot validate.")
+        env_keys = _parse_env_file(env_path)
+        out.info(f"{env_path.name} has {len(env_keys)} keys.")
+        return
+
+    env_keys = _parse_env_file(env_path)
+    example_keys = _parse_env_file(example_path)
+
+    missing = sorted(example_keys.keys() - env_keys.keys())
+    extra = sorted(env_keys.keys() - example_keys.keys())
+    shared = sorted(example_keys.keys() & env_keys.keys())
+
+    issues: list[dict] = []
+
+    for key in missing:
+        issues.append({"key": key, "status": "MISSING", "note": "In .env.example but not in .env"})
+
+    # Check for empty values on required keys
+    for key in shared:
+        if not env_keys[key] and example_keys.get(key):
+            issues.append({"key": key, "status": "EMPTY", "note": "Key exists but has no value"})
+
+    if not issues and not extra:
+        out.success(f"Validation passed — {len(shared)} keys match, {len(extra)} extra keys in .env.")
+        return
+
+    if issues:
+        rows = [[i["key"], i["status"], i["note"]] for i in issues]
+        out.table(
+            title=f"Validation Issues ({len(issues)})",
+            columns=[("Key", "bold"), ("Status", "red"), ("Note", "")],
+            rows=rows,
+            data_for_json=issues,
+        )
+
+    if extra:
+        out.info(f"Extra keys in .env (not in .env.example): {', '.join(extra[:10])}")
+
+    if issues:
+        raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# diff
+# ---------------------------------------------------------------------------
+@app.command()
+def diff(
+    ctx: typer.Context,
+    file_a: Annotated[str | None, typer.Argument(help="First .env file path.")] = None,
+    file_b: Annotated[str | None, typer.Argument(help="Second .env file path.")] = None,
+) -> None:
+    """Diff two .env files, or .env vs .env.example if no args given."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    root = find_project_root()
+
+    path_a = pathlib.Path(file_a) if file_a else root / ".env.example"
+    path_b = pathlib.Path(file_b) if file_b else root / ".env"
+
+    if not path_a.exists():
+        out.error(f"File not found: {path_a}")
+        raise typer.Exit(1)
+    if not path_b.exists():
+        out.error(f"File not found: {path_b}")
+        raise typer.Exit(1)
+
+    keys_a = _parse_env_file(path_a)
+    keys_b = _parse_env_file(path_b)
+
+    all_keys = sorted(keys_a.keys() | keys_b.keys())
+    diffs: list[dict] = []
+
+    for key in all_keys:
+        in_a = key in keys_a
+        in_b = key in keys_b
+        val_a = keys_a.get(key, "")
+        val_b = keys_b.get(key, "")
+
+        if not in_a:
+            diffs.append({"key": key, "status": "added", "a": "", "b": val_b})
+        elif not in_b:
+            diffs.append({"key": key, "status": "removed", "a": val_a, "b": ""})
+        elif val_a != val_b:
+            diffs.append({"key": key, "status": "changed", "a": val_a[:40], "b": val_b[:40]})
+
+    if not diffs:
+        out.success(f"No differences between {path_a.name} and {path_b.name}.")
+        return
+
+    rows = [
+        [
+            d["key"],
+            {
+                "added": "[green]added[/green]",
+                "removed": "[red]removed[/red]",
+                "changed": "[yellow]changed[/yellow]",
+            }.get(d["status"], d["status"]),
+            d["a"],
+            d["b"],
+        ]
+        for d in diffs
+    ]
+    out.table(
+        title=f"Diff: {path_a.name} vs {path_b.name} ({len(diffs)} differences)",
+        columns=[("Key", "bold"), ("Status", ""), (path_a.name, ""), (path_b.name, "")],
+        rows=rows,
+        data_for_json=diffs,
+    )
+
+
+# ---------------------------------------------------------------------------
+# template
+# ---------------------------------------------------------------------------
+@app.command()
+def template(
+    ctx: typer.Context,
+    source: Annotated[str | None, typer.Option("--source", "-s", help="Source .env file.")] = None,
+    output: Annotated[str | None, typer.Option("--output", "-o", help="Output path (default: .env.example).")] = None,
+    force: Annotated[bool, typer.Option("--force", "-f", help="Overwrite if exists.")] = False,
+) -> None:
+    """Generate .env.example from .env by stripping values."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    root = find_project_root()
+    source_path = pathlib.Path(source) if source else root / ".env"
+    output_path = pathlib.Path(output) if output else source_path.parent / ".env.example"
+
+    if not source_path.exists():
+        out.error(f"Source .env not found: {source_path}")
+        raise typer.Exit(1)
+
+    if output_path.exists() and not force:
+        confirm = typer.confirm(f"Overwrite existing {output_path}?", default=False)
+        if not confirm:
+            out.info("Cancelled.")
+            raise typer.Exit(0)
+
+    lines: list[str] = []
+    for line in source_path.read_text().splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            lines.append(line)
+        elif "=" in stripped:
+            key = stripped.split("=")[0].strip()
+            lines.append(f"{key}=")
+        else:
+            lines.append(line)
+
+    output_path.write_text("\n".join(lines) + "\n")
+    out.success(
+        f"Template written to {output_path} ({len([ln for ln in lines if '=' in ln and not ln.startswith('#')])} keys)"
+    )
+
+
+# ---------------------------------------------------------------------------
+# sync
+# ---------------------------------------------------------------------------
+@app.command()
+def sync(
+    ctx: typer.Context,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Show what would be synced without writing.")] = False,
+) -> None:
+    """Sync .env keys across monorepo apps — add missing keys from root .env.example."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    root = find_project_root()
+    root_example = root / ".env.example"
+
+    if not root_example.exists():
+        out.error(f"Root .env.example not found: {root_example}")
+        raise typer.Exit(1)
+
+    root_keys = _parse_env_file(root_example)
+    env_files = _find_env_files(root)
+
+    out.info(f"Root .env.example: {len(root_keys)} keys")
+    out.info(f"Found {len(env_files)} .env files in monorepo")
+
+    sync_report: list[dict] = []
+
+    for env_file in env_files:
+        example_file = env_file.parent / ".env.example"
+        if not example_file.exists():
+            sync_report.append({"file": str(env_file), "status": "no .env.example", "added": []})
+            continue
+
+        app_keys = _parse_env_file(example_file)
+        missing_from_app = sorted(root_keys.keys() - app_keys.keys())
+
+        if not missing_from_app:
+            sync_report.append({"file": str(env_file), "status": "in sync", "added": []})
+            continue
+
+        if dry_run:
+            sync_report.append({"file": str(env_file), "status": "needs sync", "added": missing_from_app})
+            out.warn(f"Would add to {example_file.relative_to(root)}: {', '.join(missing_from_app)}")
+        else:
+            # Append missing keys (with empty values) to example
+            with open(example_file, "a") as f:
+                f.write("\n# Synced from root .env.example\n")
+                for key in missing_from_app:
+                    f.write(f"{key}=\n")
+            sync_report.append({"file": str(env_file), "status": "synced", "added": missing_from_app})
+            out.success(f"Synced {len(missing_from_app)} keys to {example_file.relative_to(root)}")
+
+    rows = [
+        [
+            str(pathlib.Path(r["file"]).relative_to(root)),
+            r["status"],
+            str(len(r["added"])),
+            ", ".join(r["added"][:5]),
+        ]
+        for r in sync_report
+    ]
+    out.table(
+        title="Sync Report",
+        columns=[("File", ""), ("Status", ""), ("Added", ""), ("Keys", "")],
+        rows=rows,
+        data_for_json=sync_report,
+    )