maiactl 0.4.0__tar.gz

maiactl-0.4.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.4.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.5
+Name: maiactl
+Version: 0.4.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 maiactl      # from PyPI (the package is maiactl; the command is maia)
+maia login                   # opens your browser, then asks which workspace/project
+maia                         # where am I, what next
+maia doctor                  # if anything feels off
+```
+
+Bare `maia` is a status card (offline): who you are, which workspace and
+project, and what to try. `maia doctor` checks version, server, token,
+workspace and project, and says how to fix each.
+
+`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,
+then finishes setting you up: if you're in several workspaces it asks which,
+and if that workspace has several projects it asks which of those. One of
+each is picked for you without a question. In a script or an agent shell
+(no TTY) there's no prompt; pass `--tenant` and then `maia use <code>`.
+The token is written to `~/.config/maia/config.json` with mode 0600.
+
+## Several accounts at once
+
+Like `gh`, you can be signed into more than one account and switch between
+them. An account is (email, server), so the same person on prod and on a
+local backend are two accounts — which is the point.
+
+```bash
+maia login                       # adds an account; never evicts an existing one
+maia auth list                   # all of them, active one marked with *
+maia auth switch priya           # by email, or any unique fragment
+maia auth logout --account priya # sign out of just that one
+maia auth logout --all
+```
+
+Each account remembers its own workspace and project, so switching restores
+where you were. For a single command, `-a` (`--as`) acts as another account
+without switching, and nothing that command does is saved:
+
+```bash
+maia -a priya@cydratech.com ls --mine
+maia ls --mine -a priya          # flags may come before or after the command
+```
+
+`-a` can't be combined with `login`, `logout` or `auth switch`; those manage
+saved accounts, so name the account directly (`logout --account priya`).
+
+## Workspaces
+
+```bash
+maia workspaces              # the ones this account belongs to
+maia workspace "Cydra Tech"  # switch
+```
+
+Switching workspace clears the selected project, because a project belongs
+to exactly one workspace — keeping it would point at something the account
+can no longer see. Pick a new one with `maia projects` and `maia use`.
+
+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
+```
+
+Anything set this way applies to the current run only and is never written
+to disk: a CI job can't persist its credentials, and `MAIA_PROJECT=X maia
+use Y` won't change your saved project. Commands that would normally save
+say `(not saved: …)` on stderr. `MAIA_ACCOUNT=priya` selects a saved account
+for one run; a name that matches nothing is an error, not a silent fallback.
+With `MAIA_TOKEN` set, `logout` and `auth switch` refuse, since there is no
+saved session in play.
+
+## Reading
+
+```bash
+maia ls                       # active tickets, doing first (alias: maia tickets)
+maia status                   # same as bare `maia`
+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"   # project admins only
+```
+
+Every command takes `--json` for programmatic use, and `-p CODE` to act on
+a project other than the selected one for that command. Both may come
+before or after the subcommand. Progress notes ("uploaded x.png") go to
+stderr, so `--json` stdout is always a single parseable document.
+
+## 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. Dropping is **project-admin only from
+  the CLI** (the app lets any member), and `maia mv <key> dropped` is held
+  to the same rule.
+
+## For agents
+
+```bash
+maia agent-guide                     # a cheat-sheet written for an LLM
+maia agent-guide --write CLAUDE.md   # drop it into the repo (idempotent; re-run to refresh)
+```
+
+The guide tells the agent to use `--json`, never to run `login` itself,
+how tickets are addressed, the exit codes, and which rules the CLI
+enforces. With `--json` on, errors are JSON on stderr too
+(`{"error", "hint", "exit_code"}`), so failures parse as cleanly as
+successes.
+
+An agent on your machine shares your saved login. For a CI job or a shell
+on another box, hand it your identity for one run:
+
+```bash
+eval "$(maia auth env)"        # exports MAIA_API_URL, MAIA_TOKEN, MAIA_TENANT_ID, MAIA_PROJECT
+MAIA_TOKEN=$(maia auth token)  # or just the token
+```
+
+## 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 (a ticket, member, story, stage, project or workspace) |
+| 5 | conflict; refetch and retry |

maiactl-0.4.0/README.md

@@ -0,0 +1,172 @@
+# 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 maiactl      # from PyPI (the package is maiactl; the command is maia)
+maia login                   # opens your browser, then asks which workspace/project
+maia                         # where am I, what next
+maia doctor                  # if anything feels off
+```
+
+Bare `maia` is a status card (offline): who you are, which workspace and
+project, and what to try. `maia doctor` checks version, server, token,
+workspace and project, and says how to fix each.
+
+`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,
+then finishes setting you up: if you're in several workspaces it asks which,
+and if that workspace has several projects it asks which of those. One of
+each is picked for you without a question. In a script or an agent shell
+(no TTY) there's no prompt; pass `--tenant` and then `maia use <code>`.
+The token is written to `~/.config/maia/config.json` with mode 0600.
+
+## Several accounts at once
+
+Like `gh`, you can be signed into more than one account and switch between
+them. An account is (email, server), so the same person on prod and on a
+local backend are two accounts — which is the point.
+
+```bash
+maia login                       # adds an account; never evicts an existing one
+maia auth list                   # all of them, active one marked with *
+maia auth switch priya           # by email, or any unique fragment
+maia auth logout --account priya # sign out of just that one
+maia auth logout --all
+```
+
+Each account remembers its own workspace and project, so switching restores
+where you were. For a single command, `-a` (`--as`) acts as another account
+without switching, and nothing that command does is saved:
+
+```bash
+maia -a priya@cydratech.com ls --mine
+maia ls --mine -a priya          # flags may come before or after the command
+```
+
+`-a` can't be combined with `login`, `logout` or `auth switch`; those manage
+saved accounts, so name the account directly (`logout --account priya`).
+
+## Workspaces
+
+```bash
+maia workspaces              # the ones this account belongs to
+maia workspace "Cydra Tech"  # switch
+```
+
+Switching workspace clears the selected project, because a project belongs
+to exactly one workspace — keeping it would point at something the account
+can no longer see. Pick a new one with `maia projects` and `maia use`.
+
+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
+```
+
+Anything set this way applies to the current run only and is never written
+to disk: a CI job can't persist its credentials, and `MAIA_PROJECT=X maia
+use Y` won't change your saved project. Commands that would normally save
+say `(not saved: …)` on stderr. `MAIA_ACCOUNT=priya` selects a saved account
+for one run; a name that matches nothing is an error, not a silent fallback.
+With `MAIA_TOKEN` set, `logout` and `auth switch` refuse, since there is no
+saved session in play.
+
+## Reading
+
+```bash
+maia ls                       # active tickets, doing first (alias: maia tickets)
+maia status                   # same as bare `maia`
+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"   # project admins only
+```
+
+Every command takes `--json` for programmatic use, and `-p CODE` to act on
+a project other than the selected one for that command. Both may come
+before or after the subcommand. Progress notes ("uploaded x.png") go to
+stderr, so `--json` stdout is always a single parseable document.
+
+## 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. Dropping is **project-admin only from
+  the CLI** (the app lets any member), and `maia mv <key> dropped` is held
+  to the same rule.
+
+## For agents
+
+```bash
+maia agent-guide                     # a cheat-sheet written for an LLM
+maia agent-guide --write CLAUDE.md   # drop it into the repo (idempotent; re-run to refresh)
+```
+
+The guide tells the agent to use `--json`, never to run `login` itself,
+how tickets are addressed, the exit codes, and which rules the CLI
+enforces. With `--json` on, errors are JSON on stderr too
+(`{"error", "hint", "exit_code"}`), so failures parse as cleanly as
+successes.
+
+An agent on your machine shares your saved login. For a CI job or a shell
+on another box, hand it your identity for one run:
+
+```bash
+eval "$(maia auth env)"        # exports MAIA_API_URL, MAIA_TOKEN, MAIA_TENANT_ID, MAIA_PROJECT
+MAIA_TOKEN=$(maia auth token)  # or just the token
+```
+
+## 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 (a ticket, member, story, stage, project or workspace) |
+| 5 | conflict; refetch and retry |

maiactl-0.4.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "maiactl"
+version = "0.4.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.4.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.4.0"

maiactl-0.4.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.4.0/src/maiactl/auth.py

@@ -0,0 +1,136 @@
+"""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
+# Consecutive network errors / 5xx tolerated before the login gives up.
+_MAX_FLAKY_POLLS = 8
+
+
+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)
+        # Transient trouble (a network blip, a 5xx) is retried, but only so
+        # many times in a row: the old loop swallowed EVERY unexpected
+        # answer as "still pending" and could spin silently for the full
+        # five minutes against a server that was never going to say yes.
+        flaky_in_a_row = 0
+        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 as e:
+                flaky_in_a_row += 1
+                if flaky_in_a_row >= _MAX_FLAKY_POLLS:
+                    raise MaiaError(
+                        f"Lost contact with {config.api_url} while signing in: {e}"
+                    ) from e
+                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 poll.status_code >= 500:
+                flaky_in_a_row += 1
+                if flaky_in_a_row >= _MAX_FLAKY_POLLS:
+                    raise MaiaError(
+                        f"{config.api_url} kept failing (HTTP {poll.status_code}) while signing in."
+                    )
+                continue
+            if not poll.is_success:
+                # Any other 4xx means OUR request is wrong (a 422 on the
+                # verifier header, a 401 from a proxy). Retrying can't fix it.
+                detail = ""
+                try:
+                    detail = str(poll.json().get("detail", ""))[:200]
+                except ValueError:
+                    detail = poll.text[:200]
+                raise MaiaError(
+                    f"The server rejected the sign-in poll (HTTP {poll.status_code}). {detail}".strip()
+                )
+            flaky_in_a_row = 0
+            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.")