asecli 0.6.2__py3-none-any.whl

asecli/cli/create_command.py

@@ -0,0 +1,250 @@
+"""Safe shader creation and semantic Shader-name mutation."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import re
+
+from ..bridge import (
+    MZGUI_EDITOR,
+    McpError,
+    SpecError,
+    create_shader_via_mcp,
+    install_gui_support,
+    load_editor_graph_spec,
+    route_create_backend,
+)
+from ..checks import ChecksumFormatError, fix_checksum, validate_file
+from ..core import (
+    AseFile,
+    apply_material_gui_spec,
+    main_master_node,
+    require_property_presentation,
+    sync_compiled_property_metadata,
+)
+from .commands import CliError, _commit_text, _load
+from .gui_provider import select_editor_provider
+from .io import UnsafeWritePathError, file_digest
+
+
+_SHADER_DECLARATION = re.compile(r'(?m)^(?P<indent>[ \t]*)Shader[ \t]+"(?P<name>[^"\r\n]+)"')
+_TEMPLATE_NAME_FIELD = {
+    "AmplifyShaderEditor.TemplateMultiPassMasterNode": 12,
+    "AmplifyShaderEditor.TemplateMasterNode": 12,
+}
+
+
+def cmd_create(args) -> dict:
+    spec = None
+    if args.spec:
+        try:
+            spec = load_editor_graph_spec(args.spec)
+        except FileNotFoundError as exc:
+            raise CliError("NOT_FOUND", str(exc)) from exc
+        except SpecError as exc:
+            raise CliError("USAGE_ERROR", str(exc)) from exc
+    try:
+        backend = route_create_backend(args.backend, spec)
+    except SpecError as exc:
+        raise CliError("USAGE_ERROR", str(exc)) from exc
+    if backend == "editor":
+        return _cmd_create_editor(args, spec)
+    return _cmd_create_text(args, spec)
+
+
+def _cmd_create_text(args, spec) -> dict:
+    if spec is not None:
+        raise CliError("USAGE_ERROR", "--spec requires --backend editor or auto")
+    if not args.from_template:
+        raise CliError("USAGE_ERROR", "--from is required for the text create backend")
+    f = _load(args.from_template)
+    if args.graph_from:
+        donor = _load(args.graph_from)
+        f.replace_graph(donor.graph)
+    if args.name:
+        _set_shader_name(f, args.name)
+    try:
+        text = fix_checksum(f.serialize())
+    except ChecksumFormatError as exc:
+        raise CliError("CHECKSUM_FORMAT_ERROR", str(exc)) from exc
+    try:
+        created = AseFile.from_text(text)
+        errors = [issue for issue in validate_file(created) if issue["severity"] == "error"]
+    except ValueError as exc:
+        raise CliError("VALIDATION_ERROR", f"created shader is not parseable: {exc}") from exc
+    if errors:
+        raise CliError(
+            "VALIDATION_ERROR",
+            f"created shader contains {len(errors)} structural error(s)",
+            {"issues": errors, "error_count": len(errors)},
+        )
+    try:
+        presentation = require_property_presentation(created)
+    except ValueError as exc:
+        raise CliError("PROPERTY_PRESENTATION_ERROR", str(exc)) from exc
+    try:
+        output_digest = file_digest(args.out)
+    except FileNotFoundError:
+        output_digest = None
+    except UnsafeWritePathError as exc:
+        raise CliError("UNSAFE_PATH", str(exc)) from exc
+    if output_digest is not None and not args.force:
+        raise CliError("USAGE_ERROR", f"{args.out} exists (use --force)")
+    _commit_text(args.out, text, output_digest)
+    return {
+        "created": args.out,
+        "name": args.name,
+        "graph_from": args.graph_from,
+        "backend": "text",
+        "property_presentation": presentation,
+    }
+
+
+def _cmd_create_editor(args, spec) -> dict:
+    if spec is None:
+        raise CliError("USAGE_ERROR", "--spec is required for the editor create backend")
+    if spec.version not in {2, 3}:
+        raise CliError(
+            "USAGE_ERROR",
+            "CLI Editor creation requires EditorGraphSpec v2 or v3 with Chinese inspector_name and help for every property",
+        )
+    if args.from_template or args.graph_from or args.name:
+        raise CliError("USAGE_ERROR", "--from, --graph-from and --name are text-backend options")
+    if args.force:
+        raise CliError("USAGE_ERROR", "editor create only supports absent targets; --force is not allowed")
+    if args.instance_token_argv is not None:
+        raise CliError("USAGE_ERROR", "do not pass MCP tokens via argv; use ASECLI_MCP_INSTANCE_TOKEN")
+    try:
+        selected_editor, gui_support = select_editor_provider(args.out)
+    except (FileNotFoundError, ValueError, RuntimeError, OSError) as exc:
+        raise CliError("GUI_SUPPORT_ERROR", str(exc)) from exc
+    try:
+        result = create_shader_via_mcp(
+            args.out,
+            spec,
+            mcp_url=args.mcp_url,
+            instance_token=os.environ.get("ASECLI_MCP_INSTANCE_TOKEN"),
+            allow_remote_mcp=args.allow_remote_mcp,
+        )
+    except McpError as exc:
+        raise CliError("BRIDGE_ERROR", str(exc), exc.data) from exc
+    except FileExistsError as exc:
+        raise CliError("USAGE_ERROR", str(exc)) from exc
+    except FileNotFoundError as exc:
+        raise CliError("NOT_FOUND", str(exc)) from exc
+    except ValueError as exc:
+        raise CliError("USAGE_ERROR", str(exc)) from exc
+
+    try:
+        created = AseFile.from_path(args.out)
+        errors = [issue for issue in validate_file(created) if issue["severity"] == "error"]
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise CliError(
+            "BRIDGE_ERROR",
+            f"Editor-created shader is not parseable and was preserved for diagnosis: {exc}",
+            _preserved_editor_asset_details(args.out, result),
+        ) from exc
+    if errors:
+        raise CliError(
+            "BRIDGE_ERROR",
+            f"Editor-created shader contains {len(errors)} structural error(s) and was preserved for diagnosis",
+            {
+                "issues": errors,
+                "error_count": len(errors),
+                **_preserved_editor_asset_details(args.out, result),
+            },
+        )
+    try:
+        output, presentation = _finalize_editor_property_presentation(
+            created, spec, editor=selected_editor
+        )
+        _commit_text(args.out, output, created.source_digest)
+        result["shader_sha256"] = file_digest(args.out)
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise CliError(
+            "BRIDGE_ERROR",
+            f"Editor-created shader failed property-presentation finalization and was preserved for diagnosis: {exc}",
+            _preserved_editor_asset_details(args.out, result),
+        ) from exc
+    return {
+        "created": args.out,
+        "backend": "editor",
+        "gui_support": gui_support,
+        "property_presentation": presentation,
+        **result,
+    }
+
+
+def _finalize_editor_property_presentation(
+    created: AseFile, spec, *, editor: str = MZGUI_EDITOR
+) -> tuple[str, dict]:
+    """Apply the same v2 presentation contract after ASE commits an Editor graph."""
+    presentation_spec = {
+        "editor": editor,
+        "properties": [
+            {
+                "name": node.property_name,
+                "display_name": node.inspector_name,
+                "tooltip": node.tooltip,
+                "help": node.help,
+                "enabled_if": node.enabled_if,
+            }
+            for node in spec.nodes
+            if node.property_name is not None
+        ],
+    }
+    apply_material_gui_spec(created, presentation_spec)
+    sync_compiled_property_metadata(created)
+    from asecli.core.compiled_metadata import hide_known_template_compiled_only_properties
+
+    hide_known_template_compiled_only_properties(created, spec.template.guid)
+    presentation = require_property_presentation(created)
+    return fix_checksum(created.serialize()), presentation
+
+def _preserved_editor_asset_details(path: str, result: dict) -> dict:
+    """Describe a post-commit failure without deleting an identity that may have changed."""
+    return {
+        "preserved_path": str(Path(path).resolve()),
+        "cleanup": "skipped_untrusted_post_commit_asset",
+        "transaction_nonce": result.get("transaction_nonce"),
+        "shader_sha256": result.get("shader_sha256"),
+        "meta_sha256": result.get("meta_sha256"),
+    }
+
+
+def _set_shader_name(ase_file: AseFile, name: str) -> None:
+    if not name.strip() or len(name) > 255:
+        raise CliError("USAGE_ERROR", "shader name must be 1-255 non-whitespace characters")
+    if any(ord(char) < 32 for char in name) or any(char in name for char in ('"', "'", ";", "\\")):
+        raise CliError("USAGE_ERROR", "shader name contains a forbidden quote, separator, escape, or control character")
+    matches = list(_SHADER_DECLARATION.finditer(ase_file.prefix))
+    if len(matches) != 1:
+        raise CliError("USAGE_ERROR", f"template must contain exactly one Shader declaration, found {len(matches)}")
+    declaration = matches[0]
+    ase_file.prefix = (
+        ase_file.prefix[: declaration.start("name")]
+        + name
+        + ase_file.prefix[declaration.end("name") :]
+    )
+
+    try:
+        master = main_master_node(ase_file.graph)
+    except ValueError as exc:
+        if any("MasterNode" in node.type_name for node in ase_file.graph.nodes):
+            raise CliError("USAGE_ERROR", f"cannot resolve graph Master name field: {exc}") from exc
+        return
+    index = _TEMPLATE_NAME_FIELD.get(master.type_name)
+    if index is None:
+        old_name = declaration.group("name")
+        candidates = [i for i, value in enumerate(master.raw_fields) if value == old_name]
+        if len(candidates) != 1:
+            raise CliError(
+                "USAGE_ERROR",
+                f"unsupported Master name layout for {master.type_name}: found {len(candidates)} candidate fields",
+            )
+        index = candidates[0]
+    if index >= len(master.raw_fields):
+        raise CliError("USAGE_ERROR", f"Master node {master.node_id} has no shader-name field {index}")
+    master.raw_fields[index] = name
+    ase_file.graph.replace_node(master)

asecli/cli/custom_gui_command.py

@@ -0,0 +1,170 @@
+"""CLI composition for ASE CustomEditor and property metadata."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ..checks import fix_checksum, validate_file
+from ..core import (
+    ASECLI_GUI_EDITOR,
+    MZGUI_EDITOR,
+    SUPPORTED_GUI_EDITORS,
+    apply_material_gui_spec,
+    enable_if_attribute,
+    graph_custom_editor,
+    inspect_custom_gui,
+    remove_property_metadata_attribute,
+    resolve_property_node,
+    semantic_attribute,
+    set_custom_editor,
+    set_property_metadata_attribute,
+    sync_compiled_property_metadata,
+)
+from .commands import CliError, _commit_text, _load
+
+
+def cmd_custom_gui(args) -> dict:
+    """Inspect or safely mutate ASE CustomEditor and ASECLI property metadata."""
+    if args.enabled_if is not None and args.enabled_if_value is None:
+        raise CliError("USAGE_ERROR", "--enabled-if requires --enabled-if-value")
+    if args.enabled_if is None and args.enabled_if_value is not None:
+        raise CliError("USAGE_ERROR", "--enabled-if-value requires --enabled-if")
+    if args.enabled_if is None and args.enabled_if_operator is not None:
+        raise CliError("USAGE_ERROR", "--enabled-if-operator requires --enabled-if")
+    f = _load(args.file)
+    changes = []
+    node_actions = any(
+        (
+            args.group is not None,
+            args.clear_group,
+            args.tooltip is not None,
+            args.clear_tooltip,
+            args.help_box is not None,
+            args.clear_help_box,
+            args.enabled_if is not None,
+            args.clear_enabled_if,
+            bool(args.add_attribute),
+            bool(args.remove_attribute),
+        )
+    )
+    single_mutation = node_actions or args.editor is not None or args.clear_editor
+    if args.spec and single_mutation:
+        raise CliError("USAGE_ERROR", "--spec cannot be combined with individual custom GUI mutation options")
+    if args.spec and (args.node is not None or args.property is not None):
+        raise CliError("USAGE_ERROR", "--spec cannot be combined with --node or --property")
+    if node_actions and args.node is None and args.property is None:
+        raise CliError("USAGE_ERROR", "--node or --property is required for ASECLI property metadata operations")
+
+    try:
+        initial_presentation = inspect_custom_gui(f)["property_presentation"]
+        if args.spec:
+            changes.extend(apply_material_gui_spec(f, _load_spec(args.spec)))
+        else:
+            if args.editor is not None:
+                changes.append(set_custom_editor(f, args.editor))
+            elif args.clear_editor:
+                changes.append(set_custom_editor(f, None))
+
+            target = None
+            if args.node is not None or args.property is not None:
+                target = resolve_property_node(
+                    f.graph, node_id=args.node, property_name=args.property
+                ).node_id
+
+            additions: list[str] = []
+            if args.group is not None:
+                additions.append(semantic_attribute("FoldoutMzgui", args.group))
+            if args.tooltip is not None:
+                additions.append(semantic_attribute("TooltipMzgui", args.tooltip))
+            if args.help_box is not None:
+                additions.append(semantic_attribute("HelpBoxMzgui", args.help_box))
+            if args.enabled_if is not None:
+                additions.append(
+                    enable_if_attribute(
+                        args.enabled_if,
+                        args.enabled_if_operator or "Equal",
+                        args.enabled_if_value,
+                    )
+                )
+            additions.extend(args.add_attribute or [])
+
+            if additions and graph_custom_editor(f.graph) not in SUPPORTED_GUI_EDITORS:
+                supported = ", ".join(sorted(SUPPORTED_GUI_EDITORS))
+                raise ValueError(
+                    "MZGUI-compatible property metadata requires a selected material GUI; "
+                    f"pass --editor with one of: {supported}"
+                )
+
+            removals = (
+                [(args.clear_group, "FoldoutMzgui"), (args.clear_tooltip, "TooltipMzgui"),
+                 (args.clear_help_box, "HelpBoxMzgui"),
+                 (args.clear_enabled_if, "EnableIfMzgui")]
+            )
+            for enabled, type_name in removals:
+                if enabled:
+                    changes.append(remove_property_metadata_attribute(f.graph, target, type_name))
+            for type_name in args.remove_attribute or []:
+                changes.append(remove_property_metadata_attribute(f.graph, target, type_name))
+            for raw in additions:
+                changes.append(set_property_metadata_attribute(f.graph, target, raw))
+
+        if changes and graph_custom_editor(f.graph) == ASECLI_GUI_EDITOR:
+            changes.insert(0, set_custom_editor(f, MZGUI_EDITOR))
+        if changes:
+            changes.extend(sync_compiled_property_metadata(f))
+        state = inspect_custom_gui(f)
+    except KeyError as exc:
+        raise CliError("NOT_FOUND", str(exc))
+    except ValueError as exc:
+        raise CliError("CUSTOM_GUI_ERROR", str(exc))
+
+    if not changes:
+        if args.write:
+            raise CliError("USAGE_ERROR", "--write requires a custom GUI mutation option")
+        return {"file": args.file, "action": "inspect", "state": state, "written": False}
+
+    contract_applies = initial_presentation["claimed"] or state["property_presentation"]["claimed"]
+    if args.write and contract_applies and not state["property_presentation"]["valid"]:
+        raise CliError(
+            "PROPERTY_PRESENTATION_ERROR",
+            "ASECLI-managed property presentation contract failed: "
+            + ", ".join(state["property_presentation"]["violations"]),
+            {"property_presentation": state["property_presentation"]},
+        )
+
+    issues = validate_file(f)
+    errors = [issue for issue in issues if issue["severity"] == "error"]
+    if errors:
+        raise CliError(
+            "VALIDATION_ERROR",
+            f"mutation would leave {len(errors)} structural error(s)",
+            {"issues": issues, "error_count": len(errors)},
+        )
+    output = fix_checksum(f.serialize())
+    if args.write:
+        _commit_text(args.file, output, f.source_digest)
+    return {
+        "file": args.file,
+        "action": "mutate",
+        "changes": changes,
+        "state": state,
+        "requires_recompile": bool(changes),
+        "written": bool(args.write),
+        "path": args.file if args.write else None,
+        "preview_bytes": len(output),
+        "checksum_recomputed": True,
+    }
+
+
+def _load_spec(path: str) -> dict:
+    try:
+        text = Path(path).read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise KeyError(f"spec file not found: {path}") from exc
+    except UnicodeDecodeError as exc:
+        raise ValueError(f"material GUI spec is not valid UTF-8: {path}") from exc
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"invalid material GUI spec JSON at line {exc.lineno}, column {exc.colno}") from exc

asecli/cli/gui_provider.py

@@ -0,0 +1,30 @@
+"""Choose the single material-GUI provider for an Editor create operation."""
+
+from pathlib import Path
+
+from ..bridge import MZGUI_EDITOR, install_gui_support
+
+
+def select_editor_provider(shader_path: str) -> tuple[str, dict | None]:
+    """Install the fallback only when the enclosing Unity project lacks MZGUI.
+
+    Projectless behavior exists solely for isolated bridge test doubles; a real
+    Editor create target must be inside a Unity project.
+    """
+    project_root = unity_project_root(Path(shader_path).resolve())
+    if project_root is None:
+        return MZGUI_EDITOR, None
+    support = install_gui_support(project_root, write=True)
+    editor = support.get("recommended_editor")
+    if not isinstance(editor, str):
+        raise RuntimeError("material GUI provider selection did not return an editor")
+    return editor, support
+
+
+def unity_project_root(path: Path) -> Path | None:
+    current = path.parent
+    while current != current.parent:
+        if (current / "Assets").is_dir() and (current / "ProjectSettings").is_dir():
+            return current
+        current = current.parent
+    return None

asecli/cli/gui_support_command.py

@@ -0,0 +1,35 @@
+"""CLI composition for the built-in ASECLI Unity material GUI."""
+
+from __future__ import annotations
+
+import os
+
+from ..bridge import (
+    McpError,
+    handoff_gui_support,
+    install_gui_support,
+    probe_native_mzgui_via_mcp,
+)
+from .commands import CliError
+
+
+def cmd_gui_support(args) -> dict:
+    if args.instance_token_argv is not None:
+        raise CliError("USAGE_ERROR", "do not pass MCP tokens via argv; use ASECLI_MCP_INSTANCE_TOKEN")
+    try:
+        runtime_probe = None
+        if args.runtime_probe:
+            runtime_probe = probe_native_mzgui_via_mcp(
+                args.project,
+                mcp_url=args.mcp_url,
+                instance_token=os.environ.get("ASECLI_MCP_INSTANCE_TOKEN"),
+                allow_remote_mcp=args.allow_remote_mcp,
+            )
+        operation = handoff_gui_support if args.handoff_native else install_gui_support
+        return operation(args.project, write=args.write, runtime_probe=runtime_probe)
+    except FileNotFoundError as exc:
+        raise CliError("NOT_FOUND", str(exc)) from exc
+    except McpError as exc:
+        raise CliError("BRIDGE_ERROR", str(exc), exc.data) from exc
+    except (FileExistsError, ValueError, RuntimeError, OSError) as exc:
+        raise CliError("GUI_SUPPORT_ERROR", str(exc)) from exc