axiometa-cli 1.0.0__tar.gz

axiometa_cli-1.0.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: axiometa-cli
+Version: 1.0.0
+Summary: Prompt to hardware, in your terminal: detect a board, chat to build, deploy, watch serial.
+Author-email: Axiometa <dr.dumcius@gmail.com>
+Project-URL: Homepage, https://axiometa.io
+Project-URL: Studio, https://studio.axiometa.io
+Keywords: hardware,ai,esp32,rp2040,raspberry-pi,arduino,micropython,iot,cli,maker
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.5
+Provides-Extra: micropython
+Requires-Dist: mpremote>=1.20; extra == "micropython"
+
+# axiometa-cli
+
+Prompt → hardware, in your terminal. The CLI is a thin client of the same backend Studio's browser
+talks to: **codegen stays in the cloud** (Claude + the catalog + your auth/limits), and only the
+**local half** — provision the toolchain, deploy, read the serial channel — runs on the machine the
+board is plugged into. Same brain as Studio; the terminal (or a Pi) is the body instead of the browser.
+
+It is one experience whether the board speaks Arduino or MicroPython — the board's facts decide the
+deploy verb (`deploy` = compile+flash on Arduino; `run`/`install` on MicroPython).
+
+## Install
+
+**Raspberry Pi / Linux / macOS** (from a checkout):
+```
+./cli/install.sh
+axiometa provision        # one-time: arduino-cli + ESP32 core + libs (+ mpremote)
+axiometa                  # detect a board and start building
+```
+
+**Windows / any OS** (pip):
+```
+pip install -e cli
+axiometa provision
+axiometa
+```
+
+Config (env, all optional):
+```
+AXIOMETA_BACKEND=https://studio.axiometa.io   # or your local backend
+AXIOMETA_TOKEN=...                            # your auth (carried to the backend)
+AXIOMETA_KNOWLEDGE=/path/to/backend/knowledge/boards   # auto-found next to a repo checkout
+```
+
+## The experience (`axiometa`)
+
+Typing `axiometa` with no verb runs the guided loop:
+
+1. **Detect** — lists connected boards, naming the silicon from its USB identity (ESP32-S3 vs RP2040).
+2. **Target** — confirms the board + language, picks the port, writes `axiometa.json`.
+3. **Toolchain** — if `arduino-cli`/`mpremote` is missing, offers `axiometa provision`.
+4. **Chat** — describe what to build; Axie streams its reply, shows what it's reading, and writes the
+   project files. Refine in follow-ups ("make it blink faster").
+5. **Deploy** — when the device program is (re)generated, offers to flash it (Arduino) or
+   run/install it (MicroPython), streaming the toolchain output.
+6. **Monitor** — after a successful deploy, streams the serial channel so you see the device talk.
+
+Mid-chat commands: `/flash` `/deploy` `/run` `/install` `/monitor` `/serve` `/board` `/help` `/exit`.
+
+## Verbs (scripting / power use)
+
+```
+axiometa provision               # install the local toolchain (one-time)
+axiometa devices                 # list connected boards (with USB identity)
+axiometa board pi-hat            # set the target (writes axiometa.json)
+axiometa prompt "blink the RGB LED on port 1 red"   # one-shot: generate + write files
+axiometa flash --firmware mp.uf2 # RP2040 over SWD: lay MicroPython on the chip (Pi HAT)
+axiometa run                     # MicroPython: test in RAM (ephemeral)
+axiometa install                 # MicroPython: persist to flash
+axiometa deploy                  # Arduino: compile + flash
+axiometa monitor                 # stream serial to the terminal
+axiometa serve                   # serve browser/*.html on 127.0.0.1 (ssh -L hint when headless)
+```
+
+## The Pi HAT (RP2040 flashed over SWD, talked-to over UART)
+
+The Pi HAT's RP2040 has **no USB** — the Raspberry Pi is both its programmer and its host, over the
+40-pin header. So the Pi HAT path differs from a USB board, and the CLI handles it:
+
+- **`axiometa flash --firmware <mp.uf2>`** lays MicroPython onto the chip over **SWD** (OpenOCD
+  bit-banging Pi GPIO24=SWDIO / GPIO25=SWCLK / GPIO23=RUN). A `.uf2` is auto-converted to the `.bin`
+  OpenOCD needs; `.elf`/`.bin` also work. This is one-time, and the brick-recovery path.
+- **`run` / `install` / `monitor`** talk over the Pi's UART at **`/dev/serial0`** (RP2040 GP0/GP1 ↔
+  Pi GPIO15/14), not USB. The CLI ships `board_pins.py` + `boot.py` with each deploy; `boot.py` puts
+  the REPL on UART0 so `mpremote` can reach the board over `/dev/serial0`.
+
+One-time Pi setup (handled by `axiometa provision`, or do it yourself):
+```
+sudo apt install openocd                 # SWD flashing
+sudo raspi-config  -> Serial Port:  login shell over serial = NO, serial hardware = YES   # frees /dev/serial0
+sudo -E axiometa flash --firmware mp.uf2 # SWD needs GPIO/root; -E keeps your env
+```
+Notes: the flashed firmware must expose the **UART REPL** (freeze `boot.py` into the build, or use a
+UART-REPL MicroPython) for first contact. `bcm2835gpio` (the default OpenOCD driver) is Pi 0-4 only;
+on a **Pi 5** set `AXIOMETA_OPENOCD_DRIVER=linuxgpiod`. Override the whole OpenOCD interface with
+`AXIOMETA_OPENOCD_CFG=/path/to.cfg` if your wiring differs.
+
+## Where things live
+
+A **project is a folder** with an `axiometa.json` manifest (board + substrate + modules), the device
+program (`sketch.ino` / `main.py`), any `browser/*.html` surfaces, and `board_pins.py`. `cd` into a
+folder and run `axiometa` — it is project-rooted, like `git`.
+
+## Headless vs. desktop
+
+The CLI detects where a visual surface can render and tells the backend (the `capability_profile`):
+on a Pi with a display it serves the surface to a local browser; headless-over-SSH it prints an
+`ssh -L` line to open it from your own machine; a bare terminal degrades a surface to a serial view.
+
+## Status
+
+The agentic loop is board-agnostic and built: detect → chat (SSE codegen) → flash/deploy → monitor,
+plus a cross-platform `provision`. The Pi HAT's **SWD flash (OpenOCD)** and **UART (`/dev/serial0`)**
+deploy/monitor path is wired and unit-tested (uf2→bin, config generation, dispatch) but **not yet
+validated on real hardware** — exercise it on a connected Pi + RP2040. The one external dependency is
+a MicroPython firmware that exposes the UART REPL.
+
+The native **host-linux** runtime (the "whole Pi" brain: code using the host's own camera/files/GPIO)
+is **not** wired here — it is approval-gated and waits on the trust model in
+`backend/knowledge/runtimes/host-linux/contract.md`.

axiometa_cli-1.0.0/README.md

@@ -0,0 +1,109 @@
+# axiometa-cli
+
+Prompt → hardware, in your terminal. The CLI is a thin client of the same backend Studio's browser
+talks to: **codegen stays in the cloud** (Claude + the catalog + your auth/limits), and only the
+**local half** — provision the toolchain, deploy, read the serial channel — runs on the machine the
+board is plugged into. Same brain as Studio; the terminal (or a Pi) is the body instead of the browser.
+
+It is one experience whether the board speaks Arduino or MicroPython — the board's facts decide the
+deploy verb (`deploy` = compile+flash on Arduino; `run`/`install` on MicroPython).
+
+## Install
+
+**Raspberry Pi / Linux / macOS** (from a checkout):
+```
+./cli/install.sh
+axiometa provision        # one-time: arduino-cli + ESP32 core + libs (+ mpremote)
+axiometa                  # detect a board and start building
+```
+
+**Windows / any OS** (pip):
+```
+pip install -e cli
+axiometa provision
+axiometa
+```
+
+Config (env, all optional):
+```
+AXIOMETA_BACKEND=https://studio.axiometa.io   # or your local backend
+AXIOMETA_TOKEN=...                            # your auth (carried to the backend)
+AXIOMETA_KNOWLEDGE=/path/to/backend/knowledge/boards   # auto-found next to a repo checkout
+```
+
+## The experience (`axiometa`)
+
+Typing `axiometa` with no verb runs the guided loop:
+
+1. **Detect** — lists connected boards, naming the silicon from its USB identity (ESP32-S3 vs RP2040).
+2. **Target** — confirms the board + language, picks the port, writes `axiometa.json`.
+3. **Toolchain** — if `arduino-cli`/`mpremote` is missing, offers `axiometa provision`.
+4. **Chat** — describe what to build; Axie streams its reply, shows what it's reading, and writes the
+   project files. Refine in follow-ups ("make it blink faster").
+5. **Deploy** — when the device program is (re)generated, offers to flash it (Arduino) or
+   run/install it (MicroPython), streaming the toolchain output.
+6. **Monitor** — after a successful deploy, streams the serial channel so you see the device talk.
+
+Mid-chat commands: `/flash` `/deploy` `/run` `/install` `/monitor` `/serve` `/board` `/help` `/exit`.
+
+## Verbs (scripting / power use)
+
+```
+axiometa provision               # install the local toolchain (one-time)
+axiometa devices                 # list connected boards (with USB identity)
+axiometa board pi-hat            # set the target (writes axiometa.json)
+axiometa prompt "blink the RGB LED on port 1 red"   # one-shot: generate + write files
+axiometa flash --firmware mp.uf2 # RP2040 over SWD: lay MicroPython on the chip (Pi HAT)
+axiometa run                     # MicroPython: test in RAM (ephemeral)
+axiometa install                 # MicroPython: persist to flash
+axiometa deploy                  # Arduino: compile + flash
+axiometa monitor                 # stream serial to the terminal
+axiometa serve                   # serve browser/*.html on 127.0.0.1 (ssh -L hint when headless)
+```
+
+## The Pi HAT (RP2040 flashed over SWD, talked-to over UART)
+
+The Pi HAT's RP2040 has **no USB** — the Raspberry Pi is both its programmer and its host, over the
+40-pin header. So the Pi HAT path differs from a USB board, and the CLI handles it:
+
+- **`axiometa flash --firmware <mp.uf2>`** lays MicroPython onto the chip over **SWD** (OpenOCD
+  bit-banging Pi GPIO24=SWDIO / GPIO25=SWCLK / GPIO23=RUN). A `.uf2` is auto-converted to the `.bin`
+  OpenOCD needs; `.elf`/`.bin` also work. This is one-time, and the brick-recovery path.
+- **`run` / `install` / `monitor`** talk over the Pi's UART at **`/dev/serial0`** (RP2040 GP0/GP1 ↔
+  Pi GPIO15/14), not USB. The CLI ships `board_pins.py` + `boot.py` with each deploy; `boot.py` puts
+  the REPL on UART0 so `mpremote` can reach the board over `/dev/serial0`.
+
+One-time Pi setup (handled by `axiometa provision`, or do it yourself):
+```
+sudo apt install openocd                 # SWD flashing
+sudo raspi-config  -> Serial Port:  login shell over serial = NO, serial hardware = YES   # frees /dev/serial0
+sudo -E axiometa flash --firmware mp.uf2 # SWD needs GPIO/root; -E keeps your env
+```
+Notes: the flashed firmware must expose the **UART REPL** (freeze `boot.py` into the build, or use a
+UART-REPL MicroPython) for first contact. `bcm2835gpio` (the default OpenOCD driver) is Pi 0-4 only;
+on a **Pi 5** set `AXIOMETA_OPENOCD_DRIVER=linuxgpiod`. Override the whole OpenOCD interface with
+`AXIOMETA_OPENOCD_CFG=/path/to.cfg` if your wiring differs.
+
+## Where things live
+
+A **project is a folder** with an `axiometa.json` manifest (board + substrate + modules), the device
+program (`sketch.ino` / `main.py`), any `browser/*.html` surfaces, and `board_pins.py`. `cd` into a
+folder and run `axiometa` — it is project-rooted, like `git`.
+
+## Headless vs. desktop
+
+The CLI detects where a visual surface can render and tells the backend (the `capability_profile`):
+on a Pi with a display it serves the surface to a local browser; headless-over-SSH it prints an
+`ssh -L` line to open it from your own machine; a bare terminal degrades a surface to a serial view.
+
+## Status
+
+The agentic loop is board-agnostic and built: detect → chat (SSE codegen) → flash/deploy → monitor,
+plus a cross-platform `provision`. The Pi HAT's **SWD flash (OpenOCD)** and **UART (`/dev/serial0`)**
+deploy/monitor path is wired and unit-tested (uf2→bin, config generation, dispatch) but **not yet
+validated on real hardware** — exercise it on a connected Pi + RP2040. The one external dependency is
+a MicroPython firmware that exposes the UART REPL.
+
+The native **host-linux** runtime (the "whole Pi" brain: code using the host's own camera/files/GPIO)
+is **not** wired here — it is approval-gated and waits on the trust model in
+`backend/knowledge/runtimes/host-linux/contract.md`.

axiometa_cli-1.0.0/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-1.0.0/axiometa_cli/__main__.py

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

axiometa_cli-1.0.0/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-1.0.0/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