axiometa-cli 1.0.0__py3-none-any.whl

axiometa_cli/__init__.py

@@ -0,0 +1,19 @@
+"""axiometa-cli — the terminal client for Axiometa Studio.
+
+The CLI is a thin client of the same backend Studio's browser talks to: codegen stays in the
+cloud (Claude + prompt_builder + catalog), and only the DEVICE half (build/deploy + reading the
+serial channel) happens locally, on the machine the board is plugged into (your laptop, or a Pi
+over SSH). That mirrors Studio exactly: Studio's backend generates and the browser flashes; the
+CLI's backend generates and the terminal flashes.
+
+Three ideas the CLI implements, all grounded in the backend registries:
+  - The device program is a property of the (board, substrate): sketch.ino on Arduino, main.py on
+    MicroPython. The DEPLOY VERBS follow from board.json: an fqbn board has one verb (`deploy` =
+    compile+flash); an mpremote board has two (`run` = ephemeral RAM test, `install` = persist).
+  - The CLIENT ENVIRONMENT (where surfaces render, whether host code runs) is sent to the backend
+    as a capability profile {surface, host_exec} so Axie builds only reachable surfaces. The CLI
+    never enumerates peripherals — what is connected is discovered, never predicted.
+  - The serial CHANNEL is one contract; only its TRANSPORT changes: raw stdout in a terminal, or a
+    127.0.0.1 + token-gated localhost page (opened locally, or reached over `ssh -L`) for a surface.
+"""
+__version__ = "1.0.0"

axiometa_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

axiometa_cli/auth.py

@@ -0,0 +1,116 @@
+"""Auth: where the CLI keeps your token, and how `axiometa login` gets one.
+
+The token sent to the backend is a Supabase JWT, the same auth Studio uses. Resolution order:
+AXIOMETA_TOKEN env var (scripting / CI) > the token stored by `axiometa login`. So you sign in once
+and it persists, instead of exporting an env var every session.
+
+`axiometa login` tries a device-code browser flow against the backend (ask for a code, you approve it
+in a signed-in browser, the CLI polls until granted). If the backend does not expose that endpoint
+yet, it falls back to pasting a token. Either way the token is stored at ~/.config/axiometa/token
+(0600). Guest mode (no token) still works, rate-limited.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+
+def _config_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME")
+    if base:
+        return Path(base) / "axiometa"
+    if os.name == "nt":
+        return Path(os.environ.get("APPDATA", Path.home())) / "axiometa"
+    return Path.home() / ".config" / "axiometa"
+
+
+_TOKEN_FILE = _config_dir() / "token"
+
+
+# ── storage ──
+def stored_token() -> str | None:
+    try:
+        t = _TOKEN_FILE.read_text(encoding="utf-8").strip()
+        return t or None
+    except Exception:
+        return None
+
+
+def get_token() -> str | None:
+    """The token to authenticate with: env var first (scripting), then the stored login."""
+    return os.environ.get("AXIOMETA_TOKEN") or stored_token()
+
+
+def save_token(token: str) -> Path:
+    _TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _TOKEN_FILE.write_text(token.strip() + "\n", encoding="utf-8")
+    try:
+        os.chmod(_TOKEN_FILE, 0o600)
+    except Exception:
+        pass
+    return _TOKEN_FILE
+
+
+def clear_token() -> bool:
+    try:
+        _TOKEN_FILE.unlink()
+        return True
+    except FileNotFoundError:
+        return False
+    except Exception:
+        return False
+
+
+def token_path() -> Path:
+    return _TOKEN_FILE
+
+
+# ── device-code flow (CLI side; needs the backend's /api/cli/login endpoints) ──
+def _post(url: str, payload: dict, timeout: int = 15) -> dict:
+    req = urllib.request.Request(url, data=json.dumps(payload).encode(),
+                                 headers={"Content-Type": "application/json"})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(r.read().decode() or "{}")
+
+
+def device_login_start(backend: str) -> dict | None:
+    """Begin a device-code login. Returns the start payload (user_code, verification_url, device_code,
+    interval, expires_in), or None if the backend has no device-code endpoint yet."""
+    try:
+        return _post(backend.rstrip("/") + "/api/cli/login/start", {})
+    except urllib.error.HTTPError as e:
+        if e.code in (404, 405, 501):
+            return None
+        raise
+    except Exception:
+        return None
+
+
+def device_login_poll(backend: str, start: dict, on_wait=None) -> str | None:
+    """Poll until the user approves (returns the token) or it expires/denies (returns None)."""
+    backend = backend.rstrip("/")
+    device_code = start.get("device_code")
+    interval = max(2, int(start.get("interval", 3)))
+    deadline = time.time() + int(start.get("expires_in", 300))
+    while time.time() < deadline:
+        time.sleep(interval)
+        if on_wait:
+            on_wait()
+        try:
+            r = _post(backend + "/api/cli/login/poll", {"device_code": device_code})
+        except urllib.error.HTTPError as e:
+            if e.code in (400, 428):     # authorization_pending — keep waiting
+                continue
+            return None
+        except Exception:
+            continue
+        if r.get("token"):
+            save_token(r["token"])
+            return r["token"]
+        if r.get("error") in ("expired_token", "access_denied", "expired"):
+            return None
+    return None

axiometa_cli/chat.py

@@ -0,0 +1,137 @@
+"""Backend chat client — the SSE stream from POST /api/ai-chat.
+
+Codegen lives in the cloud (Claude + the catalog + your auth/limits): the CLI sends the conversation
++ the project VFS + the board + the client environment, and the backend streams back a Server-Sent
+Events feed. This module speaks that exact contract (the event vocabulary the backend emits) and keeps
+the multi-turn state (message history + the project files) so a follow-up like 'make it blink faster'
+sees the current build.
+
+SSE event types (from backend/app/main.py): round_start, tool_call, text, gen, tool_done,
+file_write, file_edit, file_delete, context_trace, done, error. The CLI renders `text` live, shows
+`tool_call` as activity, applies the file_* events to the VFS, and closes on `done` (whose `message`
+is the full assistant turn, plus relay_url/device_key when a relay build was produced).
+"""
+from __future__ import annotations
+
+import json
+import urllib.request
+from dataclasses import dataclass, field
+
+MANIFEST = "axiometa.json"  # canonical; backend also reads legacy genesis.json
+
+
+@dataclass
+class TurnResult:
+    text: str = ""                       # the assistant's full reply this turn
+    files_changed: list = field(default_factory=list)   # paths written/edited this turn
+    files_deleted: list = field(default_factory=list)
+    error: str | None = None
+    relay_url: str | None = None
+    device_key: str | None = None
+
+
+class ChatSession:
+    """One project conversation. Holds the VFS + history so each turn is stateful."""
+
+    def __init__(self, backend: str, token: str | None, board_id: str,
+                 capability_profile: dict, files: dict | None = None,
+                 file_meta: dict | None = None, connected_integrations: list | None = None):
+        self.backend = backend.rstrip("/")
+        self.token = token
+        self.board_id = board_id
+        self.capability_profile = capability_profile
+        self.files: dict = dict(files or {})
+        self.file_meta: dict = dict(file_meta or {})
+        self.connected_integrations = connected_integrations or []
+        self.messages: list = []
+
+    # ── transport ──
+    def _request(self, payload: dict):
+        headers = {"Content-Type": "application/json", "Accept": "text/event-stream"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        req = urllib.request.Request(self.backend + "/api/ai-chat",
+                                     data=json.dumps(payload).encode(), headers=headers)
+        return urllib.request.urlopen(req, timeout=600)
+
+    def _payload(self, active_module_ids: list | None) -> dict:
+        return {
+            "messages": self.messages,
+            "board_id": self.board_id,
+            "files": self.files,
+            "file_meta": self.file_meta,
+            "capability_profile": self.capability_profile,
+            "connected_integrations": self.connected_integrations,
+            "active_module_ids": active_module_ids,
+        }
+
+    # ── one turn ──
+    def send(self, user_text: str, on_event=None, active_module_ids: list | None = None) -> TurnResult:
+        """Append the user message, stream the reply, apply file events, return a TurnResult.
+
+        on_event(evt: dict) is called for every SSE event so the caller can render live (text deltas,
+        tool activity, file writes). The VFS and message history are updated in place.
+        """
+        self.messages.append({"role": "user", "content": user_text})
+        res = TurnResult()
+        acc_text = []
+        try:
+            resp = self._request(self._payload(active_module_ids))
+        except Exception as e:
+            res.error = f"backend call failed: {e}"
+            return res
+
+        ctype = (resp.headers.get("Content-Type") or "").lower()
+        if "text/event-stream" not in ctype:
+            # Non-streaming fallback (e.g. a local/old backend returning plain JSON).
+            try:
+                data = json.loads(resp.read().decode())
+            except Exception as e:
+                res.error = f"unexpected backend response: {e}"
+                return res
+            for path, content in (data.get("files") or data.get("project_files") or {}).items():
+                self.files[path] = content
+                res.files_changed.append(path)
+            res.text = data.get("message") or data.get("reply") or ""
+            self.messages.append({"role": "assistant", "content": res.text})
+            return res
+
+        for raw in resp:
+            line = raw.decode("utf-8", "replace").strip()
+            if not line.startswith("data:"):
+                continue
+            try:
+                evt = json.loads(line[5:].strip())
+            except Exception:
+                continue
+            if on_event:
+                on_event(evt)
+            t = evt.get("type")
+            if t == "text":
+                acc_text.append(evt.get("delta", ""))
+            elif t == "file_write":
+                self.files[evt["path"]] = evt.get("content", "")
+                if evt.get("name") or evt.get("kind"):
+                    self.file_meta[evt["path"]] = {"name": evt.get("name"), "kind": evt.get("kind")}
+                res.files_changed.append(evt["path"])
+            elif t == "file_edit":
+                if evt.get("content") is not None:
+                    self.files[evt["path"]] = evt["content"]
+                res.files_changed.append(evt["path"])
+            elif t == "file_delete":
+                self.files.pop(evt["path"], None)
+                res.files_deleted.append(evt["path"])
+            elif t == "done":
+                res.text = evt.get("message") or "".join(acc_text)
+                res.relay_url = evt.get("relay_url")
+                res.device_key = evt.get("device_key")
+            elif t == "error":
+                res.error = evt.get("message", "unknown error")
+
+        if not res.text:
+            res.text = "".join(acc_text)
+        # Dedup changed paths, preserve order.
+        seen = set()
+        res.files_changed = [p for p in res.files_changed if not (p in seen or seen.add(p))]
+        self.messages.append({"role": "assistant", "content": res.text})
+        return res

axiometa_cli/cli.py

@@ -0,0 +1,303 @@
+"""argparse dispatch for axiometa-cli.
+
+`axiometa` with no verb drops into the guided experience (detect -> target -> chat -> deploy ->
+monitor). The verbs are there for scripting and power use: provision the toolchain, set the target,
+one-shot a prompt, deploy, monitor, serve. Codegen is the backend's job over SSE; deploy/monitor/serve
+run locally on the machine the board is plugged into.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __version__, auth, chat, core, detect, interactive, ui
+from . import serve as serve_mod
+
+DEFAULT_BACKEND = os.environ.get("AXIOMETA_BACKEND", "https://studio.axiometa.io")
+
+
+def _pdir(args) -> Path:
+    return Path(getattr(args, "project", None) or os.getcwd()).resolve()
+
+
+def _target(pdir: Path, boards: dict):
+    man = interactive.load_manifest(pdir)
+    board = boards.get(man.get("board")) or boards.get("genesis-one") or next(iter(boards.values()), {"id": "?"})
+    sub = core.resolve_substrate(board, man.get("substrate"))
+    return board, sub
+
+
+# ── verbs ──────────────────────────────────────────────────────────────────────
+def cmd_chat(args):
+    interactive.run(args)
+
+
+def cmd_provision(args):
+    from . import provision
+    boards = core.load_boards()
+    targets = None
+    if args.arduino or args.micropython:
+        targets = set()
+        if args.arduino:
+            targets.add("arduino")
+        if args.micropython:
+            targets.add("micropython")
+    provision.provision(boards, targets, firmware=getattr(args, "firmware", None))
+
+
+def cmd_login(args):
+    """Sign in once: device-code browser flow if the backend supports it, else paste a token. Stored."""
+    if getattr(args, "token", None):
+        p = auth.save_token(args.token)
+        ui.ok(f"token saved ({p})")
+        return
+    backend = args.backend
+    start = auth.device_login_start(backend)
+    if start and start.get("user_code"):
+        url = start.get("verification_url") or backend
+        print()
+        ui.info("To sign in, open this URL and enter the code:")
+        ui.info("    " + ui.c(url, "cyan", "bold"))
+        ui.info("    code:  " + ui.c(start["user_code"], "magenta", "bold"))
+        try:
+            import webbrowser
+            webbrowser.open(start.get("verification_url_complete") or url)
+        except Exception:
+            pass
+        with ui.Spinner("waiting for approval in the browser"):
+            token = auth.device_login_poll(backend, start)
+        if token:
+            ui.ok("signed in")
+        else:
+            ui.err("login did not complete (timed out or was denied).")
+            sys.exit(1)
+        return
+    # Fallback: the backend has no device-code endpoint yet — paste a token.
+    ui.hint("Browser login is not available on this backend yet. Paste your token to sign in")
+    ui.hint("(from a logged-in Studio session), or press Enter to stay in guest mode:")
+    try:
+        import getpass
+        tok = getpass.getpass("token: ").strip() if sys.stdin.isatty() else ""
+    except Exception:
+        tok = ""
+    if tok:
+        p = auth.save_token(tok)
+        ui.ok(f"token saved ({p})")
+    else:
+        ui.warn("no token saved. Guest mode works (~10 builds/day); a token unlocks unlimited.")
+
+
+def cmd_logout(args):
+    if auth.clear_token():
+        ui.ok("signed out (stored token removed).")
+    else:
+        ui.info("no stored token.")
+
+
+def cmd_setup(args):
+    """Enable Pi interfaces (serial / camera / i2c / spi) via raspi-config, with approval."""
+    from . import setup as setup_mod
+    steps = args.steps or ["serial"]
+    ui.banner()
+    ui.info(ui.c("System setup on this Pi", "bold") + ui.c(f"  ({', '.join(steps)})", "grey"))
+    print()
+    res = setup_mod.apply(steps)
+    if res and res.get("_reboot") == "required":
+        ui.hint("reboot to apply:  sudo reboot")
+
+
+def cmd_devices(args):
+    devs = detect.detect()
+    if not devs:
+        ui.warn("no serial devices found.")
+        ph = detect.permission_hint()
+        if ph:
+            ui.hint(ph)
+        return
+    ui.info(ui.c("Connected:", "bold"))
+    for d in devs:
+        print("  " + d.label())
+
+
+def cmd_board(args):
+    pdir = _pdir(args)
+    boards = core.load_boards()
+    if not boards:
+        ui.err("no board facts found (set AXIOMETA_KNOWLEDGE)."); sys.exit(1)
+    man = interactive.load_manifest(pdir)
+    if not args.board_id:
+        cur = man.get("board", "(unset)")
+        for b in boards.values():
+            langs = b.get("languages_available") or [b.get("default_language")]
+            mark = ui.c(" *", "green", "bold") if b["id"] == cur else ""
+            print(f"  {b['id']:<14} {b.get('name',''):<16} [{', '.join(l for l in langs if l)}]{mark}")
+        return
+    if args.board_id not in boards:
+        ui.err(f"unknown board {args.board_id!r}. Known: {list(boards)}"); sys.exit(1)
+    man["board"] = args.board_id
+    if args.substrate:
+        man["substrate"] = args.substrate
+    interactive.save_manifest(pdir, man)
+    sub = core.resolve_substrate(boards[args.board_id], man.get("substrate"))
+    ui.ok(f"target: {boards[args.board_id].get('name')} · {sub['label']} · "
+          f"device={sub['device_program']} · verbs={core.verbs_for(sub)}")
+
+
+def cmd_prompt(args):
+    """One-shot: send a single prompt, stream the reply, write the files."""
+    pdir = _pdir(args)
+    pdir.mkdir(parents=True, exist_ok=True)
+    boards = core.load_boards()
+    if not boards:
+        ui.err("no board facts found (set AXIOMETA_KNOWLEDGE)."); sys.exit(1)
+    board, sub = _target(pdir, boards)
+    profile = core.detect_profile()
+    man = interactive.load_manifest(pdir)
+    session = chat.ChatSession(
+        backend=args.backend, token=auth.get_token(), board_id=board["id"],
+        capability_profile={"surface": profile["surface"], "host_exec": profile["host_exec"]},
+        files=interactive.read_vfs(pdir), connected_integrations=man.get("connected_integrations"),
+    )
+    ui.info(ui.c(f"[{board['id']} · {sub['substrate']} · surface {profile['surface']}]", "grey"))
+    print(ui.c("axie", "cyan", "bold"))
+    res = session.send(args.text, on_event=interactive._Renderer())
+    print()
+    if res.error:
+        ui.err(res.error); sys.exit(1)
+    for path in res.files_changed:
+        dest = pdir / path
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(session.files[path], encoding="utf-8")
+    for path in res.files_deleted:
+        try:
+            (pdir / path).unlink()
+        except Exception:
+            pass
+    if res.files_changed:
+        ui.ok("wrote: " + ", ".join(res.files_changed))
+        verb = "run" if "run" in core.verbs_for(sub) else "deploy"
+        ui.hint(f"next: axiometa {verb}")
+
+
+def cmd_deploy_like(verb):
+    def _cmd(args):
+        pdir = _pdir(args)
+        boards = core.load_boards()
+        board, sub = _target(pdir, boards)
+        port = core.serial_port(sub, args.port)
+        ui.step(f"{verb} → {board.get('name')} on {port or '(autodetect)'}")
+        res = core.deploy(board, sub, pdir, verb, port, on_line=lambda ln: print(ui.c("  " + ln, "grey")))
+        if res.ok:
+            ui.ok(res.detail.splitlines()[0] if res.detail else "done")
+            if verb == "run":
+                ui.hint("test run in RAM — NOT saved. `axiometa install` to persist.")
+        else:
+            ui.err(res.detail)
+        sys.exit(0 if res.ok else 1)
+    return _cmd
+
+
+def cmd_flash(args):
+    """SWD: lay MicroPython firmware onto the RP2040 (Pi HAT) over OpenOCD. One-time / recovery."""
+    pdir = _pdir(args)
+    boards = core.load_boards()
+    board, sub = _target(pdir, boards)
+    fw = Path(args.firmware).expanduser() if args.firmware else None
+    ui.step(f"flash firmware → {board.get('name')} over SWD")
+    res = core.flash_firmware(board, sub, fw, on_line=lambda ln: print(ui.c("  " + ln, "grey")))
+    if res.ok:
+        ui.ok(res.detail.splitlines()[0] if res.detail else "flashed")
+        ui.hint("now deploy code over the UART REPL:  axiometa run   (or  axiometa install)")
+    else:
+        ui.err(res.detail)
+    sys.exit(0 if res.ok else 1)
+
+
+def cmd_host(args):
+    """Run the Pi-side program (host/app.py) on THIS machine, after showing it and getting a yes."""
+    pdir = _pdir(args)
+    interactive.run_host(pdir, show_code=not args.yes, auto_yes=args.yes)
+
+
+def cmd_monitor(args):
+    pdir = _pdir(args)
+    boards = core.load_boards()
+    board, sub = _target(pdir, boards)
+    interactive.monitor(core.serial_port(sub, args.port))
+
+
+def cmd_serve(args):
+    pdir = _pdir(args)
+    profile = core.detect_profile()
+    serve_mod.serve(pdir, core.pick_port(args.port), http_port=args.http_port, over_ssh=profile["over_ssh"])
+
+
+# ── parser ───────────────────────────────────────────────────────────────────
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="axiometa", description="Prompt -> hardware, in your terminal.")
+    p.add_argument("--version", action="version", version=f"axiometa-cli {__version__}")
+    p.add_argument("--backend", default=DEFAULT_BACKEND, help="backend base URL")
+    p.add_argument("--project", help="project dir (default: cwd)")
+    p.add_argument("--port", help="serial port (default: autodetect)")
+    p.set_defaults(func=cmd_chat)  # no verb -> guided experience
+    sub = p.add_subparsers(dest="cmd")
+
+    sub.add_parser("chat", help="the guided build experience (default)").set_defaults(func=cmd_chat)
+
+    pr = sub.add_parser("provision", help="install the local toolchain (arduino-cli/core/libs, mpremote, openocd)")
+    pr.add_argument("--arduino", action="store_true", help="only the Arduino toolchain")
+    pr.add_argument("--micropython", action="store_true", help="only the MicroPython toolchain")
+    pr.add_argument("--firmware", help="MicroPython .uf2/.elf/.bin to SWD-flash onto the Pi HAT during provision")
+    pr.set_defaults(func=cmd_provision)
+
+    lg = sub.add_parser("login", help="sign in (device-code browser flow, or paste a token); stored")
+    lg.add_argument("--token", help="store this token directly (skip the interactive flow)")
+    lg.set_defaults(func=cmd_login)
+
+    sub.add_parser("logout", help="remove the stored token").set_defaults(func=cmd_logout)
+
+    st = sub.add_parser("setup", help="enable Pi interfaces (serial/camera/i2c/spi) via raspi-config, approved")
+    st.add_argument("steps", nargs="*", help="which to enable (default: serial). e.g. serial camera i2c spi")
+    st.set_defaults(func=cmd_setup)
+
+    sub.add_parser("devices", help="list connected boards").set_defaults(func=cmd_devices)
+
+    b = sub.add_parser("board", help="show/set the target board (+ optional substrate)")
+    b.add_argument("board_id", nargs="?"); b.add_argument("--substrate")
+    b.set_defaults(func=cmd_board)
+
+    sp = sub.add_parser("prompt", help="one-shot: describe what to build; writes the files")
+    sp.add_argument("text"); sp.set_defaults(func=cmd_prompt)
+
+    sub.add_parser("run", help="MicroPython: test in RAM (ephemeral)").set_defaults(func=cmd_deploy_like("run"))
+    sub.add_parser("install", help="MicroPython: persist to flash").set_defaults(func=cmd_deploy_like("install"))
+    sub.add_parser("deploy", help="Arduino: compile + flash").set_defaults(func=cmd_deploy_like("deploy"))
+
+    fl = sub.add_parser("flash", help="RP2040 over SWD: lay MicroPython firmware on the chip (Pi HAT)")
+    fl.add_argument("--firmware", help="path to a MicroPython .uf2/.elf/.bin for the RP2040")
+    fl.set_defaults(func=cmd_flash)
+
+    hs = sub.add_parser("host", help="run the Pi-side program host/app.py on this machine (approve first)")
+    hs.add_argument("-y", "--yes", action="store_true", help="skip the approval prompt (you already trust it)")
+    hs.set_defaults(func=cmd_host)
+
+    sub.add_parser("monitor", help="stream the serial channel").set_defaults(func=cmd_monitor)
+
+    sv = sub.add_parser("serve", help="serve browser/*.html locally + bridge serial")
+    sv.add_argument("--http-port", type=int, default=8088); sv.set_defaults(func=cmd_serve)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try:
+        args.func(args)
+    except KeyboardInterrupt:
+        print()
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()