coxswain 0.1.0b1__tar.gz

coxswain-0.1.0b1/.github/workflows/docs.yml

@@ -0,0 +1,27 @@
+name: docs
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run python docs/_pull.py
+      - run: |
+          tag=$(uv run python -c 'import tomllib; print(tomllib.load(open("manifest.toml", "rb"))["components"]["tools"].get("tag", ""))')
+          uv tool install "git+https://github.com/ppfenning/coxswain-tools@${tag:-main}"
+      - run: uv run python docs/_cli.py
+      - id: version
+        run: echo "version=$(uv run python -c 'import tomllib; print(tomllib.load(open("manifest.toml", "rb"))["coxswain"]["version"])')" >> "$GITHUB_OUTPUT"
+      - run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - run: uv run mike deploy --push --update-aliases ${{ steps.version.outputs.version }} latest
+      - run: uv run mike set-default --push latest || true

coxswain-0.1.0b1/.github/workflows/publish.yml

@@ -0,0 +1,16 @@
+name: publish
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

coxswain-0.1.0b1/.github/workflows/test.yml

@@ -0,0 +1,16 @@
+name: test
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run pytest -q
+      - name: ruff (rules in pyproject.toml; pre-commit mirrors it)
+        run: uv run ruff check .
+      - run: test ! -f mkdocs.yml || uv run mkdocs build --strict

coxswain-0.1.0b1/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+site/
+__pycache__/
+.pytest_cache/

coxswain-0.1.0b1/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+# Local mirror of the CI lint job: `pre-commit install` once, then ruff runs on
+# each commit with the same rules pyproject.toml / ruff.toml declares.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.6
+    hooks:
+      - id: ruff
+        args: [--fix]

coxswain-0.1.0b1/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.5
+Name: coxswain
+Version: 0.1.0b1
+Summary: Coxswain: the agent platform. The command is `cox`, from the coxswain-tools package.
+Requires-Python: >=3.11

coxswain-0.1.0b1/README.md

@@ -0,0 +1,7 @@
+# Coxswain
+
+The umbrella for the agent platform: methodology docs, a version manifest that pins every component in lockstep, and a one-line installer. **Beta.**
+
+The coxswain steers and calls the stroke for the crew and never rows.
+
+Design: workspace `plans/agent-platform/2026-09-05-coxswain-design.md`.

coxswain-0.1.0b1/coxswain/__init__.py

@@ -0,0 +1,5 @@
+"""Coxswain: the agent platform. The command is `cox`, from the coxswain-tools package."""
+
+from importlib.metadata import version
+
+__version__ = version("coxswain")

coxswain-0.1.0b1/docs/_cli.py

@@ -0,0 +1,71 @@
+"""Generate docs/reference/cli/ from `cox --help` at build time.
+
+The core (`parse_subcommands`) is pure: given a block of argparse `--help`
+text, it decides which names are subcommands, with no I/O. The edge (`main`)
+runs `cox --help` and one `--help` per group and subcommand it discovers, and
+writes nothing at all if `cox` isn't on PATH.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+REFERENCE_DIR = Path("docs/reference/cli")
+
+
+def parse_subcommands(help_text: str) -> list[str]:
+    """Return the subcommand names listed under "positional arguments:".
+
+    Argparse indents the `{a,b,c}` placeholder line at one depth and each
+    named subcommand one depth deeper; only the deeper indent is a name.
+    """
+    lines = help_text.splitlines()
+    starts = [i for i, line in enumerate(lines) if line.strip().startswith("positional arguments")]
+    if not starts:
+        return []
+    names = []
+    for line in lines[starts[0] + 1 :]:
+        if line and not line[:1].isspace():
+            break
+        indent = len(line) - len(line.lstrip(" "))
+        stripped = line.strip()
+        if indent == 4 and stripped and not stripped.startswith("{"):
+            names.append(stripped.split()[0])
+    return names
+
+
+def _help(*args: str) -> str:
+    return subprocess.run(["cox", *args, "--help"], capture_output=True, text=True, check=True).stdout
+
+
+def _group_page(name: str, group_help: str, subcommands: list[tuple[str, str]]) -> str:
+    lines = [f"# {name}", "", "```", group_help.rstrip(), "```", ""]
+    for sub_name, sub_help in subcommands:
+        lines += [f"## {sub_name}", "", "```", sub_help.rstrip(), "```", ""]
+    return "\n".join(lines)
+
+
+def _index_page(names: list[str]) -> str:
+    lines = ["# CLI reference", "", "Generated from `cox --help` at build time.", ""]
+    lines += [f"- [{name}]({name}.md)" for name in names]
+    return "\n".join(lines) + "\n"
+
+
+def main() -> None:
+    if shutil.which("cox") is None:
+        print("cox is not on PATH; skipping CLI reference generation")
+        return
+    names = parse_subcommands(_help())
+    REFERENCE_DIR.mkdir(parents=True, exist_ok=True)
+    for name in names:
+        group_help = _help(name)
+        subcommands = [(sub, _help(name, sub)) for sub in parse_subcommands(group_help)]
+        (REFERENCE_DIR / f"{name}.md").write_text(_group_page(name, group_help, subcommands))
+    (REFERENCE_DIR / "index.md").write_text(_index_page(names))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

coxswain-0.1.0b1/docs/_pull.py

@@ -0,0 +1,215 @@
+"""Pull each component's declared docs into docs/components/<name>/<path>.
+
+The core (`plan`) is pure: given a parsed manifest, it decides which URLs to
+fetch and where to write them, with no I/O. A `*.md` glob entry cannot be
+expanded without asking GitHub what is in the directory, so `plan` returns it
+as a single unresolved item; the edge (`_run`, called from `main`) expands it
+via the GitHub contents API and does the actual fetching and writing.
+
+Dest paths preserve each doc's full relative path (not just its basename)
+under docs/components/<component>/, e.g. `graphs/delivery/epic-swarm.md`
+lands at `docs/components/graphs/graphs/delivery/epic-swarm.md`. This is
+deliberate: the graphs component pulls both a generated page
+`docs/graphs/<name>.md` and a hand-written prose doc `graphs/<phase>/<name>.md`
+for the same graph, and the two share a basename. Collapsing to the basename
+would make the second overwrite the first.
+
+A doc that fails to fetch is a build failure, not a quiet skip: `_run`
+counts failures and `main` exits nonzero if any planned doc did not land, so
+a stale pinned tag fails the docs workflow instead of publishing the
+placeholder text in its place. A directory listing that resolves but holds
+no `.md` files counts the same way; a glob that silently expands to nothing
+is indistinguishable from success unless something says so. `_list_dir`
+returns the ref that actually resolved (the pinned tag, or `main` on a 404)
+alongside the file names, and `_glob_docs` (pure) turns that ref and those
+names into concrete `doc` items the same shape `plan` already produces for
+listed paths; `_run` fetches and writes that one shape without caring which
+kind planned it.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tomllib
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+
+def raw_url(repo: str, ref: str, entry: str) -> str:
+    """Pure: the raw.githubusercontent URL for one file at one ref."""
+    return f"https://raw.githubusercontent.com/{repo}/{ref}/{entry}"
+
+
+def fallback_url(doc: dict) -> str | None:
+    """Pure: the same document at `main`, or None when there is nowhere to fall back to.
+
+    One ref rule for every path: the pinned tag when it carries the file, else
+    `main`. The glob listing has always had this fallback because a tag may be
+    cut before a document exists. A listed path had the tag and nothing else,
+    so the same tag took the whole docs build down with it — and because the
+    pull step is required, down means publishing nothing.
+    """
+    if not doc.get("repo") or not doc.get("entry") or doc.get("ref") == "main":
+        return None
+    return raw_url(doc["repo"], "main", doc["entry"])
+
+
+def _item(name: str, repo: str, tag: str, entry: str) -> dict:
+    if entry.endswith("/*.md"):
+        directory = entry[: -len("/*.md")]
+        return {
+            "kind": "glob",
+            "repo": repo,
+            "tag": tag,
+            "dir": directory,
+            "dest_dir": f"docs/components/{name}/{directory}",
+        }
+    return {
+        "kind": "doc",
+        "repo": repo,
+        "entry": entry,
+        "ref": tag,
+        "url": raw_url(repo, tag, entry),
+        "dest": f"docs/components/{name}/{entry}",
+    }
+
+
+def plan(manifest: dict) -> list[dict]:
+    """Return one item per declared doc: a resolved `doc` or an unresolved `glob`.
+
+    Components declared with a `path` (in-repo, e.g. `desktop`) have no docs
+    to pull and are skipped, as does any repo component with no `docs` list.
+    """
+    components = manifest.get("components", {})
+    return [
+        _item(name, info["repo"], info["tag"], entry)
+        for name, info in components.items()
+        if "repo" in info
+        for entry in info.get("docs", [])
+    ]
+
+
+def _fetch(url: str) -> bytes:
+    with urllib.request.urlopen(url) as response:
+        return response.read()
+
+
+def _write(dest: str, content: bytes) -> None:
+    destination = Path(dest)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_bytes(content)
+
+
+def _list_dir(repo: str, tag: str, directory: str) -> tuple[str, list[str]]:
+    """Return the ref that resolved and the .md file names in `directory`.
+
+    The contents API 404s for a ref that does not exist yet (a tag not
+    pushed at the time docs build); `main` always resolves. The ref is
+    returned alongside the names because the raw fetch for each name must
+    use the ref the listing actually came from, not the ref that 404'd. A
+    non-404 response that isn't a directory listing (e.g. `directory` names
+    a file, not a folder) is a fetch failure too, not a crash: the caller
+    treats `URLError` as one skip, same as a 404.
+    """
+    for ref in (tag, "main"):
+        url = f"https://api.github.com/repos/{repo}/contents/{directory}?ref={ref}"
+        try:
+            listing = json.loads(_fetch(url))
+        except urllib.error.HTTPError as exc:
+            if exc.code == 404 and ref == tag:
+                continue
+            raise
+        else:
+            if not isinstance(listing, list):
+                raise urllib.error.URLError(f"{url} did not return a directory listing")
+            return ref, [entry["name"] for entry in listing if entry["name"].endswith(".md")]
+    raise AssertionError("unreachable: main always resolves or raises")
+
+
+def _glob_docs(item: dict, ref: str, names: list[str]) -> list[dict]:
+    """Turn a resolved glob directory listing into concrete `doc` items.
+
+    Pure: takes the ref and names `_list_dir` already resolved and returns
+    plain (url, dest) data in the same shape `plan` produces for a listed
+    path, so `_run` fetches and writes one shape regardless of which kind
+    planned it.
+    """
+    return [
+        {
+            "kind": "doc",
+            "url": f"https://raw.githubusercontent.com/{item['repo']}/{ref}/{item['dir']}/{name}",
+            "dest": f"{item['dest_dir']}/{name}",
+        }
+        for name in names
+    ]
+
+
+def _resolve(items: list[dict]) -> tuple[list[dict], int]:
+    """Expand every `glob` item into `doc` items; count each that failed to resolve.
+
+    A glob that lists zero `.md` files is counted as a failure: a directory
+    that is supposed to hold generated pages and comes back empty means the
+    pages were not generated yet, not that there is nothing to pull.
+    """
+    docs: list[dict] = []
+    failures = 0
+    for item in items:
+        if item["kind"] != "glob":
+            docs.append(item)
+            continue
+        try:
+            ref, names = _list_dir(item["repo"], item["tag"], item["dir"])
+        except urllib.error.URLError as exc:
+            print(f"skip: {item['dir']}: {exc}")
+            failures += 1
+            continue
+        if not names:
+            print(f"skip: {item['dir']}: no .md files at {ref}")
+            failures += 1
+            continue
+        docs.extend(_glob_docs(item, ref, names))
+    return docs, failures
+
+
+def _fetch_with_fallback(doc: dict, fetch=None) -> bytes:
+    """Edge: fetch `doc` at its ref, and on a 404 at `main` instead.
+
+    `fetch` is injected so the ref rule is testable without a network.
+    """
+    fetch = fetch or _fetch
+    try:
+        return fetch(doc["url"])
+    except urllib.error.HTTPError as exc:
+        alternate = fallback_url(doc) if exc.code == 404 else None
+        if alternate is None or alternate == doc["url"]:
+            raise
+        print(f"note: {doc['url']} is not at that ref; falling back to main")
+        return fetch(alternate)
+
+
+def _run(items: list[dict]) -> int:
+    """Fetch and write every planned doc; return how many did not land."""
+    docs, failures = _resolve(items)
+    for doc in docs:
+        try:
+            content = _fetch_with_fallback(doc)
+        except urllib.error.URLError as exc:
+            print(f"skip: {doc['url']}: {exc}")
+            failures += 1
+            continue
+        _write(doc["dest"], content)
+    return failures
+
+
+def main() -> int:
+    manifest = tomllib.loads(Path("manifest.toml").read_text())
+    failures = _run(plan(manifest))
+    if failures:
+        print(f"failed: {failures} doc(s) did not pull")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

coxswain-0.1.0b1/docs/_shots.py

@@ -0,0 +1,99 @@
+"""Render terminal screenshots of `cox` commands to SVG for the docs.
+
+The core (`shot_plan`) is pure: it names each command to capture and the
+argv to run it with, with no I/O. The edge (`main`) runs a maintainer's own
+machine, capturing real output and writing SVGs; it does nothing but say so
+and exit 0 if `cox` isn't on PATH. Rich is imported inside the edge function
+so importing this module never requires it to be installed.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SHOTS_DIR = Path("docs/assets/shots")
+
+
+def shot_plan() -> list[tuple[str, list[str]]]:
+    """Return the (name, argv) pairs to capture, one per screenshot."""
+    return [
+        ("versions", ["cox", "versions", "--manifest", "manifest.toml"]),
+        ("doctor", ["cox", "setup", "doctor"]),
+        ("route-status", ["cox", "route", "status"]),
+        (
+            "install-dry-run",
+            ["cox", "install", "--dry-run", "--manifest", "manifest.toml", "--root", "/tmp/x"],
+        ),
+    ]
+
+
+MAX_LINES = 14
+MAX_COLS = 100
+
+
+def clip(output: str, max_lines: int = MAX_LINES, max_cols: int = MAX_COLS) -> str:
+    """Pure: `output` bounded to a screenshot's worth of terminal.
+
+    A screenshot is an illustration, not a dump. Two things have to be bounded,
+    not one: `cox route status` prints a line per run the workspace has ever
+    recorded, and each of those lines carries a whole quarantine reason, so a
+    line cap alone still wraps into hundreds of rendered rows. Lines past
+    `max_lines` and columns past `max_cols` are cut, and each cut is marked so
+    the reader knows the terminal said more than the picture shows.
+    """
+    lines = output.splitlines()
+    kept = [line if len(line) <= max_cols else line[: max_cols - 1] + "\u2026" for line in lines[:max_lines]]
+    if len(lines) > max_lines:
+        kept.append(f"... {len(lines) - max_lines} more lines")
+    return "\n".join(kept)
+
+
+def redact(output: str, home: str) -> str:
+    """Pure: the maintainer's home directory replaced by `~`.
+
+    These SVGs ship on a public site. The commands print real profile and
+    workspace paths, which carry a username; `~` is what a reader needs and
+    all they should get. `home` is passed in rather than read, so the rule is
+    testable and this function has no side door.
+    """
+    return output.replace(home.rstrip("/"), "~") if home else output
+
+
+def _capture(argv: list[str], home: str) -> str:
+    result = subprocess.run(argv, capture_output=True, text=True, check=False)
+    return clip(redact(result.stdout + result.stderr, home))
+
+
+def main() -> None:
+    if shutil.which("cox") is None:
+        print("cox is not on PATH; skipping screenshot capture")
+        return
+
+    from rich.color_triplet import ColorTriplet
+    from rich.console import Console
+    from rich.terminal_theme import TerminalTheme
+
+    background = ColorTriplet(0x0B, 0x16, 0x22)
+    foreground = ColorTriplet(0xE8, 0xEE, 0xF2)
+    primary = ColorTriplet(0x2A, 0x9D, 0x8F)
+    accent = ColorTriplet(0xE9, 0xC4, 0x6A)
+    muted = ColorTriplet(0x9F, 0xB3, 0xC8)
+    cox_dark_theme = TerminalTheme(
+        background,
+        foreground,
+        [background, accent, primary, accent, primary, accent, muted, foreground],
+    )
+
+    SHOTS_DIR.mkdir(parents=True, exist_ok=True)
+    for name, argv in shot_plan():
+        console = Console(record=True, width=100)
+        console.print(_capture(argv, str(Path.home())))
+        svg = console.export_svg(title=" ".join(argv), theme=cox_dark_theme)
+        (SHOTS_DIR / f"{name}.svg").write_text(svg)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

coxswain-0.1.0b1/docs/assets/palette.css

@@ -0,0 +1,61 @@
+/* Coxswain palette: dark by default (slate), a light toggle (default). */
+/* Contrast pairs used for body text against the page background: */
+/*   slate:   text #e8eef2 on background #0b1622 -> ~16.9:1 */
+/*   default: text #14202b on background #f6f9fb -> ~16.3:1 */
+/* Both clear the 7:1 body-text bar with headroom for the muted tone too. */
+
+[data-md-color-scheme="slate"] {
+  --cox-color-background: #0b1622;
+  --cox-color-surface: #10202e;
+  --cox-color-primary: #2a9d8f;
+  --cox-color-accent: #e9c46a;
+  --cox-color-text: #e8eef2;
+  --cox-color-muted: #9fb3c8;
+
+  --md-primary-fg-color: var(--cox-color-primary);
+  --md-accent-fg-color: var(--cox-color-accent);
+  --md-default-bg-color: var(--cox-color-background);
+  --md-default-fg-color: var(--cox-color-text);
+  --md-code-bg-color: var(--cox-color-surface);
+  --md-typeset-a-color: var(--cox-color-primary);
+}
+
+[data-md-color-scheme="default"] {
+  --cox-color-background: #f6f9fb;
+  --cox-color-surface: #ffffff;
+  --cox-color-primary: #1d6f66;
+  --cox-color-accent: #b8860b;
+  --cox-color-text: #14202b;
+  --cox-color-muted: #4a5b6b;
+
+  --md-primary-fg-color: var(--cox-color-primary);
+  --md-accent-fg-color: var(--cox-color-accent);
+  --md-default-bg-color: var(--cox-color-background);
+  --md-default-fg-color: var(--cox-color-text);
+  --md-code-bg-color: var(--cox-color-surface);
+  --md-typeset-a-color: var(--cox-color-primary);
+}
+
+/* The beta banner: accent text over a translucent wash of the primary colour. */
+.md-banner {
+  background-color: color-mix(in srgb, var(--cox-color-primary) 25%, transparent);
+  color: var(--cox-color-accent);
+}
+
+/* The prev/next bar at the top of each page body. */
+.cox-page-nav {
+  display: flex;
+  gap: 1rem;
+  padding: 0.5rem 0 1rem;
+  font-size: 0.75rem;
+  color: var(--cox-color-muted);
+}
+
+.cox-page-nav a {
+  color: var(--cox-color-primary);
+  text-decoration: none;
+}
+
+.cox-page-nav__next {
+  margin-left: auto;
+}