acsetra 0.1.0__py3-none-any.whl

acsetra-0.1.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: acsetra
+Version: 0.1.0
+Summary: Runner CLI — author and run hosted Runner apps from your terminal (the `runner` command).
+Project-URL: Homepage, https://acsetra.com
+Author: Acsetra
+License: MIT
+Keywords: acsetra,agent,cli,low-code,runner
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# acsetra — the Runner CLI
+
+A thin client for building and running **hosted Runner apps** from your terminal.
+It holds no framework logic: every authoring command serializes to `{op, args}`
+and is POSTed to the hosted API, where validation, reserved-code guards, and
+doctor compiles all run server-side. You get the *grammar* of the framework, not
+its implementation.
+
+## Install
+
+```bash
+pipx install acsetra        # recommended (isolated)
+# or: pip install acsetra
+runner signin
+```
+
+Exposes three console scripts — `runner` (primary), `acsetra` (brand alias), and
+`r` (continuity with `./r`).
+
+## Quick start
+
+```bash
+runner signin                              # device-flow sign-in; caches a token
+runner whoami
+runner app create crm --label "CRM"        # create an app scope in your workspace
+runner set put crm contacts ada --json '{"role":"eng"}'
+runner read contacts -S <workspace>.crm
+runner doctor <workspace>.crm && runner compile <workspace>.crm
+runner dev <workspace>.crm                 # localhost surface proxied to hosted Runner
+```
+
+## How it fits together
+
+- `runner signin` runs the OAuth device flow: it prints a URL + code, you approve
+  in the browser, and the CLI caches a token at `~/.config/acsetra/credentials` (0600).
+- `runner docs pull` writes `CLAUDE.md` + `.runner/docs/*` — a compact model of the
+  framework, the exact command grammar, and a live skeleton of your app — so a
+  coding agent (Claude Code) has the context it needs to build with `runner`.
+- The hosted DB is the source of truth. Local files are **instructions and mirrors**,
+  never runtime source. `runner checkout`/`runner dev` produce disposable working
+  copies under `.tmp/` for grep and inspection.
+
+## Environment overrides
+
+| Var | Meaning |
+|---|---|
+| `ACSETRA_API_BASE` | hosted API origin (default `https://pen.acsetra.com`) |
+| `ACSETRA_TOKEN` | bearer token (skips the cached credential) |
+| `ACSETRA_WORKSPACE` | act in this workspace slug |
+| `ACSETRA_SCOPE` | default app scope for `-S`-less commands |
+
+Run `runner help` for the full verb list.

acsetra-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+acsetra_cli/__init__.py,sha256=9U38n-isE94tEn9YaKGBiR7xwnrQ3H3aq6d_rTGp6AA,360
+acsetra_cli/__main__.py,sha256=wEeH6JdwAxaS0RtX_n0vlYBX9C2HHchUazratRuDUIY,5733
+acsetra_cli/api.py,sha256=zZrWd9YrK03hj374AfHR3CTnFhvn52SO49vjy1qK6K4,2822
+acsetra_cli/config.py,sha256=-IOenIL-V33dfCOsxHyR3gd2AAHwbtglM4QXGDk-Kb4,2197
+acsetra_cli/dev.py,sha256=K_3leT4-G1A76gD2lsFIGTdXbK46WCZtzJPBXqMGHvU,5453
+acsetra_cli/docs.py,sha256=ZMuwey-aN6XtmStbu-kNE8XlYFVXgbiOU925Ay_N1RY,1406
+acsetra_cli/signin.py,sha256=i1AxfcQFbxiFGo28Gh4ePpbfl5bnQ5PaoKRcED1TfgM,2525
+acsetra_cli/verbs.py,sha256=pyVhqTO_TJmr64M7gD09ti1RwFkXBEQqJPUd2GGKRhw,12917
+acsetra-0.1.0.dist-info/METADATA,sha256=KyBY_LENDsszXo7f949y5QI0UvE-eMWr7gMRx0q4B2U,2430
+acsetra-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+acsetra-0.1.0.dist-info/entry_points.txt,sha256=rRbLUKJqy41zhDKaDjM51L-lC70LktEaZTF7wGsyQYo,119
+acsetra-0.1.0.dist-info/RECORD,,

acsetra-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

acsetra-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+acsetra = acsetra_cli.__main__:main
+r = acsetra_cli.__main__:main
+runner = acsetra_cli.__main__:main

acsetra_cli/__init__.py

@@ -0,0 +1,8 @@
+"""acsetra — the Runner CLI client.
+
+A thin client over the hosted Runner API. It holds NO framework logic: every
+authoring command serializes to {op, args} and POSTs to /api/v1/op, where the real
+validation, reserved-code guards, and doctor compiles run server-side. Users get
+the GRAMMAR of the framework, not its implementation.
+"""
+__version__ = "0.1.0"

acsetra_cli/__main__.py

@@ -0,0 +1,140 @@
+"""runner — the CLI entry point.
+
+Top-level: a handful of client commands (signin, whoami, workspaces, docs, dev,
+usage, tokens). Everything else is an authoring verb that serializes to {op, args}
+and POSTs to /api/v1/op. JSON to stdout; any rejection to stderr + exit 1, so an
+agent loop can branch on the exit code exactly like it does with `./r`.
+"""
+import json
+import sys
+
+from . import __version__, api, config, docs as docs_mod, signin as signin_mod
+from . import dev as dev_mod
+from .verbs import VerbError, to_op
+
+HELP = """runner — author and run hosted Runner apps.
+
+Session
+  runner signin [--api URL]      sign in (device flow); caches a token
+  runner whoami                  show the signed-in user + workspace
+  runner workspaces [--use SLUG] list workspaces; --use switches the active one
+  runner use <slug>              set the active workspace for this project
+  runner logout                  forget the cached token
+  runner usage [--days N]        metered usage vs your plan caps
+  runner tokens [new|list|revoke <id>]
+
+Context + dev
+  runner docs pull [-S scope]    refresh CLAUDE.md + .runner/docs/*
+  runner dev <app> [--hosted]    localhost surface proxied to hosted Runner
+
+Authoring (serialized to /api/v1/op)
+  runner app create <name>       create an app scope; runner apps  lists them
+  runner ls | inspect <set>      list / read value sets        (-S scope)
+  runner set put <set> <row> --json '{…}'        write a row
+  runner pipe <code> -S <scope> --writes c:l     create a pipeline
+  runner w <code> snippet -b -                   add a worker (stdin body)
+  runner css|component|asset|behavior|head <sub> …
+  runner read <code>             read a value set (me_* = your own zone)
+  runner run <pipeline> -i '{…}' ; runner runs <id>
+  runner doctor <app> ; runner compile <app>
+  runner op <name> --json '{…}'  call any op directly
+
+Env: ACSETRA_API_BASE, ACSETRA_TOKEN, ACSETRA_WORKSPACE, ACSETRA_SCOPE
+"""
+
+
+def emit(result):
+    # peel the /op envelope {ok, result}, then the dispatch envelope {ok, op, scope,
+    # result}, so the CLI prints the actual payload — not nested confirmation wrappers.
+    if isinstance(result, dict) and "result" in result and set(result.keys()) <= {"ok", "result"}:
+        result = result["result"]
+    if isinstance(result, dict) and "result" in result and set(result.keys()) <= {"ok", "op", "scope", "result"}:
+        result = result["result"]
+    print(json.dumps(result, indent=2, default=str, ensure_ascii=False))
+
+
+def fail(msg, code=1):
+    print(f"REJECTED: {msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("help", "-h", "--help"):
+        print(HELP); return 0
+    cmd, rest = argv[0], argv[1:]
+
+    if cmd in ("version", "--version", "-V"):
+        print(f"runner (acsetra) {__version__}"); return 0
+
+    # --- client-only commands ---------------------------------------------
+    if cmd in ("signin", "login"):
+        api_base = _opt(rest, "--api")
+        return signin_mod.signin(api_base=api_base, open_browser="--no-browser" not in rest)
+    if cmd in ("logout", "signout"):
+        cred = config.load_user(); cred.pop("token", None); config.save_user(cred)
+        print("logged out", file=sys.stderr); return 0
+    if cmd == "use":
+        if not rest:
+            fail("usage: runner use <workspace-slug>")
+        config.set_project(workspace=rest[0]); print(f"workspace -> {rest[0]}", file=sys.stderr); return 0
+    if cmd == "dev":
+        app = rest[0] if rest and not rest[0].startswith("-") else None
+        return dev_mod.dev(app, port=int(_opt(rest, "--port") or 8787),
+                           hosted="--hosted" in rest, open_browser="--no-browser" not in rest)
+    if cmd == "docs":
+        if rest and rest[0] == "pull":
+            return docs_mod.pull(scope=_opt(rest, "-S") or _opt(rest, "--scope"))
+        fail("usage: runner docs pull [-S scope]")
+
+    # --- everything below needs the API; wrap API errors uniformly --------
+    try:
+        if cmd == "whoami":
+            return emit(api.get("/api/v1/whoami")) or 0
+        if cmd == "workspaces":
+            use = _opt(rest, "--use")
+            if use:
+                config.set_project(workspace=use)
+            return emit(api.get("/api/v1/workspaces")) or 0
+        if cmd == "usage":
+            days = _opt(rest, "--days") or "30"
+            return emit(api.get("/api/v1/usage", {"days": days})) or 0
+        if cmd == "tokens":
+            return _tokens(rest)
+
+        # --- authoring verbs ---------------------------------------------
+        op, args = to_op(cmd, rest)
+        result = api.post_op(op, args)
+        emit(result)
+        return 0
+    except VerbError as e:
+        fail(str(e), 2)
+    except api.ApiError as e:
+        detail = ""
+        if e.detail and isinstance(e.detail, dict):
+            extra = {k: v for k, v in e.detail.items() if k != "error"}
+            if extra:
+                detail = " " + json.dumps(extra, default=str)
+        fail(f"{e}{detail}", 1)
+
+
+def _tokens(rest):
+    if rest and rest[0] == "new":
+        out = api.post("/api/v1/tokens", {"name": _opt(rest, "--name") or "cli"})
+        print(json.dumps(out, indent=2)); return 0
+    if rest and rest[0] == "revoke" and len(rest) > 1:
+        return emit(api.delete(f"/api/v1/tokens/{rest[1]}")) or 0
+    return emit(api.get("/api/v1/tokens")) or 0
+
+
+def _opt(rest, flag):
+    """Pull `--flag value` out of a flat arg list (for client-only commands)."""
+    if flag in rest:
+        i = rest.index(flag)
+        if i + 1 < len(rest):
+            return rest[i + 1]
+    return None
+
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)

acsetra_cli/api.py

@@ -0,0 +1,88 @@
+"""The HTTP layer — every command ends up here.
+
+A tiny wrapper over httpx that attaches the bearer token + workspace header and
+turns non-2xx responses into a clean ApiError (so the CLI can print the server's
+message and exit 1, the same branch contract as ./r's REJECTED).
+"""
+import httpx
+
+from . import config
+
+
+class ApiError(Exception):
+    def __init__(self, message, status=0, detail=None):
+        self.status, self.detail = status, detail or {}
+        super().__init__(message)
+
+
+def _headers(auth=True):
+    h = {"Content-Type": "application/json"}
+    if auth:
+        tok = config.token()
+        if not tok:
+            raise ApiError("not signed in — run `runner signin`", 401)
+        h["Authorization"] = "Bearer " + tok
+        ws = config.workspace()
+        if ws:
+            h["X-Runner-Workspace"] = ws
+    return h
+
+
+def _base():
+    return config.api_base()
+
+
+def _check(resp):
+    if resp.status_code // 100 == 2:
+        return resp.json() if resp.content else {}
+    try:
+        body = resp.json()
+        msg = body.get("error") or body.get("detail") or resp.text
+    except Exception:
+        body, msg = {}, resp.text
+    raise ApiError(msg, resp.status_code, body)
+
+
+def post_op(op, args, *, timeout=120):
+    """The one authoring call: POST /api/v1/op {op, args}."""
+    with httpx.Client(timeout=timeout) as c:
+        r = c.post(_base() + "/api/v1/op", json={"op": op, "args": args}, headers=_headers())
+    return _check(r)
+
+
+def get(path, params=None, *, auth=True, timeout=60):
+    with httpx.Client(timeout=timeout) as c:
+        r = c.get(_base() + path, params=params, headers=_headers(auth))
+    return _check(r)
+
+
+def post(path, body=None, *, auth=True, timeout=60):
+    with httpx.Client(timeout=timeout) as c:
+        r = c.post(_base() + path, json=body or {}, headers=_headers(auth))
+    return _check(r)
+
+
+def delete(path, *, timeout=60):
+    with httpx.Client(timeout=timeout) as c:
+        r = c.delete(_base() + path, headers=_headers())
+    return _check(r)
+
+
+# --- device flow (used by signin; no bearer yet) ---------------------------
+def device_start(token_name="cli"):
+    with httpx.Client(timeout=30) as c:
+        r = c.post(_base() + "/api/v1/auth/device/start", json={"token_name": token_name},
+                   headers={"Content-Type": "application/json"})
+    return _check(r)
+
+
+def device_token(device_code):
+    """Poll the grant. Returns (status_code, body) WITHOUT raising, because the
+    poll's 202/410/403 are control signals, not errors."""
+    with httpx.Client(timeout=30) as c:
+        r = c.post(_base() + "/api/v1/auth/device/token", json={"device_code": device_code},
+                   headers={"Content-Type": "application/json"})
+    try:
+        return r.status_code, r.json()
+    except Exception:
+        return r.status_code, {}

acsetra_cli/config.py

@@ -0,0 +1,79 @@
+"""Config + credential resolution.
+
+Two stores, resolved in order (env wins, then project, then user):
+  - env: ACSETRA_API_BASE / ACSETRA_TOKEN / ACSETRA_WORKSPACE
+  - project: ./.runner/config.json  (api_base, workspace, default_scope, dev_port)
+  - user:    ~/.config/acsetra/credentials  (api_base, token, workspace, user_sub)
+
+The token only ever lives in the user credential file (chmod 600), never in the
+project config (which is safe to commit). signin writes the user store; `--api`
+and workspace switches update the project store.
+"""
+import json
+import os
+import stat
+from pathlib import Path
+
+DEFAULT_API_BASE = "https://pen.acsetra.com"
+
+USER_DIR = Path(os.environ.get("ACSETRA_HOME") or (Path.home() / ".config" / "acsetra"))
+CRED_PATH = USER_DIR / "credentials"
+PROJECT_DIR = Path(".runner")
+PROJECT_CFG = PROJECT_DIR / "config.json"
+
+
+def _read_json(path):
+    try:
+        return json.loads(Path(path).read_text())
+    except (FileNotFoundError, ValueError, OSError):
+        return {}
+
+
+def load_user():
+    return _read_json(CRED_PATH)
+
+
+def load_project():
+    return _read_json(PROJECT_CFG)
+
+
+def save_user(data):
+    USER_DIR.mkdir(parents=True, exist_ok=True)
+    CRED_PATH.write_text(json.dumps(data, indent=2))
+    try:
+        CRED_PATH.chmod(stat.S_IRUSR | stat.S_IWUSR)   # 0600 — secrets are user-only
+    except OSError:
+        pass
+
+
+def save_project(data):
+    PROJECT_DIR.mkdir(parents=True, exist_ok=True)
+    PROJECT_CFG.write_text(json.dumps(data, indent=2))
+
+
+def api_base():
+    return (os.environ.get("ACSETRA_API_BASE")
+            or load_project().get("api_base")
+            or load_user().get("api_base")
+            or DEFAULT_API_BASE).rstrip("/")
+
+
+def token():
+    return os.environ.get("ACSETRA_TOKEN") or load_user().get("token")
+
+
+def workspace():
+    return (os.environ.get("ACSETRA_WORKSPACE")
+            or load_project().get("workspace")
+            or load_user().get("workspace"))
+
+
+def default_scope():
+    return os.environ.get("ACSETRA_SCOPE") or load_project().get("default_scope")
+
+
+def set_project(**kw):
+    cfg = load_project()
+    cfg.update({k: v for k, v in kw.items() if v is not None})
+    save_project(cfg)
+    return cfg

acsetra_cli/dev.py

@@ -0,0 +1,133 @@
+"""runner dev <app> — localhost ergonomics over the hosted engine (prod.md §Local dev).
+
+The app is rows in hosted Runner, so "local dev" means: make the hosted app
+comfortable to work on from a local URL. This starts a small localhost server that
+proxies the runtime surface (/, /bundle, /feed, /run, /read, assets) to hosted
+Runner, attaching a session cookie obtained by trading the workspace bearer for a
+scoped dev session. The browser gets same-origin localhost ergonomics; the real
+engine, DB, workers, auth, and metering stay server-side.
+
+  runner dev <app>            proxy on http://127.0.0.1:8787
+  runner dev <app> --hosted   just open the canonical hosted URL (no proxy)
+"""
+import sys
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlparse
+
+import httpx
+
+from . import api, config
+
+# hop-by-hop headers we must not forward (RFC 7230 §6.1) + ones httpx re-derives.
+_STRIP = {"connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+          "te", "trailers", "transfer-encoding", "upgrade", "host", "content-length",
+          "accept-encoding"}
+
+
+def dev(app, port=8787, hosted=False, open_browser=True):
+    base = config.api_base()
+    scope = app or config.default_scope()
+    if not scope:
+        print("runner dev: which app? pass a scope, e.g. `runner dev acme.crm`", file=sys.stderr)
+        return 2
+
+    if hosted:
+        url = f"{base}/?scope={scope}"
+        print(f"Opening hosted app: {url}", file=sys.stderr)
+        if open_browser:
+            try: webbrowser.open(url)
+            except Exception: pass
+        return 0
+
+    # Trade the bearer for a runtime session cookie scoped to this app.
+    try:
+        sess = api.post("/api/v1/dev/session", {"scope": scope})
+    except api.ApiError as e:
+        print(f"runner dev: could not open a dev session: {e}", file=sys.stderr)
+        return 1
+    cookie = f"{sess['cookie_name']}={sess['cookie_value']}"
+    prefix = sess.get("prefix", "")
+    target = urlparse(base)
+    upstream = f"{target.scheme}://{target.netloc}"
+
+    handler = _make_handler(upstream, cookie, scope)
+    httpd = ThreadingHTTPServer(("127.0.0.1", port), handler)
+    local = f"http://127.0.0.1:{port}{prefix}/?scope={scope}"
+    print(f"runner dev: proxying {scope} → {upstream}", file=sys.stderr)
+    print(f"  open  {local}", file=sys.stderr)
+    print("  (Ctrl-C to stop)", file=sys.stderr)
+    if open_browser:
+        threading.Timer(0.6, lambda: _safe_open(local)).start()
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\nrunner dev: stopped", file=sys.stderr)
+    finally:
+        httpd.server_close()
+    return 0
+
+
+def _safe_open(url):
+    try: webbrowser.open(url)
+    except Exception: pass
+
+
+def _make_handler(upstream, cookie, scope):
+    class Proxy(BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.1"
+
+        def log_message(self, *a):
+            pass
+
+        def _fwd(self, method):
+            length = int(self.headers.get("content-length", 0) or 0)
+            body = self.rfile.read(length) if length else None
+            headers = {k: v for k, v in self.headers.items() if k.lower() not in _STRIP}
+            headers["cookie"] = cookie + ("; " + headers["cookie"] if headers.get("cookie") else "")
+            url = upstream + self.path
+            is_sse = self.path.split("?")[0].endswith("/feed")
+            try:
+                if is_sse:
+                    return self._stream(method, url, headers, body)
+                with httpx.Client(timeout=120, follow_redirects=False) as c:
+                    r = c.request(method, url, headers=headers, content=body)
+                self._respond(r.status_code, r.headers, r.content)
+            except Exception as e:
+                self._respond(502, {"content-type": "text/plain"}, f"dev proxy error: {e}".encode())
+
+        def _stream(self, method, url, headers, body):
+            with httpx.Client(timeout=None) as c:
+                with c.stream(method, url, headers=headers, content=body) as r:
+                    self.send_response(r.status_code)
+                    for k, v in r.headers.items():
+                        if k.lower() not in _STRIP and k.lower() != "content-length":
+                            self.send_header(k, v)
+                    self.send_header("connection", "keep-alive")
+                    self.end_headers()
+                    try:
+                        for chunk in r.iter_raw():
+                            if chunk:
+                                self.wfile.write(chunk); self.wfile.flush()
+                    except (BrokenPipeError, ConnectionResetError):
+                        pass
+
+        def _respond(self, status, headers, content):
+            self.send_response(status)
+            for k, v in headers.items():
+                if k.lower() not in _STRIP:
+                    self.send_header(k, v)
+            self.send_header("content-length", str(len(content)))
+            self.end_headers()
+            if content:
+                try: self.wfile.write(content)
+                except (BrokenPipeError, ConnectionResetError): pass
+
+        do_GET = lambda self: self._fwd("GET")
+        do_POST = lambda self: self._fwd("POST")
+        do_PUT = lambda self: self._fwd("PUT")
+        do_DELETE = lambda self: self._fwd("DELETE")
+        do_PATCH = lambda self: self._fwd("PATCH")
+
+    return Proxy

acsetra_cli/docs.py

@@ -0,0 +1,41 @@
+"""runner docs pull — hydrate the agent's local context (prod.md §Context pack).
+
+Fetches the versioned Markdown pack from the server and writes CLAUDE.md +
+.runner/docs/*. Never clobbers a user's own notes: any path ending in `.local.md`
+is left untouched, and we record the pack version in .runner/config.json so a
+no-change pull is a cheap no-op.
+"""
+import sys
+from pathlib import Path
+
+from . import api, config
+
+
+def pull(scope=None, target="claude"):
+    params = {"target": target}
+    sc = scope or config.default_scope()
+    if sc:
+        params["scope"] = sc
+    try:
+        pack = api.get("/api/v1/context-pack", params)
+    except api.ApiError as e:
+        print(f"docs pull failed: {e}", file=sys.stderr)
+        return 1
+
+    written, skipped = [], []
+    for rel, content in pack["files"].items():
+        p = Path(rel)
+        if p.name.endswith(".local.md"):
+            skipped.append(rel)
+            continue
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content)
+        written.append(rel)
+
+    config.set_project(context_version=pack.get("version"), workspace=pack.get("workspace"))
+    print(f"docs: wrote {len(written)} files (version {pack.get('version')})", file=sys.stderr)
+    for w in written:
+        print(f"  {w}", file=sys.stderr)
+    if skipped:
+        print(f"  kept {len(skipped)} *.local.md untouched", file=sys.stderr)
+    return 0

acsetra_cli/signin.py

@@ -0,0 +1,67 @@
+"""runner signin — the OAuth device flow (prod.md §Sign-in).
+
+Print a URL + short code, the human approves it in the browser, the CLI polls
+until it gets a token, and the token is cached at ~/.config/acsetra/credentials
+(0600). No token -> every command tells you to run `runner signin`, so sign-in is
+structurally required, not a flag.
+"""
+import sys
+import time
+import webbrowser
+
+from . import api, config
+
+
+def signin(api_base=None, token_name="cli", open_browser=True):
+    if api_base:
+        config.set_project(api_base=api_base.rstrip("/"))
+    base = config.api_base()
+    print(f"Signing in to {base}", file=sys.stderr)
+    try:
+        start = api.device_start(token_name)
+    except api.ApiError as e:
+        print(f"could not start sign-in: {e}", file=sys.stderr)
+        return 1
+
+    user_code = start["user_code"]
+    verify = start.get("verification_uri_complete") or start.get("verification_uri")
+    interval = max(1, int(start.get("interval", 5)))
+    device_code = start["device_code"]
+
+    print("\n  To sign in, visit:\n")
+    print(f"    {verify}\n")
+    print(f"  and confirm the code:  {user_code}\n", file=sys.stderr)
+    if open_browser:
+        try:
+            webbrowser.open(verify)
+        except Exception:
+            pass
+
+    deadline = time.time() + int(start.get("expires_in", 900))
+    while time.time() < deadline:
+        time.sleep(interval)
+        status, body = api.device_token(device_code)
+        st = body.get("status")
+        if status == 200 and body.get("token"):
+            _persist(base, body)
+            print(f"\n✓ Signed in. Workspace: {body.get('workspace')}", file=sys.stderr)
+            return 0
+        if st == "denied":
+            print("\n✗ Sign-in was denied.", file=sys.stderr)
+            return 1
+        if st in ("expired",) or status == 410:
+            print("\n✗ The code expired. Run `runner signin` again.", file=sys.stderr)
+            return 1
+        # 202 pending / 404 not-yet-visible -> keep polling
+    print("\n✗ Timed out waiting for approval.", file=sys.stderr)
+    return 1
+
+
+def _persist(base, body):
+    cred = config.load_user()
+    cred.update({"api_base": base, "token": body["token"],
+                 "workspace": body.get("workspace"), "scope_root": body.get("scope_root")})
+    config.save_user(cred)
+    # mirror the workspace into the project config (safe to commit; no token)
+    config.set_project(api_base=base, workspace=body.get("workspace"),
+                       default_scope=body.get("scope_root"))

acsetra_cli/verbs.py

@@ -0,0 +1,292 @@
+"""The verb grammar — argv turned into {op, args}.
+
+A thin client can't know each op's schema, but the framework's grammar is small
+and stable, so we carry a compact map of POSITIONAL arg names per op and let
+everything else arrive as --flags / --json. The server binds args BY NAME, so the
+client only has to get the right names into the bag — positional or flag, either
+works. Short names (`w`, `i`, `ls`) and the `-b -` stdin body convention mirror
+`./r`. Anything without a friendly verb is still reachable via `runner op <name>`.
+"""
+import json
+import sys
+
+# Arg names whose values are parsed as JSON (or @file). Everything else is a string.
+# ('writes' is NOT here: for pipe.set it is the `code:label` shorthand, for a worker
+#  it is a bare set code — both strings, handled in their verb branches.)
+JSON_ARGS = {"meta", "schema", "decls", "tree", "props", "parts", "input",
+             "attrs", "config", "config_schema", "storage", "allow_hosts", "spec"}
+
+# For these ops a bare `--json '{…}'` IS the primary payload arg (mirrors ./r, where
+# `set put … --json` is the row meta). Anywhere else, --json merges into args.
+PRIMARY_JSON = {
+    "set.put": "meta", "set.fetch_url": "meta", "set.declare_schema": "schema",
+    "css.set_rule": "decls", "component.set": "tree", "component.set_route": "props",
+    "behavior.attach": "config", "head.set": "attrs",
+}
+INT_ARGS = {"ordinal", "rate", "timeout", "retries", "at", "max_bytes", "ttl_days", "days"}
+FLOAT_ARGS = {"backoff"}
+BOOL_ARGS = {"replace", "force", "keep", "probe", "enabled", "muted", "autoplay",
+             "controls", "auth_flow"}
+
+# Ordered positional arg names per op (UX only; the server binds by name).
+POS = {
+    "set.create": ["code"], "set.put": ["set_code", "row_code"],
+    "set.declare_schema": ["code"], "set.fetch_url": ["set_code", "row_code", "url"],
+    "set.remove_row": ["set_code", "row_code"], "set.drop": ["set_code"],
+    "set.describe": ["set_code"], "set.rows": ["set_code"],
+    "pipe.set": ["code"], "pipe.show": ["code"], "pipe.remove": ["code"],
+    "css.set_class": ["code"], "css.set_rule": ["class_code", "variant"],
+    "css.clear_rule": ["class_code"], "css.attach": ["class_code", "target"],
+    "css.detach": ["code"], "css.describe": ["class_code"], "css.resolve": ["page"],
+    "asset.add": ["code", "kind"], "asset.attach": ["asset", "slot"],
+    "asset.detach": ["code"], "asset.describe": ["code"], "asset.resolve": ["page"],
+    "behavior.add": ["code"], "behavior.set_enabled": ["code", "enabled"],
+    "behavior.remove": ["code"], "behavior.attach": ["behavior_code", "target"],
+    "behavior.set_attachment_enabled": ["code", "enabled"], "behavior.detach": ["code"],
+    "behavior.describe": ["code"],
+    "component.set": ["code"], "component.remove": ["code"],
+    "component.set_route": ["code", "component"], "component.remove_route": ["code"],
+    "component.describe": ["code"],
+    "head.set": ["code"], "head.remove": ["code"],
+}
+
+# Planes that take `runner <plane> <subverb> …` (subverb maps to op `<plane>.<subverb>`).
+PLANES = {"set", "css", "asset", "behavior", "component", "head"}
+
+# Short flag aliases (match ./r): -w writes, -k keys, -u url, -f body_from, etc.
+SHORT = {"w": "writes", "k": "keys", "u": "url", "f": "body_from", "H": "handler",
+         "X": "method", "s": "spec", "l": "label", "i": "input"}
+
+
+class VerbError(Exception):
+    pass
+
+
+def coerce(name, value):
+    if value is None:
+        return None
+    try:
+        if name in JSON_ARGS:
+            if isinstance(value, str) and value.startswith("@"):
+                with open(value[1:]) as f:
+                    return json.load(f)
+            return json.loads(value) if isinstance(value, str) else value
+        if name in INT_ARGS:
+            return int(value)
+        if name in FLOAT_ARGS:
+            return float(value)
+        if name in BOOL_ARGS:
+            return str(value).lower() in ("1", "true", "yes", "on")
+    except (ValueError, OSError) as e:
+        raise VerbError(f"bad value for --{name}: {e}")
+    return value
+
+
+def _read_body(value):
+    return sys.stdin.read() if value == "-" else value
+
+
+def _walk(rest):
+    """Split the argv tail into (positionals, flags). Handles -S/--scope, --json,
+    -b/--body, bare boolean flags, and --name value pairs."""
+    positionals, flags = [], {}
+    i = 0
+    while i < len(rest):
+        tok = rest[i]
+        if tok in ("-S", "--scope"):
+            flags["scope"] = rest[i + 1]; i += 2; continue
+        if tok in ("-b", "--body"):
+            flags["__body"] = _read_body(rest[i + 1]); i += 2; continue
+        if tok == "--json":
+            blob = rest[i + 1]
+            obj = (json.load(open(blob[1:])) if blob.startswith("@") else json.loads(blob))
+            flags.setdefault("__json", {}).update(obj); i += 2; continue
+        if tok.startswith("--") or (tok.startswith("-") and len(tok) == 2 and not tok[1:].isdigit()):
+            name = tok.lstrip("-").replace("-", "_")
+            name = SHORT.get(name, name)
+            nxt = rest[i + 1] if i + 1 < len(rest) else None
+            if name in BOOL_ARGS and (nxt is None or nxt.startswith("-")
+                                      or nxt.lower() not in ("true", "false", "1", "0", "yes", "no", "on", "off")):
+                flags[name] = True; i += 1; continue
+            if nxt is None:
+                raise VerbError(f"missing value for {tok}")
+            flags[name] = nxt; i += 2; continue
+        positionals.append(tok); i += 1
+    return positionals, flags
+
+
+def _assemble(op, positionals, flags):
+    args = {}
+    names = POS.get(op, [])
+    for idx, val in enumerate(positionals):
+        if idx < len(names):
+            args[names[idx]] = coerce(names[idx], val)
+        else:
+            raise VerbError(f"too many positional args for `{op}` (expected {len(names)})")
+    if "scope" in flags:
+        args["scope"] = flags.pop("scope")
+    if "__json" in flags:
+        blob = flags.pop("__json")
+        prim = PRIMARY_JSON.get(op)
+        if prim and prim not in args:
+            args[prim] = blob               # `--json` is this op's primary payload
+        else:
+            args.update(blob)               # otherwise merge keys into args
+    flags.pop("__body", None)   # body only meaningful to special verbs (handled there)
+    for k, v in flags.items():
+        args[k] = coerce(k, v)
+    return args
+
+
+# ---------------------------------------------------------------------------
+# The public entry: map (verb, rest) -> (op_name, args). Returns None for op when
+# the verb is a client-only command (signin, dev, …) handled in __main__.
+# ---------------------------------------------------------------------------
+def to_op(verb, rest):
+    verb = verb.replace("-", "_")
+
+    if verb in ("w", "work"):
+        return _worker(rest)
+    if verb == "op":                                   # universal escape hatch
+        if not rest:
+            raise VerbError("usage: runner op <name> [--json '{…}'] [--flag value]")
+        pos, flags = _walk(rest[1:])
+        args = _assemble(rest[0], pos, flags)
+        if "__body" in flags:
+            args["body"] = flags["__body"]
+        return rest[0], args
+    if verb in ("inspect", "i"):
+        pos, flags = _walk(rest)
+        op = "set.rows" if pos else "set.list"
+        return op, _assemble(op, pos, flags)
+    if verb == "ls":
+        _, flags = _walk(rest)
+        return "set.list", _assemble("set.list", [], flags)
+    if verb in ("pipe",):
+        if rest and rest[0] in ("show", "list", "remove"):
+            sub = rest[0]
+            op = "pipe." + ("set" if sub == "set" else sub)
+            op = {"show": "pipe.show", "list": "pipe.list", "remove": "pipe.remove"}[sub]
+            pos, flags = _walk(rest[1:])
+            return op, _assemble(op, pos, flags)
+        pos, flags = _walk(rest)
+        args = _assemble("pipe.set", pos, flags)
+        if isinstance(args.get("writes"), str):       # --writes code:label -> {code,label}
+            c, _, lbl = args["writes"].partition(":")
+            args["writes"] = {"code": c, "label": lbl or c}
+        return "pipe.set", args
+    if verb in ("pipes",):
+        _, flags = _walk(rest)
+        return "pipe.list", _assemble("pipe.list", [], flags)
+    if verb == "show":
+        pos, flags = _walk(rest)
+        return "pipe.show", _assemble("pipe.show", pos, flags)
+    if verb == "read":
+        pos, flags = _walk(rest)
+        args = {"code": pos[0] if pos else flags.get("code")}
+        if "scope" in flags:
+            args["scope"] = flags["scope"]
+        return "read", args
+    if verb == "run":
+        pos, flags = _walk(rest)
+        args = {"pipeline": pos[0] if pos else flags.get("pipeline")}
+        if "input" in flags:
+            args["input"] = coerce("input", flags["input"])
+        return "run", args
+    if verb == "runs":
+        pos, _ = _walk(rest)
+        return "runs", {"launch": pos[0] if pos else None}
+    if verb in ("compile",):
+        pos, flags = _walk(rest)
+        args = {}
+        if pos: args["scope"] = pos[0]
+        if "scope" in flags: args["scope"] = flags["scope"]
+        return "bundle.compile", args
+    if verb in ("doctor",):
+        pos, flags = _walk(rest)
+        args = {}
+        if pos: args["scope"] = pos[0]
+        if "scope" in flags: args["scope"] = flags["scope"]
+        return "doctor.compile", args
+    if verb == "app":
+        if rest and rest[0] == "create":
+            pos, flags = _walk(rest[1:])
+            return "app.create", {"name": pos[0] if pos else None, **({"label": flags["label"]} if "label" in flags else {})}
+        if rest and rest[0] == "list":
+            return "app.list", {}
+        raise VerbError("usage: runner app create <name> [--label L] | runner app list")
+    if verb == "apps":
+        return "app.list", {}
+
+    # plane subverb form: runner <plane> <subverb> …
+    if verb in PLANES:
+        if not rest:
+            raise VerbError(f"usage: runner {verb} <subverb> … (e.g. `{verb} list`)")
+        sub = rest[0].replace("-", "_")
+        # convenience aliases
+        sub = {"class": "set_class", "rule": "set_rule"}.get(sub, sub) if verb == "css" else sub
+        op = f"{verb}.{sub}"
+        pos, flags = _walk(rest[1:])
+        args = _assemble(op, pos, flags)
+        # planes that take a body (behavior.add) accept -b/--body -> body
+        if "__body" in flags:
+            args["body"] = flags["__body"]
+        return op, args
+
+    raise VerbError(f"unknown command '{verb}' — try `runner help`")
+
+
+def _worker(rest):
+    """`runner w <code> <tier> …` — assemble a worker spec from tier-specific flags,
+    exactly like ./r work. Output op is pipe.add_worker {code, tier, spec, writes?, at?}."""
+    if len(rest) < 2:
+        raise VerbError("usage: runner w <pipeline-code> <tier> [flags]")
+    code, tier = rest[0], rest[1]
+    pos, flags = _walk(rest[2:])
+    spec = {}
+    body = flags.get("__body")
+    if tier == "snippet":
+        if not body:
+            raise VerbError("snippet worker needs -b <code|->")
+        spec["body"] = body
+    elif tier == "internal":
+        if "handler" not in flags:
+            raise VerbError("internal worker needs --handler NAME")
+        spec["handler"] = flags["handler"]
+    elif tier == "httpx":
+        if "url" not in flags:
+            raise VerbError("httpx worker needs --url")
+        spec.update({"url": flags["url"], "method": flags.get("method", "POST"),
+                     "keys": [k.strip() for k in flags.get("keys", "").split(",") if k.strip()]})
+        if "body_from" in flags:
+            spec["body_from"] = flags["body_from"]
+    elif tier == "read":
+        if "set" not in flags:
+            raise VerbError("read worker needs --set CODE")
+        spec.update({"set": flags["set"], "mode": flags.get("mode", "latest")})
+        for k in ("key", "scope", "as"):
+            if k in flags:
+                spec[k] = flags[k]
+        if "read_scope" in flags:
+            spec["scope"] = flags["read_scope"]
+    elif tier == "llm":
+        spec["provider"] = flags.get("provider", "openai")
+        spec["user_from"] = flags.get("user_from", "ask")
+        for src, dst in (("model", "model"), ("system_from", "system_from"), ("url", "url"),
+                         ("response_path", "response_path"), ("as", "as")):
+            if src in flags:
+                spec[dst] = flags[src]
+        if "keys" in flags:
+            spec["keys"] = [k.strip() for k in flags["keys"].split(",") if k.strip()]
+    if "spec" in flags:
+        spec.update(coerce("spec", flags["spec"]))
+    args = {"code": code, "tier": tier, "spec": spec}
+    if "writes" in flags:
+        args["writes"] = flags["writes"]
+    if "w" in flags:
+        args["writes"] = flags["w"]
+    if "at" in flags:
+        args["at"] = coerce("at", flags["at"])
+    if "scope" in flags:
+        args["scope"] = flags["scope"]
+    return "pipe.add_worker", args