carterkit 0.1.0__py3-none-any.whl

carterkit/__init__.py

@@ -0,0 +1,69 @@
+"""carterkit — build and drive CAR-TER layouts from Python.
+
+The control vocabulary *is* the bundled documentation: every control's schema,
+fields, and examples are parsed at runtime from the ControlDocs markdown shipped
+inside this package (``carterkit/controldocs/``) — the same docs the CAR-TER app
+renders. So the docs never drift from the definitions; they are one and the same.
+
+Quick map:
+  - ``controls()`` / ``doc()`` / ``examples()`` — the docs-as-catalog surface
+  - ``LayoutBuffer`` — incrementally build a layout (auto-placement, dedupe)
+  - ``validate_layout()`` — schema + grid lint against the bundled catalog
+  - ``infer`` / ``codegen`` / ``theming`` / ``tune`` — generate layouts, servers, themes
+  - ``CarterClient`` / ``notify_http`` — connect over MeshSocket, push, send alerts
+"""
+from importlib.resources import files
+from pathlib import Path
+
+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
+
+__version__ = "0.1.0"
+
+#: The layout/wire protocol version carterkit emits and understands. The JSON
+#: contract — not this Python API — is the real compatibility boundary across the
+#: app, the relay, and this library; unknown fields are tolerated on read.
+PROTOCOL_VERSION = 1
+
+
+def controldocs_dir() -> Path:
+    """Filesystem path to the bundled ControlDocs markdown (the source of truth)."""
+    return Path(files(__package__) / "controldocs")
+
+
+def controls(types=None, include_theme: bool = False) -> dict:
+    """Machine-readable schema for every placeable control, keyed by layout ``type``."""
+    return catalog.build_catalog(controldocs_dir(), types=types, include_theme=include_theme)
+
+
+def doc(control: str):
+    """Full parsed doc (fields, themeFields, body, examples) for a control type or node_id."""
+    return catalog.resolve_doc(controldocs_dir(), control)
+
+
+def doc_markdown(control: str):
+    """The control's human/AI documentation prose (the rendered markdown body)."""
+    d = doc(control)
+    return d["body"] if d else None
+
+
+def examples(control: str):
+    """Documented example snippets for a control: ``[{"name", "json"}, ...]``."""
+    return catalog.get_examples(controldocs_dir(), control)
+
+
+def validate_layout(layout: dict, catalog_: dict = None) -> list:
+    """Lint a layout (schema + grid). Defaults to the bundled control catalog."""
+    return _validate_layout(layout, catalog_ if catalog_ is not None else controls(include_theme=True))
+
+
+__all__ = [
+    "__version__", "PROTOCOL_VERSION",
+    "CarterClient", "notify_http", "CarterNotifyError",
+    "LayoutBuffer", "BufferError",
+    "controls", "doc", "doc_markdown", "examples", "validate_layout",
+    "format_findings", "controldocs_dir",
+    "catalog", "grid", "codegen", "infer", "theming", "tune",
+]

carterkit/buffer.py

@@ -0,0 +1,230 @@
+"""Working-layout buffer + incremental patch ops.
+
+The headline authoring model: instead of re-emitting an 800-line layout on every
+change, the LLM issues surgical operations against a server-held draft. The buffer
+keeps the full document; each op mutates it and the result is pushed to the device as
+a full layout (which it already knows how to render). Pure (no I/O, no socket) so it
+is fully unit-testable; the async push/save live in server.py.
+
+Top-level children (controls + groups) of a tab are addressable by id. Editing inside
+a group is not yet supported (ids inside groups still count for uniqueness).
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Optional
+
+from . import grid as gridmod
+
+DEFAULT_COLUMNS = 4
+DEFAULT_ROWS = 8
+
+
+class BufferError(Exception):
+    """Raised on an invalid buffer operation (rendered to the user as a tool error)."""
+
+
+class LayoutBuffer:
+    def __init__(self, layout: dict):
+        self.layout = layout
+
+    # ─── construction ────────────────────────────────────────────────────────
+
+    @classmethod
+    def blank(cls, name: str = "Untitled", columns: int = DEFAULT_COLUMNS,
+              rows: int = DEFAULT_ROWS, accent: str = "#667eea",
+              tab_title: str = "Tab 1", tab_icon: str = "house.fill") -> "LayoutBuffer":
+        return cls({
+            "name": name,
+            "version": 1,
+            "accentColor": accent,
+            "tabs": [{
+                "title": tab_title,
+                "icon": tab_icon,
+                "grid": {"columns": columns, "rows": rows},
+                "children": [],
+            }],
+        })
+
+    @classmethod
+    def from_layout(cls, layout: dict) -> "LayoutBuffer":
+        if not isinstance(layout, dict) or "tabs" not in layout:
+            raise BufferError("source layout must be an object with a 'tabs' array")
+        return cls(copy.deepcopy(layout))
+
+    # ─── access ──────────────────────────────────────────────────────────────
+
+    @property
+    def tabs(self) -> list:
+        return self.layout.setdefault("tabs", [])
+
+    def _tab(self, i: int) -> dict:
+        tabs = self.tabs
+        if i < 0 or i >= len(tabs):
+            raise BufferError(f"tab index {i} out of range (have {len(tabs)} tab(s))")
+        return tabs[i]
+
+    @staticmethod
+    def _grid_dims(tab: dict) -> tuple[int, int]:
+        g = tab.get("grid") or {}
+        return int(g.get("columns", DEFAULT_COLUMNS)), int(g.get("rows", DEFAULT_ROWS))
+
+    def all_ids(self) -> set[str]:
+        ids: set[str] = set()
+
+        def walk(children):
+            for ch in children or []:
+                if isinstance(ch, dict):
+                    if "id" in ch:
+                        ids.add(ch["id"])
+                    if ch.get("type") == "group":
+                        walk(ch.get("children"))
+
+        for tab in self.tabs:
+            walk(tab.get("children"))
+        return ids
+
+    def unique_id(self, base: str) -> str:
+        base = base or "control"
+        ids = self.all_ids()
+        if base not in ids:
+            return base
+        i = 2
+        while f"{base}-{i}" in ids:
+            i += 1
+        return f"{base}-{i}"
+
+    def find(self, control_id: str) -> Optional[tuple[int, int, dict]]:
+        """Locate a top-level child by id -> (tab_index, child_index, child)."""
+        for ti, tab in enumerate(self.tabs):
+            for ci, ch in enumerate(tab.get("children", [])):
+                if isinstance(ch, dict) and ch.get("id") == control_id:
+                    return ti, ci, ch
+        return None
+
+    # ─── mutations ───────────────────────────────────────────────────────────
+
+    def add_control(self, control: dict, tab_index: int = 0,
+                    position: Optional[list[int]] = None,
+                    default_span: Optional[list[int]] = None) -> dict:
+        if not isinstance(control, dict) or "type" not in control:
+            raise BufferError("control must be an object with a 'type'")
+        control = copy.deepcopy(control)
+        control["id"] = self.unique_id(control.get("id") or control["type"])
+
+        tab = self._tab(tab_index)
+        children = tab.setdefault("children", [])
+        cols, rows = self._grid_dims(tab)
+
+        if control.get("span") is None and default_span and default_span != [1, 1]:
+            control["span"] = default_span
+        span = control.get("span") or [1, 1]
+
+        if position is None:
+            slot = gridmod.find_slot(children, cols, rows, span)
+            if slot is None:
+                raise BufferError(
+                    f"no free {span} slot in tab {tab_index} ({rows}x{cols} grid). "
+                    f"Grow the grid (add_tab/edit grid) or pass an explicit position.")
+            position = slot
+        control["position"] = position
+        children.append(control)
+        return control
+
+    def update_control(self, control_id: str, patch: dict) -> dict:
+        found = self.find(control_id)
+        if not found:
+            raise BufferError(f"no control '{control_id}' in the buffer")
+        ch = found[2]
+        for k, v in patch.items():
+            if v is None:
+                ch.pop(k, None)
+            else:
+                ch[k] = v
+        return ch
+
+    def remove_control(self, control_id: str) -> dict:
+        found = self.find(control_id)
+        if not found:
+            raise BufferError(f"no control '{control_id}' in the buffer")
+        ti, ci, _ = found
+        return self.tabs[ti]["children"].pop(ci)
+
+    def move_control(self, control_id: str, position: Optional[list[int]] = None,
+                     span: Optional[list[int]] = None,
+                     tab_index: Optional[int] = None) -> dict:
+        found = self.find(control_id)
+        if not found:
+            raise BufferError(f"no control '{control_id}' in the buffer")
+        ti, ci, ch = found
+        if tab_index is not None and tab_index != ti:
+            ch = self.tabs[ti]["children"].pop(ci)
+            self._tab(tab_index).setdefault("children", []).append(ch)
+        if position is not None:
+            ch["position"] = position
+        if span is not None:
+            ch["span"] = span
+        return ch
+
+    def add_tab(self, title: str, icon: str = "square.grid.2x2",
+                columns: int = DEFAULT_COLUMNS, rows: int = DEFAULT_ROWS) -> int:
+        self.tabs.append({
+            "title": title, "icon": icon,
+            "grid": {"columns": columns, "rows": rows}, "children": [],
+        })
+        return len(self.tabs) - 1
+
+    def add_group(self, group: dict, tab_index: int = 0,
+                  position: Optional[list[int]] = None) -> dict:
+        group = copy.deepcopy(group)
+        group["type"] = "group"
+        group["id"] = self.unique_id(group.get("id") or "group")
+        tab = self._tab(tab_index)
+        children = tab.setdefault("children", [])
+        cols, rows = self._grid_dims(tab)
+        span = group.get("span") or [1, 1]
+        if position is None:
+            slot = gridmod.find_slot(children, cols, rows, span)
+            if slot is None:
+                raise BufferError(f"no free {span} slot in tab {tab_index} for the group")
+            position = slot
+        group["position"] = position
+        children.append(group)
+        return group
+
+    # ─── views ───────────────────────────────────────────────────────────────
+
+    def issues(self) -> list[dict]:
+        """Placement issues across all tabs, each tagged with its tab index."""
+        out: list[dict] = []
+        for ti, tab in enumerate(self.tabs):
+            cols, rows = self._grid_dims(tab)
+            for issue in gridmod.validate_placement(tab.get("children", []), cols, rows):
+                out.append({"tab": ti, **issue})
+        return out
+
+    def summary(self, show_grids: bool = True) -> str:
+        name = self.layout.get("name", "Untitled")
+        accent = self.layout.get("accentColor")
+        head = f"**{name}**" + (f" · accent {accent}" if accent else "")
+        lines = [head]
+        for ti, tab in enumerate(self.tabs):
+            cols, rows = self._grid_dims(tab)
+            children = tab.get("children", [])
+            lines.append(f"\nTab {ti}: {tab.get('title','?')} ({tab.get('icon','')}) "
+                         f"— {rows}x{cols}, {len(children)} item(s)")
+            for ch in children:
+                pos = ch.get("position")
+                span = ch.get("span")
+                extra = f" span {span}" if span and span != [1, 1] else ""
+                lines.append(f"  - {ch.get('id','?')} ({ch.get('type','?')}) @ {pos}{extra}")
+            if show_grids and children:
+                lines.append(gridmod.render_grid(children, cols, rows))
+        problems = self.issues()
+        if problems:
+            lines.append("\n⚠ placement issues:")
+            for p in problems:
+                ids = p.get("ids") or [p.get("id")]
+                lines.append(f"  - [tab {p['tab']}] {p['kind']}: {', '.join(ids)} — {p['detail']}")
+        return "\n".join(lines)

carterkit/catalog.py

@@ -0,0 +1,285 @@
+"""Control catalog + example extraction — pure parsing of the ControlDocs markdown.
+
+Mirrors the app's `ControlDocLoader` frontmatter parser (Swift) so the MCP and the
+device agree on the field schema for every control. Deliberately does NOT use a real
+YAML parser: the docs carry unquoted `#hex` defaults (e.g. `default: #667eea`) which
+YAML would treat as comments, and some values omit quotes inconsistently. The
+hand-rolled parser tolerates both.
+
+Public surface (all pure; `docs_dir` is injected for testability):
+    parse_doc(content, node_id)      -> dict | None   one doc's frontmatter + body + examples
+    parse_all(docs_dir)              -> {node_id: doc}
+    build_catalog(docs_dir, types)   -> {type: compact}   placeable-control schema
+    get_examples(docs_dir, control)  -> [{"name", "json"}]
+    find_example(docs_dir, control, name) -> {"name", "json"} | None
+    resolve_doc(docs_dir, control)   -> doc | None   accepts node_id OR control type
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+
+# ─── Frontmatter parsing (mirrors ControlDocLoader.swift) ────────────────────
+
+
+def _parse_str_array(value: str) -> list[str]:
+    inner = value.strip().strip("[]")
+    out = []
+    for part in inner.split(","):
+        s = part.strip().strip("\"'")
+        if s:
+            out.append(s)
+    return out
+
+
+def _parse_int_array(value: str) -> Optional[list[int]]:
+    inner = value.strip().strip("[]")
+    parts = []
+    for part in inner.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            parts.append(int(part))
+        except ValueError:
+            return None
+    return parts or None
+
+
+def _make_field(raw: dict[str, str]) -> dict:
+    field: dict = {"name": raw.get("name", ""), "type": raw.get("type", "string")}
+    if "values" in raw:
+        field["values"] = _parse_str_array(raw["values"])
+    if "default" in raw:
+        field["default"] = raw["default"]
+    if raw.get("description"):
+        field["description"] = raw["description"]
+    return field
+
+
+def parse_doc(content: str, node_id: str) -> Optional[dict]:
+    """Parse one control doc into {node_id,type,label,icon,category,defaultSpan,
+    fields,themeFields,body,examples}. Returns None if it lacks a type+label
+    (matches the Swift loader, which skips non-control prose-only docs)."""
+    lines = content.split("\n")
+    if not lines or lines[0].strip() != "---":
+        return None
+    end = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            end = i
+            break
+    if end is None:
+        return None
+
+    front = lines[1:end]
+    body = "\n".join(lines[end + 1:]).strip()
+
+    meta: dict = {
+        "node_id": node_id,
+        "type": "",
+        "label": "",
+        "icon": "",
+        "category": "",
+        "defaultSpan": None,
+        "fields": [],
+        "themeFields": [],
+    }
+
+    in_fields = False
+    current_list: Optional[list] = None
+    current: dict[str, str] = {}
+
+    def flush():
+        nonlocal current
+        if in_fields and current and current_list is not None:
+            current_list.append(_make_field(current))
+        current = {}
+
+    for line in front:
+        if not line.strip():
+            continue
+        top_level = not line.startswith((" ", "\t")) and ":" in line
+        if top_level:
+            flush()
+            in_fields = False
+            current_list = None
+            key, _, value = line.partition(":")
+            key, value = key.strip(), value.strip()
+            if key == "type":
+                meta["type"] = value
+            elif key == "label":
+                meta["label"] = value
+            elif key == "icon":
+                meta["icon"] = value
+            elif key == "category":
+                meta["category"] = value
+            elif key == "defaultSpan":
+                meta["defaultSpan"] = _parse_int_array(value)
+            elif key == "fields":
+                in_fields = True
+                current_list = meta["fields"]
+            elif key == "themeFields":
+                in_fields = True
+                current_list = meta["themeFields"]
+        elif in_fields:
+            trimmed = line.strip()
+            if trimmed.startswith("- name:"):
+                flush()
+                current = {"name": trimmed[len("- name:"):].strip().strip("\"'")}
+            elif ":" in trimmed:
+                k, _, v = trimmed.partition(":")
+                current[k.strip()] = v.strip().strip('"')
+    flush()
+
+    if not meta["type"] or not meta["label"]:
+        return None
+    meta["body"] = body
+    meta["examples"] = extract_examples(body)
+    return meta
+
+
+# ─── Example extraction (the `## Examples` section) ──────────────────────────
+
+
+def extract_examples(body: str) -> list[dict]:
+    """Pull named JSON snippets from a doc's `## Examples` section: each `### Title`
+    followed by a ```json fenced block becomes {"name", "json"}. Only the Examples
+    section is scanned, so unrelated json blocks (e.g. a "## Segments" sample) are
+    ignored."""
+    lines = body.split("\n")
+    start = None
+    for i, l in enumerate(lines):
+        if l.strip().lower() == "## examples":
+            start = i + 1
+            break
+    if start is None:
+        return []
+    end = len(lines)
+    for i in range(start, len(lines)):
+        if lines[i].startswith("## "):
+            end = i
+            break
+    section = lines[start:end]
+
+    examples: list[dict] = []
+    title: Optional[str] = None
+    seen: dict[str, int] = {}
+    i = 0
+    while i < len(section):
+        l = section[i]
+        if l.startswith("### "):
+            title = l[4:].strip().strip("`")
+            i += 1
+            continue
+        if l.strip().startswith("```json"):
+            j = i + 1
+            buf = []
+            while j < len(section) and not section[j].strip().startswith("```"):
+                buf.append(section[j])
+                j += 1
+            name = title or f"Example {len(examples) + 1}"
+            if name in seen:
+                seen[name] += 1
+                name = f"{name} ({seen[name]})"
+            else:
+                seen[name] = 1
+            examples.append({"name": name, "json": "\n".join(buf).strip()})
+            i = j + 1
+            continue
+        i += 1
+    return examples
+
+
+# ─── Catalog assembly ────────────────────────────────────────────────────────
+
+# Categories whose docs describe controls that can be placed in a layout grid.
+PLACEABLE_CATEGORIES = {"controls", "display"}
+
+
+def parse_all(docs_dir) -> dict[str, dict]:
+    """Parse every `*.md` doc in the directory. Keyed by node_id (filename stem)."""
+    out: dict[str, dict] = {}
+    for f in sorted(Path(docs_dir).glob("*.md")):
+        doc = parse_doc(f.read_text(), f.stem)
+        if doc:
+            out[doc["node_id"]] = doc
+    return out
+
+
+def _compact(doc: dict, include_theme: bool = False) -> dict:
+    out: dict = {
+        "type": doc["type"],
+        "node_id": doc["node_id"],
+        "label": doc["label"],
+        "category": doc["category"],
+    }
+    if doc.get("defaultSpan"):
+        out["defaultSpan"] = doc["defaultSpan"]
+    if doc.get("fields"):
+        out["fields"] = doc["fields"]
+    if include_theme and doc.get("themeFields"):
+        out["themeFields"] = doc["themeFields"]
+    if doc.get("examples"):
+        out["examples"] = [e["name"] for e in doc["examples"]]
+    return out
+
+
+def build_catalog(docs_dir, types: Optional[list[str]] = None,
+                  include_theme: bool = False) -> dict[str, dict]:
+    """Compact, machine-readable schema for placeable controls, keyed by control
+    `type` (the value used in a layout). `types` filters to specific control types;
+    `include_theme` adds the per-control theme override fields."""
+    docs = parse_all(docs_dir)
+    catalog: dict[str, dict] = {}
+    wanted = set(types) if types else None
+    for doc in docs.values():
+        t = doc["type"]
+        if wanted is not None:
+            if t not in wanted and doc["node_id"] not in wanted:
+                continue
+        elif doc["category"] not in PLACEABLE_CATEGORIES:
+            continue
+        catalog[t] = _compact(doc, include_theme=include_theme)
+    return catalog
+
+
+def resolve_doc(docs_dir, control: str) -> Optional[dict]:
+    """Find a doc by node_id (e.g. 'color-picker') or control type (e.g. 'colorPicker')."""
+    docs = parse_all(docs_dir)
+    if control in docs:
+        return docs[control]
+    for doc in docs.values():
+        if doc["type"] == control:
+            return doc
+    return None
+
+
+def get_examples(docs_dir, control: str) -> list[dict]:
+    doc = resolve_doc(docs_dir, control)
+    return doc["examples"] if doc else []
+
+
+def find_example(docs_dir, control: str, name: str) -> Optional[dict]:
+    """Match an example by exact or case-insensitive-prefix name."""
+    examples = get_examples(docs_dir, control)
+    for ex in examples:
+        if ex["name"] == name:
+            return ex
+    low = name.lower()
+    for ex in examples:
+        if ex["name"].lower().startswith(low):
+            return ex
+    return None
+
+
+def example_as_obj(example: dict) -> Optional[dict]:
+    """Parse an example's JSON snippet into a dict (None if it doesn't parse)."""
+    try:
+        obj = json.loads(example["json"])
+        return obj if isinstance(obj, dict) else None
+    except (json.JSONDecodeError, TypeError):
+        return None