ctrlrelay 0.3.0__tar.gz → 0.4.0__tar.gz

{ctrlrelay-0.3.0 → ctrlrelay-0.4.0}/.gitignore

@@ -40,3 +40,14 @@ uv.lock
 
 # Operator-private notes (runbooks, personal cheatsheets).
 notes/
+
+# Rendered service unit files. `ctrlrelay install launchd|systemd`
+# substitutes CTRLRELAY_TELEGRAM_TOKEN into a copy of the in-package
+# template and writes it to the system path (~/Library/LaunchAgents on
+# macOS, ~/.config/systemd/user on Linux). The default install command
+# never lands a rendered file inside the repo, but a future flag — or
+# an operator running it with --target-dir pointed at the working tree —
+# would. Defense-in-depth so a `git add .` after such a slip can't
+# scoop the literal token into a commit.
+*.plist
+*.service

{ctrlrelay-0.3.0 → ctrlrelay-0.4.0}/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-08
+
+Minor release. One new feature plus one schema simplification:
+
+- **`ctrlrelay setup`** — first-run onboarding command. Detects every
+  GitHub org you belong to, enumerates non-fork non-archived repos in
+  each, writes a fresh `~/.config/ctrlrelay/orchestrator.yaml`, clones
+  every repo to `~/Projects/<owner.lower()>/<repo>`, optionally
+  configures the personalization sync block, and optionally renders
+  launchd/systemd unit files. Replaces the multi-step manual playbook
+  operators previously had to follow on a new machine. Interactive by
+  default; `--yes` and `--owner` flags make it scriptable.
+- **`paths.owner_aliases` deprecated; lowercase-org-folder convention.**
+  The path resolver now always derives `local_path` as
+  `${repo_root}/${owner.lower()}/${repo}` (closes #128). The previous
+  `owner_aliases` indirection caused `clone-all`/`pull-all`/`status`
+  to disagree with the dev pipeline on where a given repo lived.
+  Parsing of `owner_aliases` is retained so 0.3.x configs still load;
+  a `DeprecationWarning` fires when the block is non-empty.
+
+### Added
+
+- **`ctrlrelay setup`** (closes the onboarding gap reported during the
+  v0.3.0 reinstall flow). Composes existing primitives (gh discovery,
+  config generation, `git clone`, `personalization init`, `install
+  launchd|systemd`) into a single command. Reads
+  `$CTRLRELAY_TELEGRAM_TOKEN` so the rendered plist isn't a
+  placeholder. Refuses to overwrite an existing `orchestrator.yaml`
+  without `--force`.
+- **`repos clone-all` / `pull-all` / `status` accept DEST as
+  optional**. When omitted, each command operates on the
+  config-resolved `local_path` of every repo, so the same path
+  resolution serves the bulk commands and the dev pipeline. Pass DEST
+  to override (lands at `DEST/<owner.lower()>/<repo>`).
+
+### Changed
+
+- **Path resolver: `owner.lower()` is the folder, always.** Closes #128.
+  Affects every command that touches `repo.local_path`. Operators on
+  v0.3.0 with mixed-case folders (e.g. `~/Projects/AInvirion/...`)
+  must either rename the folder, set per-repo `local_path` overrides,
+  or run `ctrlrelay setup --force` to land everything at the new
+  lowercase paths.
+
+### Migration from 0.3.0
+
+- Drop `paths.owner_aliases` from `orchestrator.yaml` (or ignore the
+  deprecation warning until you next regenerate the config).
+- Rename existing on-disk folders to lowercase (e.g.
+  `mv ~/Projects/AInvirion ~/Projects/ainvirion`) — or, easier, run
+  `ctrlrelay setup --force` to clone everything fresh under the new
+  convention.
+
 ## [0.3.0] - 2026-05-08
 
 Minor release. Three additive features: cross-machine **personalization

{ctrlrelay-0.3.0 → ctrlrelay-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrlrelay
-Version: 0.3.0
+Version: 0.4.0
 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.3.0 → ctrlrelay-0.4.0}/docs/cli.md

@@ -41,6 +41,51 @@ ctrlrelay [--version] <command> ...
 Every command that reads config accepts `--config` / `-c` to point at a
 non-default `orchestrator.yaml` (default: `config/orchestrator.yaml`).
 
+## `ctrlrelay setup`
+
+```bash
+ctrlrelay setup [OPTIONS]
+```
+
+First-run onboarding: detect GitHub orgs, enumerate their non-fork
+non-archived repos, write a fresh `~/.config/ctrlrelay/orchestrator.yaml`,
+clone every repo to `~/Projects/<owner.lower()>/<repo>`, and (optionally)
+configure the personalization sync block plus install launchd/systemd unit
+files. Composes the building blocks operators previously had to wire by hand.
+
+The interactive flow asks one question at a time. `--yes` skips prompts and
+accepts every default. Repeat `--owner` to lock the owner list non-interactively.
+
+Key flags:
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--owner OWNER` | (interactive prompt) | Repeatable. When omitted, prompts to pick from accessible owners. |
+| `--repo-root PATH` | `~/Projects` | Where repos land — `~/Projects/<owner.lower()>/<repo>`. |
+| `--config-out PATH` | `~/.config/ctrlrelay/orchestrator.yaml` | Where to write the generated config. |
+| `--timezone TZ` | `UTC` | IANA zone for cron schedules. |
+| `--transport TRANSPORT` | `file_mock` | `telegram` or `file_mock`. |
+| `--telegram-chat-id ID` | none | Required for `--transport=telegram`. |
+| `--personalization-repo OWNER/REPO` | none | Adds a personalization block. |
+| `--no-personalization` | off | Skip the personalization prompt entirely. |
+| `--install-daemons` | (prompted) | Render and write launchd/systemd unit files. Reads `$CTRLRELAY_TELEGRAM_TOKEN` so the rendered plist isn't a placeholder. |
+| `--skip-archived/--include-archived` | skip | gh repo list filter. |
+| `--skip-forks/--include-forks` | skip | gh repo list filter. |
+| `--yes` / `-y` | off | Accept every default; never prompt. |
+| `--force` | off | Overwrite an existing `orchestrator.yaml` (and existing daemon plists when `--install-daemons`). |
+
+Refuses to overwrite an existing config or daemon plist without `--force`.
+Refuses to proceed if `gh auth status` fails — run `gh auth login` first.
+
+After setup completes, the next manual steps are:
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.ctrlrelay.ctrlrelay-poller.plist
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.ctrlrelay.ctrlrelay-bridge.plist
+```
+
+(Or the systemd equivalents on Linux.)
+
 ## `ctrlrelay config`
 
 ### `config validate`

{ctrlrelay-0.3.0 → ctrlrelay-0.4.0}/docs/configuration.md

@@ -55,9 +55,6 @@ paths:
   skills:      "~/.claude/skills"
   # Optional convention for repos[].local_path:
   repo_root:   "~/Projects"
-  owner_aliases:
-    AInvirion: AINVIRION       # GitHub owner -> on-disk folder name
-    SemClone: SEMCL.ONE
 ```
 
 | Key | Type | Required | Description |
@@ -67,8 +64,8 @@ paths:
 | `bare_repos` | path | **yes** | Where ctrlrelay clones bare mirrors of each configured repo. |
 | `contexts` | path | **yes** | Per-repo context directory (looked up as `<contexts>/<owner-repo>/CLAUDE.md`). If a `CLAUDE.md` exists, it is symlinked into the worktree at session start. |
 | `skills` | path | **yes** | Claude Code skills directory used by `ctrlrelay skills audit` and `ctrlrelay skills list`. |
-| `repo_root` | path | no | Convention root for repo clones. When set, `repos[].local_path` may be omitted and is derived as `${repo_root}/${owner_aliases.get(owner, owner)}/${repo}`. Without `repo_root`, every repo entry must declare its own `local_path` (legacy behaviour). |
-| `owner_aliases` | object | no | Map of GitHub owner -> on-disk folder name. Lets the convention work when local folders use a vanity name (`SemClone` repos under `~/Projects/SEMCL.ONE/`). Lookup falls through to the literal owner if not present. |
+| `repo_root` | path | no | Convention root for repo clones. When set, `repos[].local_path` may be omitted and is derived as `${repo_root}/${owner.lower()}/${repo}` (since v0.4.0). Without `repo_root`, every repo entry must declare its own `local_path` (legacy behaviour). |
+| `owner_aliases` | object | no | **Deprecated since v0.4.0.** Pre-0.4.0 this remapped the on-disk folder name (e.g. `SemClone` -> `SEMCL.ONE`). The path resolver now always uses `owner.lower()`, so aliases are no longer consulted. Parsing is retained so 0.3.x configs still load; a `DeprecationWarning` is emitted when a non-empty mapping is supplied. To silence: drop the `owner_aliases` block, rename your on-disk folder to match `owner.lower()`, or set a per-repo `local_path` override for any that genuinely deviate. |
 
 ## claude
 
@@ -181,7 +178,7 @@ repos:
 | Key | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `name` | string | **yes** | — | GitHub `owner/repo` slug. Used for `gh` calls and bare-repo / worktree naming. |
-| `local_path` | path | conditional | derived | Where the repo is checked out on disk for human use. Optional when `paths.repo_root` is set (then derived as `${repo_root}/${owner_aliases.get(owner, owner)}/${repo}`); required otherwise. An explicit value always wins as override. ctrlrelay itself uses bare mirrors under `paths.bare_repos`. |
+| `local_path` | path | conditional | derived | Where the repo is checked out on disk for human use. Optional when `paths.repo_root` is set (then derived as `${repo_root}/${owner.lower()}/${repo}`, since v0.4.0); required otherwise. An explicit value always wins as override. ctrlrelay itself uses bare mirrors under `paths.bare_repos`. |
 | `dev_branch_template` | string | no | `"fix/issue-{n}"` | Branch-name template for dev-pipeline runs. `{n}` is replaced by the issue number. |
 | `automation` | object | no | (defaults) | See [automation](#repos-automation). |
 | `code_review` | object | no | (defaults) | Reserved for code-review policy. Currently unused by the bundled pipelines. |

{ctrlrelay-0.3.0 → ctrlrelay-0.4.0}/docs/getting-started.md

@@ -28,75 +28,52 @@ Optional:
 
 ## Install
 
-Clone the repo and install in editable mode:
+The recommended install is via `pipx`:
 
 ```bash
-git clone https://github.com/AInvirion/ctrlrelay.git
-cd ctrlrelay
+pipx install ctrlrelay
+ctrlrelay --version
+```
 
-# With uv (recommended):
-uv pip install -e .
+Use `uv tool install ctrlrelay` if you prefer uv. For local development, see
+[Development]({{ '/development/' | relative_url }}).
 
-# Or with pip:
-pip install -e .
-```
+## First-run setup
+
+Since v0.4.0, `ctrlrelay setup` does the boring parts of onboarding for you:
+detect every GitHub org you belong to, list the non-fork non-archived repos
+in each, write a fresh `orchestrator.yaml` to `~/.config/ctrlrelay/`, and
+clone every repo to `~/Projects/<owner.lower()>/<repo>`. It can also
+configure the personalization sync block and render daemon unit files for
+launchd (macOS) or systemd (Linux).
 
-This installs the `ctrlrelay` console script. Verify:
+Interactive (recommended for the first machine you set up):
 
 ```bash
-ctrlrelay --version
+ctrlrelay setup
 ```
 
-## Write your first config
+Pick which owners to monitor when prompted. Setup will then enumerate repos,
+write the config, clone everything, and ask whether you want personalization
+sync and background services.
 
-ctrlrelay reads `config/orchestrator.yaml` by default. Start from the example:
+Non-interactive (good for second/third machines once you know the answers):
 
 ```bash
-cp config/orchestrator.yaml.example config/orchestrator.yaml
+ctrlrelay setup --yes \
+  --owner alice \
+  --owner AInvirion \
+  --transport telegram \
+  --telegram-chat-id 12345 \
+  --personalization-repo alice/dotclaude \
+  --install-daemons
 ```
 
-Open `config/orchestrator.yaml` and edit at least:
-
-- `timezone` — your local IANA timezone.
-- `repos[].name` — the `owner/repo` slug of a repository you can push to.
-- `repos[].local_path` — where the local clone lives (or will live) on disk.
-  *Or* set `paths.repo_root` to a workspace root and let the path be
-  derived as `${repo_root}/${owner}/${repo}` (recommended for >1 repo).
-
-`node_id` is optional — when omitted it defaults to your machine's
-hostname (`socket.gethostname()`). Set it explicitly only if the
-hostname is meaningless (CI runners, containers).
-
-A minimal working config:
-
-```yaml
-version: "1"
-timezone: "America/New_York"
-
-paths:
-  state_db: "~/.ctrlrelay/state.db"
-  worktrees: "~/.ctrlrelay/worktrees"
-  bare_repos: "~/.ctrlrelay/repos"
-  contexts: "~/.ctrlrelay/contexts"
-  skills: "~/.claude/skills"
-
-claude:
-  binary: "claude"
-  default_timeout_seconds: 1800
-  output_format: "json"
-
-transport:
-  type: "file_mock"
-  file_mock:
-    inbox: "~/.ctrlrelay/inbox.txt"
-    outbox: "~/.ctrlrelay/outbox.txt"
-
-repos:
-  - name: "your-org/your-repo"
-    local_path: "~/Projects/your-repo"
-```
+`--yes` accepts every default and never prompts. The Telegram bot token is
+read from `$CTRLRELAY_TELEGRAM_TOKEN`; export it before running setup if you
+want it baked into the rendered launchd plist.
 
-Validate it:
+After setup completes, validate:
 
 ```bash
 ctrlrelay config validate
@@ -105,14 +82,22 @@ ctrlrelay config validate
 You should see something like:
 
 ```
-✓ Config valid: config/orchestrator.yaml
+✓ Config valid: ~/.config/ctrlrelay/orchestrator.yaml
   Node ID: your-hostname.local
-  Timezone: America/New_York
-  Transport: file_mock
-  Repos: 1
+  Timezone: UTC
+  Transport: telegram
+  Repos: 86
 ```
 
-For the full schema (every key, every default), see [Configuration]({{ '/configuration/' | relative_url }}).
+For the full schema (every key, every default), see
+[Configuration]({{ '/configuration/' | relative_url }}). To edit the file
+later, open `~/.config/ctrlrelay/orchestrator.yaml`; ctrlrelay re-reads it on
+every command. Re-running `ctrlrelay setup` refuses to clobber an existing
+config without `--force`.
+
+`node_id` is optional in the generated config — when omitted it defaults to
+your machine's hostname (`socket.gethostname()`). Set it explicitly only if
+the hostname is meaningless (CI runners, containers).
 
 ## Your first dev-pipeline run
 

{ctrlrelay-0.3.0 → ctrlrelay-0.4.0}/pyproject.toml

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