carterkit 0.1.0__tar.gz → 0.3.0__tar.gz

{carterkit-0.1.0 → carterkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.1.0
+Version: 0.3.0
 Summary: Build and drive CAR-TER layouts from Python — the control docs are the library.
 Author: Carter Beaudoin
 License-Expression: MIT
@@ -51,23 +51,45 @@ carterkit.examples("button")    # documented example snippets
 
 ## Build a layout
 
-```python
-from carterkit import LayoutBuffer, validate_layout
-
-b = LayoutBuffer.blank(name="Dashboard", columns=4, rows=4)
-b.add_control({"type": "gauge", "id": "cpu", "label": "CPU", "min": 0, "max": 100},
-              default_span=[2, 2])
-b.add_control({"type": "button", "id": "refresh", "label": "Refresh"})
+The fluent `Layout` builder composes **typed builders** (`build.<control>`) and
+**binding helpers** (`bind`) — all generated from / shaped by the bundled docs, so
+unknown control types and bad enum values raise instead of silently shipping a broken
+layout:
 
-layout = b.layout
-findings = validate_layout(layout)      # schema + grid lint against the bundled catalog
-print(carterkit.format_findings(findings))
+```python
+from carterkit import Layout, build, bind
+
+lay = (Layout("Dashboard", columns=4, rows=4)
+       .connect("ws://192.168.1.50:8765", channel="home")
+       .tab("Main", icon="gauge")
+       .add(build.gauge(id="cpu", label="CPU", min=0, max=100,
+                        sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
+            default_span=[2, 2])
+       .add(build.button(id="refresh", label="Refresh", action=bind.action("refresh"))))
+
+print(lay.findings())    # schema + grid + binding lint against the bundled catalog
+help(build.gauge)        # ← prints the gauge documentation, straight from the docs
+layout = lay.layout      # the composed dict, ready to push/save
 ```
 
+Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_control` / `move_control`
+over a held draft; `lay.buffer` exposes it.
+
 `infer.build_layout(payload)` generates a wired layout from a sample telemetry dict;
 `codegen.generate_service_stub(layout)` emits a runnable MeshSocket server skeleton;
 `theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
 
+## CLI
+
+```bash
+carterkit catalog                 # list every control type
+carterkit doc gauge               # print a control's documentation
+carterkit examples button         # list a control's examples (--name to print one)
+carterkit validate layout.json    # lint a layout (exit 1 on errors)
+carterkit gen layout.json         # generate a MeshSocket service stub
+carterkit relay --port 8765       # run the bundled MeshSocket relay
+```
+
 ## Drive a device
 
 ```python
@@ -75,13 +97,12 @@ import asyncio
 from carterkit import CarterClient
 
 async def main():
-    c = CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
-                     channel="home", role="device", name="my-hub")
-    c.on("toggle", lambda d: {"ok": True, **d})
-    await c.connect()
-    await c.broadcast("reading", {"temp_c": 21.4})
-    await asyncio.sleep(60)
-    await c.close()
+    async with CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
+                            channel="home", role="device", name="my-hub") as c:
+        c.on("toggle", lambda d: {"ok": True, **d})
+        await c.broadcast("reading", {"temp_c": 21.4})
+        await asyncio.sleep(60)
+    # leaving the `async with` disconnects automatically
 
 asyncio.run(main())
 ```

{carterkit-0.1.0 → carterkit-0.3.0}/README.md

@@ -28,23 +28,45 @@ carterkit.examples("button")    # documented example snippets
 
 ## Build a layout
 
-```python
-from carterkit import LayoutBuffer, validate_layout
-
-b = LayoutBuffer.blank(name="Dashboard", columns=4, rows=4)
-b.add_control({"type": "gauge", "id": "cpu", "label": "CPU", "min": 0, "max": 100},
-              default_span=[2, 2])
-b.add_control({"type": "button", "id": "refresh", "label": "Refresh"})
+The fluent `Layout` builder composes **typed builders** (`build.<control>`) and
+**binding helpers** (`bind`) — all generated from / shaped by the bundled docs, so
+unknown control types and bad enum values raise instead of silently shipping a broken
+layout:
 
-layout = b.layout
-findings = validate_layout(layout)      # schema + grid lint against the bundled catalog
-print(carterkit.format_findings(findings))
+```python
+from carterkit import Layout, build, bind
+
+lay = (Layout("Dashboard", columns=4, rows=4)
+       .connect("ws://192.168.1.50:8765", channel="home")
+       .tab("Main", icon="gauge")
+       .add(build.gauge(id="cpu", label="CPU", min=0, max=100,
+                        sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
+            default_span=[2, 2])
+       .add(build.button(id="refresh", label="Refresh", action=bind.action("refresh"))))
+
+print(lay.findings())    # schema + grid + binding lint against the bundled catalog
+help(build.gauge)        # ← prints the gauge documentation, straight from the docs
+layout = lay.layout      # the composed dict, ready to push/save
 ```
 
+Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_control` / `move_control`
+over a held draft; `lay.buffer` exposes it.
+
 `infer.build_layout(payload)` generates a wired layout from a sample telemetry dict;
 `codegen.generate_service_stub(layout)` emits a runnable MeshSocket server skeleton;
 `theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
 
+## CLI
+
+```bash
+carterkit catalog                 # list every control type
+carterkit doc gauge               # print a control's documentation
+carterkit examples button         # list a control's examples (--name to print one)
+carterkit validate layout.json    # lint a layout (exit 1 on errors)
+carterkit gen layout.json         # generate a MeshSocket service stub
+carterkit relay --port 8765       # run the bundled MeshSocket relay
+```
+
 ## Drive a device
 
 ```python
@@ -52,13 +74,12 @@ import asyncio
 from carterkit import CarterClient
 
 async def main():
-    c = CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
-                     channel="home", role="device", name="my-hub")
-    c.on("toggle", lambda d: {"ok": True, **d})
-    await c.connect()
-    await c.broadcast("reading", {"temp_c": 21.4})
-    await asyncio.sleep(60)
-    await c.close()
+    async with CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
+                            channel="home", role="device", name="my-hub") as c:
+        c.on("toggle", lambda d: {"ok": True, **d})
+        await c.broadcast("reading", {"temp_c": 21.4})
+        await asyncio.sleep(60)
+    # leaving the `async with` disconnects automatically
 
 asyncio.run(main())
 ```

{carterkit-0.1.0 → carterkit-0.3.0}/carterkit/__init__.py

@@ -19,8 +19,11 @@ from . import catalog, grid, codegen, infer, theming, tune
 from .buffer import LayoutBuffer, BufferError
 from .validate import validate_layout as _validate_layout, format_findings
 from .client import CarterClient, notify_http, CarterNotifyError
+from . import bind
+from .controls import build, control
+from .layout import Layout
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 #: The layout/wire protocol version carterkit emits and understands. The JSON
 #: contract — not this Python API — is the real compatibility boundary across the
@@ -65,5 +68,6 @@ __all__ = [
     "LayoutBuffer", "BufferError",
     "controls", "doc", "doc_markdown", "examples", "validate_layout",
     "format_findings", "controldocs_dir",
+    "build", "control", "bind", "Layout",
     "catalog", "grid", "codegen", "infer", "theming", "tune",
 ]

carterkit-0.3.0/carterkit/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

carterkit-0.3.0/carterkit/bind.py

@@ -0,0 +1,40 @@
+"""Helpers that build the (verbose, easy-to-get-wrong) sync / action / connection
+dicts controls use. Shapes mirror the bundled ControlDocs (sync.md, actions.md).
+
+    from carterkit import bind
+    bind.listen("cpu", filter={"msg_type": "telemetry"})
+    bind.action("set_power", payload={"state": "{{value}}"}, mode="request")
+    bind.connection("ws://192.168.1.50:8765", channel="home")
+"""
+from __future__ import annotations
+
+
+def listen(value_path: str, *, event: str = "broadcast", filter: dict | None = None,
+           method: str = "meshsocket") -> dict:
+    """A `sync` entry: subscribe to `event`, match `filter`, extract `value_path`
+    (dot-notation). Returns one sync dict — controls take a list of them."""
+    s: dict = {"method": method, "type": "listen", "event": event, "valuePath": value_path}
+    if filter is not None:
+        s["filter"] = filter
+    return s
+
+
+def action(event: str, *, payload: dict | None = None, mode: str = "broadcast",
+           method: str = "meshsocket") -> dict:
+    """An `action` dict: fire `event` on tap/change. `mode` is "broadcast" (fire and
+    forget) or "request" (await reply). `payload` strings support `{{value}}`."""
+    if mode not in ("broadcast", "request"):
+        raise ValueError(f"mode must be 'broadcast' or 'request', got {mode!r}")
+    a: dict = {"method": method, "mode": mode, "event": event}
+    if payload is not None:
+        a["payload"] = payload
+    return a
+
+
+def connection(url: str, *, channel: str = "home", name: str = "CAR-TER",
+               role: str = "controller", token: str | None = None) -> dict:
+    """A layout `connection` block (relay URL + identity)."""
+    conn: dict = {"url": url, "identity": {"name": name, "channel": channel, "role": role}}
+    if token is not None:
+        conn["token"] = token
+    return conn

carterkit-0.3.0/carterkit/cli.py

@@ -0,0 +1,128 @@
+"""Command-line interface: ``carterkit <command>`` (also ``python -m carterkit``).
+
+Commands: catalog · doc · examples · validate · gen · relay · version.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def _cmd_catalog(args) -> int:
+    import carterkit
+    cat = carterkit.controls(types=[args.type] if args.type else None, include_theme=args.theme)
+    if args.json:
+        print(json.dumps(cat, indent=2))
+    else:
+        for t in sorted(cat):
+            spec = cat[t]
+            print(f"{t:18} {spec.get('label', ''):16} ({spec.get('category', '')})")
+    return 0
+
+
+def _cmd_doc(args) -> int:
+    import carterkit
+    md = carterkit.doc_markdown(args.control)
+    if md is None:
+        print(f"no doc for {args.control!r}", file=sys.stderr)
+        return 1
+    print(md)
+    return 0
+
+
+def _cmd_examples(args) -> int:
+    import carterkit
+    if args.name:
+        from carterkit import catalog, controldocs_dir
+        ex = catalog.find_example(controldocs_dir(), args.control, args.name)
+        if not ex:
+            print(f"no example {args.name!r} for {args.control!r}", file=sys.stderr)
+            return 1
+        print(ex["json"])
+        return 0
+    exs = carterkit.examples(args.control)
+    if not exs:
+        print(f"no examples for {args.control!r}", file=sys.stderr)
+        return 1
+    for ex in exs:
+        print("•", ex["name"])
+    return 0
+
+
+def _cmd_validate(args) -> int:
+    import carterkit
+    with open(args.file) as f:
+        layout = json.load(f)
+    findings = carterkit.validate_layout(layout)
+    print(carterkit.format_findings(findings))
+    return 1 if any(f["severity"] == "error" for f in findings) else 0
+
+
+def _cmd_gen(args) -> int:
+    import carterkit
+    with open(args.file) as f:
+        layout = json.load(f)
+    print(carterkit.codegen.generate_service_stub(layout))
+    return 0
+
+
+def _cmd_relay(args) -> int:
+    import asyncio
+    from socket_server import MeshServer  # bundled with meshsocket
+    print(f"MeshSocket relay on ws://{args.host}:{args.port}", file=sys.stderr)
+    asyncio.run(MeshServer(host=args.host, port=args.port).start())
+    return 0
+
+
+def _cmd_version(args) -> int:
+    import carterkit
+    print(carterkit.__version__)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="carterkit", description="Build and drive CAR-TER layouts.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("catalog", help="list the control catalog")
+    c.add_argument("--type", help="restrict to one control type")
+    c.add_argument("--theme", action="store_true", help="include per-control theme fields")
+    c.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    c.set_defaults(fn=_cmd_catalog)
+
+    c = sub.add_parser("doc", help="print a control's documentation")
+    c.add_argument("control")
+    c.set_defaults(fn=_cmd_doc)
+
+    c = sub.add_parser("examples", help="list a control's examples, or print one with --name")
+    c.add_argument("control")
+    c.add_argument("--name", help="print the JSON of the named example")
+    c.set_defaults(fn=_cmd_examples)
+
+    c = sub.add_parser("validate", help="lint a layout JSON file (exit 1 on errors)")
+    c.add_argument("file")
+    c.set_defaults(fn=_cmd_validate)
+
+    c = sub.add_parser("gen", help="generate a MeshSocket service stub from a layout file")
+    c.add_argument("file")
+    c.set_defaults(fn=_cmd_gen)
+
+    c = sub.add_parser("relay", help="run the bundled MeshSocket relay")
+    c.add_argument("--host", default="0.0.0.0")
+    c.add_argument("--port", type=int, default=8765)
+    c.set_defaults(fn=_cmd_relay)
+
+    c = sub.add_parser("version", help="print the carterkit version")
+    c.set_defaults(fn=_cmd_version)
+
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{carterkit-0.1.0 → carterkit-0.3.0}/carterkit/client.py

@@ -136,3 +136,11 @@ class CarterClient:
 
     async def close(self):
         await self._sock.stop()
+
+    async def __aenter__(self):
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.close()
+        return False

carterkit-0.3.0/carterkit/controls.py

@@ -0,0 +1,90 @@
+"""Typed control constructors, generated at runtime from the bundled ControlDocs.
+
+Because the catalog *is* the docs, every placeable control type is available as a
+builder whose validation and `help()` come straight from its documentation:
+
+    from carterkit import build
+    build.gauge(id="cpu", min=0, max=100, sync=[bind.listen("cpu")])
+    build.color_picker(id="tint")             # snake_case maps to the catalog type
+    help(build.gauge)                          # prints the gauge documentation
+
+Unknown control types and bad enum values raise; unknown props are allowed
+(forward-compatible — the device ignores props it doesn't understand).
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from . import catalog
+
+
+@lru_cache(maxsize=1)
+def _catalog() -> dict:
+    from . import controldocs_dir
+    return catalog.build_catalog(controldocs_dir())
+
+
+def _resolve_type(name: str) -> str | None:
+    """Map an attribute name to a catalog control type: exact, or snake_case→camelCase."""
+    cat = _catalog()
+    if name in cat:
+        return name
+    head, *rest = name.split("_")
+    camel = head + "".join(p.title() for p in rest)
+    return camel if camel in cat else None
+
+
+def control(type: str, *, id: str, position=None, span=None, **props) -> dict:
+    """Build and validate one control dict. `id` is required; `position`/`span` are
+    optional. Raises on an unknown control type or an out-of-range enum value."""
+    cat = _catalog()
+    if type not in cat:
+        raise ValueError(f"unknown control type {type!r}. Known: {', '.join(sorted(cat))}")
+    spec = cat[type]
+    enums = {f["name"]: f["values"] for f in spec.get("fields", [])
+             if f.get("type") == "enum" and f.get("values")}
+    for key, val in props.items():
+        if key in enums and val not in enums[key]:
+            raise ValueError(
+                f"{type}.{key}={val!r} is not a valid option; choose one of {enums[key]}")
+    out: dict = {"type": type, "id": id}
+    if position is not None:
+        out["position"] = list(position)
+    if span is not None:
+        out["span"] = list(span)
+    out.update(props)
+    return out
+
+
+class _Controls:
+    """Attribute access returns a builder bound to a catalog control type."""
+
+    def __getattr__(self, name: str):
+        ctype = _resolve_type(name)
+        if ctype is None:
+            raise AttributeError(
+                f"no control type {name!r}. Available: {', '.join(self.__dir__())}")
+
+        def make(*, id: str, position=None, span=None, **props) -> dict:
+            return control(ctype, id=id, position=position, span=span, **props)
+
+        doc = catalog.resolve_doc(_catalog_dir(), ctype)
+        make.__name__ = ctype
+        make.__qualname__ = f"controls.{ctype}"
+        make.__doc__ = (doc or {}).get("body") or f"Build a {ctype} control."
+        return make
+
+    def __dir__(self):
+        return sorted(_catalog())
+
+    def types(self) -> list[str]:
+        """All placeable control types available as builders."""
+        return sorted(_catalog())
+
+
+def _catalog_dir():
+    from . import controldocs_dir
+    return controldocs_dir()
+
+
+build = _Controls()

carterkit-0.3.0/carterkit/layout.py

@@ -0,0 +1,87 @@
+"""A fluent layout builder — the ergonomic front door over LayoutBuffer.
+
+    from carterkit import Layout, build, bind
+
+    layout = (Layout("Dashboard", columns=4, rows=4)
+              .connect("ws://192.168.1.50:8765", channel="home")
+              .tab("Main", icon="gauge")
+              .add(build.gauge(id="cpu", min=0, max=100,
+                               sync=[bind.listen("cpu")]), default_span=[2, 2])
+              .add(build.button(id="refresh", action=bind.action("refresh")))
+              .layout)
+
+Auto-placement, id de-duplication, and grid bookkeeping come from LayoutBuffer;
+`.validate()` lints against the bundled catalog. Chainable: every mutator returns self.
+"""
+from __future__ import annotations
+
+import json
+
+from . import bind as _bind
+from . import validate as _validate
+from .buffer import LayoutBuffer
+
+
+class Layout:
+    def __init__(self, name: str = "Layout", *, columns: int = 4, rows: int = 6,
+                 accent: str = "#667eea"):
+        self._buf = LayoutBuffer.blank(name=name, columns=columns, rows=rows, accent=accent)
+        self._tab = 0
+        self._first_tab_used = False
+
+    def connect(self, url: str, **identity) -> "Layout":
+        """Attach a `connection` block (see bind.connection for the identity kwargs)."""
+        self._buf.layout["connection"] = _bind.connection(url, **identity)
+        return self
+
+    def tab(self, title: str, *, icon: str = "square.grid.2x2",
+            columns: int = 4, rows: int = 6) -> "Layout":
+        """Start a tab and make it current. The first call configures the default tab;
+        later calls append new tabs."""
+        if not self._first_tab_used:
+            t = self._buf.tabs[0]
+            t["title"], t["icon"] = title, icon
+            t["grid"] = {"columns": columns, "rows": rows}
+            self._tab = 0
+            self._first_tab_used = True
+        else:
+            self._tab = self._buf.add_tab(title, icon=icon, columns=columns, rows=rows)
+        return self
+
+    def add(self, control: dict, *, position=None, span=None, default_span=None) -> "Layout":
+        """Add a control to the current tab (auto-placed unless `position` is given)."""
+        self._buf.add_control(control, tab_index=self._tab, position=position,
+                              default_span=default_span or span)
+        return self
+
+    def group(self, group: dict, *, position=None) -> "Layout":
+        """Add a group container to the current tab."""
+        self._buf.add_group(group, tab_index=self._tab, position=position)
+        return self
+
+    @property
+    def layout(self) -> dict:
+        """The composed layout dict (ready to push/save)."""
+        return self._buf.layout
+
+    @property
+    def buffer(self) -> LayoutBuffer:
+        """The underlying LayoutBuffer, for advanced ops (update/move/remove)."""
+        return self._buf
+
+    def validate(self) -> list:
+        """Lint against the bundled control catalog."""
+        import carterkit
+        return carterkit.validate_layout(self.layout)
+
+    def findings(self) -> str:
+        """Human-readable lint report."""
+        return _validate.format_findings(self.validate())
+
+    def json(self, indent: int = 2) -> str:
+        return json.dumps(self.layout, indent=indent)
+
+    def __repr__(self) -> str:
+        n = sum(len(t.get("children", [])) for t in self._buf.tabs)
+        return (f"<Layout {self.layout.get('name')!r}: "
+                f"{len(self._buf.tabs)} tab(s), {n} control(s)>")

{carterkit-0.1.0 → carterkit-0.3.0}/carterkit/validate.py

@@ -116,6 +116,26 @@ def _validate_child(ch, catalog, where, findings, seen_ids):
             if v not in fd["values"]:
                 findings.append(_f("error", "bad_enum", spot,
                                    f"{ctype}.{k} = '{v}' is not one of {fd['values']}"))
+    _validate_bindings(ch, ctype, spot, findings)
+
+
+def _validate_bindings(ch, ctype, spot, findings):
+    """Shape-check the data bindings: every `sync` entry needs a `valuePath`, and
+    `action`/`longPressAction` need an `event` (else they silently do nothing)."""
+    sync = ch.get("sync")
+    if sync is not None:
+        if not isinstance(sync, list):
+            findings.append(_f("warn", "bad_sync", spot, f"{ctype}.sync should be a list"))
+        else:
+            for i, s in enumerate(sync):
+                if not isinstance(s, dict) or not s.get("valuePath"):
+                    findings.append(_f("warn", "bad_sync", spot,
+                                       f"{ctype}.sync[{i}] is missing a 'valuePath'"))
+    for akey in ("action", "longPressAction"):
+        a = ch.get(akey)
+        if a is not None and (not isinstance(a, dict) or not a.get("event")):
+            findings.append(_f("error", "bad_action", spot,
+                               f"{ctype}.{akey} is missing an 'event'"))
 
 
 def format_findings(findings: list[dict]) -> str:

{carterkit-0.1.0 → carterkit-0.3.0}/carterkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.1.0
+Version: 0.3.0
 Summary: Build and drive CAR-TER layouts from Python — the control docs are the library.
 Author: Carter Beaudoin
 License-Expression: MIT
@@ -51,23 +51,45 @@ carterkit.examples("button")    # documented example snippets
 
 ## Build a layout
 
-```python
-from carterkit import LayoutBuffer, validate_layout
-
-b = LayoutBuffer.blank(name="Dashboard", columns=4, rows=4)
-b.add_control({"type": "gauge", "id": "cpu", "label": "CPU", "min": 0, "max": 100},
-              default_span=[2, 2])
-b.add_control({"type": "button", "id": "refresh", "label": "Refresh"})
+The fluent `Layout` builder composes **typed builders** (`build.<control>`) and
+**binding helpers** (`bind`) — all generated from / shaped by the bundled docs, so
+unknown control types and bad enum values raise instead of silently shipping a broken
+layout:
 
-layout = b.layout
-findings = validate_layout(layout)      # schema + grid lint against the bundled catalog
-print(carterkit.format_findings(findings))
+```python
+from carterkit import Layout, build, bind
+
+lay = (Layout("Dashboard", columns=4, rows=4)
+       .connect("ws://192.168.1.50:8765", channel="home")
+       .tab("Main", icon="gauge")
+       .add(build.gauge(id="cpu", label="CPU", min=0, max=100,
+                        sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
+            default_span=[2, 2])
+       .add(build.button(id="refresh", label="Refresh", action=bind.action("refresh"))))
+
+print(lay.findings())    # schema + grid + binding lint against the bundled catalog
+help(build.gauge)        # ← prints the gauge documentation, straight from the docs
+layout = lay.layout      # the composed dict, ready to push/save
 ```
 
+Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_control` / `move_control`
+over a held draft; `lay.buffer` exposes it.
+
 `infer.build_layout(payload)` generates a wired layout from a sample telemetry dict;
 `codegen.generate_service_stub(layout)` emits a runnable MeshSocket server skeleton;
 `theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
 
+## CLI
+
+```bash
+carterkit catalog                 # list every control type
+carterkit doc gauge               # print a control's documentation
+carterkit examples button         # list a control's examples (--name to print one)
+carterkit validate layout.json    # lint a layout (exit 1 on errors)
+carterkit gen layout.json         # generate a MeshSocket service stub
+carterkit relay --port 8765       # run the bundled MeshSocket relay
+```
+
 ## Drive a device
 
 ```python
@@ -75,13 +97,12 @@ import asyncio
 from carterkit import CarterClient
 
 async def main():
-    c = CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
-                     channel="home", role="device", name="my-hub")
-    c.on("toggle", lambda d: {"ok": True, **d})
-    await c.connect()
-    await c.broadcast("reading", {"temp_c": 21.4})
-    await asyncio.sleep(60)
-    await c.close()
+    async with CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
+                            channel="home", role="device", name="my-hub") as c:
+        c.on("toggle", lambda d: {"ok": True, **d})
+        await c.broadcast("reading", {"temp_c": 21.4})
+        await asyncio.sleep(60)
+    # leaving the `async with` disconnects automatically
 
 asyncio.run(main())
 ```

{carterkit-0.1.0 → carterkit-0.3.0}/carterkit.egg-info/SOURCES.txt

@@ -2,19 +2,26 @@ LICENSE
 README.md
 pyproject.toml
 carterkit/__init__.py
+carterkit/__main__.py
+carterkit/bind.py
 carterkit/buffer.py
 carterkit/catalog.py
+carterkit/cli.py
 carterkit/client.py
 carterkit/codegen.py
+carterkit/controls.py
 carterkit/e2ee.py
 carterkit/grid.py
 carterkit/infer.py
+carterkit/layout.py
+carterkit/py.typed
 carterkit/theming.py
 carterkit/tune.py
 carterkit/validate.py
 carterkit.egg-info/PKG-INFO
 carterkit.egg-info/SOURCES.txt
 carterkit.egg-info/dependency_links.txt
+carterkit.egg-info/entry_points.txt
 carterkit.egg-info/requires.txt
 carterkit.egg-info/top_level.txt
 carterkit/controldocs/accordion.md
@@ -61,12 +68,18 @@ carterkit/controldocs/theming.md
 carterkit/controldocs/toggle.md
 carterkit/controldocs/visibility.md
 carterkit/controldocs/web-view.md
+tests/test_bind.py
 tests/test_buffer.py
 tests/test_catalog.py
+tests/test_cli.py
+tests/test_client.py
 tests/test_codegen.py
+tests/test_controls.py
 tests/test_e2ee.py
 tests/test_grid.py
 tests/test_infer.py
+tests/test_layout.py
 tests/test_theming.py
 tests/test_tune.py
-tests/test_validate.py
+tests/test_validate.py
+tests/test_validate_bindings.py

carterkit-0.3.0/carterkit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+carterkit = carterkit.cli:main

{carterkit-0.1.0 → carterkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "carterkit"
-version = "0.1.0"
+version = "0.3.0"
 description = "Build and drive CAR-TER layouts from Python — the control docs are the library."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,8 +30,11 @@ classifiers = [
 Homepage = "https://github.com/Mariner10/carterkit"
 Repository = "https://github.com/Mariner10/carterkit"
 
+[project.scripts]
+carterkit = "carterkit.cli:main"
+
 [tool.setuptools]
 packages = ["carterkit"]
 
 [tool.setuptools.package-data]
-carterkit = ["controldocs/*.md"]
+carterkit = ["controldocs/*.md", "py.typed"]

carterkit-0.3.0/tests/test_bind.py

@@ -0,0 +1,40 @@
+"""Tests for bind.py — sync/action/connection helper shapes."""
+
+import pytest
+
+from carterkit import bind
+
+
+def test_listen_basic():
+    assert bind.listen("cpu") == {
+        "method": "meshsocket", "type": "listen", "event": "broadcast", "valuePath": "cpu"}
+
+
+def test_listen_with_filter_and_event():
+    s = bind.listen("battery", event="metrics", filter={"msg_type": "telemetry"})
+    assert s["event"] == "metrics"
+    assert s["filter"] == {"msg_type": "telemetry"}
+    assert s["valuePath"] == "battery"
+
+
+def test_action_broadcast_default():
+    assert bind.action("refresh") == {
+        "method": "meshsocket", "mode": "broadcast", "event": "refresh"}
+
+
+def test_action_request_with_payload():
+    a = bind.action("set_power", payload={"state": "{{value}}"}, mode="request")
+    assert a["mode"] == "request"
+    assert a["payload"] == {"state": "{{value}}"}
+
+
+def test_action_rejects_bad_mode():
+    with pytest.raises(ValueError):
+        bind.action("x", mode="nope")
+
+
+def test_connection():
+    c = bind.connection("ws://h:8765", channel="lab", token="t")
+    assert c["url"] == "ws://h:8765"
+    assert c["identity"] == {"name": "CAR-TER", "channel": "lab", "role": "controller"}
+    assert c["token"] == "t"

carterkit-0.3.0/tests/test_cli.py

@@ -0,0 +1,53 @@
+"""Tests for the carterkit CLI."""
+
+import json
+
+import carterkit
+from carterkit import cli
+
+
+def test_catalog_json(capsys):
+    assert cli.main(["catalog", "--json"]) == 0
+    cat = json.loads(capsys.readouterr().out)
+    assert "gauge" in cat and "button" in cat
+
+
+def test_catalog_table(capsys):
+    assert cli.main(["catalog"]) == 0
+    assert "gauge" in capsys.readouterr().out
+
+
+def test_doc(capsys):
+    assert cli.main(["doc", "gauge"]) == 0
+    assert "# Gauge" in capsys.readouterr().out
+
+
+def test_doc_unknown(capsys):
+    assert cli.main(["doc", "frobnicator"]) == 1
+
+
+def test_examples_list(capsys):
+    assert cli.main(["examples", "button"]) == 0
+    assert "•" in capsys.readouterr().out
+
+
+def test_version(capsys):
+    assert cli.main(["version"]) == 0
+    assert capsys.readouterr().out.strip() == carterkit.__version__
+
+
+def test_validate_clean(tmp_path):
+    b = carterkit.LayoutBuffer.blank(columns=4, rows=4)
+    b.add_control(carterkit.build.gauge(id="cpu", min=0, max=100), default_span=[2, 2])
+    f = tmp_path / "layout.json"
+    f.write_text(json.dumps(b.layout))
+    assert cli.main(["validate", str(f)]) == 0
+
+
+def test_gen_emits_meshsocket_service(tmp_path, capsys):
+    b = carterkit.LayoutBuffer.blank(columns=4, rows=4)
+    b.add_control(carterkit.build.button(id="go"))
+    f = tmp_path / "layout.json"
+    f.write_text(json.dumps(b.layout))
+    assert cli.main(["gen", str(f)]) == 0
+    assert "from meshsocket import MeshSocket" in capsys.readouterr().out

carterkit-0.3.0/tests/test_client.py

@@ -0,0 +1,32 @@
+"""Test the CarterClient async context manager (no network — fake socket)."""
+
+import asyncio
+
+from carterkit import CarterClient
+
+
+class _FakeSock:
+    def __init__(self):
+        self.events = []
+
+    async def start(self):
+        self.events.append("start")
+
+    async def wait_until_ready(self):
+        self.events.append("ready")
+
+    async def stop(self):
+        self.events.append("stop")
+
+
+def test_async_context_manager_connects_and_closes():
+    c = CarterClient(gateway_url="ws://x", token="t", channel="home")
+    fake = _FakeSock()
+    c._sock = fake  # swap the real MeshSocket for a recorder
+
+    async def run():
+        async with c as ctx:
+            assert ctx is c
+        return fake.events
+
+    assert asyncio.run(run()) == ["start", "ready", "stop"]

carterkit-0.3.0/tests/test_controls.py

@@ -0,0 +1,54 @@
+"""Tests for controls.py — typed builders generated from the bundled catalog."""
+
+import pytest
+
+import carterkit
+from carterkit import build, control
+
+
+def test_build_gauge_returns_valid_control():
+    g = build.gauge(id="cpu", min=0, max=100, position=[0, 0], span=[2, 2])
+    assert g["type"] == "gauge" and g["id"] == "cpu"
+    assert g["position"] == [0, 0] and g["span"] == [2, 2]
+    assert g["min"] == 0 and g["max"] == 100
+
+
+def test_snake_case_alias_maps_to_camel_type():
+    assert build.color_picker(id="tint")["type"] == "colorPicker"
+    assert build.status_light(id="s")["type"] == "statusLight"
+
+
+def test_unknown_control_raises():
+    with pytest.raises(AttributeError):
+        build.frobnicator  # noqa: B018
+
+
+def test_bad_enum_value_raises():
+    with pytest.raises(ValueError):
+        build.gauge(id="g", gaugeStyle="triangular")  # gaugeStyle is half|full
+
+
+def test_good_enum_value_ok():
+    assert build.gauge(id="g", gaugeStyle="full")["gaugeStyle"] == "full"
+
+
+def test_control_factory_unknown_type():
+    with pytest.raises(ValueError):
+        control("nope", id="x")
+
+
+def test_builder_doc_comes_from_controldocs():
+    assert build.gauge.__doc__.startswith("# Gauge")
+
+
+def test_types_listing_nonempty():
+    types = build.types()
+    assert "gauge" in types and "button" in types and "colorPicker" in types
+
+
+def test_built_controls_validate_clean():
+    b = carterkit.LayoutBuffer.blank(columns=4, rows=4)
+    b.add_control(build.gauge(id="cpu", min=0, max=100), default_span=[2, 2])
+    b.add_control(build.button(id="go", label="Go"))
+    errs = [f for f in carterkit.validate_layout(b.layout) if f["severity"] == "error"]
+    assert errs == [], errs

carterkit-0.3.0/tests/test_layout.py

@@ -0,0 +1,40 @@
+"""Tests for the fluent Layout builder."""
+
+from carterkit import Layout, build, bind
+
+
+def test_fluent_compose():
+    lay = (Layout("Dash", columns=4, rows=4)
+           .connect("ws://h:8765", channel="home")
+           .tab("Main", icon="gauge")
+           .add(build.gauge(id="cpu", min=0, max=100, sync=[bind.listen("cpu")]),
+                default_span=[2, 2])
+           .add(build.button(id="go", action=bind.action("go"))))
+    layout = lay.layout
+    assert layout["name"] == "Dash"
+    assert layout["connection"]["url"] == "ws://h:8765"
+    tab0 = layout["tabs"][0]
+    assert tab0["title"] == "Main" and tab0["icon"] == "gauge"
+    assert {c["id"] for c in tab0["children"]} == {"cpu", "go"}
+    g = next(c for c in tab0["children"] if c["id"] == "cpu")
+    assert g["span"] == [2, 2] and g["position"] == [0, 0]
+
+
+def test_first_tab_renames_then_appends():
+    lay = (Layout("X")
+           .tab("One").add(build.button(id="a"))
+           .tab("Two").add(build.button(id="b")))
+    assert [t["title"] for t in lay.layout["tabs"]] == ["One", "Two"]
+    assert lay.layout["tabs"][1]["children"][0]["id"] == "b"
+
+
+def test_validate_and_findings_clean():
+    lay = Layout("X").add(
+        build.gauge(id="g", min=0, max=100, sync=[bind.listen("g")]), default_span=[2, 2])
+    assert [f for f in lay.validate() if f["severity"] == "error"] == []
+    assert "No issues" in lay.findings()
+
+
+def test_repr_counts_controls():
+    lay = Layout("X").add(build.button(id="a")).add(build.button(id="b"))
+    assert "2 control" in repr(lay)

carterkit-0.3.0/tests/test_validate_bindings.py

@@ -0,0 +1,40 @@
+"""Tests for the richer sync/action binding validation."""
+
+import carterkit
+from carterkit import validate, build, bind
+
+CAT = carterkit.controls(include_theme=True)
+
+
+def _layout(children):
+    return {"name": "T", "version": 1,
+            "tabs": [{"title": "Main", "icon": "house.fill",
+                      "grid": {"columns": 4, "rows": 4}, "children": children}]}
+
+
+def _kinds(findings):
+    return {f["kind"] for f in findings}
+
+
+def test_action_missing_event_is_error():
+    lay = _layout([{"type": "button", "id": "b", "position": [0, 0],
+                    "action": {"method": "meshsocket", "mode": "broadcast"}}])
+    findings = validate.validate_layout(lay, CAT)
+    assert "bad_action" in _kinds(findings)
+    assert any(f["severity"] == "error" for f in findings if f["kind"] == "bad_action")
+
+
+def test_sync_missing_valuepath_is_warning():
+    lay = _layout([{"type": "gauge", "id": "g", "position": [0, 0], "min": 0, "max": 100,
+                    "sync": [{"method": "meshsocket", "type": "listen", "event": "broadcast"}]}])
+    bs = [f for f in validate.validate_layout(lay, CAT) if f["kind"] == "bad_sync"]
+    assert bs and bs[0]["severity"] == "warn"
+
+
+def test_helper_built_bindings_are_clean():
+    lay = _layout([
+        build.button(id="b", position=[0, 0], action=bind.action("go")),
+        build.gauge(id="g", position=[0, 1], min=0, max=100, sync=[bind.listen("g")]),
+    ])
+    kinds = _kinds(validate.validate_layout(lay, CAT))
+    assert "bad_action" not in kinds and "bad_sync" not in kinds