fadenstack 0.4.2__py3-none-any.whl

faden_cli/commands/dev/dev_init.py

@@ -0,0 +1,710 @@
+"""``faden dev init`` — bootstrap a full development workspace.
+
+Clones all repositories, installs dependencies, starts shared
+infrastructure, runs migrations, and generates a VS Code workspace file.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import click
+from click.core import ParameterSource
+
+from faden_cli.core.compose import ComposeContext, up as compose_up
+from faden_cli.core.console import console, success, warning, error, info
+from faden_cli.core.detect import detect_docker
+from faden_cli.core.env_gen import dev_env_vars, read_env_file, write_env_file
+from faden_cli.core.git import clone_all_repos
+from faden_cli.core.install import ensure_prerequisites
+from faden_cli.core.registry import (
+    BACKEND_DEV_ENV,
+    DATABASES,
+    INFRA_SERVICES,
+    MODULES_COMPAT,
+    POSTGRES_CONTAINER,
+    backend_dev_env_for,
+)
+from faden_cli.core.rmq import (
+    write_definitions as _write_rmq_definitions,
+)
+from faden_cli.core.settings import (
+    DevConfig,
+    FadenConfig,
+    REPO_DIR_MAP,
+    load_config,
+    save_config,
+)
+from faden_cli.core.workspace import detect_workspace, find_service_dir, resolve_shared_compose
+
+from .dev_group import dev_group
+
+# Backwards-compatible aliases — the canonical implementations live in
+# faden_cli.core.workspace so dev_up / dev_status resolve paths identically.
+_find_service_dir = find_service_dir
+_resolve_shared_compose = resolve_shared_compose
+
+
+def _wait_for_postgres(container: str = POSTGRES_CONTAINER, timeout: int = 60) -> bool:
+    """Block until the Postgres container reports healthy or running."""
+    import time
+
+    waited = 0
+    while waited < timeout:
+        try:
+            result = subprocess.run(
+                [
+                    "docker", "inspect", "--format",
+                    "{{if .State.Health}}{{.State.Health.Status}}{{else}}running{{end}}",
+                    container,
+                ],
+                capture_output=True,
+                text=True,
+            )
+            status = result.stdout.strip()
+            if status in ("healthy", "running"):
+                return True
+        except Exception:
+            pass
+        time.sleep(3)
+        waited += 3
+    return False
+
+
+def _parse_env_file(path: Path) -> dict[str, str]:
+    """Parse a simple KEY=VALUE env file."""
+    if not path.exists():
+        return {}
+
+    values: dict[str, str] = {}
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip()
+    return values
+
+
+def _backend_db_creds(backend_dir: Path) -> tuple[str, str, str]:
+    """Resolve backend DB user/password/database from backend .env or defaults."""
+    defaults = ("faden_backend", "faden_backend", "faden_backend")
+    env_values = _parse_env_file(backend_dir / ".env")
+    return (
+        env_values.get("FADEN_BACKEND_DB_USER", defaults[0]),
+        env_values.get("FADEN_BACKEND_DB_PASS", defaults[1]),
+        env_values.get("FADEN_BACKEND_DB_BASE", defaults[2]),
+    )
+
+
+def _ensure_backend_role(backend_dir: Path, pg_user: str = "postgres") -> None:
+    """Ensure backend DB role exists and can migrate the backend database."""
+    db_user, db_pass, db_name = _backend_db_creds(backend_dir)
+    role_lit = db_user.replace("'", "''")
+    pass_lit = db_pass.replace("'", "''")
+    db_lit = db_name.replace("'", "''")
+    role_ident = '"' + db_user.replace('"', '""') + '"'
+
+    create_or_update_role_sql = (
+        "DO $$ "
+        "BEGIN "
+        f"  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '{role_lit}') THEN "
+        f"    CREATE ROLE {role_ident} LOGIN PASSWORD '{pass_lit}'; "
+        "  ELSE "
+        f"    ALTER ROLE {role_ident} WITH LOGIN PASSWORD '{pass_lit}'; "
+        "  END IF; "
+        "END "
+        "$$;"
+    )
+    role_result = subprocess.run(
+        [
+            "docker",
+            "exec",
+            POSTGRES_CONTAINER,
+            "psql",
+            "-U",
+            pg_user,
+            "-v",
+            "ON_ERROR_STOP=1",
+            "-d",
+            "postgres",
+            "-c",
+            create_or_update_role_sql,
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if role_result.returncode != 0:
+        warning(
+            "Could not ensure backend DB role before migrations:\n"
+            f"{(role_result.stderr or role_result.stdout).strip()}"
+        )
+        return
+
+    grant_db_sql = (
+        f"GRANT CONNECT ON DATABASE \"{db_lit}\" TO {role_ident}; "
+        f"GRANT ALL PRIVILEGES ON DATABASE \"{db_lit}\" TO {role_ident};"
+    )
+    subprocess.run(
+        [
+            "docker",
+            "exec",
+            POSTGRES_CONTAINER,
+            "psql",
+            "-U",
+            pg_user,
+            "-v",
+            "ON_ERROR_STOP=1",
+            "-d",
+            "postgres",
+            "-c",
+            grant_db_sql,
+        ],
+        capture_output=True,
+        text=True,
+    )
+    subprocess.run(
+        [
+            "docker",
+            "exec",
+            POSTGRES_CONTAINER,
+            "psql",
+            "-U",
+            pg_user,
+            "-v",
+            "ON_ERROR_STOP=1",
+            "-d",
+            db_name,
+            "-c",
+            f"GRANT ALL ON SCHEMA public TO {role_ident};",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    subprocess.run(
+        [
+            "docker",
+            "exec",
+            POSTGRES_CONTAINER,
+            "psql",
+            "-U",
+            pg_user,
+            "-v",
+            "ON_ERROR_STOP=1",
+            "-d",
+            db_name,
+            "-c",
+            (
+                f"GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO {role_ident}; "
+                f"GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO {role_ident}; "
+                f"ALTER DEFAULT PRIVILEGES IN SCHEMA public "
+                f"GRANT ALL PRIVILEGES ON TABLES TO {role_ident}; "
+                f"ALTER DEFAULT PRIVILEGES IN SCHEMA public "
+                f"GRANT ALL PRIVILEGES ON SEQUENCES TO {role_ident};"
+            ),
+        ],
+        capture_output=True,
+        text=True,
+    )
+
+
+def _ensure_database(db_name: str, pg_user: str = "postgres", *, quiet: bool = False) -> bool:
+    """Ensure a database exists inside the shared Postgres container.
+
+    Returns True when this call created it.  ``quiet`` suppresses the
+    per-database chatter for callers that run this on every invocation
+    (``dev up``) rather than once during setup.
+    """
+    check_sql = f"SELECT 1 FROM pg_database WHERE datname='{db_name}'"
+    result = subprocess.run(
+        ["docker", "exec", POSTGRES_CONTAINER, "psql", "-U", pg_user, "-tAc", check_sql],
+        capture_output=True,
+        text=True,
+    )
+    if "1" in (result.stdout or ""):
+        if not quiet:
+            info(f"Database '{db_name}' already exists.")
+        return False
+
+    subprocess.run(
+        ["docker", "exec", POSTGRES_CONTAINER, "psql", "-U", pg_user, "-c", f"CREATE DATABASE {db_name};"],
+        capture_output=True,
+        text=True,
+    )
+    if not quiet:
+        success(f"Created database '{db_name}'.")
+    return True
+
+
+def _install_backend_deps(backend_dir: Path) -> None:
+    """Run ``uv sync`` in the backend directory."""
+    console.print("[cyan]Installing backend dependencies (uv sync)…[/cyan]")
+    result = subprocess.run(["uv", "sync", "--locked"], cwd=str(backend_dir))
+    if result.returncode != 0:
+        warning("uv sync --locked failed, retrying without --locked…")
+        result = subprocess.run(["uv", "sync"], cwd=str(backend_dir))
+        if result.returncode != 0:
+            error("uv sync failed.")
+            return
+    success("Backend dependencies installed.")
+
+
+def _install_frontend_deps(frontend_dir: Path) -> None:
+    """Run ``npm install`` in the frontend directory."""
+    console.print("[cyan]Installing frontend dependencies (npm install)…[/cyan]")
+    result = subprocess.run(["npm", "install"], cwd=str(frontend_dir), shell=(os.name == "nt"))  # noqa: S603, S607
+    if result.returncode != 0:
+        error("npm install failed.")
+        return
+    success("Frontend dependencies installed.")
+
+
+def _run_migrations(backend_dir: Path) -> None:
+    """Run Alembic migrations for backend and API gateway."""
+    console.print("[cyan]Running database migrations…[/cyan]")
+    _ensure_backend_role(backend_dir)
+    db_user, db_pass, db_base = _backend_db_creds(backend_dir)
+    env = os.environ.copy()
+    # Ensure backend Alembic connects with the right credentials.
+    env.setdefault("FADEN_BACKEND_DB_HOST", "127.0.0.1")  # not localhost: see INFRA_LOOPBACK
+    env.setdefault("FADEN_BACKEND_DB_PORT", "5432")
+    env.setdefault("FADEN_BACKEND_DB_USER", db_user)
+    env.setdefault("FADEN_BACKEND_DB_PASS", db_pass)
+    env.setdefault("FADEN_BACKEND_DB_BASE", db_base)
+    result = subprocess.run(["uv", "run", "alembic", "upgrade", "head"], cwd=str(backend_dir), env=env)
+    if result.returncode != 0:
+        warning("Backend Alembic migration exited with non-zero code.")
+    else:
+        success("Backend migrations up to date.")
+
+    # API gateway migrations (creates llm_gateway_request_log, etc.)
+    api_dir = backend_dir.parent / "gateway"
+    if api_dir.exists() and (api_dir / "alembic.ini").exists():
+        console.print("[cyan]Running API gateway migrations…[/cyan]")
+        result = subprocess.run(["uv", "run", "alembic", "upgrade", "head"], cwd=str(api_dir), env=env)
+        if result.returncode != 0:
+            warning("API gateway Alembic migration exited with non-zero code.")
+        else:
+            success("API gateway migrations up to date.")
+
+
+def _generate_vscode_workspace(workspace: Path) -> None:
+    """Create a VS Code multi-root workspace file."""
+    workspace_file = workspace / "fadenstack.code-workspace"
+
+    folders = []
+    for _gh_name, local_name in sorted(REPO_DIR_MAP.items()):
+        repo_path = find_service_dir(workspace, local_name)
+        if repo_path.exists():
+            rel = os.path.relpath(repo_path, workspace).replace("\\", "/")
+            folders.append({"path": rel})
+
+    content = {
+        "folders": folders,
+        "settings": {
+            "python.defaultInterpreterPath": ".venv/bin/python",
+            "editor.formatOnSave": True,
+            "[python]": {
+                "editor.defaultFormatter": "charliermarsh.ruff",
+            },
+            "[typescript]": {
+                "editor.defaultFormatter": "esbenp.prettier-vscode",
+            },
+            "[typescriptreact]": {
+                "editor.defaultFormatter": "esbenp.prettier-vscode",
+            },
+        },
+    }
+    workspace_file.write_text(json.dumps(content, indent=2) + "\n", encoding="utf-8")
+    success(f"VS Code workspace file: {workspace_file}")
+
+
+def _resync_rmq_credentials(shared_dir: Path, *, skip_infra: bool) -> None:
+    """Regenerate RMQ ``definitions.json`` from the shared ``.env`` and
+    restart the broker so the on-disk users match the in-env passwords.
+
+    ``shared/rabbitmq/definitions.json`` is generated, not tracked. When it
+    is missing or older than the shared ``.env`` (new ``RABBITMQ_*_PASS``
+    values), the broker's users drift out of sync and the backend/worker —
+    which are told to log in as ``faden-backend`` / ``RABBITMQ_BACKEND_PASS``
+    — get ``ACCESS_REFUSED`` from the mgmt API / AMQP layer.
+
+    Skipped when ``--skip-infra`` (no broker to restart), docker is
+    unavailable, or the shared ``.env`` predates the per-service users.
+    """
+    env_path = shared_dir / ".env"
+    env_vars = read_env_file(env_path)
+    admin_pass = env_vars.get("RABBITMQ_ADMIN_PASS")
+    backend_pass = env_vars.get("RABBITMQ_BACKEND_PASS")
+    if not admin_pass or not backend_pass:
+        warning("Shared .env has no RABBITMQ_*_PASS — skipping RMQ definitions resync.")
+        return
+
+    profiles = {
+        p.strip()
+        for p in env_vars.get("MODULES", "").split(",")
+        if p.strip()
+    }
+    defs_path = _write_rmq_definitions(
+        shared_dir,
+        admin_user=env_vars.get("RABBITMQ_ADMIN_USER", "admin"),
+        admin_pass=admin_pass,
+        backend_pass=backend_pass,
+        api_pass=env_vars.get("RABBITMQ_API_PASS", backend_pass),
+        pii_pass=env_vars.get("RABBITMQ_PII_PASS") if "pii" in profiles else None,
+    )
+    info(f"RMQ definitions regenerated: {defs_path}")
+
+    if skip_infra:
+        info("Skipping RMQ restart (--skip-infra); definitions load on next broker start.")
+        return
+    docker = shutil.which("docker")
+    if not docker or not _wait_for_postgres(timeout=10):
+        info("Docker not ready — RMQ definitions will load on next broker start.")
+        return
+
+    container = "faden-rmq"  # explicit container_name in the shared compose
+    running = subprocess.run(
+        [docker, "inspect", "-f", "{{.State.Running}}", container],
+        capture_output=True,
+        text=True,
+    )
+    if running.returncode != 0:
+        info("RMQ container not found — definitions will load on first broker start.")
+        return
+
+    # Recreate the broker: the container mounts ./rabbitmq/definitions.json,
+    # but load_definitions runs once at startup, so a plain restart of an
+    # already-running container keeps the old users.
+    if subprocess.run([docker, "rm", "-f", container], capture_output=True).returncode != 0:
+        warning("Could not remove the RMQ container — restart it manually to load new credentials.")
+        return
+    compose_file = next(
+        (p for p in (shared_dir / "docker-compose.yaml", shared_dir / "docker-compose.yml") if p.exists()),
+        None,
+    )
+    if not compose_file:
+        warning("Shared compose file not found for RMQ restart.")
+        return
+    ctx = ComposeContext(
+        compose_files=[str(compose_file)],
+        env_file=str(env_path),
+        project_dir=str(shared_dir),
+    )
+    rc = compose_up(ctx, services=["faden-rmq"], detach=True)
+    if rc != 0:
+        warning("docker compose up faden-rmq failed — retry after infra is up.")
+        return
+    # Wait until the broker accepts logins with the new service user.
+    # rabbitmqctl prints "… ok" (3.x) or "… Success" (4.x); either is
+    # accompanied by exit code 0, but we check both to be safe.
+    for _ in range(60):
+        time.sleep(2)
+        rc = subprocess.run(
+            [docker, "exec", container, "rabbitmqctl",
+             "authenticate_user", "faden-backend", backend_pass],
+            capture_output=True,
+            text=True,
+        )
+        out = (rc.stdout or "").lower()
+        if rc.returncode == 0 and ("ok" in out or "success" in out):
+            success("RMQ credentials resynced (faden-backend accepts login).")
+            return
+    warning("RMQ broker restarted; could not confirm faden-backend login within 120s.")
+
+
+def _resolve_init_workspace(workspace: str, *, explicit: bool) -> Path:
+    """Decide where ``dev init`` sets up.
+
+    Adopts a checkout the developer already has rather than cloning a second
+    copy beside it — which is what happened whenever ``init`` was run from
+    somewhere other than the exact directory holding the code.
+
+    An *explicit* path is honoured as given: it is an instruction about where
+    the workspace should live, and silently relocating it to some ancestor
+    that happens to contain a checkout would be the wrong kind of clever.
+    Detection therefore applies only to the default argument.
+    """
+    target = Path(workspace).resolve()
+    if explicit:
+        return target
+    detected = detect_workspace()
+    if detected and detected != target:
+        info(f"Existing checkout detected at {detected} — using it as the workspace.")
+        return detected
+    return target
+
+
+@dev_group.command("init")
+@click.argument("workspace", type=click.Path(), default=".")
+@click.option("--ssh", is_flag=True, help="Clone using SSH instead of HTTPS.")
+@click.option("--branch", "-b", default="main", show_default=True, help="Branch to checkout after cloning.")
+@click.option("--overwrite", is_flag=True, help="Remove and re-clone existing repos.")
+@click.option("--skip-infra", is_flag=True, help="Skip starting shared infrastructure.")
+@click.option("--skip-deps", is_flag=True, help="Skip installing dependencies.")
+@click.option("--skip-migrations", is_flag=True, help="Skip running database migrations.")
+@click.option(
+    "--modules",
+    default=None,
+    help="Comma-separated list of modules to enable (e.g. pii,auth).",
+)
+@click.option("--force-env", is_flag=True, help="Regenerate .env files even if they already exist.")
+@click.option("--install-prereqs", is_flag=True, help="Auto-install missing prerequisites (uv, git, node).")
+def dev_init(
+    workspace: str,
+    *,
+    ssh: bool,
+    branch: str,
+    overwrite: bool,
+    skip_infra: bool,
+    skip_deps: bool,
+    skip_migrations: bool,
+    modules: str | None,
+    force_env: bool,
+    install_prereqs: bool,
+) -> None:
+    """Bootstrap a full Fadenstack development workspace.
+
+    Clones all repositories, installs dependencies, starts shared
+    infrastructure, runs migrations, and generates a VS Code workspace.
+
+    \b
+    Steps:
+      1. Clone all Fadenstack repositories
+      2. Generate .env with dev credentials
+      3. Start shared infrastructure (Postgres, Redis, RabbitMQ, …)
+      4. Ensure databases exist
+      5. Install backend (uv) and frontend (npm) dependencies
+      6. Run Alembic migrations
+      7. Generate VS Code workspace file
+
+    Example:
+
+        faden dev init --workspace ~/projects/fadenstack --branch feature/my-work
+    """
+    explicit = (
+        click.get_current_context().get_parameter_source("workspace")
+        is not ParameterSource.DEFAULT
+    )
+    workspace_path = _resolve_init_workspace(workspace, explicit=explicit)
+    workspace_path.mkdir(parents=True, exist_ok=True)
+
+    # Parse --modules into profile list
+    profiles: list[str] = []
+    if modules:
+        for m in modules.split(","):
+            m = m.strip().lower()
+            if m in MODULES_COMPAT:
+                profiles.append(MODULES_COMPAT[m]["profile"])
+            else:
+                warning(f"Unknown module '{m}'. Available: {', '.join(MODULES_COMPAT)}")
+
+    console.print(f"\n[bold magenta]fadenstack Developer Workspace Setup[/bold magenta]")
+    console.print(f"[dim]Workspace: {workspace_path}[/dim]")
+    if profiles:
+        console.print(f"[dim]Modules:   {', '.join(profiles)}[/dim]")
+    console.print()
+
+    # ── Prerequisites ─────────────────────────────────────────────
+    console.print("[bold cyan]Checking prerequisites…[/bold cyan]")
+    all_ok = ensure_prerequisites(install=install_prereqs)
+    if not all_ok:
+        error(
+            "Some prerequisites are missing.\n"
+            "  Run: faden dev doctor --install"
+        )
+        sys.exit(1)
+
+    # Docker daemon must also be running
+    docker_info = detect_docker()
+    if not docker_info.daemon_running:
+        error(f"Docker daemon is not running. {docker_info.daemon_hint}")
+        if docker_info.error:
+            info(f"  Detail: {docker_info.error}")        
+        sys.exit(1)
+
+    success("Prerequisites OK.")
+
+    # ── 1. Clone repos ────────────────────────────────────────────
+    # Repos already present are skipped, so re-running against an existing
+    # workspace pulls only what is missing rather than touching the tree.
+    console.print("\n[bold cyan]Step 1: Cloning missing repositories…[/bold cyan]")
+    clone_method = "ssh" if ssh else "https"
+
+    # Resolve GitHub token for cloning private repos (if configured)
+    existing_cfg = load_config()
+    github_token = existing_cfg.dev.github_token if existing_cfg.dev else ""
+
+    results = clone_all_repos(list(REPO_DIR_MAP.keys()), target_dir=workspace_path, method=clone_method, branch=branch, force=overwrite, token=github_token)
+
+    cloned = sum(1 for r in results if r.cloned)
+    skipped = sum(1 for r in results if r.skipped)
+    errors = [r for r in results if r.error]
+    info(f"Cloned: {cloned}, Skipped (already exist): {skipped}, Errors: {len(errors)}")
+    for r in errors:
+        error(f"  {r.repo}: {r.error}")
+
+    # ── 2. Generate .env ──────────────────────────────────────────
+    console.print("\n[bold cyan]Step 2: Generating .env files…[/bold cyan]")
+
+    # ── 2a. Shared infrastructure .env ────────────────────────────
+    shared_dir = workspace_path / "shared"
+    if not shared_dir.is_dir():
+        shared_dir = workspace_path / "fadenstack" / "shared"
+    env_path = shared_dir / ".env"
+    if env_path.exists() and not force_env:
+        warning(f".env already exists at {env_path} — skipping (use --force-env to regenerate).")
+        from faden_cli.commands.dev.dev_up import heal_dev_env
+
+        heal_dev_env(env_path)
+    else:
+        env_vars = dev_env_vars(profiles=profiles)
+        write_env_file(env_path, env_vars)
+        success(f".env written to {env_path}")
+
+    # ── 2b. Backend local .env (so uv run uses localhost) ─────────
+    backend_dir = _find_service_dir(workspace_path, "backend")
+    backend_env_path = backend_dir / ".env"
+    # Resolve the broker credentials from the shared env BEFORE writing the
+    # backend env, so the backend logs in as the per-service AMQP user that
+    # the shared RabbitMQ definitions create (faden-backend /
+    # RABBITMQ_BACKEND_PASS), not the hard-coded guest/guest default.
+    shared_env_path = env_path if env_path.exists() else (
+        workspace_path / "shared" / ".env"
+    )
+    backend_env = backend_dev_env_for(shared_env_path)
+    if backend_env_path.exists() and not force_env:
+        warning(f"Backend .env already exists at {backend_env_path} — skipping (use --force-env to regenerate).")
+    elif backend_dir.exists():
+        write_env_file(backend_env_path, backend_env)
+        success(f"Backend .env written to {backend_env_path}")
+
+    # ── 2c. Resync RabbitMQ credentials with the shared .env ──────
+    # definitions.json is not tracked: it holds the users' password
+    # hashes, written from the shared .env. Write it (and the snippet
+    # that loads it) and recreate the broker so the backend and worker
+    # can authenticate as faden-backend / RABBITMQ_BACKEND_PASS.
+    _resync_rmq_credentials(shared_dir, skip_infra=skip_infra)
+
+    # ── 3. Start shared infrastructure ────────────────────────────
+    if not skip_infra:
+        console.print("\n[bold cyan]Step 3: Starting shared infrastructure…[/bold cyan]")
+        compose_file = _resolve_shared_compose(workspace_path)
+        if compose_file:
+            ctx = ComposeContext(
+                compose_files=[str(compose_file)],
+                env_file=str(env_path) if env_path.exists() else None,
+                project_dir=str(compose_file.parent),
+            )
+            returncode = compose_up(ctx, services=INFRA_SERVICES, detach=True)
+            if returncode != 0:
+                error("docker compose up failed for shared infrastructure.")
+            else:
+                console.print("[cyan]Waiting for Postgres…[/cyan]")
+                if _wait_for_postgres():
+                    success("Shared infrastructure is running.")
+                else:
+                    warning("Postgres did not become ready in time.")
+        else:
+            warning("Could not find shared compose file. Skipping infrastructure startup.")
+    else:
+        info("Skipping infrastructure startup (--skip-infra).")
+
+    # ── 4. Ensure databases ───────────────────────────────────────
+    if not skip_infra:
+        console.print("\n[bold cyan]Step 4: Ensuring databases…[/bold cyan]")
+        for db_name in DATABASES:
+            _ensure_database(db_name)
+        if backend_dir.exists():
+            _ensure_backend_role(backend_dir)
+
+    # ── 5. Install dependencies ───────────────────────────────────
+    if not skip_deps:
+        console.print("\n[bold cyan]Step 5: Installing dependencies…[/bold cyan]")
+        backend_dir = _find_service_dir(workspace_path, "backend")
+        frontend_dir = _find_service_dir(workspace_path, "frontend")
+
+        if backend_dir.exists():
+            _install_backend_deps(backend_dir)
+        else:
+            warning("Backend directory not found. Skipping.")
+
+        if frontend_dir.exists():
+            _install_frontend_deps(frontend_dir)
+        else:
+            warning("Frontend directory not found. Skipping.")
+    else:
+        info("Skipping dependency installation (--skip-deps).")
+
+    # ── 6. Migrations ─────────────────────────────────────────────
+    if not skip_migrations and not skip_infra:
+        console.print("\n[bold cyan]Step 6: Running migrations…[/bold cyan]")
+        backend_dir = _find_service_dir(workspace_path, "backend")
+        if backend_dir.exists():
+            _run_migrations(backend_dir)
+        else:
+            warning("Backend directory not found. Skipping migrations.")
+    else:
+        info("Skipping migrations.")
+
+    # ── 7. VS Code workspace ─────────────────────────────────────
+    console.print("\n[bold cyan]Step 7: Generating VS Code workspace…[/bold cyan]")
+    _generate_vscode_workspace(workspace_path)
+
+    # ── Save config ───────────────────────────────────────────────
+    cfg = load_config()
+    cfg.install_dir = str(shared_dir)
+    cfg.profiles = sorted(set(cfg.profiles or []) | set(profiles))
+    cfg.dev = DevConfig(
+        workspace_dir=str(workspace_path),
+        clone_method=clone_method,
+        branch=branch,
+        repos=list(REPO_DIR_MAP.keys()),
+    )
+    save_config(cfg)
+    success("Configuration saved.")
+
+    # ── Summary ───────────────────────────────────────────────────
+    console.print("\n[bold green]✨ Development workspace ready![/bold green]")
+
+    from rich.panel import Panel  # noqa: PLC0415
+    from rich.text import Text  # noqa: PLC0415
+
+    cred_lines = Text()
+    cred_lines.append("  Admin email:     ", style="bold")
+    cred_lines.append("admin@localhost", style="cyan")
+    cred_lines.append("\n  Admin password:  ", style="bold")
+    cred_lines.append("admin", style="cyan")
+    cred_lines.append("\n")
+    cred_lines.append(
+        "\n  The dev admin user is created automatically when the\n"
+        "  backend starts.  These credentials are for local dev only.",
+        style="dim",
+    )
+    console.print()
+    console.print(
+        Panel(
+            cred_lines,
+            title="[bold cyan]Dev Credentials[/bold cyan]",
+            border_style="cyan",
+            padding=(1, 2),
+        )
+    )
+
+    console.print(
+        "\n[dim]Next steps:\n"
+        "  cd {workspace}\n"
+        "  faden dev up        # start backend + frontend\n"
+        "  faden dev status    # check service status\n"
+        "  code fadenstack.code-workspace  # open in VS Code[/dim]".format(
+            workspace=workspace_path
+        )
+    )