asecli 0.6.2__py3-none-any.whl

asecli/cli/io.py

@@ -0,0 +1,214 @@
+"""Filesystem commit helpers for CLI write commands."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+import hashlib
+import os
+from pathlib import Path
+import stat
+import tempfile
+
+
+_UNCHECKED = object()
+
+
+class UnsafeWritePathError(OSError):
+    """Raised when a target, backup, or lock path is not safe to write."""
+
+
+class WriteConflictError(OSError):
+    """Raised when the on-disk file changed after the command loaded it."""
+
+    def __init__(self, path: Path, expected: str | None, actual: str | None):
+        super().__init__(f"file changed since load: {path}")
+        self.path = path
+        self.expected = expected
+        self.actual = actual
+
+
+def read_text_snapshot(path: str | Path) -> tuple[str, str]:
+    """Read one regular UTF-8 file without following a final symlink."""
+    target = Path(path)
+    data, _ = _read_regular_file(target)
+    return data.decode("utf-8"), _digest(data)
+
+
+def file_digest(path: str | Path) -> str:
+    """Return a SHA-256 snapshot without decoding the file."""
+    data, _ = _read_regular_file(Path(path))
+    return _digest(data)
+
+
+def atomic_write(
+    path: str | Path,
+    text: str,
+    *,
+    expected_digest: str | None | object = _UNCHECKED,
+) -> None:
+    """Safely replace a file, back it up, and reject stale snapshots.
+
+    ``expected_digest`` is the SHA-256 captured when the caller loaded the
+    file. Passing ``None`` means the target is expected not to exist. Omitting
+    it keeps the low-level helper backward compatible but disables conflict
+    detection; CLI mutation paths always pass an expectation.
+    """
+    target = Path(path)
+    if not target.parent.is_dir():
+        raise FileNotFoundError(f"parent directory not found: {target.parent}")
+    with _exclusive_lock(target):
+        _reject_symlink(target.with_suffix(target.suffix + ".tmp"), "legacy temporary")
+        current, current_mode = _current_bytes(target)
+        actual_digest = _digest(current) if current is not None else None
+        if expected_digest is not _UNCHECKED and actual_digest != expected_digest:
+            raise WriteConflictError(target, expected_digest, actual_digest)
+
+        if current is not None:
+            backup = target.with_suffix(target.suffix + ".bak")
+            _reject_symlink(backup, "backup")
+            _replace_bytes(backup, current, current_mode)
+
+        mode = current_mode if current_mode is not None else 0o644
+        _replace_bytes(target, text.encode("utf-8"), mode)
+        _fsync_directory(target.parent)
+
+
+def restore_from_backup(path: str | Path) -> None:
+    """Restore the exact ``.bak`` snapshot without replacing that evidence."""
+    target = Path(path)
+    backup = target.with_suffix(target.suffix + ".bak")
+    if not target.parent.is_dir():
+        raise FileNotFoundError(f"parent directory not found: {target.parent}")
+    with _exclusive_lock(target):
+        _reject_symlink(target, "target")
+        _reject_symlink(backup, "backup")
+        backup_bytes, backup_mode = _read_regular_file(backup)
+        _replace_bytes(target, backup_bytes, backup_mode)
+        _fsync_directory(target.parent)
+
+
+def _digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _current_bytes(path: Path) -> tuple[bytes | None, int | None]:
+    try:
+        return _read_regular_file(path)
+    except FileNotFoundError:
+        return None, None
+
+
+def _read_regular_file(path: Path) -> tuple[bytes, int]:
+    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        fd = os.open(path, flags)
+    except OSError as exc:
+        if path.is_symlink():
+            raise UnsafeWritePathError(f"refusing symlink path: {path}") from exc
+        raise
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode):
+            raise UnsafeWritePathError(f"refusing non-regular file: {path}")
+        chunks = []
+        while True:
+            chunk = os.read(fd, 1024 * 1024)
+            if not chunk:
+                break
+            chunks.append(chunk)
+        return b"".join(chunks), stat.S_IMODE(info.st_mode)
+    finally:
+        os.close(fd)
+
+
+def _reject_symlink(path: Path, label: str) -> None:
+    try:
+        info = path.lstat()
+    except FileNotFoundError:
+        return
+    if stat.S_ISLNK(info.st_mode):
+        raise UnsafeWritePathError(f"refusing {label} symlink: {path}")
+    if not stat.S_ISREG(info.st_mode):
+        raise UnsafeWritePathError(f"refusing non-regular {label} path: {path}")
+
+
+def _replace_bytes(path: Path, data: bytes, mode: int) -> None:
+    fd, raw_tmp = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+    tmp = Path(raw_tmp)
+    try:
+        os.fchmod(fd, mode)
+        with os.fdopen(fd, "wb", closefd=True) as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        try:
+            tmp.unlink()
+        except FileNotFoundError:
+            pass
+        raise
+
+
+@contextmanager
+def _exclusive_lock(target: Path):
+    lock = _lock_path(target)
+    _reject_symlink(lock, "lock")
+    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+    fd = os.open(lock, flags, 0o600)
+    try:
+        if os.name == "nt":  # pragma: no cover - exercised on Windows CI
+            import msvcrt
+
+            if os.fstat(fd).st_size == 0:
+                os.write(fd, b"\0")
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(fd, msvcrt.LK_LOCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        if os.name == "nt":  # pragma: no cover - exercised on Windows CI
+            import msvcrt
+
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        os.close(fd)
+
+
+def _lock_path(target: Path) -> Path:
+    uid = getattr(os, "getuid", lambda: 0)()
+    root = Path(tempfile.gettempdir()) / f"asecli-locks-{uid}"
+    try:
+        root.mkdir(mode=0o700)
+    except FileExistsError:
+        pass
+    info = root.lstat()
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+        raise UnsafeWritePathError(f"refusing unsafe lock directory: {root}")
+    if hasattr(os, "getuid") and info.st_uid != os.getuid():
+        raise UnsafeWritePathError(f"lock directory is owned by another user: {root}")
+    key = hashlib.sha256(os.fsencode(str(target.resolve(strict=False)))).hexdigest()
+    return root / f"{key}.lock"
+
+
+def _fsync_directory(directory: Path) -> None:
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    try:
+        fd = os.open(directory, flags)
+    except OSError:  # pragma: no cover - some platforms cannot open directories
+        return
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)

asecli/cli/layout_command.py

@@ -0,0 +1,213 @@
+"""CLI composition for legacy and editor-accurate meticulous layout."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+
+from ..bridge import McpError, apply_wire_routes_via_mcp, inspect_graph_geometry_via_mcp
+from ..checks import fix_checksum, validate_file
+from ..core import (
+    AseFile,
+    COMMENTARY_TYPE,
+    WIRE_NODE_TYPE,
+    apply_meticulous_layout,
+    audit_meticulous_layout,
+    govern_comment_purposes,
+    meticulous_layout_positions,
+    logical_wire_manifest,
+    refit_comments_for_layout,
+    require_managed_property_presentation,
+    tidy,
+)
+from .commands import CliError, _commit_text, _load, _save
+from .io import restore_from_backup
+
+
+def cmd_layout(args) -> dict:
+    if args.mode == "legacy":
+        if args.route_wires:
+            raise CliError("USAGE_ERROR", "--route-wires requires --mode meticulous")
+        if args.audit:
+            raise CliError("USAGE_ERROR", "--audit requires --mode meticulous")
+        f = _load(args.file)
+        try:
+            moved = tidy(f.graph, gap_x=args.gap_x, gap_y=args.gap_y)
+        except ValueError as exc:
+            raise CliError("LAYOUT_ERROR", str(exc)) from exc
+        saved = _save(f, args.file, args.write)
+        return {
+            "mode": "legacy", "moved": moved, "structural_validation": "passed",
+            "visual_validation": "pending", **saved,
+        }
+    if args.audit and args.write:
+        raise CliError("USAGE_ERROR", "--audit is read-only and cannot be combined with --write")
+    if args.gap_x != 280.0 or args.gap_y != 120.0:
+        raise CliError("USAGE_ERROR", "--gap-x/--gap-y apply only to --mode legacy")
+    if args.instance_token_argv is not None:
+        raise CliError("USAGE_ERROR", "do not pass MCP tokens via argv; use ASECLI_MCP_INSTANCE_TOKEN")
+    return _meticulous(args)
+
+
+def _meticulous(args) -> dict:
+    f = _load(args.file)
+    before_semantics = _semantic_fingerprint(f.graph)
+    try:
+        geometry = inspect_graph_geometry_via_mcp(
+            args.file,
+            mcp_url=args.mcp_url,
+            instance_token=os.environ.get("ASECLI_MCP_INSTANCE_TOKEN"),
+            unity_instance=args.unity_instance,
+            allow_remote_mcp=args.allow_remote_mcp,
+        )
+        plan = meticulous_layout_positions(f.graph, geometry, route_wires=args.route_wires)
+        moved = apply_meticulous_layout(f.graph, plan)
+        # Audit/dry-run reports a proposed title without mutating the in-memory
+        # graph.  Only an explicitly authorized write may persist the title.
+        comment_purpose = govern_comment_purposes(f.graph, geometry, apply=bool(args.write))
+        comment_changes = refit_comments_for_layout(f.graph, geometry, plan.positions)
+        report = audit_meticulous_layout(
+            f.graph, geometry, plan, moved=moved, comment_purpose=comment_purpose,
+        )
+    except McpError as exc:
+        raise CliError("BRIDGE_ERROR", str(exc), exc.data) from exc
+    except FileNotFoundError as exc:
+        raise CliError("NOT_FOUND", str(exc)) from exc
+    except (KeyError, ValueError) as exc:
+        raise CliError("LAYOUT_ERROR", str(exc)) from exc
+
+    after_semantics = _semantic_fingerprint(f.graph)
+    if before_semantics != after_semantics:
+        raise CliError("LAYOUT_ERROR", "meticulous layout changed graph semantics; refusing output")
+    issues = validate_file(f)
+    structural_errors = [item for item in issues if item["severity"] == "error"]
+    if structural_errors:
+        raise CliError(
+            "VALIDATION_ERROR",
+            f"layout would leave {len(structural_errors)} structural error(s)",
+            {"issues": issues, "error_count": len(structural_errors)},
+        )
+    if args.write and report["hard_failures"]:
+        raise CliError(
+            "LAYOUT_ERROR",
+            f"meticulous layout failed {len(report['hard_failures'])} hard gate(s); file was not written",
+            {"audit": report, "written": False},
+        )
+    output = fix_checksum(f.serialize())
+    route_transaction = None
+    if args.write:
+        try:
+            require_managed_property_presentation(f)
+        except ValueError as exc:
+            raise CliError("PROPERTY_PRESENTATION_ERROR", str(exc)) from exc
+        _commit_text(args.file, output, f.source_digest)
+        if args.route_wires and plan.wire_route_changes:
+            expected_manifest = logical_wire_manifest(f.graph)
+            expected_semantics = _routed_semantic_fingerprint(f.graph)
+            try:
+                route_transaction = apply_wire_routes_via_mcp(
+                    args.file,
+                    plan.wire_route_changes,
+                    mcp_url=args.mcp_url,
+                    instance_token=os.environ.get("ASECLI_MCP_INSTANCE_TOKEN"),
+                    unity_instance=args.unity_instance,
+                    allow_remote_mcp=args.allow_remote_mcp,
+                )
+                persisted = AseFile.from_path(args.file)
+                if logical_wire_manifest(persisted.graph) != expected_manifest:
+                    raise ValueError("WireNode routing changed the logical connection set")
+                if _routed_semantic_fingerprint(persisted.graph) != expected_semantics:
+                    raise ValueError("WireNode routing changed non-layout node semantics")
+                created = {str(value) for value in route_transaction["created_node_ids"]}
+                if any(
+                    persisted.graph.node_by_id(node_id) is None
+                    or persisted.graph.node_by_id(node_id).type_name != WIRE_NODE_TYPE
+                    for node_id in created
+                ):
+                    raise ValueError("WireNode routing created-node manifest does not match the saved graph")
+                post_errors = [
+                    item for item in validate_file(persisted) if item["severity"] == "error"
+                ]
+                if post_errors:
+                    raise ValueError(f"WireNode routing left {len(post_errors)} structural error(s)")
+            except (McpError, FileNotFoundError, KeyError, ValueError) as exc:
+                try:
+                    restore_from_backup(args.file)
+                except OSError as restore_exc:
+                    raise CliError(
+                        "WRITE_ERROR",
+                        f"WireNode routing failed and backup restore failed: {restore_exc}",
+                        {"route_error": str(exc), "recovery": "failed"},
+                    ) from restore_exc
+                code = "BRIDGE_ERROR" if isinstance(exc, (McpError, FileNotFoundError)) else "LAYOUT_ERROR"
+                data = getattr(exc, "data", None) if isinstance(exc, McpError) else None
+                raise CliError(
+                    code, f"WireNode routing failed; original file restored: {exc}",
+                    {**(data or {}), "written": False, "recovery": "restored_from_backup"},
+                ) from exc
+    return {
+        "file": args.file,
+        "mode": "meticulous",
+        "measurement": "live_ase_geometry_v3",
+        "moved": moved,
+        "comment_changes": comment_changes,
+        "comment_changed_count": len(comment_changes),
+        "comment_purpose": comment_purpose,
+        "route_wires": bool(args.route_wires),
+        "wire_route_transaction": route_transaction,
+        "audit_only": bool(args.audit),
+        "audit": report,
+        "written": bool(args.write),
+        "path": args.file if args.write else None,
+        "preview_bytes": os.path.getsize(args.file) if args.write else len(output),
+        "checksum_recomputed": True,
+        "structural_validation": "passed",
+        "visual_validation": report["visual_validation"],
+        "requires_editor_reload": bool(args.write),
+    }
+
+
+def _semantic_fingerprint(graph) -> str:
+    nodes = []
+    for node in graph.nodes:
+        fields = list(node.raw_fields)
+        fields[3] = "<position>"
+        if node.type_name == COMMENTARY_TYPE:
+            fields[6], fields[7] = "<width>", "<height>"
+            try:
+                fields[10 + int(fields[9])] = "<title>"
+            except (IndexError, ValueError):
+                pass
+        nodes.append(fields)
+    payload = {
+        "nodes": nodes,
+        "wires": sorted((wire.out_node, wire.out_port, wire.in_node, wire.in_port) for wire in graph.wires),
+        "other": [raw for kind, raw in graph.instructions if kind == "other"],
+    }
+    return hashlib.sha256(json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode()).hexdigest()
+
+
+def _routed_semantic_fingerprint(graph) -> str:
+    """Ignore routing anchors/positions while protecting all algorithm data."""
+    nodes = []
+    for node in graph.nodes:
+        if node.type_name == WIRE_NODE_TYPE:
+            continue
+        fields = list(node.raw_fields)
+        fields[3] = "<position>"
+        if node.type_name == COMMENTARY_TYPE:
+            fields[6], fields[7] = "<width>", "<height>"
+            try:
+                fields[10 + int(fields[9])] = "<title>"
+            except (IndexError, ValueError):
+                pass
+        nodes.append(fields)
+    payload = {
+        "nodes": nodes,
+        "logical_wires": logical_wire_manifest(graph),
+        "other": [raw for kind, raw in graph.instructions if kind == "other"],
+    }
+    return hashlib.sha256(
+        json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode()
+    ).hexdigest()

asecli/cli/main.py

@@ -0,0 +1,245 @@
+"""asecli CLI entry point (TASK-0010): every command emits JSON on stdout."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from .. import __version__
+from ..core import ENABLE_IF_OPERATORS
+from .commands import EXIT_BRIDGE, EXIT_ERROR, EXIT_OK, CliError
+from .commands import (
+    cmd_add_node,
+    cmd_connect,
+    cmd_disconnect,
+    cmd_fix_checksum,
+    cmd_parse,
+    cmd_recompile,
+    cmd_set_field,
+    cmd_validate,
+)
+from .create_command import cmd_create
+from .custom_gui_command import cmd_custom_gui
+from .gui_support_command import cmd_gui_support
+from .commentary_command import cmd_comment_group
+from .skill_command import cmd_install_skill
+from .usage_command import cmd_graph_audit, cmd_remove_node
+from .layout_command import cmd_layout
+
+
+class JsonArgumentParser(argparse.ArgumentParser):
+    """Keep argparse diagnostics on stderr while routing failures through JSON."""
+
+    def error(self, message: str) -> None:
+        self.print_usage(sys.stderr)
+        raise CliError("USAGE_ERROR", message)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = JsonArgumentParser(prog="asecli", description="Agent-native CLI for Amplify Shader Editor assets")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("parse", help="parse ASE file and print graph summary")
+    s.add_argument("file")
+    s.set_defaults(func=cmd_parse)
+
+    s = sub.add_parser("set-field", help="set one serialized field of a node")
+    s.add_argument("file")
+    s.add_argument("--node", required=True)
+    s.add_argument("--field", type=int, required=True)
+    s.add_argument("--value", required=True)
+    s.add_argument("--write", action="store_true")
+    s.set_defaults(func=cmd_set_field)
+
+    s = sub.add_parser("add-node", help="add a node (schema-driven, or raw via --line)")
+    s.add_argument("file")
+    s.add_argument("--type")
+    s.add_argument("--id", type=int)
+    s.add_argument("--pos", default="0,0")
+    s.add_argument("--line", help="raw serialized Node;... line")
+    s.add_argument("--write", action="store_true")
+    s.set_defaults(func=cmd_add_node)
+
+    s = sub.add_parser("connect", help="wire source output port to destination input port")
+    s.add_argument("file")
+    s.add_argument("--from", dest="src", required=True, help="source node:port")
+    s.add_argument("--to", dest="dst", required=True, help="destination node:port")
+    s.add_argument("--write", action="store_true")
+    s.set_defaults(func=cmd_connect)
+
+    s = sub.add_parser("disconnect", help="remove a wire")
+    s.add_argument("file")
+    s.add_argument("--from", dest="src", required=True)
+    s.add_argument("--to", dest="dst", required=True)
+    s.add_argument("--write", action="store_true")
+    s.set_defaults(func=cmd_disconnect)
+
+    s = sub.add_parser("remove-node", help="remove node and attached wires")
+    s.add_argument("file")
+    s.add_argument("--node", required=True)
+    s.add_argument("--force-external", action="store_true", help="allow removal despite external source references")
+    s.add_argument("--write", action="store_true")
+    s.set_defaults(func=cmd_remove_node)
+
+    s = sub.add_parser("graph-audit", help="find output-dead nodes and distinguish external property consumers")
+    s.add_argument("file")
+    s.set_defaults(func=cmd_graph_audit)
+
+    s = sub.add_parser("validate", help="validate graph structure")
+    s.add_argument("file")
+    s.set_defaults(func=cmd_validate)
+
+    s = sub.add_parser("fix-checksum", help="recompute //CHKSM")
+    s.add_argument("file")
+    s.add_argument("--write", action="store_true")
+    s.set_defaults(func=cmd_fix_checksum)
+
+    s = sub.add_parser("layout", help="auto-arrange nodes using legacy or meticulous DAG layout")
+    s.add_argument("file")
+    s.add_argument("--mode", choices=("legacy", "meticulous"), default="legacy")
+    s.add_argument("--audit", action="store_true", help="report meticulous layout quality without writing")
+    s.add_argument(
+        "--route-wires", action="store_true",
+        help="explicitly allow meticulous mode to move or add WireNode routing anchors",
+    )
+    s.add_argument("--gap-x", type=float, default=280.0)
+    s.add_argument("--gap-y", type=float, default=120.0)
+    s.add_argument("--mcp-url", default="http://127.0.0.1:8080/mcp")
+    s.add_argument("--unity-instance", help="target Name@hash when multiple Unity/Tuanjie instances are connected")
+    s.add_argument("--allow-remote-mcp", action="store_true")
+    s.add_argument("--instance-token", dest="instance_token_argv", help=argparse.SUPPRESS)
+    s.add_argument("--write", action="store_true")
+    s.set_defaults(func=cmd_layout)
+
+    s = sub.add_parser("custom-gui", help="inspect or edit CustomEditor and MZGUI-compatible property metadata")
+    s.add_argument("file")
+    target = s.add_mutually_exclusive_group()
+    target.add_argument("--node", help="PropertyNode id for GUI metadata operations")
+    target.add_argument("--property", help="exact ShaderLab property name, for example _PaintColor")
+    s.add_argument("--spec", help="JSON file for atomic ordering/group/tooltip/help/enable operations")
+    editor = s.add_mutually_exclusive_group()
+    editor.add_argument("--editor", help="namespace-qualified ShaderGUI class")
+    editor.add_argument("--clear-editor", action="store_true")
+    group = s.add_mutually_exclusive_group()
+    group.add_argument("--group", help="set FoldoutMzgui group title")
+    group.add_argument("--clear-group", action="store_true")
+    tooltip = s.add_mutually_exclusive_group()
+    tooltip.add_argument("--tooltip", help="set TooltipMzgui text")
+    tooltip.add_argument("--clear-tooltip", action="store_true")
+    help_box = s.add_mutually_exclusive_group()
+    help_box.add_argument("--help-box", help="set optional user-authored HelpBoxMzgui content")
+    help_box.add_argument("--clear-help-box", action="store_true")
+    enabled_if = s.add_mutually_exclusive_group()
+    enabled_if.add_argument(
+        "--enabled-if",
+        metavar="PROPERTY",
+        help="enable this control only when another float property matches",
+    )
+    enabled_if.add_argument("--clear-enabled-if", action="store_true")
+    s.add_argument(
+        "--enabled-if-operator",
+        choices=ENABLE_IF_OPERATORS,
+    )
+    s.add_argument("--enabled-if-value", type=float)
+    s.add_argument("--add-attribute", action="append", help="expert: add/replace an MZGUI-compatible metadata value")
+    s.add_argument("--remove-attribute", action="append", help="expert: remove an MZGUI-compatible metadata type")
+    s.add_argument("--write", action="store_true")
+    s.set_defaults(func=cmd_custom_gui)
+
+    s = sub.add_parser("gui-support", help="prefer native MZGUI, otherwise install the Editor fallback")
+    s.add_argument("project", help="Unity/Tuanjie project root containing Assets and ProjectSettings")
+    s.add_argument("--runtime-probe", action="store_true", help="confirm MZGUI.MZGUI by reflection in the connected Editor")
+    s.add_argument("--mcp-url", default="http://127.0.0.1:8080/mcp")
+    s.add_argument("--allow-remote-mcp", action="store_true")
+    s.add_argument("--instance-token", dest="instance_token_argv", help=argparse.SUPPRESS)
+    s.add_argument("--handoff-native", action="store_true", help="reversibly disable a known fallback for native MZGUI takeover")
+    s.add_argument("--write", action="store_true", help="install the fallback into Assets/Editor only when MZGUI is absent")
+    s.set_defaults(func=cmd_gui_support)
+
+    s = sub.add_parser("install-skill", help="install the bundled ASECLI Agent Skill for Codex")
+    s.add_argument(
+        "--skill-root",
+        help="Codex skills directory; defaults to $CODEX_HOME/skills or ~/.codex/skills",
+    )
+    s.set_defaults(func=cmd_install_skill)
+
+    s = sub.add_parser("comment-group", help="inspect or create native ASE Comment frames")
+    s.add_argument("file")
+    s.add_argument("--fit", action="store_true", help="resize all existing frames using live ASE node bounds")
+    s.add_argument(
+        "--check-bounds",
+        action="store_true",
+        help="report members outside frames and unrelated Comment-frame overlaps",
+    )
+    s.add_argument("--editor-bounds", action="store_true", help="use live ASE bounds when creating a frame")
+    s.add_argument("--nodes", help="comma-separated member node ids; Comment ids enable nesting")
+    s.add_argument("--title", help="large functional or causal heading above the frame")
+    s.add_argument("--note", help="small text in the Comment header; defaults to Comment")
+    s.add_argument("--padding", type=float, help="frame padding in canvas units; defaults to 50")
+    s.add_argument("--id", type=int, help="explicit Comment node id; defaults to the next free id")
+    s.add_argument("--mcp-url", default="http://127.0.0.1:8080/mcp")
+    s.add_argument(
+        "--unity-instance",
+        help="target Name@hash when multiple Unity/Tuanjie instances are connected",
+    )
+    s.add_argument("--allow-remote-mcp", action="store_true")
+    s.add_argument("--instance-token", dest="instance_token_argv", help=argparse.SUPPRESS)
+    s.add_argument("--write", action="store_true")
+    s.set_defaults(func=cmd_comment_group)
+
+    s = sub.add_parser("create", help="create new shader from a compiled template shell")
+    s.add_argument("out")
+    s.add_argument("--from", dest="from_template")
+    s.add_argument("--name")
+    s.add_argument("--graph-from", help="donor ASE file whose graph is injected")
+    s.add_argument("--backend", choices=("text", "editor", "auto"), default="text")
+    s.add_argument("--spec", help="strict EditorGraphSpec v2 JSON (editor/auto backend)")
+    s.add_argument("--mcp-url", default="http://127.0.0.1:8080/mcp")
+    s.add_argument("--allow-remote-mcp", action="store_true")
+    s.add_argument("--instance-token", dest="instance_token_argv", help=argparse.SUPPRESS)
+    s.add_argument("--force", action="store_true")
+    s.set_defaults(func=cmd_create)
+
+    s = sub.add_parser("recompile", help="trigger ASE regeneration inside running editor (MCP)")
+    s.add_argument("file")
+    s.add_argument("--mcp-url", default="http://127.0.0.1:8080/mcp")
+    s.add_argument("--allow-remote-mcp", action="store_true")
+    s.add_argument("--instance-token", dest="instance_token_argv", help=argparse.SUPPRESS)
+    s.set_defaults(func=cmd_recompile)
+    return p
+
+
+def app(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+        data = args.func(args)
+    except CliError as e:
+        message = str(e)
+        token = os.environ.get("ASECLI_MCP_INSTANCE_TOKEN")
+        if token:
+            message = message.replace(token, "<redacted>")
+        payload = {"ok": False, "error": {"code": e.code, "message": message}}
+        if e.data is not None:
+            payload["data"] = e.data
+        json.dump(payload, sys.stdout, ensure_ascii=False)
+        sys.stdout.write("\n")
+        return EXIT_BRIDGE if e.code == "BRIDGE_ERROR" else EXIT_ERROR
+    except Exception as e:  # noqa: BLE001
+        message = f"{type(e).__name__}: {e}"
+        token = os.environ.get("ASECLI_MCP_INSTANCE_TOKEN")
+        if token:
+            message = message.replace(token, "<redacted>")
+        json.dump({"ok": False, "error": {"code": "INTERNAL", "message": message}}, sys.stdout, ensure_ascii=False)
+        sys.stdout.write("\n")
+        return EXIT_ERROR
+    json.dump({"ok": True, "data": data}, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    raise SystemExit(app())