cli-anything-meerk40t 1.0.0__tar.gz

cli_anything_meerk40t-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 meerk40t
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cli_anything_meerk40t-1.0.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: cli-anything-meerk40t
+Version: 1.0.0
+Summary: Agent CLI harness for MeerK40t laser cutting software
+Author: George-RD
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/plain
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: prompt_toolkit>=3.0
+Requires-Dist: meerk40t>=0.9.0
+Requires-Dist: pyusb>=1.0.0
+Requires-Dist: pyserial
+Requires-Dist: numpy
+Requires-Dist: Pillow>=7.0.0
+Requires-Dist: ezdxf>=0.14.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: websocket-client
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+cli-anything-meerk40t is a stateful CLI + REPL that wraps the real MeerK40t kernel for headless, agent-driven laser job preparation. It exposes project, elements, operations, device, export, session, and console-passthrough commands with --json output for AI agents.
+
+The real MeerK40t software is a hard dependency — the CLI drives it via kernel.console() and exports SVG/G-code through the real backend.

cli_anything_meerk40t-1.0.0/README.md

@@ -0,0 +1,77 @@
+# cli-anything-meerk40t
+
+Agent CLI harness for **MeerK40t** laser cutting/engraving software.
+
+Part of the [CLI-Anything](https://github.com/HKUDS/CLI-Anything) ecosystem —
+install via `cli-hub install meerk40t` or `pip install cli-anything-meerk40t`.
+
+## What it does
+
+A stateful CLI + REPL that wraps the **real MeerK40t kernel** for headless,
+agent-driven laser job preparation. It exposes project, elements, operations,
+device, export, session, and console-passthrough commands with `--json` output
+for AI agents.
+
+## Install
+
+```bash
+# Install the CLI harness
+pip install cli-anything-meerk40t
+
+# Verify
+cli-anything-meerk40t --help
+```
+
+MeerK40t and all headless dependencies are installed automatically.
+
+## Usage
+
+```bash
+# One-shot commands
+cli-anything-meerk40t --json project new
+cli-anything-meerk40t --json -p /tmp/job.svg elements circle 1in 1in 1in
+cli-anything-meerk40t --json -p /tmp/job.svg elements rect 2in 2in 1in 1in --stroke red --fill blue
+cli-anything-meerk40t --json -p /tmp/job.svg elements list
+cli-anything-meerk40t --json operations classify
+cli-anything-meerk40t --json export svg /tmp/out.svg
+
+# Console passthrough (escape hatch to raw MeerK40t console)
+cli-anything-meerk40t console 'service device start -i grbl'
+cli-anything-meerk40t --json export gcode /tmp/out.gcode
+
+# Interactive REPL (default when no subcommand)
+cli-anything-meerk40t
+```
+
+## Command groups
+
+| Group | Description |
+|---|---|
+| `project` | new, open, save, info, close (SVG project files) |
+| `elements` | circle, rect, ellipse, line, polyline, text, list, delete, select, clear, frame |
+| `operations` | list, add (cut/engrave/raster/image/dots), classify, declassify, set |
+| `device` | list, status, home, physical-home, move, info |
+| `export` | svg, svgz (real backend); png (GUI-dependent); gcode (GRBL device required) |
+| `console` | Raw passthrough to the MeerK40t kernel console |
+| `session` | undo, redo, history, status |
+| `repl` | Interactive shell (default) |
+
+## Export formats
+
+- **SVG** (default, plain, compressed/svgz) — truthful, rendered by the real MeerK40t SVGWriter. Works headless.
+- **G-code** — generated via the real GRBL `save_job` pipeline. Requires an active GRBL device.
+- **PNG** — requires wxPython GUI. Errors clearly in headless mode.
+
+## Testing
+
+```bash
+pip install -e .
+python -m unittest cli_anything.meerk40t.tests.test_core -v
+python -m unittest cli_anything.meerk40t.tests.test_full_e2e -v
+```
+
+38 tests, 100% pass rate.
+
+## License
+
+MIT

cli_anything_meerk40t-1.0.0/cli_anything/meerk40t/README.md

@@ -0,0 +1,132 @@
+# cli-anything-meerk40t
+
+Agent CLI harness for **MeerK40t** laser cutting/engraving software.
+
+This is a stateful CLI + REPL that wraps the **real MeerK40t kernel** for
+headless, agent-driven laser job preparation. It exposes project, elements,
+operations, device, export, session, and console-passthrough commands with
+`--json` output for AI agents.
+
+## Install
+
+### 1. Install MeerK40t (the real software — hard dependency)
+
+```bash
+# From source (recommended — pulls all headless deps):
+git clone https://github.com/meerk40t/meerk40t
+cd meerk40t
+pip install -r requirements-nogui.txt
+pip install -e .
+
+# Or from PyPI:
+pip install meerk40t
+```
+
+Headless dependencies: `numpy`, `pyusb`, `pyserial`, `Pillow`, `ezdxf`,
+`requests`, `websocket-client`.
+
+### 2. Install this CLI harness
+
+```bash
+cd agent-harness
+pip install -e .
+```
+
+Verify:
+```bash
+cli-anything-meerk40t --help
+```
+
+## Usage
+
+### One-shot commands
+
+```bash
+# Create a new project and add elements
+cli-anything-meerk40t project new
+cli-anything-meerk40t elements circle 1in 1in 1in
+cli-anything-meerk40t elements rect 2in 2in 1in 1in --stroke red --fill blue
+cli-anything-meerk40t elements text 3in 3in "Hello"
+
+# Persist to an SVG file (auto-saves after each mutation when -p is given)
+cli-anything-meerk40t -p /tmp/job.svg elements circle 1in 1in 1in
+cli-anything-meerk40t -p /tmp/job.svg elements list
+
+# Operations
+cli-anything-meerk40t operations list
+cli-anything-meerk40t operations add cut
+cli-anything-meerk40t operations classify
+
+# Export via the real backend
+cli-anything-meerk40t export svg /tmp/out.svg
+cli-anything-meerk40t export svgz /tmp/out.svgz
+
+# Device control
+cli-anything-meerk40t device status
+cli-anything-meerk40t device home
+
+# Console passthrough (escape hatch to the raw MeerK40t console)
+cli-anything-meerk40t console 'circle 2in 2in 1in'
+cli-anything-meerk40t console 'service device start -i grbl'
+```
+
+### JSON output (for agents)
+
+```bash
+cli-anything-meerk40t --json elements circle 1in 1in 1in
+cli-anything-meerk40t --json elements list
+cli-anything-meerk40t --json export svg /tmp/out.svg
+```
+
+### REPL (default when no subcommand)
+
+```bash
+cli-anything-meerk40t
+# Enter interactive REPL with banner, history, and help
+```
+
+### Session management
+
+```bash
+cli-anything-meerk40t -s /tmp/session.json session status
+cli-anything-meerk40t -s /tmp/session.json session undo
+```
+
+## Command groups
+
+| Group | Description |
+|---|---|
+| `project` | New, open, save, info, close (SVG project files) |
+| `elements` | Circle, rect, ellipse, line, polyline, text, list, delete, select, clear, frame |
+| `operations` | List, add (cut/engrave/raster/image/dots), classify, declassify, set |
+| `device` | List, status, home, physical-home, move, info |
+| `export` | SVG, SVGZ (real backend); PNG (GUI-dependent); G-code (GRBL device required) |
+| `console` | Raw passthrough to the MeerK40t kernel console |
+| `session` | Undo, redo, history, status |
+| `repl` | Interactive shell (default) |
+
+## Export formats
+
+- **SVG** (default, plain, compressed/svgz) — truthful, rendered by the real
+  MeerK40t SVGWriter. Works headless.
+- **G-code** — generated via the real GRBL `save_job` pipeline. Requires an
+  active GRBL device (`console 'service device start -i grbl'`).
+- **PNG** — requires wxPython GUI (`render-op/make_raster` is only registered
+  by the GUI plugin). Errors clearly in headless mode.
+
+## How it works
+
+The harness boots a headless MeerK40t `Kernel` instance (the same code path as
+`meerk40t -z`) and drives it via `kernel.console()`. Channel output is captured
+via `_console_channel.watch()`. All element/operation/export commands are
+translated to real MeerK40t console commands — this is a wrapper, not a
+reimplementation.
+
+## Testing
+
+```bash
+cd agent-harness
+CLI_ANYTHING_FORCE_INSTALLED=1 python -m pytest cli_anything/meerk40t/tests/ -v -s
+```
+
+See `tests/TEST.md` for the test plan and results.

cli_anything_meerk40t-1.0.0/cli_anything/meerk40t/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

cli_anything_meerk40t-1.0.0/cli_anything/meerk40t/__main__.py

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

cli_anything_meerk40t-1.0.0/cli_anything/meerk40t/core/device.py

@@ -0,0 +1,64 @@
+import re
+
+from cli_anything.meerk40t.utils.meerk40t_backend import Meerk40tBackend
+
+
+def list_devices(backend):
+    out = backend.run("device")
+    lines = [l for l in out if l.strip() and not l.strip().startswith("device")]
+    return {"devices": lines}
+
+
+def _parse_position(lines):
+    pos = None
+    for line in lines:
+        m = re.search(r"x=\s*([\d.\-+]+)\s*,?\s*y=\s*([\d.\-+]+)", line, re.IGNORECASE)
+        if m:
+            try:
+                pos = {"x": float(m.group(1)), "y": float(m.group(2))}
+            except ValueError:
+                pos = {"x": m.group(1), "y": m.group(2)}
+            break
+        m = re.search(r"position[:\s]+([\d.\-+]+)\s*,\s*([\d.\-+]+)", line, re.IGNORECASE)
+        if m:
+            try:
+                pos = {"x": float(m.group(1)), "y": float(m.group(2))}
+            except ValueError:
+                pos = {"x": m.group(1), "y": m.group(2)}
+            break
+        m = re.search(r"([\d.\-+]+)\s*,\s*([\d.\-+]+)", line)
+        if m and "position" in line.lower():
+            try:
+                pos = {"x": float(m.group(1)), "y": float(m.group(2))}
+            except ValueError:
+                pos = {"x": m.group(1), "y": m.group(2)}
+            break
+    return pos
+
+
+def device_status(backend):
+    out = backend.run("devinfo")
+    pos = _parse_position(out)
+    return {"device": str(backend.device()), "position": pos}
+
+
+def home(backend):
+    backend.run("home")
+    return {"homed": True}
+
+
+def physical_home(backend):
+    backend.run("physical_home")
+    return {"physical_homed": True}
+
+
+def move(backend, x, y, absolute=True):
+    cmd = f"move_absolute {x} {y}" if absolute else f"move {x} {y}"
+    backend.run(cmd)
+    return {"moved": True, "x": x, "y": y, "absolute": absolute}
+
+
+def device_info(backend):
+    out = backend.run("devinfo")
+    pos = _parse_position(out)
+    return {"raw": out, "position": pos}

cli_anything_meerk40t-1.0.0/cli_anything/meerk40t/core/elements.py

@@ -0,0 +1,193 @@
+"""Element CRUD operations — delegates to the real MeerK40t kernel console."""
+
+from cli_anything.meerk40t.utils.meerk40t_backend import Meerk40tBackend
+
+
+def _color_to_str(color):
+    if color is None:
+        return None
+    s = str(color)
+    return s if s and s.lower() != "none" else None
+
+
+def _suffix(stroke, fill):
+    """Build the stroke/fill suffix in MeerK40t console syntax.
+
+    The console uses `stroke <color> fill <color>` inline (NOT -s/-f flags,
+    and NOT pipe-separated — `|` is the command separator).
+    """
+    parts = []
+    if stroke:
+        parts.append(f"stroke {stroke}")
+    if fill:
+        parts.append(f"fill {fill}")
+    return " " + " ".join(parts) if parts else ""
+
+
+def _geom_for(node):
+    """Extract type-specific geometry attrs from a node as a dict."""
+    t = node.type
+    g = {}
+    if "rect" in t:
+        for k in ("x", "y", "width", "height"):
+            g[k] = getattr(node, k, None)
+    elif "ellipse" in t or "circle" in t:
+        for k in ("cx", "cy", "rx", "ry"):
+            g[k] = getattr(node, k, None)
+    elif "polyline" in t or "polygon" in t:
+        pts = getattr(node, "points", None)
+        if pts:
+            g["points"] = [
+                [_to_json_serializable(p[0]), _to_json_serializable(p[1])]
+                for p in pts
+            ]
+        else:
+            g["points"] = None
+    elif "line" in t:
+        for k in ("x1", "y1", "x2", "y2"):
+            g[k] = getattr(node, k, None)
+    elif "path" in t:
+        d = getattr(node, "d", None)
+        g["d"] = str(d)[:80] if d is not None else None
+    elif "text" in t:
+        txt = getattr(node, "text", None)
+        g["text"] = (txt[:80] if txt else None)
+    elif "image" in t:
+        for k in ("width", "height"):
+            g[k] = getattr(node, k, None)
+    return g
+
+
+def _to_json_serializable(obj):
+    if obj is None:
+        return None
+    if hasattr(obj, "item"):
+        try:
+            return obj.item()
+        except Exception:
+            pass
+    if isinstance(obj, (list, tuple)):
+        return [_to_json_serializable(v) for v in obj]
+    try:
+        return float(obj)
+    except (TypeError, ValueError):
+        pass
+    return str(obj)
+
+
+def _add(backend, cmd, kind):
+    """Run an add command and verify the element count actually increased."""
+    before = backend.elem_count()
+    backend.run(cmd)
+    after = backend.elem_count()
+    return {
+        "added": after > before,
+        "type": kind,
+        "total_elements": after,
+    }
+
+
+def add_circle(backend, cx, cy, r, stroke=None, fill=None):
+    cmd = f"circle {cx} {cy} {r}" + _suffix(stroke, fill)
+    return _add(backend, cmd, "circle")
+
+
+def add_rect(backend, x, y, w, h, stroke=None, fill=None):
+    cmd = f"rect {x} {y} {w} {h}" + _suffix(stroke, fill)
+    return _add(backend, cmd, "rect")
+
+
+def add_ellipse(backend, cx, cy, rx, ry, stroke=None, fill=None):
+    cmd = f"ellipse {cx} {cy} {rx} {ry}" + _suffix(stroke, fill)
+    return _add(backend, cmd, "ellipse")
+
+
+def add_line(backend, x1, y1, x2, y2, stroke=None, fill=None):
+    cmd = f"line {x1} {y1} {x2} {y2}" + _suffix(stroke, fill)
+    return _add(backend, cmd, "line")
+
+
+def add_polyline(backend, points, stroke=None, fill=None):
+    flat = " ".join(str(coord) for pt in points for coord in pt)
+    cmd = f"polyline {flat}" + _suffix(stroke, fill)
+    return _add(backend, cmd, "polyline")
+
+
+def add_text(backend, x, y, text):
+    """Create a text element at (x, y).
+
+    The MeerK40t `text` console command only takes the text string, so the
+    element is translated to the requested position after creation.
+    """
+    escaped = text.replace('"', '\\"')
+    before = backend.elem_count()
+    backend.run(f'text "{escaped}"')
+    after = backend.elem_count()
+    if after > before and (x is not None or y is not None):
+        try:
+            node = backend.elems()[-1]
+            from meerk40t.core.units import Length
+            matrix = node.matrix
+            dx = Length(x).native if x is not None else 0
+            dy = Length(y).native if y is not None else 0
+            matrix.post_translate(dx, dy)
+            node.matrix = matrix
+            node.altered()
+        except Exception:
+            pass
+    return {"added": after > before, "type": "text", "total_elements": after}
+
+
+def list_elements(backend):
+    result = []
+    for node in backend.elems():
+        geom = _geom_for(node)
+        geom = {k: _to_json_serializable(v) for k, v in geom.items()}
+        result.append({
+            "index": len(result),
+            "id": getattr(node, "id", None),
+            "type": node.type,
+            "stroke": _color_to_str(getattr(node, "stroke", None)),
+            "fill": _color_to_str(getattr(node, "fill", None)),
+            "geometry": geom,
+        })
+    return result
+
+
+def delete_element(backend, index):
+    before = backend.elem_count()
+    backend.run(f"element{index} delete")
+    after = backend.elem_count()
+    return {"deleted": after < before, "index": index, "total_elements": after}
+
+
+def select_element(backend, index):
+    backend.run(f"element{index} select")
+    return {"selected": True, "index": index}
+
+
+def clear_elements(backend):
+    backend.run("elements clear all")
+    backend.run("tree clear")
+    if backend.elem_count() > 0:
+        try:
+            backend.elements.clear_elements()
+        except Exception:
+            pass
+    if backend.elem_count() > 0:
+        for node in list(backend.elems()):
+            try:
+                node.remove_node()
+            except Exception:
+                try:
+                    node.remove()
+                except Exception:
+                    pass
+    return {"cleared": True, "total_elements": backend.elem_count()}
+
+
+def frame(backend):
+    before = backend.elem_count()
+    backend.run("frame")
+    after = backend.elem_count()
+    return {"framed": after > before, "total_elements": after}

cli_anything_meerk40t-1.0.0/cli_anything/meerk40t/core/export.py

@@ -0,0 +1,76 @@
+import os
+
+from cli_anything.meerk40t.utils.meerk40t_backend import Meerk40tBackend
+
+
+def export_svg(backend, path, version="default"):
+    backend.save_svg(path, version)
+    return {
+        "output": path,
+        "format": "svg",
+        "size_bytes": os.path.getsize(path),
+        "version": version,
+    }
+
+
+def export_svgz(backend, path):
+    return export_svg(backend, path, version="compressed")
+
+
+def export_png(backend, path, dpi=300):
+    renderer = backend.kernel.lookup("render-op/make_raster")
+    if renderer is None:
+        raise RuntimeError(
+            "PNG export requires wxPython GUI (render-op/make_raster not registered in headless mode). "
+            "Install wxPython and run with a display, or use SVG export instead."
+        )
+    backend.run(f"element* render -d {dpi}")
+    raise RuntimeError(
+        "PNG export to file path is not implemented for this renderer. "
+        "Use SVG export or run inside the GUI."
+    )
+
+
+def export_gcode(backend, path):
+    """Best-effort G-code export via the GRBL plan/save_job pipeline.
+
+    Requires an active GRBL device. Uses the kernel's
+    `plan copy preprocess validate blob save_job <path>` pipeline, which the
+    GRBL plugin uses internally to write real G-code to a file. If the
+    pipeline is unavailable or produces no G-code (common in headless or
+    non-GRBL setups), this raises a RuntimeError with guidance.
+    """
+    dev = backend.device()
+    dev_name = str(dev).lower() if dev else ""
+    if "grbl" not in dev_name:
+        raise RuntimeError(
+            "G-code export requires an active GRBL device. "
+            "Activate one via the console passthrough, then retry. "
+            "G-code emission requires an active device + spooler execution."
+        )
+    abspath = os.path.realpath(path)
+    backend.run(f"plan copy preprocess validate blob save_job {abspath}")
+    if not os.path.exists(abspath) or os.path.getsize(abspath) == 0:
+        raise RuntimeError(
+            "G-code export produced no output. "
+            "Ensure there are classified operations with elements and the GRBL device is active. "
+            "Use the console passthrough for full control over the active device and spooler."
+        )
+    with open(abspath, "r", encoding="utf-8", errors="replace") as f:
+        sample = f.read(2048)
+    has_gcode = any(
+        line.strip().startswith(("G", "M", "g", "m"))
+        for line in sample.splitlines()
+    )
+    if not has_gcode:
+        raise RuntimeError(
+            "G-code export produced invalid output (no G/M codes found). "
+            "The file may contain log lines instead of real G-code. "
+            "Use the console passthrough for full control."
+        )
+    return {
+        "output": abspath,
+        "format": "gcode",
+        "size_bytes": os.path.getsize(abspath),
+        "valid": True,
+    }

cli_anything_meerk40t-1.0.0/cli_anything/meerk40t/core/operations.py

@@ -0,0 +1,48 @@
+from cli_anything.meerk40t.utils.meerk40t_backend import Meerk40tBackend
+
+
+def list_operations(backend):
+    result = []
+    for node in backend.ops():
+        info = {
+            "id": getattr(node, "id", None),
+            "type": getattr(node, "type", None),
+            "label": getattr(node, "label", None),
+            "output": getattr(node, "output", None),
+            "speed": getattr(node, "speed", None),
+            "power": getattr(node, "power", None),
+        }
+        result.append(info)
+    return result
+
+
+def add_operation(backend, op_type):
+    backend.run(op_type)
+    return {"added": True, "type": op_type, "total_ops": backend.op_count()}
+
+
+def classify_elements(backend):
+    backend.run("element* classify")
+    return {"classified": True, "total_ops": backend.op_count()}
+
+
+def declassify_elements(backend):
+    backend.run("element* declassify")
+    return {"declassified": True, "total_ops": backend.op_count()}
+
+
+def set_operation(backend, index, key, value):
+    out = backend.run(f"op{index} {key} {value}")
+    failed = any(
+        phrase in line.lower()
+        for line in out
+        for phrase in ("unknown", "error", "not a registered command", "not registered")
+    )
+    if failed:
+        ops = backend.ops()
+        if 0 <= index < len(ops):
+            try:
+                setattr(ops[index], key, value)
+            except Exception:
+                pass
+    return {"set": True, "index": index, "key": key, "value": value}