fadenstack 0.4.2__py3-none-any.whl

faden_cli/commands/dev/__init__.py

@@ -0,0 +1 @@
+"""Dev-mode commands for workspace and development stack management."""

faden_cli/commands/dev/dev_doctor.py

@@ -0,0 +1,46 @@
+"""``faden dev doctor`` — check and optionally install prerequisites."""
+
+from __future__ import annotations
+
+import click
+
+from faden_cli.core.console import console, success, warning
+from faden_cli.core.install import ensure_prerequisites
+
+from .dev_group import dev_group
+
+
+@dev_group.command("doctor")
+@click.option(
+    "--install",
+    is_flag=True,
+    help="Offer to install missing tools (uv, git, node).",
+)
+@click.option(
+    "--yes", "-y",
+    is_flag=True,
+    help="Auto-confirm installation without prompting.",
+)
+def dev_doctor(*, install: bool, yes: bool) -> None:
+    """Check development prerequisites and system readiness.
+
+    Verifies that Docker, Git, uv, and Node.js are installed.
+    With --install, offers to install missing tools automatically.
+
+    \b
+    Examples:
+        faden dev doctor
+        faden dev doctor --install
+        faden dev doctor --install -y
+    """
+    console.print("\n[bold cyan]Checking prerequisites…[/bold cyan]")
+    all_ok = ensure_prerequisites(install=install, auto_confirm=yes)
+
+    if all_ok:
+        success("\nAll prerequisites are satisfied.")
+    else:
+        warning(
+            "\nSome prerequisites are missing. "
+            "Run [bold]faden dev doctor --install[/bold] to install them."
+        )
+        raise SystemExit(1)

faden_cli/commands/dev/dev_down.py

@@ -0,0 +1,241 @@
+"""``faden dev down`` — stop the development environment (full reset).
+
+Counterpart of ``faden dev up``:
+
+  1. Stops the dev host processes (backend, taskiq worker, API gateway,
+     frontend) launched by ``dev up`` — on Windows/macOS/Linux.
+  2. Runs ``docker compose down --volumes --remove-orphans`` on the shared
+     infrastructure compose file — removes the containers AND every named
+     data volume (postgres, redis, minio, clickhouse, langfuse, …).
+  3. Deletes the generated secret/env files
+     (``shared/.env``, ``backend/.env``,
+     ``gateway/.env``) so the next ``dev up`` starts from a clean
+     slate with freshly generated credentials.
+
+The full reset avoids the failure modes that occur when stale volumes or
+env files from an older commit outlive a code update (alembic revision
+not found, RMQ credential drift, …).
+
+``faden dev up`` regenerates any deleted env file (fresh dev
+credentials + RMQ definitions) before infra starts, so the workspace is
+always restorable with a plain ``dev up``.
+
+Use ``--keep-infra`` to only stop the host processes and leave the shared
+infra (and its data) running; ``dev up --skip-deps`` then restarts fast.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+from faden_cli.core.console import console, error, info, success, warning
+from faden_cli.core.settings import load_config
+from faden_cli.core.workspace import CORE_DIRNAME, dev_logs_dir, resolve_shared_compose
+
+from .dev_group import dev_group
+
+# (label, [pattern, …]) — a service counts as "was running" if ANY of its
+# patterns matched a live process. Patterns are EREs over the full command
+# line, tuned to the real `ps` output of a live dev stack:
+#
+#   Backend        uv run -m faden_backend   → python3 -m faden_backend
+#   TaskIQ worker  uv run taskiq worker faden_backend.tkq:broker … (+ forkserver)
+#   API gateway    uv run -m faden_gateway       → python3 -m faden_gateway
+#   Frontend       npm run dev                  → node …/react-router dev
+#
+# The Backend pattern is ``m faden_backend`` (the ``-m`` module form),
+# NOT bare ``faden_backend``: the worker's cmdline also contains
+# ``faden_backend`` (so a bare match would kill the worker too), and
+# ``postgres: … faden_backend …`` backend sessions carry the db name in
+# their rewritten cmdline — both would be matched by a bare pattern. The
+# ``m …`` form (leading dash dropped so pkill doesn't parse it as its own
+# flag) hits only the real ``-m faden_backend`` server.
+_DEV_PROCESS_PATTERNS: list[tuple[str, list[str]]] = [
+    # ``taskiq worker`` hits the uv launcher + taskiq main; the broker URI
+    # additionally hits the forkserver workers whose argv no longer carries
+    # the word "taskiq".
+    ("TaskIQ worker", ["taskiq worker", "faden_backend.tkq:broker"]),
+    ("API gateway", ["m faden_gateway"]),
+    ("Backend", ["m faden_backend"]),
+    ("Frontend", ["npm run dev", "react-router dev"]),
+    # Optional modules started by ``dev up --modules``.
+    ("PII", ["m faden_pii"]),
+    ("MCP", ["m faden_mcp"]),
+    ("Skills", ["m faden_skills"]),
+]
+
+
+def _kill_pattern(pattern: str) -> bool:
+    """Kill processes whose command line matches *pattern*.
+
+    Returns ``True`` if at least one process was matched & killed.
+    Cross-platform: ``pkill -f`` on Unix, Win32 query on Windows.
+    """
+    system = platform.system()
+
+    if system in ("Linux", "Darwin"):
+        if not shutil.which("pkill"):
+            warning("pkill not found — cannot stop host processes.")
+            return False
+        result = subprocess.run(["pkill", "-f", pattern])
+        return result.returncode == 0
+
+    # Windows: match on the full command line, kill the whole set.
+    ps_cmd = (
+        "$m = Get-CimInstance Win32_Process | "
+        f"Where-Object {{ $_.CommandLine -like '*{pattern}*' }} | "
+        "Select-Object -ExpandProperty ProcessId; "
+        "if ($m) { Stop-Process -Id $m -Force -ErrorAction SilentlyContinue; 'KILLED' } "
+        "else { 'NONE' }"
+    )
+    result = subprocess.run(
+        ["powershell", "-NoProfile", "-Command", ps_cmd],
+        capture_output=True,
+        text=True,
+    )
+    return "KILLED" in result.stdout
+
+
+def _stop_dev_processes() -> int:
+    """Stop every dev host process group. Returns how many groups matched."""
+    stopped = 0
+    for label, patterns in _DEV_PROCESS_PATTERNS:
+        matched = any(_kill_pattern(p) for p in patterns)
+        if matched:
+            stopped += 1
+            console.print(f"  [green]✓[/green] {label}")
+        else:
+            console.print(f"  [dim]○[/dim] {label} (not running)")
+    return stopped
+
+
+def _find_workspace() -> Path:
+    """Resolve the dev workspace (shared with dev up / dev status)."""
+    from faden_cli.core.workspace import resolve_workspace
+
+    return resolve_workspace()
+
+
+def _generated_env_files(workspace: Path) -> list[Path]:
+    """Locate the secret/env files generated by ``dev init`` / ``dev up``.
+
+    ``resolve_shared_compose`` handles the monorepo/flat layout for the
+    shared file; the service-local files follow the same two layouts, so
+    both candidate positions are collected and deduplicated.
+    """
+    env_files: list[Path] = []
+
+    compose_file = resolve_shared_compose(workspace)
+    if compose_file:
+        env_files.append(compose_file.parent / ".env")
+
+    for name in ("backend", "gateway"):
+        base = workspace / CORE_DIRNAME
+        for candidate in (base / name / ".env", workspace / name / ".env"):
+            if candidate not in env_files:
+                env_files.append(candidate)
+
+    return env_files
+
+
+@dev_group.command("down")
+@click.option(
+    "--keep-infra",
+    is_flag=True,
+    help="Only stop the dev host processes; leave shared infra containers, volumes and env files running/kept.",
+)
+@click.option("--yes", "-y", is_flag=True, help="Do not prompt for confirmation.")
+def dev_down(*, keep_infra: bool, yes: bool) -> None:
+    """Stop the dev environment and reset its state (full teardown).
+
+    Kills the host processes, then removes the infra containers, the named
+    data volumes (postgres, redis, minio, clickhouse, langfuse, …) and the
+    generated .env secret files. Everything is regenerated on the next
+    ``faden dev up``.
+
+    \b
+    Examples:
+        faden dev down          # full reset (prompts for confirmation)
+        faden dev down -y       # full reset, no prompt (scripts)
+        faden dev down --keep-infra  # stop only the host processes
+    """
+    console.print("\n[bold magenta]fadenstack — Dev Environment Teardown[/bold magenta]\n")
+
+    # ── 1. Stop host processes ───────────────────────────────────
+    console.print("[cyan]Stopping dev processes…[/cyan]")
+    stopped = _stop_dev_processes()
+    if stopped:
+        success(f"Stopped {stopped} dev process group(s).")
+    else:
+        info("No dev processes running.")
+
+    # ── 2. Keep-infra mode: host processes only ──────────────────
+    if keep_infra:
+        console.print(
+            f"\n[dim]Shared infra, volumes and .env files left running. Logs kept: {dev_logs_dir()}\n"
+            "[dim]Restart with: faden dev up --skip-deps[/dim]\n"
+        )
+        return
+
+    workspace = _find_workspace()
+    compose_file = resolve_shared_compose(workspace)
+    env_files = _generated_env_files(workspace)
+
+    if not yes:
+        if not click.confirm(
+            "[red]Full teardown:[/red] removes infra containers + "
+            "[red]all dev data volumes[/red] (postgres, redis, minio, "
+            "clickhouse, langfuse, …) and generated .env files. "
+            "Everything is regenerated on the next 'dev up'. Continue?",
+            default=False,
+        ):
+            error("Aborted — no changes made.")
+            sys.exit(1)
+
+    # ── 3. Stop shared infrastructure + volumes ──────────────────
+    if not compose_file:
+        warning(f"Shared compose file not found in {workspace}. Infra may have been started manually.")
+    else:
+        from faden_cli.core.compose import ComposeContext, down as compose_down
+
+        env_file = compose_file.parent / ".env"
+        if env_file.exists():
+            from faden_cli.commands.dev.dev_up import heal_dev_env
+
+            heal_dev_env(env_file)
+        ctx = ComposeContext(
+            compose_files=[compose_file],
+            env_file=env_file if env_file.exists() else None,
+            project_dir=compose_file.parent,
+        )
+        # NOTE: dev up only brings up INFRA_SERVICES, but `down` on the
+        # whole project is correct — it removes exactly the containers
+        # defined here that are actually running.
+        with console.status("[bold cyan]docker compose down --volumes --remove-orphans[/bold cyan]"):
+            rc = compose_down(ctx, volumes=True, remove_orphans=True)
+        if rc == 0:
+            success("Shared infrastructure and data volumes removed.")
+        else:
+            error(f"docker compose down exited with code {rc}.")
+            sys.exit(rc)
+
+    # ── 4. Remove generated env / secret files ───────────────────
+    removed = 0
+    for env_path in env_files:
+        if env_path.exists():
+            env_path.unlink()
+            removed += 1
+            info(f"Removed {env_path}")
+    if removed == 0:
+        info("No generated .env files to remove.")
+
+    console.print(
+        f"\n[dim]Dev state fully reset. Logs kept: {dev_logs_dir()}\n"
+        f"[dim]Start fresh with: faden dev up[/dim]\n"
+    )

faden_cli/commands/dev/dev_group.py

@@ -0,0 +1,24 @@
+"""``faden dev`` — developer workflow commands."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.group("dev")
+def dev_group() -> None:
+    """Developer workflow — clone, set up, and run the dev environment."""
+
+
+def _register_dev_commands() -> None:
+    """Import and register dev subcommands."""
+    # Importing these modules triggers the @dev_group.command() decorators
+    from faden_cli.commands.dev import dev_doctor as _doctor  # noqa: F401
+    from faden_cli.commands.dev import dev_down as _down  # noqa: F401
+    from faden_cli.commands.dev import dev_init as _init  # noqa: F401
+    from faden_cli.commands.dev import dev_pull as _pull  # noqa: F401
+    from faden_cli.commands.dev import dev_up as _up  # noqa: F401
+    from faden_cli.commands.dev import dev_status as _status  # noqa: F401
+
+
+_register_dev_commands()