kctl-react 0.6.2__py3-none-any.whl

kctl_react/commands/dev.py

@@ -0,0 +1,96 @@
+"""Dev server management commands."""
+
+from __future__ import annotations
+
+import signal
+import subprocess
+from typing import Annotated
+
+import typer
+
+from kctl_react.core.callbacks import AppContext
+
+app = typer.Typer(help="Dev server management.")
+
+
+@app.command()
+def start(
+    ctx: typer.Context,
+    app_name: Annotated[str | None, typer.Argument(help="App name (omit for all apps)")] = None,
+) -> None:
+    """Start dev server(s) via Turbo.
+
+    Examples:
+      kctl-react dev start sfa     # Start SFA only
+      kctl-react dev start         # Start all apps
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+    root = actx.project_root
+
+    if app_name:
+        actx.validate_app(app_name)
+        info = actx.apps[app_name]
+        out.info(f"Starting {app_name} on port {info['port']}...")
+        cmd = ["pnpm", "turbo", "run", "dev", "--filter", f"@kodemeio/{app_name}"]
+    else:
+        out.info("Starting all apps...")
+        cmd = ["pnpm", "turbo", "run", "dev"]
+
+    try:
+        proc = subprocess.Popen(cmd, cwd=root)
+        proc.wait()
+    except KeyboardInterrupt:
+        out.info("Stopping dev server(s)...")
+        proc.send_signal(signal.SIGINT)
+        proc.wait()
+
+
+@app.command()
+def logs(
+    ctx: typer.Context,
+    app_name: Annotated[str, typer.Argument(help="App name")],
+) -> None:
+    """Show build output / dev logs for an app (re-runs dev with output)."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    root = actx.project_root
+
+    actx.validate_app(app_name)
+    info = actx.apps[app_name]
+    out.info(f"Tailing dev output for {app_name} (port {info['port']})...")
+
+    try:
+        proc = subprocess.Popen(
+            ["pnpm", "turbo", "run", "dev", "--filter", f"@kodemeio/{app_name}"],
+            cwd=root,
+        )
+        proc.wait()
+    except KeyboardInterrupt:
+        proc.send_signal(signal.SIGINT)
+        proc.wait()
+
+
+@app.command("list")
+def list_(ctx: typer.Context) -> None:
+    """List available apps and their dev ports."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    rows: list[list[str]] = []
+    for name in actx.app_names:
+        info = actx.apps[name]
+        rows.append(
+            [
+                name,
+                str(info["port"]),
+                f"pnpm dev:{name}",
+                f"http://localhost:{info['port']}",
+            ]
+        )
+
+    out.table(
+        "Dev Servers",
+        [("App", "cyan"), ("Port", "green"), ("Command", "dim"), ("URL", "")],
+        rows,
+    )

kctl_react/commands/docker_cmd.py

@@ -0,0 +1,73 @@
+"""Docker container management."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib.docker import DockerManager
+
+from kctl_react.core.callbacks import AppContext
+
+app = typer.Typer(help="Docker container management.")
+
+
+def _get_manager(actx: AppContext, app_name: str | None = None) -> DockerManager:
+    compose = (
+        actx.project_root / f"docker-compose.prod.{app_name}.yml"
+        if app_name
+        else actx.project_root / "docker-compose.yml"
+    )
+    if not compose.exists():
+        compose = actx.project_root / "docker-compose.prod.yml"
+    return DockerManager(compose_file=compose, project_name=app_name or "kodemeio-react")
+
+
+@app.command()
+def ps(ctx: typer.Context) -> None:
+    """List running containers."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    mgr = _get_manager(actx)
+    containers = mgr.ps()
+    if not containers:
+        out.info("No running containers")
+        return
+    rows = [[c.get("Name", ""), c.get("State", ""), c.get("Status", "")] for c in containers]
+    out.table("Containers", [("Name", "cyan"), ("State", "green"), ("Status", "dim")], rows, data_for_json=containers)
+
+
+@app.command()
+def logs(
+    ctx: typer.Context,
+    service: Annotated[str | None, typer.Argument(help="Service name")] = None,
+    tail: Annotated[int, typer.Option("--tail", help="Lines")] = 100,
+) -> None:
+    """Stream container logs."""
+    actx: AppContext = ctx.obj
+    mgr = _get_manager(actx)
+    mgr.logs(service=service, tail=tail)
+
+
+@app.command()
+def restart(ctx: typer.Context, service: Annotated[str, typer.Argument(help="Service name")]) -> None:
+    """Restart a container."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    mgr = _get_manager(actx)
+    mgr.restart(service)
+    out.success(f"Restarted {service}")
+
+
+@app.command("image-size")
+def image_size(ctx: typer.Context) -> None:
+    """Show Docker image sizes."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    mgr = _get_manager(actx)
+    images = mgr.image_size()
+    if not images:
+        out.info("No images found")
+        return
+    rows = [[i.get("Repository", ""), i.get("Tag", ""), i.get("Size", "")] for i in images]
+    out.table("Images", [("Repository", "cyan"), ("Tag", "dim"), ("Size", "")], rows, data_for_json=images)

kctl_react/commands/doctor.py

@@ -0,0 +1,170 @@
+"""Top-level doctor command group."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+import typer
+
+from kctl_react.core.callbacks import AppContext
+from kctl_react.core.discovery import get_app_dir
+
+app = typer.Typer(help="Monorepo health checks.")
+
+
+def _check_cmd(name: str) -> tuple[bool, str]:
+    """Check if a command exists and return its version."""
+    path = shutil.which(name)
+    if not path:
+        return False, ""
+    try:
+        result = subprocess.run([name, "--version"], capture_output=True, text=True, timeout=5)
+        version = result.stdout.strip().split("\n")[0]
+        return True, version
+    except Exception:
+        return True, "(version unknown)"
+
+
+def run_doctor(actx: AppContext) -> None:
+    """Run comprehensive monorepo health checks.
+
+    Checks: node, pnpm, turbo, git, docker, all apps, packages, env files,
+    codegen config, and dependency installation.
+    """
+    out = actx.output
+    root = actx.project_root
+
+    issues = 0
+    checks = 0
+
+    def ok(msg: str) -> None:
+        nonlocal checks
+        checks += 1
+        out.success(msg)
+
+    def fail(msg: str) -> None:
+        nonlocal checks, issues
+        checks += 1
+        issues += 1
+        out.error(msg)
+
+    def warn(msg: str) -> None:
+        nonlocal checks, issues
+        checks += 1
+        issues += 1
+        out.warn(msg)
+
+    out.header("System Tools")
+
+    found, ver = _check_cmd("node")
+    if found:
+        ok(f"node: {ver}")
+    else:
+        fail("node: not found")
+
+    found, ver = _check_cmd("pnpm")
+    if found:
+        ok(f"pnpm: {ver}")
+    else:
+        fail("pnpm: not found")
+
+    found, ver = _check_cmd("turbo")
+    if found:
+        ok(f"turbo: {ver}")
+    else:
+        warn("turbo: not found (optional, runs via pnpm)")
+
+    found, ver = _check_cmd("git")
+    if found:
+        ok(f"git: {ver}")
+    else:
+        fail("git: not found")
+
+    found, ver = _check_cmd("docker")
+    if found:
+        ok(f"docker: {ver}")
+    else:
+        warn("docker: not found (needed for deploy commands)")
+
+    out.header("Monorepo Structure")
+
+    if (root / "turbo.json").exists():
+        ok(f"turbo.json found at {root}")
+    else:
+        fail(f"turbo.json NOT found at {root}")
+
+    if (root / "package.json").exists():
+        ok("Root package.json exists")
+    else:
+        fail("Root package.json missing")
+
+    if (root / "pnpm-lock.yaml").exists():
+        ok("pnpm-lock.yaml exists")
+    else:
+        fail("pnpm-lock.yaml missing — run `pnpm install`")
+
+    if (root / "node_modules").is_dir():
+        ok("node_modules installed")
+    else:
+        fail("node_modules missing — run `pnpm install`")
+
+    out.header("Apps")
+
+    for name in actx.app_names:
+        app_dir = get_app_dir(root, name)
+        if not app_dir.is_dir():
+            fail(f"{name}: directory missing")
+            continue
+
+        problems: list[str] = []
+        if not (app_dir / "package.json").exists():
+            problems.append("no package.json")
+        if not (app_dir / "src").is_dir():
+            problems.append("no src/")
+        if not (app_dir / "openapi-ts.config.ts").exists():
+            problems.append("no openapi-ts.config.ts")
+
+        has_env = (app_dir / ".env").exists() or (app_dir / ".env.local").exists()
+        if not has_env:
+            problems.append("no .env file")
+
+        if problems:
+            warn(f"{name}: {', '.join(problems)}")
+        else:
+            ok(f"{name}: OK (port {actx.apps[name]['port']})")
+
+    out.header("Shared Packages")
+
+    for pkg_name in actx.packages:
+        pkg_dir = root / "packages" / pkg_name
+        if not (pkg_dir / "package.json").exists():
+            fail(f"@kodemeio/{pkg_name}: package.json missing")
+        elif not (pkg_dir / "src").is_dir():
+            warn(f"@kodemeio/{pkg_name}: no src/ directory")
+        else:
+            ok(f"@kodemeio/{pkg_name}: OK")
+
+    out.header("Summary")
+
+    if issues == 0:
+        out.success(f"All {checks} checks passed — monorepo is healthy!")
+    else:
+        out.warn(f"{issues} issue(s) found out of {checks} checks")
+
+    if out.json_mode:
+        out.raw_json({"checks": checks, "issues": issues, "healthy": issues == 0})
+
+    if issues > 0:
+        raise typer.Exit(1) from None
+
+
+@app.command("check")
+def check(ctx: typer.Context) -> None:
+    """Run comprehensive monorepo health checks.
+
+    Checks: node, pnpm, turbo, git, docker, all apps, packages, env files,
+    codegen config, and dependency installation.
+    """
+    actx: AppContext = ctx.obj
+    run_doctor(actx)

kctl_react/commands/e2e.py

@@ -0,0 +1,343 @@
+"""Playwright E2E testing and screenshot commands."""
+
+from __future__ import annotations
+
+import signal
+import subprocess
+from typing import Annotated
+
+import typer
+
+from kctl_react.core.callbacks import AppContext
+from kctl_react.core.runner import run
+
+app = typer.Typer(help="E2E testing and screenshots via Playwright.")
+
+
+@app.command()
+def test(
+    ctx: typer.Context,
+    app_name: Annotated[str | None, typer.Argument(help="App name (omit for all)")] = None,
+    headed: Annotated[bool, typer.Option("--headed", help="Run with visible browser.")] = False,
+    ui: Annotated[bool, typer.Option("--ui", help="Open Playwright UI mode.")] = False,
+    shared_only: Annotated[bool, typer.Option("--shared", help="Run only shared tests.")] = False,
+    debug: Annotated[bool, typer.Option("--debug", help="Run with Playwright debug mode.")] = False,
+    screenshots: Annotated[bool, typer.Option("--screenshots", help="Capture screenshots for every test.")] = False,
+    video: Annotated[bool, typer.Option("--video", help="Record video for every test.")] = False,
+    mobile: Annotated[bool, typer.Option("--mobile", help="Run with mobile viewport (iPhone 14).")] = False,
+    grep: Annotated[str | None, typer.Option("--grep", "-g", help="Filter tests by title pattern.")] = None,
+    api_only: Annotated[bool, typer.Option("--api", help="Run only API CRUD tests.")] = False,
+    pages_only: Annotated[bool, typer.Option("--pages", help="Run only page screenshot tests.")] = False,
+) -> None:
+    """Run Playwright E2E tests.
+
+    Uses multi-project config with --project flag for per-app targeting.
+
+    Examples:
+      kctl-react e2e test              # Run all E2E tests
+      kctl-react e2e test sfa          # Run SFA tests (shared + app-specific)
+      kctl-react e2e test sfa --headed # Run SFA tests with visible browser
+      kctl-react e2e test sfa --shared # Run only shared tests for SFA
+      kctl-react e2e test hrm --screenshots  # Run with screenshots
+      kctl-react e2e test hrm --video        # Run with video recording
+      kctl-react e2e test hrm --mobile       # Run with mobile viewport
+      kctl-react e2e test hrm --mobile --screenshots  # Mobile + screenshots
+      kctl-react e2e test hrm --api          # Run only API CRUD tests
+      kctl-react e2e test hrm --pages        # Run only page screenshot tests
+      kctl-react e2e test hrm --grep "Leave" # Run tests matching "Leave"
+      kctl-react e2e test --ui         # Open Playwright UI mode
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+    root = actx.project_root
+
+    if app_name:
+        actx.validate_app(app_name)
+
+    e2e_dir = root / "e2e"
+    if not e2e_dir.is_dir():
+        out.error("e2e/ directory not found")
+        raise typer.Exit(1) from None
+
+    cmd = ["npx", "playwright", "test"]
+
+    # File filter must come before --project
+    if api_only and app_name:
+        cmd.append(f"tests/apps/{app_name}/api-crud.spec.ts")
+    elif pages_only and app_name:
+        app_pages = e2e_dir / "tests" / "apps" / app_name / "all-pages.spec.ts"
+        if app_pages.exists():
+            cmd.append(f"tests/apps/{app_name}/all-pages.spec.ts")
+        else:
+            # Use generic factory (auto-generates from app-registry)
+            cmd.append("factories/all-pages.factory.ts")
+    elif shared_only:
+        cmd.append("tests/shared/")
+
+    # Build project name: "hrm" or "hrm-mobile"
+    project_name = app_name
+    if app_name and mobile:
+        project_name = f"{app_name}-mobile"
+    elif mobile and not app_name:
+        out.error("--mobile requires an app name (e.g. kctl-react e2e test hrm --mobile)")
+        raise typer.Exit(1) from None
+
+    if project_name:
+        cmd.extend(["--project", project_name])
+
+    if headed:
+        cmd.append("--headed")
+    if ui:
+        cmd.append("--ui")
+    if debug:
+        cmd.append("--debug")
+    if grep:
+        cmd.extend(["--grep", grep])
+
+    env: dict[str, str] = {}
+    if app_name:
+        env["E2E_APPS"] = app_name
+    if screenshots:
+        env["E2E_SCREENSHOTS"] = "on"
+    if video:
+        env["E2E_VIDEO"] = "on"
+
+    viewport = "mobile" if mobile else "desktop"
+    flags = []
+    if screenshots:
+        flags.append("screenshots")
+    if video:
+        flags.append("video")
+    if api_only:
+        flags.append("API only")
+    if pages_only:
+        flags.append("pages only")
+    if grep:
+        flags.append(f'grep="{grep}"')
+    flags_str = f"  ({', '.join(flags)})" if flags else ""
+    out.info(f"Running E2E tests{f' for {app_name}' if app_name else ' (all apps)'} [{viewport}]{flags_str}...")
+
+    try:
+        import os
+
+        run_env = {**os.environ, **(env or {})}
+        proc = subprocess.Popen(cmd, cwd=e2e_dir, env=run_env)
+        proc.wait()
+        if proc.returncode == 0:
+            out.success("E2E tests passed")
+            if screenshots or video:
+                results_dir = root / "e2e" / "screenshots"
+                if results_dir.is_dir():
+                    parts = []
+                    if screenshots:
+                        pngs = list(results_dir.rglob("*.png"))
+                        parts.append(f"Screenshots: {len(pngs)} file(s)")
+                    if video:
+                        videos = list(results_dir.rglob("*.webm"))
+                        parts.append(f"Videos: {len(videos)} file(s)")
+                    out.info(f"{', '.join(parts)} in e2e/screenshots/")
+        else:
+            out.error("E2E tests failed")
+            raise typer.Exit(1)
+    except KeyboardInterrupt:
+        proc.send_signal(signal.SIGINT)
+        proc.wait()
+
+
+@app.command(name="list")
+def list_tests(
+    ctx: typer.Context,
+    app_name: Annotated[str | None, typer.Argument(help="App name (omit for all)")] = None,
+) -> None:
+    """List all discovered E2E tests.
+
+    Examples:
+      kctl-react e2e list          # List all tests
+      kctl-react e2e list sfa      # List SFA tests only
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+    root = actx.project_root
+
+    if app_name:
+        actx.validate_app(app_name)
+
+    e2e_dir = root / "e2e"
+    if not e2e_dir.is_dir():
+        out.error("e2e/ directory not found")
+        raise typer.Exit(1) from None
+
+    cmd = ["npx", "playwright", "test", "--list"]
+    env: dict[str, str] | None = None
+
+    if app_name:
+        cmd.extend(["--project", app_name])
+        env = {"E2E_APPS": app_name}
+
+    try:
+        run(cmd, cwd=e2e_dir, capture=False, timeout=30, env=env)
+    except Exception as e:
+        out.error(f"Failed to list tests: {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def report(ctx: typer.Context) -> None:
+    """Open Playwright HTML test report."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    root = actx.project_root
+
+    e2e_dir = root / "e2e"
+    if not e2e_dir.is_dir():
+        out.error("e2e/ directory not found")
+        raise typer.Exit(1) from None
+
+    out.info("Opening Playwright report...")
+    try:
+        proc = subprocess.Popen(
+            ["npx", "playwright", "show-report"],
+            cwd=e2e_dir,
+        )
+        proc.wait()
+    except KeyboardInterrupt:
+        proc.send_signal(signal.SIGINT)
+        proc.wait()
+    except Exception as e:
+        out.error(f"Failed to open report: {e}")
+
+
+@app.command()
+def discover(
+    ctx: typer.Context,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Preview without writing.")] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
+) -> None:
+    """Auto-discover app configs and regenerate e2e/app-registry.ts.
+
+    Scans apps/spa/*/src/ for ports, token keys, routes, and nav items.
+    Run this after adding new pages, routes, or nav items.
+
+    Examples:
+      kctl-react e2e discover            # Regenerate registry
+      kctl-react e2e discover --dry-run  # Preview changes
+      kctl-react e2e discover --json     # Output as JSON
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+    root = actx.project_root
+
+    script = root / "e2e" / "scripts" / "discover.mjs"
+    if not script.exists():
+        out.error("e2e/scripts/discover.mjs not found")
+        raise typer.Exit(1) from None
+
+    cmd = ["node", str(script)]
+    if dry_run:
+        cmd.append("--dry-run")
+    if json_output:
+        cmd.append("--json")
+
+    out.info("Discovering app configs from source files...")
+    try:
+        run(cmd, cwd=root, capture=False, timeout=30)
+    except Exception as e:
+        out.error(f"Discovery failed: {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def install(ctx: typer.Context) -> None:
+    """Install Playwright browsers (chromium).
+
+    Examples:
+      kctl-react e2e install
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+    root = actx.project_root
+
+    e2e_dir = root / "e2e"
+    if not e2e_dir.is_dir():
+        out.error("e2e/ directory not found")
+        raise typer.Exit(1) from None
+
+    out.info("Installing Playwright browsers...")
+    try:
+        run(
+            ["npx", "playwright", "install", "--with-deps", "chromium"],
+            cwd=e2e_dir,
+            capture=False,
+            timeout=120,
+        )
+        out.success("Playwright browsers installed")
+    except Exception as e:
+        out.error(f"Failed to install browsers: {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def screenshots(
+    ctx: typer.Context,
+    app_name: Annotated[str | None, typer.Argument(help="App name (omit for all)")] = None,
+    mobile: Annotated[bool, typer.Option("--mobile", help="Use mobile viewport (default).")] = True,
+    desktop: Annotated[bool, typer.Option("--desktop", help="Use desktop viewport.")] = False,
+) -> None:
+    """Capture screenshots of all app pages via Playwright.
+
+    Runs the all-pages.factory.ts test which saves timestamped screenshots
+    to e2e/screenshots/{app}/{viewport}/{YYYYMMDD-HHMMSS}/.
+
+    Examples:
+      kctl-react e2e screenshots           # All apps, mobile viewport
+      kctl-react e2e screenshots sfa       # SFA only
+      kctl-react e2e screenshots --desktop # Desktop viewport
+    """
+    actx: AppContext = ctx.obj
+    out = actx.output
+    root = actx.project_root
+
+    if app_name:
+        actx.validate_app(app_name)
+
+    e2e_dir = root / "e2e"
+    if not e2e_dir.is_dir():
+        out.error("e2e/ directory not found")
+        raise typer.Exit(1) from None
+
+    # Determine viewport: --desktop overrides default mobile
+    use_mobile = not desktop
+
+    # Build playwright command — delegates to all-pages.factory.ts
+    cmd = ["npx", "playwright", "test", "factories/all-pages.factory.ts"]
+
+    if app_name:
+        project_name = f"{app_name}-mobile" if use_mobile else app_name
+        cmd.extend(["--project", project_name])
+
+    viewport_label = "mobile" if use_mobile else "desktop"
+    out.info(f"Capturing screenshots{f' for {app_name}' if app_name else ' (all apps)'} [{viewport_label}]...")
+
+    import os
+
+    env = {**os.environ}
+    if app_name:
+        env["E2E_APPS"] = app_name
+
+    try:
+        proc = subprocess.Popen(cmd, cwd=e2e_dir, env=env)
+        proc.wait()
+        if proc.returncode == 0:
+            out.success("Screenshots captured")
+        else:
+            out.error("Screenshot capture failed (Playwright exited with errors)")
+            raise typer.Exit(1)
+    except KeyboardInterrupt:
+        proc.send_signal(signal.SIGINT)
+        proc.wait()
+
+    # Show screenshot directory
+    screenshots_dir = root / "e2e" / "screenshots"
+    if screenshots_dir.is_dir():
+        count = len(list(screenshots_dir.rglob("*.png")))
+        out.info(f"Screenshots: {count} file(s) in e2e/screenshots/")