devlauncher 0.1.0__py3-none-any.whl

devlauncher/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

devlauncher/cli.py

@@ -0,0 +1,165 @@
+"""devlauncher CLI entry point.
+
+Usage:
+    devlauncher               # reads dev.toml, or auto-discovers services
+    devlauncher path/to/dev.toml
+    python -m devlauncher
+"""
+
+import sys
+from dataclasses import replace
+from pathlib import Path
+from typing import List
+
+from .config import Service, load_config, resolve_port_refs
+from .discovery import discover_services, services_to_toml
+from .installer import needs_install, run_install
+from .ports import find_free_port
+from .runner import BOLD, RESET, YELLOW, _PALETTE, run_services
+
+
+def _run_install_phase(services: List[Service]) -> None:
+    """Run dependency installs for any service that needs them.
+
+    Installs run sequentially (not in parallel) so output stays readable.
+    A non-zero exit code from an install command warns but does not abort —
+    services may still start successfully even with partial install failures.
+    """
+    needs = [svc for svc in services if needs_install(svc)]
+    to_install = [
+        (svc, _PALETTE[i % len(_PALETTE)])
+        for i, svc in enumerate(needs)
+    ]
+    if not to_install:
+        return
+
+    print(f"{BOLD}Installing dependencies...{RESET}\n")
+    for svc, color in to_install:
+        exit_code = run_install(svc, color=color)
+        if exit_code != 0:
+            print(
+                f"{YELLOW}⚠  install_cmd for '{svc.name}' exited {exit_code} "
+                f"— continuing anyway{RESET}"
+            )
+    print()
+
+
+def _resolve_services(services: List[Service]) -> List[Service]:
+    """Detect port conflicts, notify user, return services with actual ports."""
+    resolved_ports: dict[str, int] = {}
+    final: List[Service] = []
+
+    for svc in services:
+        actual = find_free_port(svc.port)
+        resolved_ports[svc.name] = actual
+        if actual != svc.port:
+            print(
+                f"{YELLOW}⚠  Port {svc.port} in use → using {actual} "
+                f"for {svc.name}{RESET}"
+            )
+        final.append(replace(svc, port=actual))
+
+    # Resolve {name.port} and {self.port} references now that all ports are known
+    return resolve_port_refs(final, resolved_ports)
+
+
+def main() -> None:
+    explicit_config = len(sys.argv) > 1
+    config_path = sys.argv[1] if explicit_config else "dev.toml"
+
+    services: List[Service] = []
+
+    if Path(config_path).exists():
+        # dev.toml present — use it
+        try:
+            services = load_config(config_path)
+        except (ValueError, Exception) as e:
+            print(f"Config error: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    elif explicit_config:
+        # User passed a path that doesn't exist
+        print(f"Error: config file not found: {config_path}", file=sys.stderr)
+        sys.exit(1)
+
+    else:
+        # No dev.toml — run auto-discovery once, confirm, then save
+        print(f"{YELLOW}No dev.toml found — running auto-discovery...{RESET}\n")
+        services, warnings = discover_services()
+
+        for w in warnings:
+            print(f"{YELLOW}⚠  {w}{RESET}")
+
+        if not services:
+            print(
+                "\nNo services detected. Create a dev.toml to define your services.\n"
+                "  Example:\n"
+                "    [services.api]\n"
+                '    cmd = "uvicorn main:app --reload --port {self.port}"\n'
+                "    port = 8000\n"
+                '    cwd = "api"\n',
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        # ── Discovery report ───────────────────────────────────────────────────
+        _FW_WIDTH = 10
+        _DIR_WIDTH = 14
+        print(f"  {'SERVICE':<8}  {'FRAMEWORK':<{_FW_WIDTH}}  {'DIR':<{_DIR_WIDTH}}  COMMAND")
+        print(f"  {'─'*8}  {'─'*_FW_WIDTH}  {'─'*_DIR_WIDTH}  {'─'*38}")
+        for svc in services:
+            # Infer framework label from cmd for display
+            fw = "unknown"
+            cmd_lower = svc.cmd.lower()
+            if "uvicorn" in cmd_lower:    fw = "fastapi"
+            elif "manage.py" in cmd_lower: fw = "django"
+            elif "flask" in cmd_lower:     fw = "flask"
+            elif "cargo" in cmd_lower:     fw = "rust"
+            elif "go run" in cmd_lower:    fw = "go"
+            elif "vite" in cmd_lower or "npm" in cmd_lower or "bun" in cmd_lower or "pnpm" in cmd_lower:
+                fw = "node/vite"
+            cwd_display = svc.cwd if svc.cwd != "." else "(root)"
+            print(
+                f"  [{svc.name.upper()}]    {fw:<{_FW_WIDTH}}  "
+                f"{cwd_display:<{_DIR_WIDTH}}  {svc.cmd}"
+            )
+        print()
+        print(f"  A {BOLD}dev.toml{RESET} will be saved so you won't be asked again.")
+        print()
+
+        # ── Confirmation prompt ────────────────────────────────────────────────
+        try:
+            answer = input("  Start these services? [Y/n] ").strip().lower()
+        except (KeyboardInterrupt, EOFError):
+            print("\nAborted.")
+            sys.exit(0)
+
+        if answer in ("n", "no"):
+            print("\nRun 'devlauncher init' to configure services manually.")
+            sys.exit(0)
+
+        # ── Write dev.toml ─────────────────────────────────────────────────────
+        toml_content = services_to_toml(services)
+        try:
+            Path("dev.toml").write_text(toml_content, encoding="utf-8")
+            print(f"\n  {BOLD}dev.toml{RESET} saved. Edit it anytime to adjust services.\n")
+        except OSError as e:
+            print(f"{YELLOW}⚠  Could not write dev.toml: {e} — continuing without saving.{RESET}")
+
+    # Run install phase before resolving ports or starting services
+    _run_install_phase(services)
+
+    services = _resolve_services(services)
+
+    # Print startup header
+    print(f"\n{BOLD}devlauncher{RESET}")
+    for i, svc in enumerate(services):
+        color = _PALETTE[i % len(_PALETTE)]
+        print(f"  {color}{BOLD}[{svc.name.upper()}]{RESET} http://localhost:{svc.port}")
+    print()
+
+    run_services(services)
+
+
+if __name__ == "__main__":
+    main()

devlauncher/config.py

@@ -0,0 +1,115 @@
+"""dev.toml config loading and port-reference resolution.
+
+Config format:
+
+    [services.api]
+    cmd = "uvicorn main:app --reload"
+    port = 8000
+    cwd = "api"
+
+    [services.web]
+    cmd = "npm run dev"
+    port = 5173
+    cwd = "frontend"
+    env = { PUBLIC_API_URL = "http://localhost:{api.port}" }
+
+Port references like {api.port} are resolved after conflict detection,
+so if the API lands on 8001 instead of 8000, PUBLIC_API_URL gets the
+correct URL automatically.
+"""
+
+import re
+import sys
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Dict, List, Optional
+
+# tomllib is stdlib in Python 3.11+; fall back to tomli on 3.9-3.10
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ImportError as exc:
+        raise ImportError(
+            "Python < 3.11 requires the 'tomli' package: pip install tomli"
+        ) from exc
+
+
+@dataclass(frozen=True)
+class Service:
+    name: str
+    cmd: str
+    port: int
+    cwd: str = "."
+    env: Dict[str, str] = field(default_factory=dict)
+    install_cmd: Optional[str] = None
+
+
+def load_config(path: str = "dev.toml") -> List[Service]:
+    """Parse dev.toml and return services in declaration order."""
+    config_path = Path(path)
+    if not config_path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+
+    with config_path.open("rb") as f:
+        data = tomllib.load(f)
+
+    services = []
+    for name, cfg in data.get("services", {}).items():
+        if "cmd" not in cfg:
+            raise ValueError(f"Service '{name}' is missing required field 'cmd'")
+        if "port" not in cfg:
+            raise ValueError(f"Service '{name}' is missing required field 'port'")
+        services.append(Service(
+            name=name,
+            cmd=cfg["cmd"],
+            port=int(cfg["port"]),
+            cwd=cfg.get("cwd", "."),
+            env={k: str(v) for k, v in cfg.get("env", {}).items()},
+            install_cmd=cfg.get("install_cmd") or None,
+        ))
+
+    if not services:
+        raise ValueError("No services defined in dev.toml")
+
+    return services
+
+
+_REF_PATTERN = re.compile(r"\{(\w+)\.port\}")
+
+
+def resolve_port_refs(
+    services: List[Service],
+    resolved_ports: Dict[str, int],
+) -> List[Service]:
+    """Replace {name.port} placeholders with actual resolved ports.
+
+    Called after find_free_port() has run for each service, so references
+    always reflect the real port in use (not the preferred default).
+    """
+    def _replace(m: re.Match) -> str:
+        ref = m.group(1)
+        if ref in resolved_ports:
+            return str(resolved_ports[ref])
+        return m.group(0)  # leave unresolved refs as-is
+
+    result = []
+    for svc in services:
+        # Build a resolver that also handles {self.port} as an alias
+        # for the current service's own resolved port.
+        self_ports = {**resolved_ports, "self": resolved_ports.get(svc.name, svc.port)}
+
+        def _replace_with_self(m: re.Match, _sp: dict = self_ports) -> str:
+            ref = m.group(1)
+            if ref in _sp:
+                return str(_sp[ref])
+            return m.group(0)
+
+        resolved_cmd = _REF_PATTERN.sub(_replace_with_self, svc.cmd)
+        resolved_env = {
+            key: _REF_PATTERN.sub(_replace_with_self, val)
+            for key, val in svc.env.items()
+        }
+        result.append(replace(svc, cmd=resolved_cmd, env=resolved_env))
+    return result

devlauncher/discovery.py

@@ -0,0 +1,512 @@
+"""Auto-discovery: infer services from project structure without a dev.toml.
+
+Scans the project directory, collects evidence (signals) per subdirectory,
+scores each directory for frontend/backend roles, and returns the best
+match per role as a list of Service objects ready for the runner.
+
+Accuracy is intentional: confident detections start silently, uncertain ones
+warn the user, and anything too ambiguous recommends `devlauncher init` instead.
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from .config import Service
+
+# ── Signal weights ─────────────────────────────────────────────────────────────
+HIGH   = 3
+MEDIUM = 2
+LOW    = 1
+
+# ── Confidence thresholds ──────────────────────────────────────────────────────
+CONFIDENT  = "CONFIDENT"   # score >= 6
+LIKELY     = "LIKELY"      # score 4–5
+PLAUSIBLE  = "PLAUSIBLE"   # score == 3
+UNCERTAIN  = "UNCERTAIN"   # score 1–2
+SKIP       = "SKIP"        # score == 0
+
+
+def _score_to_confidence(score: int) -> str:
+    if score >= 6: return CONFIDENT
+    if score >= 4: return LIKELY
+    if score >= 3: return PLAUSIBLE
+    if score >= 1: return UNCERTAIN
+    return SKIP
+
+
+# ── Directories to skip during scan ───────────────────────────────────────────
+_SKIP_DIRS = {
+    ".git", "node_modules", "__pycache__", ".venv", "venv", "env",
+    "dist", "build", ".next", ".svelte-kit", ".nuxt", "target",
+    "coverage", ".coverage", "docs", "tests", "test", "scripts",
+    ".github", ".idea", ".vscode", "tmp", "temp", "logs", ".cache",
+    "static", "public", "assets", "migrations",
+}
+
+
+# ── Internal result types ──────────────────────────────────────────────────────
+@dataclass
+class _DirScore:
+    path: Path
+    frontend_score: int = 0
+    backend_score: int = 0
+    frontend_framework: Optional[str] = None
+    backend_framework: Optional[str] = None
+    package_manager: str = "npm"
+    warnings: List[str] = field(default_factory=list)
+
+
+@dataclass
+class DiscoveredService:
+    name: str
+    role: str           # "frontend" | "backend"
+    cmd: str
+    port: int
+    cwd: str
+    confidence: str
+    framework: str
+    warnings: List[str] = field(default_factory=list)
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return ""
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8", errors="ignore"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _has_dep(text: str, *names: str) -> bool:
+    """Case-insensitive check for package names in a deps file."""
+    lower = text.lower()
+    return any(name.lower() in lower for name in names)
+
+
+def _detect_package_manager(directory: Path) -> str:
+    if (directory / "bun.lockb").exists():
+        return "bun"
+    if (directory / "pnpm-lock.yaml").exists():
+        return "pnpm"
+    if (directory / "yarn.lock").exists():
+        return "yarn"
+    return "npm"
+
+
+def _npm_dev_cmd(pm: str, port_ref: str) -> str:
+    """Build the dev command for a given package manager."""
+    if pm == "bun":
+        return f"bun run dev -- --port {port_ref}"
+    if pm == "pnpm":
+        return f"pnpm run dev -- --port {port_ref}"
+    if pm == "yarn":
+        return f"yarn dev --port {port_ref}"
+    return f"npm run dev -- --port {port_ref}"
+
+
+# ── Directory scorer ───────────────────────────────────────────────────────────
+def _score_directory(directory: Path) -> _DirScore:
+    result = _DirScore(path=directory)
+    name = directory.name.lower()
+
+    # ── Package manager ────────────────────────────────────────────────────────
+    result.package_manager = _detect_package_manager(directory)
+
+    # ── package.json analysis ──────────────────────────────────────────────────
+    pkg_json = _read_json(directory / "package.json")
+    has_pkg = bool(pkg_json)
+    scripts = pkg_json.get("scripts", {})
+    deps = {
+        **pkg_json.get("dependencies", {}),
+        **pkg_json.get("devDependencies", {}),
+    }
+    has_dev_script = "dev" in scripts
+    has_start_script = "start" in scripts
+
+    # Detect JS frontend frameworks from package.json deps
+    if has_pkg:
+        if "vite" in deps or "vite" in pkg_json.get("devDependencies", {}):
+            result.frontend_score += HIGH
+            result.frontend_framework = "vite"
+        if "next" in deps:
+            result.frontend_score += HIGH
+            result.frontend_framework = "nextjs"
+        if "nuxt" in deps:
+            result.frontend_score += HIGH
+            result.frontend_framework = "nuxt"
+        if "@angular/core" in deps:
+            result.frontend_score += HIGH
+            result.frontend_framework = "angular"
+        if "svelte" in deps or "@sveltejs/kit" in deps:
+            result.frontend_score += HIGH
+            result.frontend_framework = "svelte"
+
+        if has_dev_script:
+            result.frontend_score += HIGH
+        elif has_start_script:
+            result.backend_score += MEDIUM  # node backend pattern
+        elif has_pkg:
+            result.frontend_score += MEDIUM
+
+    # ── Framework config files ─────────────────────────────────────────────────
+    for pattern in ("vite.config.ts", "vite.config.js", "vite.config.mjs"):
+        if (directory / pattern).exists():
+            result.frontend_score += HIGH
+            result.frontend_framework = result.frontend_framework or "vite"
+            break
+
+    for pattern in ("next.config.js", "next.config.ts", "next.config.mjs"):
+        if (directory / pattern).exists():
+            result.frontend_score += HIGH
+            result.frontend_framework = result.frontend_framework or "nextjs"
+            break
+
+    for pattern in ("nuxt.config.js", "nuxt.config.ts"):
+        if (directory / pattern).exists():
+            result.frontend_score += HIGH
+            result.frontend_framework = result.frontend_framework or "nuxt"
+            break
+
+    for pattern in ("svelte.config.js", "svelte.config.ts"):
+        if (directory / pattern).exists():
+            result.frontend_score += HIGH
+            result.frontend_framework = result.frontend_framework or "svelte"
+            break
+
+    if (directory / "angular.json").exists():
+        result.frontend_score += HIGH
+        result.frontend_framework = result.frontend_framework or "angular"
+
+    # ── Python backend signals ─────────────────────────────────────────────────
+    python_deps_text = ""
+    for deps_file in ("requirements.txt", "requirements-dev.txt"):
+        p = directory / deps_file
+        if p.exists():
+            python_deps_text += _read_text(p)
+
+    pyproject = directory / "pyproject.toml"
+    if pyproject.exists():
+        python_deps_text += _read_text(pyproject)
+
+    if python_deps_text:
+        if _has_dep(python_deps_text, "fastapi", "uvicorn"):
+            result.backend_score += HIGH
+            result.backend_framework = "fastapi"
+        elif _has_dep(python_deps_text, "flask"):
+            result.backend_score += HIGH
+            result.backend_framework = "flask"
+        elif _has_dep(python_deps_text, "django"):
+            result.backend_score += HIGH
+            result.backend_framework = "django"
+
+    if (directory / "manage.py").exists():
+        result.backend_score += HIGH
+        result.backend_framework = result.backend_framework or "django"
+
+    if (directory / "main.py").exists():
+        result.backend_score += LOW
+        result.backend_framework = result.backend_framework or "python"
+
+    if (directory / "app.py").exists():
+        result.backend_score += LOW
+        result.backend_framework = result.backend_framework or "flask"
+
+    # ── Rust backend ───────────────────────────────────────────────────────────
+    cargo = directory / "Cargo.toml"
+    if cargo.exists():
+        cargo_text = _read_text(cargo)
+        if _has_dep(cargo_text, "axum", "actix-web", "rocket", "warp"):
+            result.backend_score += HIGH
+            result.backend_framework = "rust"
+        else:
+            result.backend_score += MEDIUM
+            result.backend_framework = result.backend_framework or "rust"
+
+    # ── Go backend ─────────────────────────────────────────────────────────────
+    if (directory / "go.mod").exists():
+        result.backend_score += MEDIUM
+        result.backend_framework = result.backend_framework or "go"
+    if (directory / "main.go").exists():
+        result.backend_score += MEDIUM
+        result.backend_framework = result.backend_framework or "go"
+
+    # ── Directory name bonuses ─────────────────────────────────────────────────
+    if name in ("frontend", "web", "client", "app", "ui"):
+        result.frontend_score += MEDIUM
+    if name in ("api", "backend", "server", "service"):
+        result.backend_score += MEDIUM
+
+    return result
+
+
+# ── Command + port inference ───────────────────────────────────────────────────
+def _infer_frontend(score: _DirScore) -> Tuple[str, int]:
+    """Return (command, default_port) for a frontend service."""
+    pm = score.package_manager
+    fw = score.frontend_framework or "vite"
+
+    if fw == "nextjs":
+        cmd = f"{pm} run dev -- -p {{self.port}}" if pm == "npm" else f"{pm} run dev -- --port {{self.port}}"
+        return cmd, 3000
+    if fw == "nuxt":
+        return _npm_dev_cmd(pm, "{self.port}"), 3000
+    if fw == "angular":
+        return f"ng serve --port {{self.port}}", 4200
+    # vite / svelte / generic
+    return _npm_dev_cmd(pm, "{self.port}"), 5173
+
+
+def _infer_backend(score: _DirScore) -> Tuple[str, int, List[str]]:
+    """Return (command, default_port, warnings) for a backend service."""
+    fw = score.backend_framework or "python"
+    warnings: List[str] = []
+
+    if fw == "fastapi":
+        # Try to find the entry point
+        directory = score.path
+        entry = "main:app"
+        for candidate in ("main.py", "app.py", "server.py", "run.py"):
+            if (directory / candidate).exists():
+                module = candidate.replace(".py", "")
+                entry = f"{module}:app"
+                break
+        if entry == "main:app" and not (directory / "main.py").exists():
+            warnings.append(f"Could not find FastAPI entry point — defaulting to 'main:app'. Update dev.toml if wrong.")
+        return f"uvicorn {entry} --reload --port {{self.port}}", 8000, warnings
+
+    if fw == "flask":
+        return "flask run --port {self.port}", 5000, warnings
+
+    if fw == "django":
+        return "python manage.py runserver {self.port}", 8000, warnings
+
+    if fw == "rust":
+        warnings.append("Rust detected — command defaults to 'cargo run'. Port injection via PORT env var may be needed.")
+        return "cargo run", 8080, warnings
+
+    if fw == "go":
+        warnings.append("Go detected — command defaults to 'go run .'. You may need to handle port binding in your code.")
+        return "go run .", 8080, warnings
+
+    # Generic node backend
+    return "npm run start", 3000, warnings
+
+
+# ── Install command inference ──────────────────────────────────────────────────
+def _infer_install_cmd(score: _DirScore) -> Optional[str]:
+    """Return the install command for a discovered service, or None if not applicable.
+
+    Rules:
+    - Node project (has package.json): use package-manager-specific install
+    - Python project with requirements.txt: "pip install -r requirements.txt"
+    - Python project with only pyproject.toml: "pip install -e ."
+    - Go project (go.mod present): "go mod download"
+    - Rust / anything else: None (cargo fetches deps on build; no pre-install step)
+    """
+    directory = score.path
+
+    # Node — package.json present
+    if (directory / "package.json").exists():
+        pm = score.package_manager
+        if pm == "bun":
+            return "bun install"
+        if pm == "pnpm":
+            return "pnpm install"
+        if pm == "yarn":
+            return "yarn install"
+        return "npm install"
+
+    # Python — requirements.txt takes priority over requirements-dev.txt
+    req_file = None
+    if (directory / "requirements.txt").exists():
+        req_file = "requirements.txt"
+    elif (directory / "requirements-dev.txt").exists():
+        req_file = "requirements-dev.txt"
+
+    if req_file:
+        return f"pip install -r {req_file}"
+    if (directory / "pyproject.toml").exists():
+        return "pip install -e ."
+
+    # Go
+    if (directory / "go.mod").exists():
+        return "go mod download"
+
+    return None
+
+
+# ── Monorepo detection ─────────────────────────────────────────────────────────
+def _is_monorepo(root: Path) -> bool:
+    """Heuristic: looks like a monorepo if packages/ or apps/ exist with 2+ subdirs."""
+    for dirname in ("packages", "apps"):
+        candidate = root / dirname
+        if candidate.is_dir():
+            subdirs = [d for d in candidate.iterdir() if d.is_dir()]
+            if len(subdirs) >= 2:
+                return True
+    return False
+
+
+# ── Main discovery function ────────────────────────────────────────────────────
+def discover_services(root: Optional[str] = None) -> Tuple[List[Service], List[str]]:
+    """Scan project and return (services, warnings).
+
+    Returns up to 2 services (one frontend, one backend).
+    Warnings are printed by the caller before starting.
+    """
+    root_path = Path(root) if root else Path.cwd()
+    warnings: List[str] = []
+
+    # Monorepo guard
+    if _is_monorepo(root_path):
+        warnings.append(
+            "Monorepo structure detected (packages/ or apps/ with multiple subdirs). "
+            "Auto-discovery may be inaccurate. Run 'devlauncher init' to create a dev.toml."
+        )
+
+    # Scan candidate directories (immediate subdirs + root itself)
+    candidates: List[_DirScore] = []
+
+    # Check root
+    root_score = _score_directory(root_path)
+    root_score.path = root_path
+    if root_score.frontend_score > 0 or root_score.backend_score > 0:
+        candidates.append(root_score)
+
+    # Check subdirs
+    for entry in sorted(root_path.iterdir()):
+        if not entry.is_dir():
+            continue
+        if entry.name in _SKIP_DIRS or entry.name.startswith("."):
+            continue
+        score = _score_directory(entry)
+        if score.frontend_score > 0 or score.backend_score > 0:
+            candidates.append(score)
+
+    # Pick best frontend and backend
+    frontend_candidates = sorted(
+        [c for c in candidates if c.frontend_score > 0],
+        key=lambda c: c.frontend_score, reverse=True,
+    )
+    backend_candidates = sorted(
+        [c for c in candidates if c.backend_score > 0],
+        key=lambda c: c.backend_score, reverse=True,
+    )
+
+    # Warn if multiple strong candidates per role
+    if len(frontend_candidates) >= 2:
+        top, second = frontend_candidates[0], frontend_candidates[1]
+        if second.frontend_score >= HIGH:
+            warnings.append(
+                f"Multiple frontend candidates found: '{top.path.name}' (score {top.frontend_score}) "
+                f"and '{second.path.name}' (score {second.frontend_score}). "
+                f"Using '{top.path.name}'. Run 'devlauncher init' if wrong."
+            )
+
+    if len(backend_candidates) >= 2:
+        top, second = backend_candidates[0], backend_candidates[1]
+        if second.backend_score >= HIGH:
+            warnings.append(
+                f"Multiple backend candidates found: '{top.path.name}' (score {top.backend_score}) "
+                f"and '{second.path.name}' (score {second.backend_score}). "
+                f"Using '{top.path.name}'. Run 'devlauncher init' if wrong."
+            )
+
+    services: List[Service] = []
+
+    # Build frontend service
+    if frontend_candidates:
+        fs = frontend_candidates[0]
+        confidence = _score_to_confidence(fs.frontend_score)
+        if confidence != SKIP:
+            cmd, port = _infer_frontend(fs)
+            cwd = str(fs.path.relative_to(root_path)) if fs.path != root_path else "."
+            svc_warnings = list(fs.warnings)
+            if confidence == UNCERTAIN:
+                svc_warnings.append(
+                    f"Low confidence for frontend in '{fs.path.name}' (score {fs.frontend_score}). "
+                    "Run 'devlauncher init' to verify."
+                )
+            services.append(Service(
+                name="web",
+                cmd=cmd,
+                port=port,
+                cwd=cwd,
+                env={},
+                install_cmd=_infer_install_cmd(fs),
+            ))
+            warnings.extend(svc_warnings)
+    else:
+        warnings.append("No frontend service detected.")
+
+    # Build backend service
+    if backend_candidates:
+        bs = backend_candidates[0]
+        confidence = _score_to_confidence(bs.backend_score)
+        if confidence != SKIP:
+            cmd, port, extra_warnings = _infer_backend(bs)
+            cwd = str(bs.path.relative_to(root_path)) if bs.path != root_path else "."
+            svc_warnings = list(bs.warnings) + extra_warnings
+            if confidence == UNCERTAIN:
+                svc_warnings.append(
+                    f"Low confidence for backend in '{bs.path.name}' (score {bs.backend_score}). "
+                    "Run 'devlauncher init' to verify."
+                )
+            services.append(Service(
+                name="api",
+                cmd=cmd,
+                port=port,
+                cwd=cwd,
+                env={},
+                install_cmd=_infer_install_cmd(bs),
+            ))
+            warnings.extend(svc_warnings)
+    else:
+        warnings.append("No backend service detected.")
+
+    # 3+ services total → recommend dev.toml
+    total = len(frontend_candidates) + len(backend_candidates)
+    if total >= 4:
+        warnings.append(
+            f"{total} potential services found. "
+            "For complex projects, 'devlauncher init' is strongly recommended."
+        )
+
+    return services, warnings
+
+
+# ── TOML serialisation ─────────────────────────────────────────────────────────
+def services_to_toml(services: List[Service]) -> str:
+    """Serialise discovered services to a dev.toml string.
+
+    Written when the user confirms auto-discovery results, so subsequent
+    runs skip discovery entirely and use this file directly.
+    """
+    lines: List[str] = [
+        "# Generated by devlauncher auto-discovery.",
+        "# Edit freely - devlauncher will use this file on all future runs.",
+        "",
+    ]
+    for svc in services:
+        lines.append(f"[services.{svc.name}]")
+        lines.append(f'cmd = "{svc.cmd}"')
+        lines.append(f"port = {svc.port}")
+        lines.append(f'cwd = "{svc.cwd}"')
+        if svc.install_cmd:
+            lines.append(f'install_cmd = "{svc.install_cmd}"')
+        if svc.env:
+            env_parts = ", ".join(
+                f'{k} = "{v}"' for k, v in svc.env.items()
+            )
+            lines.append(f"env = {{ {env_parts} }}")
+        lines.append("")
+    return "\n".join(lines)

devlauncher/installer.py

@@ -0,0 +1,99 @@
+"""Dependency install detection and execution.
+
+Before starting services, devlauncher checks whether dependencies are present
+and runs the appropriate install command if not.
+
+Detection heuristics:
+  Node.js  — node_modules/ missing, or lock file newer than node_modules/
+  Python   — no .venv/, venv/, or env/ directory present
+  Go       — go mod download is idempotent; always run
+"""
+
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .config import Service
+
+# Import ANSI codes used for [INSTALL:NAME] labels
+from .runner import BOLD, RESET
+
+_NODE_INSTALL_PREFIXES = ("npm install", "yarn install", "pnpm install", "bun install")
+_NODE_LOCK_FILES = ("package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb")
+_PYTHON_INSTALL_PREFIXES = ("pip install", "uv pip install", "uv sync", "poetry install")
+_PYTHON_VENV_DIRS = (".venv", "venv", "env")
+
+
+def needs_install(service: "Service") -> bool:
+    """Return True if the service's dependencies need to be installed.
+
+    Returns False immediately if service.install_cmd is None or empty.
+    """
+    if not service.install_cmd:
+        return False
+
+    cwd = Path(service.cwd)
+    cmd = service.install_cmd
+
+    # ── Node.js ────────────────────────────────────────────────────────────────
+    if any(cmd.startswith(prefix) for prefix in _NODE_INSTALL_PREFIXES):
+        node_modules = cwd / "node_modules"
+        if not node_modules.exists():
+            return True
+        # Stale check: any lock file newer than node_modules/ → reinstall
+        nm_mtime = node_modules.stat().st_mtime
+        for lock_name in _NODE_LOCK_FILES:
+            lock_path = cwd / lock_name
+            if lock_path.exists() and lock_path.stat().st_mtime > nm_mtime:
+                return True
+        return False
+
+    # ── Python ─────────────────────────────────────────────────────────────────
+    if any(cmd.startswith(prefix) for prefix in _PYTHON_INSTALL_PREFIXES):
+        for venv_dir in _PYTHON_VENV_DIRS:
+            if (cwd / venv_dir).is_dir():
+                return False
+        return True
+
+    # ── Go: go mod download is fast and idempotent — always run ───────────────
+    if cmd.startswith("go mod download"):
+        return True
+
+    return False
+
+
+def run_install(service: "Service", color: str) -> int:
+    """Run service.install_cmd, streaming output with a colored label prefix.
+
+    Returns the process exit code. Callers should warn on non-zero but
+    should NOT abort — services can still start even if install partially
+    fails (e.g. optional dev deps).
+    """
+    if not service.install_cmd:
+        return 0
+
+    label = f"INSTALL:{service.name.upper()}"
+    is_win = sys.platform == "win32"
+    cmd = service.install_cmd
+
+    print(f"{color}{BOLD}[{label}]{RESET} {cmd}", flush=True)
+
+    proc = subprocess.Popen(
+        cmd if is_win else shlex.split(cmd),
+        cwd=service.cwd or None,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        shell=is_win,
+    )
+
+    for line in proc.stdout:  # type: ignore[union-attr]
+        stripped = line.rstrip()
+        if stripped:
+            print(f"{color}{BOLD}[{label}]{RESET} {stripped}", flush=True)
+
+    proc.wait()
+    return proc.returncode

devlauncher/ports.py

@@ -0,0 +1,30 @@
+"""Port detection utilities.
+
+Checks both IPv4 (127.0.0.1) and IPv6 (::1) localhost because Node.js 18+
+binds to ::1 by default. Checking only 127.0.0.1 gives false "port free"
+results when Vite or other Node-based servers are running.
+"""
+
+import socket
+
+
+def _is_port_free(port: int) -> bool:
+    """Return True only if port is free on both IPv4 and IPv6 localhost."""
+    for family, addr in [
+        (socket.AF_INET,  "127.0.0.1"),
+        (socket.AF_INET6, "::1"),
+    ]:
+        try:
+            with socket.socket(family, socket.SOCK_STREAM) as s:
+                s.bind((addr, port))
+        except OSError:
+            return False
+    return True
+
+
+def find_free_port(start: int) -> int:
+    """Return the first free port at or above `start`."""
+    port = start
+    while not _is_port_free(port):
+        port += 1
+    return port

devlauncher/runner.py

@@ -0,0 +1,117 @@
+"""Service runner: subprocess lifecycle, log streaming, graceful shutdown.
+
+Each service runs as a subprocess with stdout/stderr merged. Two daemon
+threads per service consume the output and print it with a colored prefix
+([API], [WEB], etc.) so all services are visible in one terminal.
+
+Shutdown is two-phase:
+  1. SIGTERM all processes, wait up to 5 seconds each
+  2. SIGKILL any that did not exit in time
+"""
+
+import os
+import shlex
+import signal
+import subprocess
+import sys
+import threading
+from typing import List
+
+from .config import Service
+
+# ANSI colors — cycling palette for arbitrary number of services
+RESET  = "\033[0m"
+BOLD   = "\033[1m"
+YELLOW = "\033[93m"
+
+_PALETTE = [
+    "\033[94m",  # blue
+    "\033[92m",  # green
+    "\033[95m",  # magenta
+    "\033[96m",  # cyan
+    "\033[91m",  # red
+    "\033[93m",  # yellow
+]
+
+
+def _enable_windows_ansi() -> None:
+    """Enable ANSI escape codes in Windows 10+ console."""
+    if sys.platform != "win32":
+        return
+    try:
+        import ctypes
+        handle = ctypes.windll.kernel32.GetStdHandle(-11)
+        mode = ctypes.c_ulong()
+        ctypes.windll.kernel32.GetConsoleMode(handle, ctypes.byref(mode))
+        ctypes.windll.kernel32.SetConsoleMode(handle, mode.value | 0x0004)
+    except Exception:
+        pass
+
+
+def _stream(proc: subprocess.Popen, label: str, color: str) -> None:
+    """Read lines from proc.stdout and print with colored label prefix."""
+    try:
+        for line in proc.stdout:  # type: ignore[union-attr]
+            stripped = line.rstrip()
+            if stripped:
+                print(f"{color}{BOLD}[{label}]{RESET} {stripped}", flush=True)
+    except ValueError:
+        # Pipe closed (process exited) — normal during shutdown
+        pass
+
+
+def run_services(services: List[Service]) -> None:
+    """Start all services, stream their logs, and block until they exit.
+
+    Handles SIGINT (Ctrl+C) and SIGTERM with graceful two-phase shutdown.
+    """
+    _enable_windows_ansi()
+
+    is_win = sys.platform == "win32"
+    procs: list[tuple[subprocess.Popen, str, str]] = []
+
+    for i, svc in enumerate(services):
+        color = _PALETTE[i % len(_PALETTE)]
+        label = svc.name.upper()
+
+        env = os.environ.copy()
+        env["PYTHONUNBUFFERED"] = "1"
+        env["FORCE_COLOR"] = "1"
+        env.update(svc.env)
+
+        # shlex.split handles quoted args correctly on POSIX; shell=True on Windows
+        cmd = svc.cmd if is_win else shlex.split(svc.cmd)
+
+        proc = subprocess.Popen(
+            cmd,
+            cwd=svc.cwd or None,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            env=env,
+            shell=is_win,
+        )
+        procs.append((proc, label, color))
+        threading.Thread(
+            target=_stream,
+            args=(proc, label, color),
+            daemon=True,
+        ).start()
+
+    def _shutdown(sig=None, frame=None) -> None:
+        print(f"\n{YELLOW}⏹  Shutting down...{RESET}", flush=True)
+        for proc, _, _ in procs:
+            proc.terminate()
+        for proc, _, _ in procs:
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT,  _shutdown)
+    signal.signal(signal.SIGTERM, _shutdown)
+
+    # Block until all processes exit naturally
+    for proc, _, _ in procs:
+        proc.wait()

devlauncher-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: devlauncher
+Version: 0.1.0
+Summary: Start all your dev services with one command
+Author-email: Ayush Jhunjhunwala <ayushjhun13@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/the-non-expert/devlauncher
+Project-URL: Repository, https://github.com/the-non-expert/devlauncher
+Project-URL: Bug Tracker, https://github.com/the-non-expert/devlauncher/issues
+Keywords: dev,services,runner,process,developer-tools,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli; python_version < "3.11"
+Dynamic: license-file
+
+# devlauncher
+
+Start all your dev services with one command.
+
+## The Problem
+
+Every multi-service project means opening multiple terminals, remembering startup commands, and
+dealing with silent port conflicts. devlauncher runs everything in one place.
+
+## Install
+
+```
+pip install devlauncher
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+**Zero-config** — run in any project root:
+
+```
+cd my-project
+devlauncher
+```
+
+devlauncher scans your project, detects services (Vite, FastAPI, Django, etc.), shows you what it found,
+and asks once to confirm. On confirmation it writes a `dev.toml` and starts everything. It never
+asks again.
+
+**Manual** — create a `dev.toml`:
+
+```toml
+[services.api]
+cmd = "uvicorn main:app --reload --port {self.port}"
+port = 8000
+cwd = "api"
+
+[services.web]
+cmd = "npm run dev -- --port {self.port}"
+port = 5173
+cwd = "frontend"
+env = { VITE_API_URL = "http://localhost:{api.port}" }
+```
+
+Then run:
+
+```
+devlauncher
+```
+
+## How It Works
+
+- Scans subdirectories for framework signals (package.json, requirements.txt, Cargo.toml, etc.)
+- Infers services by role (frontend/backend), shows a discovery report
+- Prompts once to confirm; writes `dev.toml` so it never asks again
+- Runs dependency install phase (`npm install`, `pip install`, etc.) if needed
+- Checks ports on both IPv4 and IPv6 — finds a free port if your preferred one is taken
+- Starts all services with color-coded, prefixed log output
+- Shuts down cleanly on Ctrl+C (SIGTERM → 5s timeout → SIGKILL)
+
+## Configuration (dev.toml)
+
+All fields:
+
+```toml
+[services.<name>]
+cmd         = "command to start this service"          # required
+port        = 8000                                     # required; preferred port
+cwd         = "subdirectory"                           # optional; default is project root
+install_cmd = "pip install -r requirements.txt"        # optional; runs when deps are missing
+env         = { KEY = "value" }                        # optional; supports port refs
+```
+
+**Port references** — resolved after conflict detection, so they always reflect the actual port in use:
+
+- `{self.port}` — this service's resolved port
+- `{api.port}` — another service's resolved port (use the service name as the key)
+
+## Features
+
+- Zero-config auto-discovery (Vite, Next.js, Nuxt, FastAPI, Django, Flask, Go, Rust)
+- Dual IPv4 + IPv6 port conflict detection (handles Node.js 18+ IPv6-default binding)
+- Dependency install phase with per-service `install_cmd`
+- Port reference interpolation (`{self.port}`, `{api.port}`)
+- Color-coded, prefixed log output per service
+- Graceful shutdown (SIGTERM → 5s timeout → SIGKILL)
+- Cross-platform: macOS, Linux, Windows
+- Zero external dependencies on Python 3.11+ (`tomli` required on 3.9–3.10)
+
+## Supported Frameworks (auto-discovery)
+
+| Role | Detected |
+|------|----------|
+| Frontend | Vite, Next.js, Nuxt, Angular, SvelteKit |
+| Backend | FastAPI, Django, Flask, Go, Rust (Cargo) |
+| Package managers | npm, yarn, pnpm, bun, pip, go mod |
+
+## License
+
+MIT

devlauncher-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+devlauncher/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+devlauncher/cli.py,sha256=h46QLk2qngB7lyuxv8kRl1ldpE1iA7V2-PMiNFetRzM,6299
+devlauncher/config.py,sha256=5vq_JXPo75tDfkArVxvxECo-lp31bleoK4O_Fl88MS0,3499
+devlauncher/discovery.py,sha256=-vKPQLtZmCICPN9QGXoX4hq0qnyhDp_dCESzC-xt0X0,21008
+devlauncher/installer.py,sha256=b0r8emmFf_cXJLQ9cUwYsHLN-NKGuRf6Mg03ovb5o6s,3607
+devlauncher/ports.py,sha256=v_o8kGd3jcMmUUAXmz4mrFBggRLvncT4HWRBFIi7qzs,843
+devlauncher/runner.py,sha256=t3UOaEisJZpmTJgL-O4u015j7oSIOmxzIhTk0tYEmo8,3438
+devlauncher-0.1.0.dist-info/licenses/LICENSE,sha256=dmRhwnGhQW7_A1m6qyQqnBSoupcXfRv78CgwPrLlSEg,1075
+devlauncher-0.1.0.dist-info/METADATA,sha256=8DQ6BFjn7FHHTCRXRSiP3oISXXW1RrqzgvZHfVb5ST8,4245
+devlauncher-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+devlauncher-0.1.0.dist-info/entry_points.txt,sha256=bsLenVO6QJlohgAHzfGsHD0YOYRDYLBSZf8L4elGIko,53
+devlauncher-0.1.0.dist-info/top_level.txt,sha256=ayIdVHnZQXL8uuRdi7vWhrtWBYGQsaEp0Ede3pEmtf8,12
+devlauncher-0.1.0.dist-info/RECORD,,

devlauncher-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

devlauncher-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devlauncher = devlauncher.cli:main

devlauncher-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayush Jhunjhunwala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devlauncher-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+devlauncher