ctrlrelay 0.2.0__tar.gz → 0.2.1__tar.gz

{ctrlrelay-0.2.0 → ctrlrelay-0.2.1}/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-04-28
+
+Patch release. Fixes a long-standing UX bug where `ctrlrelay` could
+only be invoked from a directory containing `config/orchestrator.yaml`.
+
+### Fixed
+
+- **`--config` now auto-discovers `orchestrator.yaml`.** Every CLI
+  command previously hardcoded a relative `config/orchestrator.yaml`
+  default, so running `ctrlrelay status` (or any other subcommand)
+  from `/tmp`, `$HOME`, or anywhere outside the project root failed
+  with `Config file not found: config/orchestrator.yaml`. The CLI
+  now resolves the config in this order:
+
+  1. The path passed to `--config` / `-c`, if any.
+  2. `$CTRLRELAY_CONFIG` (a new environment variable).
+  3. `./config/orchestrator.yaml`, walking up from the current
+     working directory to the filesystem root — matches how `git`
+     and `uv` find their config.
+  4. `$XDG_CONFIG_HOME/ctrlrelay/orchestrator.yaml` (defaults to
+     `~/.config/ctrlrelay/orchestrator.yaml`).
+
+  When nothing matches, the error now lists every location searched
+  so it's clear where to drop the file or which env var to set.
+  Daemon spawn paths (`ctrlrelay poller start` re-exec under
+  `--foreground`) pass the *resolved* absolute path to the child so
+  the daemon doesn't break when launchd starts it from `/`.
+
 ## [0.2.0] - 2026-04-27
 
 Minor release. Adds bulk repo operations driven by

{ctrlrelay-0.2.0 → ctrlrelay-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrlrelay
-Version: 0.2.0
+Version: 0.2.1
 Summary: Local-first orchestrator for headless coding agents across multiple GitHub repos
 Project-URL: Homepage, https://github.com/AInvirion/ctrlrelay
 Project-URL: Documentation, https://ainvirion.github.io/ctrlrelay/

{ctrlrelay-0.2.0 → ctrlrelay-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrlrelay"
-version = "0.2.0"
+version = "0.2.1"
 description = "Local-first orchestrator for headless coding agents across multiple GitHub repos"
 readme = "README.md"
 requires-python = ">=3.12"

{ctrlrelay-0.2.0 → ctrlrelay-0.2.1}/src/ctrlrelay/cli.py

@@ -7,7 +7,7 @@ from rich.console import Console
 from rich.table import Table
 
 from ctrlrelay import __version__
-from ctrlrelay.core.config import ConfigError, load_config
+from ctrlrelay.core.config import ConfigError, load_config, resolve_config_path
 from ctrlrelay.core.github import GitHubCLI, GitHubError
 from ctrlrelay.core.pr_verifier import PRVerifier
 
@@ -39,6 +39,15 @@ def main(
     """ctrlrelay orchestrator CLI."""
 
 
+def _resolve_config_or_exit(config_path: str | None) -> Path:
+    """Resolve --config (or auto-discover) and exit with a friendly error if missing."""
+    try:
+        return resolve_config_path(config_path)
+    except ConfigError as e:
+        console.print(f"[red]Error loading config:[/red] {e}")
+        raise typer.Exit(1)
+
+
 # Subcommand groups
 config_app = typer.Typer(help="Configuration commands.")
 app.add_typer(config_app, name="config")
@@ -46,15 +55,15 @@ app.add_typer(config_app, name="config")
 
 @config_app.command("validate")
 def config_validate(
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """Validate orchestrator.yaml configuration."""
-    path = Path(config_path)
+    path = _resolve_config_or_exit(config_path)
 
     if not path.exists():
         console.print(f"[red]Error:[/red] Config file not found: {path}")
@@ -75,15 +84,15 @@ def config_validate(
 
 @config_app.command("repos")
 def config_repos(
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """List configured repositories."""
-    path = Path(config_path)
+    path = _resolve_config_or_exit(config_path)
 
     try:
         config = load_config(path)
@@ -112,13 +121,13 @@ skills_app = typer.Typer(help="Skill management commands.")
 app.add_typer(skills_app, name="skills")
 
 
-def _resolve_skills_dir(skills_path: str | None, config_path: str) -> Path:
+def _resolve_skills_dir(skills_path: str | None, config_path: str | None) -> Path:
     """Resolve skills directory from flag or config."""
     if skills_path is not None:
         skills_dir = Path(skills_path).expanduser().resolve()
     else:
         try:
-            config = load_config(config_path)
+            config = load_config(resolve_config_path(config_path))
             skills_dir = config.paths.skills.expanduser().resolve()
         except ConfigError as e:
             console.print(f"[red]Error loading config:[/red] {e}")
@@ -140,11 +149,11 @@ def skills_audit(
         "-p",
         help="Path to skills directory (default: from config)",
     ),
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """Audit skills for orchestrator readiness."""
@@ -176,11 +185,11 @@ def skills_list(
         "-p",
         help="Path to skills directory (default: from config)",
     ),
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """List available skills."""
@@ -209,10 +218,10 @@ bridge_app = typer.Typer(help="Telegram bridge commands.")
 app.add_typer(bridge_app, name="bridge")
 
 
-def _get_socket_path(config_path: str) -> Path:
+def _get_socket_path(config_path: str | None) -> Path:
     """Get socket path from config."""
     try:
-        config = load_config(config_path)
+        config = load_config(resolve_config_path(config_path))
         if config.transport.telegram:
             return config.transport.telegram.socket_path.expanduser().resolve()
     except ConfigError:
@@ -227,11 +236,11 @@ def _get_bridge_pid_file(socket_path: Path) -> Path:
 
 @bridge_app.command("start")
 def bridge_start(
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
     foreground: bool = typer.Option(
         False,
@@ -251,7 +260,7 @@ def bridge_start(
     import sys
 
     try:
-        config = load_config(config_path)
+        config = load_config(resolve_config_path(config_path))
     except ConfigError as e:
         console.print(f"[red]Error loading config:[/red] {e}")
         raise typer.Exit(1)
@@ -400,11 +409,11 @@ def bridge_start(
 
 @bridge_app.command("stop")
 def bridge_stop(
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """Stop the Telegram bridge."""
@@ -433,11 +442,11 @@ def bridge_stop(
 
 @bridge_app.command("status")
 def bridge_status(
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """Check bridge status."""
@@ -477,11 +486,11 @@ def bridge_test(
         "-m",
         help="Message to send",
     ),
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """Send a test message to verify bridge is working."""
@@ -518,11 +527,11 @@ app.add_typer(run_app, name="run")
 
 @run_app.command("secops")
 def run_secops(
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
     repo: str = typer.Option(
         None,
@@ -541,7 +550,7 @@ def run_secops(
     from ctrlrelay.dashboard.client import DashboardClient
     from ctrlrelay.pipelines.secops import run_secops_all
 
-    path = Path(config_path)
+    path = _resolve_config_or_exit(config_path)
 
     try:
         config = load_config(path)
@@ -635,11 +644,11 @@ def run_dev(
         "-r",
         help="Run on specific repo only",
     ),
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """Run dev pipeline for a GitHub issue."""
@@ -651,7 +660,7 @@ def run_dev(
     from ctrlrelay.core.worktree import WorktreeManager
     from ctrlrelay.pipelines.dev import run_dev_issue
 
-    path = Path(config_path)
+    path = _resolve_config_or_exit(config_path)
 
     try:
         config = load_config(path)
@@ -830,10 +839,10 @@ poller_app = typer.Typer(help="Issue poller commands.")
 app.add_typer(poller_app, name="poller")
 
 
-def _get_poller_pid_file(config_path: str) -> Path:
+def _get_poller_pid_file(config_path: str | None) -> Path:
     """Get PID file path for poller process."""
     try:
-        config = load_config(config_path)
+        config = load_config(resolve_config_path(config_path))
         return config.paths.state_db.parent / "poller.pid"
     except ConfigError:
         pass
@@ -842,11 +851,11 @@ def _get_poller_pid_file(config_path: str) -> Path:
 
 @poller_app.command("start")
 def poller_start(
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
     foreground: bool = typer.Option(
         False,
@@ -873,13 +882,15 @@ def poller_start(
     import subprocess
     import sys
 
+    resolved_config = _resolve_config_or_exit(config_path)
+
     try:
-        config = load_config(Path(config_path))
+        config = load_config(resolved_config)
     except ConfigError as e:
         console.print(f"[red]Error loading config:[/red] {e}")
         raise typer.Exit(1)
 
-    pid_file = _get_poller_pid_file(config_path)
+    pid_file = _get_poller_pid_file(str(resolved_config))
     if pid_file.exists():
         try:
             pid = int(pid_file.read_text().strip())
@@ -903,7 +914,7 @@ def poller_start(
             "poller",
             "start",
             "--config",
-            config_path,
+            str(resolved_config),
             "--interval",
             str(interval),
             "--foreground",
@@ -1917,11 +1928,11 @@ def poller_start(
 
 @poller_app.command("stop")
 def poller_stop(
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """Stop the issue poller."""
@@ -1949,11 +1960,11 @@ def poller_stop(
 
 @poller_app.command("status")
 def poller_status(
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """Check poller status."""
@@ -1982,18 +1993,18 @@ def version() -> None:
 
 @app.command("status")
 def status(
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml",
+    config_path: str | None = typer.Option(
+        None,
         "--config",
         "-c",
-        help="Path to orchestrator.yaml",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
 ) -> None:
     """Show orchestrator status and active sessions."""
     from ctrlrelay.core.state import StateDB
 
     try:
-        config = load_config(config_path)
+        config = load_config(resolve_config_path(config_path))
     except ConfigError as e:
         console.print(f"[red]Error loading config:[/red] {e}")
         raise typer.Exit(1)
@@ -2063,10 +2074,10 @@ repos_app = typer.Typer(help="Bulk repo operations across the orchestrator manif
 app.add_typer(repos_app, name="repos")
 
 
-def _iter_repos(config_path: str, filter_str: str | None):
+def _iter_repos(config_path: str | None, filter_str: str | None):
     """Yield (name, org, repo, remote) tuples for repos in the orchestrator config."""
     try:
-        config = load_config(config_path)
+        config = load_config(resolve_config_path(config_path))
     except ConfigError as e:
         console.print(f"[red]Error loading config:[/red] {e}")
         raise typer.Exit(1)
@@ -2088,8 +2099,11 @@ def _iter_repos(config_path: str, filter_str: str | None):
 @repos_app.command("clone-all")
 def repos_clone_all(
     dest: Path = typer.Argument(..., help="Workspace root (e.g. ~/code/myproject)"),
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml", "--config", "-c", help="Path to orchestrator.yaml"
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
     filter_str: str | None = typer.Option(
         None, "--filter", "-f", help="Substring filter on repo name (e.g. 'AInvirion')"
@@ -2139,8 +2153,11 @@ def repos_clone_all(
 @repos_app.command("pull-all")
 def repos_pull_all(
     dest: Path = typer.Argument(..., help="Workspace root to pull (must already be cloned)"),
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml", "--config", "-c", help="Path to orchestrator.yaml"
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
     filter_str: str | None = typer.Option(
         None, "--filter", "-f", help="Substring filter on repo name"
@@ -2213,8 +2230,11 @@ def repos_pull_all(
 @repos_app.command("status")
 def repos_status(
     dest: Path = typer.Argument(..., help="Workspace root to inspect"),
-    config_path: str = typer.Option(
-        "config/orchestrator.yaml", "--config", "-c", help="Path to orchestrator.yaml"
+    config_path: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
     filter_str: str | None = typer.Option(
         None, "--filter", "-f", help="Substring filter on repo name"

{ctrlrelay-0.2.0 → ctrlrelay-0.2.1}/src/ctrlrelay/core/config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import re
 from enum import Enum
 from pathlib import Path
@@ -10,6 +11,10 @@ from typing import Any
 import yaml
 from pydantic import BaseModel, Field, field_validator, model_validator
 
+CONFIG_FILENAME = "orchestrator.yaml"
+CONFIG_SUBDIR = "config"
+CONFIG_ENV_VAR = "CTRLRELAY_CONFIG"
+
 
 class ConfigError(Exception):
     """Raised when configuration loading or validation fails."""
@@ -286,6 +291,58 @@ class Config(BaseModel):
         return v
 
 
+def _xdg_config_home() -> Path:
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg).expanduser()
+    return Path.home() / ".config"
+
+
+def default_config_search_paths() -> list[Path]:
+    """Ordered list of locations searched when no --config is supplied.
+
+    Order: $CTRLRELAY_CONFIG, then ./config/orchestrator.yaml walking up from
+    cwd to filesystem root, then $XDG_CONFIG_HOME/ctrlrelay/orchestrator.yaml
+    (defaulting to ~/.config/ctrlrelay/orchestrator.yaml).
+    """
+    paths: list[Path] = []
+
+    env = os.environ.get(CONFIG_ENV_VAR)
+    if env:
+        paths.append(Path(env).expanduser())
+
+    cwd = Path.cwd().resolve()
+    for parent in [cwd, *cwd.parents]:
+        paths.append(parent / CONFIG_SUBDIR / CONFIG_FILENAME)
+
+    paths.append(_xdg_config_home() / "ctrlrelay" / CONFIG_FILENAME)
+
+    return paths
+
+
+def resolve_config_path(explicit: Path | str | None = None) -> Path:
+    """Resolve the orchestrator.yaml path.
+
+    If ``explicit`` is given, it is returned as-is (the caller decides how to
+    handle a missing file). Otherwise, the first existing path among the
+    defaults is returned. If nothing exists, raises ConfigError listing the
+    locations searched so users know where to put the file.
+    """
+    if explicit is not None:
+        return Path(explicit).expanduser()
+
+    candidates = default_config_search_paths()
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+
+    searched = "\n  ".join(str(p) for p in candidates)
+    raise ConfigError(
+        "No orchestrator.yaml found. Set $CTRLRELAY_CONFIG, pass --config, "
+        "or place the file at one of:\n  " + searched
+    )
+
+
 def load_config(path: Path | str) -> Config:
     """Load and validate configuration from a YAML file.
 

{ctrlrelay-0.2.0 → ctrlrelay-0.2.1}/tests/test_config.py

@@ -5,7 +5,13 @@ from pathlib import Path
 import pytest
 import yaml
 
-from ctrlrelay.core.config import AutomationConfig, Config, ConfigError, load_config
+from ctrlrelay.core.config import (
+    AutomationConfig,
+    Config,
+    ConfigError,
+    load_config,
+    resolve_config_path,
+)
 
 
 class TestConfigLoading:
@@ -246,3 +252,69 @@ class TestAutomationExcludeLabels:
         config = load_config(cfg_path)
 
         assert config.repos[0].automation.exclude_labels == ["no-agent", "wontfix"]
+
+
+class TestResolveConfigPath:
+    def test_explicit_path_returned_as_is(self, tmp_path: Path) -> None:
+        """An explicit --config value is returned even if it doesn't exist (caller validates)."""
+        target = tmp_path / "anywhere.yaml"
+        assert resolve_config_path(target) == target
+        assert resolve_config_path(str(target)) == target
+
+    def test_env_var_takes_precedence(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """$CTRLRELAY_CONFIG wins over cwd-walk-up and home dir."""
+        env_target = tmp_path / "env.yaml"
+        env_target.write_text("version: '1'\n")
+        monkeypatch.setenv("CTRLRELAY_CONFIG", str(env_target))
+        monkeypatch.chdir(tmp_path)
+        # Even with a config/orchestrator.yaml in cwd, env wins.
+        cwd_cfg = tmp_path / "config" / "orchestrator.yaml"
+        cwd_cfg.parent.mkdir()
+        cwd_cfg.write_text("version: '1'\n")
+
+        assert resolve_config_path(None) == env_target
+
+    def test_walks_up_from_cwd(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """When run from a subdir, finds config/orchestrator.yaml in an ancestor."""
+        monkeypatch.delenv("CTRLRELAY_CONFIG", raising=False)
+        cfg = tmp_path / "config" / "orchestrator.yaml"
+        cfg.parent.mkdir()
+        cfg.write_text("version: '1'\n")
+        deep = tmp_path / "a" / "b" / "c"
+        deep.mkdir(parents=True)
+        monkeypatch.chdir(deep)
+
+        assert resolve_config_path(None) == cfg
+
+    def test_falls_back_to_xdg_config_home(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """With no env var and no cwd-walk-up hit, uses $XDG_CONFIG_HOME/ctrlrelay/."""
+        monkeypatch.delenv("CTRLRELAY_CONFIG", raising=False)
+        xdg = tmp_path / "xdg"
+        cfg = xdg / "ctrlrelay" / "orchestrator.yaml"
+        cfg.parent.mkdir(parents=True)
+        cfg.write_text("version: '1'\n")
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(xdg))
+        empty_cwd = tmp_path / "empty"
+        empty_cwd.mkdir()
+        monkeypatch.chdir(empty_cwd)
+
+        assert resolve_config_path(None) == cfg
+
+    def test_raises_when_nothing_found(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """No env var, no cwd hit, no XDG hit → ConfigError lists searched paths."""
+        monkeypatch.delenv("CTRLRELAY_CONFIG", raising=False)
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "nope"))
+        empty = tmp_path / "empty"
+        empty.mkdir()
+        monkeypatch.chdir(empty)
+
+        with pytest.raises(ConfigError, match="No orchestrator.yaml found"):
+            resolve_config_path(None)