maiactl 0.1.0__tar.gz

maiactl-0.1.0/.gitignore

@@ -0,0 +1,112 @@
+# ── Python ──────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+
+# ── Test / lint / type caches ──────────────────────────────
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage/
+.tox/
+
+# ── Virtual environments ───────────────────────────────────
+.venv/
+venv/
+env/
+
+# ── IDE / editor ───────────────────────────────────────────
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# ── OS ─────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+
+# ── Environment files (keep examples + frontend prod) ─────
+# .env.production for the frontend has no secrets — it points at the
+# same-origin Firebase Hosting rewrite. Keeping it tracked means anyone
+# redeploying gets the prod config without manually recreating the file.
+.env
+.env.*
+!.env.example
+!frontend/.env.production
+
+# ── Docker / databases ─────────────────────────────────────
+pgdata/
+*.db
+*.sqlite
+*.sqlite3
+
+# ── uv ─────────────────────────────────────────────────────
+backend/.python-version
+
+# ── Node / Vite / Next ─────────────────────────────────────
+node_modules/
+.next/
+dist/
+.vite/
+*.tsbuildinfo
+
+# ── Logs ───────────────────────────────────────────────────
+*.log
+logs/
+
+# ── Archives / bundles (not source) ────────────────────────
+*.zip
+*.tar
+*.tar.gz
+*.tgz
+
+# ── Firebase ───────────────────────────────────────────────
+# Per-machine deploy cache; firebase.json + .firebaserc stay tracked.
+.firebase/
+firebase-debug.log
+firestore-debug.log
+ui-debug.log
+
+# ── Claude Code per-machine state ──────────────────────────
+# scheduled_tasks.lock + settings.local.json are local to the operator,
+# not part of the repo's shared config.
+.claude/
+
+# ── Misc ───────────────────────────────────────────────────
+.cache/
+tmp/
+*.pid
+messages.json
+
+# ── Design handoff (generated static mockups) ──────────────
+design-handoff/
+
+# Google service-account JSON keys — NEVER commit. Local dev keys live in
+# backend/.secrets/ (vertex-sa.json, maia-sa.json) and are gitignored as a
+# directory so a new key dropped in won't accidentally leak. Prod uses
+# Secret Manager / workload identity instead.
+backend/.secrets/
+# Legacy patterns kept so any straggler key at the repo root still gets caught.
+/trusty-vim-*.json
+/maia-493810-*.json
+*-service-account*.json
+*-gcp-key*.json
+*-vertex*.json
+
+client_secret_497788162142-r2a24nb8hl679nloc43jiqctpvmbb5v8.apps.googleusercontent.com.json
+# Claude Code skill artifacts (local tooling, not app code)
+.agents/
+skills-lock.json
+scratchpad.md
+
+# ── Desktop (Electron) ──────────────────────────────────────
+# build/ above is a Python pattern; desktop/build holds source-controlled
+# packaging resources (icon, entitlements). dist output stays ignored.
+!desktop/build/
+desktop/dist/

maiactl-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: maiactl
+Version: 0.1.0
+Summary: Drive the M.AI.A board from a terminal (and from terminal agents).
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.1
+Description-Content-Type: text/markdown
+
+# maia
+
+The M.AI.A board from a terminal, for people and for the coding agents they
+run there.
+
+It talks to the same public HTTP API the web app uses, so it inherits the
+server's rules rather than restating them: any active project member can
+move, edit, assign or reassign any ticket, and observers are read-only.
+
+## Install
+
+```bash
+uv tool install --from ./cli maiactl    # from a checkout
+maia login                               # opens your browser
+maia projects
+maia use MVP
+```
+
+`login` runs the same brokered PKCE flow the desktop app uses: it opens
+Google in your real browser and polls until the backend releases a token.
+The token is written to `~/.config/maia/config.json` with mode 0600.
+
+It is a normal app session token, not a scoped API key, so it carries your
+full access and expires on the server's schedule. Treat the file as a
+credential. `maia logout` removes it.
+
+For CI or a throwaway shell, skip the file entirely:
+
+```bash
+export MAIA_TOKEN=...        MAIA_TENANT_ID=...
+export MAIA_PROJECT=MVP      MAIA_API_URL=https://maia.cydratech.com
+```
+
+## Reading
+
+```bash
+maia ls                       # active tickets, doing first
+maia ls --mine --status doing
+maia ls --stage "In QA"
+maia ls -s payment            # title/description search
+maia show MVP-42              # detail + comments
+maia show MVP-42 --history
+maia board                    # stages and card counts
+maia members                  # who's on it, and their roles
+maia stories
+maia files MVP-42 --download ./tmp
+```
+
+Tickets are addressed by key (`MVP-42`), bare number (`42`), or a title
+fragment. A fragment matching more than one ticket is an error, never a
+guess.
+
+## Writing
+
+```bash
+maia new "Payment webhook retries" -d "Stripe retries land as duplicates." \
+  --assign priya --stage "In Progress" --story "Billing"
+
+git log -1 --format=%B | maia new "Ship the retry fix" -d -
+
+maia mv MVP-42 doing          # a status…
+maia mv MVP-42 "In QA"        # …or a stage by name
+maia assign MVP-42 priya
+maia story MVP-42 "Billing"   # file under an existing story
+maia comment MVP-42 "Deployed to staging." --mention priya
+maia comment MVP-42 - < notes.md
+maia attach MVP-42 screenshot.png trace.pdf
+maia drop MVP-42 --reason "superseded by MVP-51"
+```
+
+Every command takes `--json` for programmatic use, and `-p CODE` to act on
+a project other than the selected one.
+
+## What it deliberately doesn't do
+
+- **No stage (column) create, rename or delete.** Board structure is
+  admin-curated in the app.
+- **No story create, edit or delete.** Same reason. You can file a ticket
+  into an existing story with `maia story`.
+- **No ticket delete.** The API has none. `maia drop` sets the reversible
+  `dropped` status, which is what "scrap that" means on this board;
+  `maia mv <key> next` puts it back.
+
+## For agents
+
+Point your terminal agent at `maia --help` and the per-command
+`maia <command> --help`; both are written to be read once and remembered.
+Two habits worth putting in a project's `CLAUDE.md`:
+
+- Prefer `--json` when parsing, plain output when showing a human.
+- Narrow before listing. `maia ls` caps at 40 rows by default; on a big
+  board use `--mine`, `--stage`, or `-s` rather than `--limit 0`.
+
+## Exit codes
+
+| code | meaning |
+|------|---------|
+| 0 | fine |
+| 1 | generic failure |
+| 2 | not authenticated, or nothing selected |
+| 3 | forbidden (e.g. you're an observer) |
+| 4 | not found |
+| 5 | conflict; refetch and retry |

maiactl-0.1.0/README.md

@@ -0,0 +1,103 @@
+# maia
+
+The M.AI.A board from a terminal, for people and for the coding agents they
+run there.
+
+It talks to the same public HTTP API the web app uses, so it inherits the
+server's rules rather than restating them: any active project member can
+move, edit, assign or reassign any ticket, and observers are read-only.
+
+## Install
+
+```bash
+uv tool install --from ./cli maiactl    # from a checkout
+maia login                               # opens your browser
+maia projects
+maia use MVP
+```
+
+`login` runs the same brokered PKCE flow the desktop app uses: it opens
+Google in your real browser and polls until the backend releases a token.
+The token is written to `~/.config/maia/config.json` with mode 0600.
+
+It is a normal app session token, not a scoped API key, so it carries your
+full access and expires on the server's schedule. Treat the file as a
+credential. `maia logout` removes it.
+
+For CI or a throwaway shell, skip the file entirely:
+
+```bash
+export MAIA_TOKEN=...        MAIA_TENANT_ID=...
+export MAIA_PROJECT=MVP      MAIA_API_URL=https://maia.cydratech.com
+```
+
+## Reading
+
+```bash
+maia ls                       # active tickets, doing first
+maia ls --mine --status doing
+maia ls --stage "In QA"
+maia ls -s payment            # title/description search
+maia show MVP-42              # detail + comments
+maia show MVP-42 --history
+maia board                    # stages and card counts
+maia members                  # who's on it, and their roles
+maia stories
+maia files MVP-42 --download ./tmp
+```
+
+Tickets are addressed by key (`MVP-42`), bare number (`42`), or a title
+fragment. A fragment matching more than one ticket is an error, never a
+guess.
+
+## Writing
+
+```bash
+maia new "Payment webhook retries" -d "Stripe retries land as duplicates." \
+  --assign priya --stage "In Progress" --story "Billing"
+
+git log -1 --format=%B | maia new "Ship the retry fix" -d -
+
+maia mv MVP-42 doing          # a status…
+maia mv MVP-42 "In QA"        # …or a stage by name
+maia assign MVP-42 priya
+maia story MVP-42 "Billing"   # file under an existing story
+maia comment MVP-42 "Deployed to staging." --mention priya
+maia comment MVP-42 - < notes.md
+maia attach MVP-42 screenshot.png trace.pdf
+maia drop MVP-42 --reason "superseded by MVP-51"
+```
+
+Every command takes `--json` for programmatic use, and `-p CODE` to act on
+a project other than the selected one.
+
+## What it deliberately doesn't do
+
+- **No stage (column) create, rename or delete.** Board structure is
+  admin-curated in the app.
+- **No story create, edit or delete.** Same reason. You can file a ticket
+  into an existing story with `maia story`.
+- **No ticket delete.** The API has none. `maia drop` sets the reversible
+  `dropped` status, which is what "scrap that" means on this board;
+  `maia mv <key> next` puts it back.
+
+## For agents
+
+Point your terminal agent at `maia --help` and the per-command
+`maia <command> --help`; both are written to be read once and remembered.
+Two habits worth putting in a project's `CLAUDE.md`:
+
+- Prefer `--json` when parsing, plain output when showing a human.
+- Narrow before listing. `maia ls` caps at 40 rows by default; on a big
+  board use `--mine`, `--stage`, or `-s` rather than `--limit 0`.
+
+## Exit codes
+
+| code | meaning |
+|------|---------|
+| 0 | fine |
+| 1 | generic failure |
+| 2 | not authenticated, or nothing selected |
+| 3 | forbidden (e.g. you're an observer) |
+| 4 | not found |
+| 5 | conflict; refetch and retry |

maiactl-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "maiactl"
+version = "0.1.0"
+description = "Drive the M.AI.A board from a terminal (and from terminal agents)."
+readme = "README.md"
+requires-python = ">=3.10"
+# httpx only, on purpose. This package is installed by developers on their
+# own machines (and run via `uvx`), so every dependency is a thing that can
+# break someone's shell. The backend package is NOT a dependency: the CLI
+# talks to the same public HTTP API a browser does.
+dependencies = ["httpx>=0.28.1"]
+
+[project.scripts]
+maia = "maiactl.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maiactl"]
+
+[dependency-groups]
+dev = ["pytest>=9.0.3", "ruff>=0.15.11"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+# Same ruleset the backend uses, so a contributor moving between the two
+# doesn't hit different lint opinions.
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["maiactl"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

maiactl-0.1.0/src/maiactl/__init__.py

@@ -0,0 +1,10 @@
+"""maia — the M.AI.A board from a terminal.
+
+Layering, deliberately: ``client.py`` holds every operation and knows
+nothing about argv, stdout or exit codes; ``cli.py`` is the argument
+parsing and rendering shell over it. A future MCP server is a second
+shell over the same ``MaiaClient`` rather than a reimplementation, which
+is the whole reason the split exists.
+"""
+
+__version__ = "0.1.0"

maiactl-0.1.0/src/maiactl/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m maiactl`` runs the same entry point as the ``maia`` script."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

maiactl-0.1.0/src/maiactl/auth.py

@@ -0,0 +1,109 @@
+"""Browser login for a terminal, over the backend's brokered poll flow.
+
+This is the same flow the desktop app uses, and it exists because a CLI
+can't safely host an OAuth redirect. We generate a PKCE verifier, ask the
+backend to start a session, open the user's real browser at Google, and
+poll until the backend releases a JWT. The verifier never leaves this
+process except as a header on the poll, and it's what binds redemption to
+us: a leaked session id on its own buys nothing.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import time
+import webbrowser
+
+import httpx
+
+from .config import Config
+from .errors import MaiaError
+
+# The server allows 43-128 chars; 32 random bytes lands at 43 base64url chars.
+_VERIFIER_BYTES = 32
+_MAX_WAIT_SECONDS = 300
+
+
+def _pkce_pair() -> tuple[str, str]:
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(_VERIFIER_BYTES)).rstrip(b"=").decode()
+    challenge = (
+        base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+    )
+    return verifier, challenge
+
+
+def login(
+    config: Config,
+    *,
+    open_browser: bool = True,
+    echo=print,
+    transport: httpx.BaseTransport | None = None,
+    sleep=time.sleep,
+) -> Config:
+    """Run the flow to completion and return the config with a token on it.
+
+    Does not save — the caller decides, because `maia login` also needs to
+    pick a workspace before the file is worth writing.
+
+    ``transport`` and ``sleep`` exist so tests can drive the poll loop
+    without a server and without waiting; nothing in the CLI passes them.
+    """
+    base = f"{config.api_url}/api/v1"
+    verifier, challenge = _pkce_pair()
+
+    with httpx.Client(timeout=httpx.Timeout(30.0, connect=10.0), transport=transport) as http:
+        try:
+            r = http.post(f"{base}/auth/login/session", json={"code_challenge": challenge})
+        except httpx.HTTPError as e:
+            raise MaiaError(f"Couldn't reach {config.api_url}: {e}") from e
+        if not r.is_success:
+            detail = ""
+            try:
+                detail = r.json().get("detail", "")
+            except ValueError:
+                detail = r.text[:200]
+            raise MaiaError(f"Couldn't start a login session: {detail or r.status_code}")
+
+        started = r.json()
+        session_id = started["session_id"]
+        url = started["url"]
+        interval = float(started.get("interval") or 2)
+        expires_in = float(started.get("expires_in") or _MAX_WAIT_SECONDS)
+
+        echo("Opening your browser to sign in with Google.")
+        echo(f"If it doesn't open, paste this into a browser:\n\n  {url}\n")
+        if open_browser:
+            try:
+                webbrowser.open(url)
+            except Exception:
+                # A headless box has no browser; the printed URL is the fallback.
+                pass
+
+        echo("Waiting for you to finish signing in… (Ctrl-C to cancel)")
+        deadline = time.monotonic() + min(expires_in, _MAX_WAIT_SECONDS)
+        while time.monotonic() < deadline:
+            sleep(interval)
+            try:
+                poll = http.get(
+                    f"{base}/auth/login/session/{session_id}",
+                    headers={"X-Pkce-Verifier": verifier},
+                )
+            except httpx.HTTPError:
+                # Transient network blip mid-flow: keep polling until the
+                # session itself expires rather than failing the login.
+                continue
+            if poll.status_code == 410:
+                raise MaiaError("That login session expired.", hint="Run `maia login` again.")
+            if poll.status_code == 403:
+                raise MaiaError("Login verification failed (PKCE mismatch).")
+            if poll.status_code == 404:
+                raise MaiaError("That login session is gone.", hint="Run `maia login` again.")
+            if not poll.is_success:
+                continue
+            body = poll.json()
+            if body.get("status") == "complete" and body.get("token"):
+                config.token = body["token"]
+                return config
+        raise MaiaError("Timed out waiting for the browser sign-in.")