asecli 0.6.2__py3-none-any.whl

asecli/bridge/_editor_spec_validation.py

@@ -0,0 +1,218 @@
+"""Validation implementation split from the public EditorGraphSpec model."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._editor_port_contract import validate_connections
+from ._editor_spec_grammar import (
+    GENERIC_NODE_TYPES,
+    OUTPUT_TYPES,
+    PROPERTY_NODE_TYPES,
+    PROPERTY_TYPES,
+    SUPPORTED_PRIMITIVES_VERSIONS,
+    _ALIAS,
+    _CSHARP_MARKERS,
+    _COMMON_NODE_KEYS,
+    _GUID,
+    _IDENTIFIER,
+    _NODE_KEYS_V1,
+    _NODE_KEYS_V2,
+    _NODE_KEYS_V3,
+    _PROPERTY_NAME,
+    _ROOT_KEYS,
+    _TEMPLATE_KEYS,
+    object_dict,
+    parse_input,
+    parse_precision,
+    parse_primitive,
+    parse_property_semantics,
+    parse_recipe,
+    position,
+    reject_unknown,
+    require_string,
+    safe_text,
+)
+from .editor_spec import (
+    ConnectionSpec,
+    EditorGraphSpec,
+    EndpointSpec,
+    InputSpec,
+    NodeSpec,
+    SpecError,
+    TemplateSpec,
+)
+from ..core import contains_han, validate_enable_if
+
+
+def parse_editor_graph_spec(value: Any) -> EditorGraphSpec:
+    root = object_dict(value, "spec")
+    reject_unknown(root, _ROOT_KEYS, "spec")
+    version = root.get("version")
+    if version not in {1, 2, 3}:
+        raise SpecError("spec version must be integer 1, 2, or 3")
+    primitives_version = None
+    if version == 3:
+        primitives_version = root.get("primitives_version")
+        if isinstance(primitives_version, bool) or not isinstance(primitives_version, int):
+            raise SpecError("spec primitives_version must be an integer")
+        if primitives_version not in SUPPORTED_PRIMITIVES_VERSIONS:
+            raise SpecError(f"spec primitives_version {primitives_version} is not supported")
+    else:
+        if "primitives_version" in root:
+            raise SpecError("spec primitives_version is only valid for version 3")
+    template = _parse_template(root.get("template"))
+    raw_nodes = root.get("nodes")
+    if not isinstance(raw_nodes, list):
+        raise SpecError("spec nodes must be an array")
+    if len(raw_nodes) > 128:
+        raise SpecError("spec nodes exceeds the v1 limit of 128")
+    nodes = tuple(_parse_node(item, index, version) for index, item in enumerate(raw_nodes))
+    aliases = {node.alias for node in nodes}
+    if len(aliases) != len(nodes):
+        raise SpecError("node alias must be unique")
+    property_names = [node.property_name for node in nodes if node.property_name is not None]
+    if len(set(property_names)) != len(property_names):
+        raise SpecError("property_name must be unique across property and sampler nodes")
+    raw_connections = root.get("connections", [])
+    if not isinstance(raw_connections, list):
+        raise SpecError("spec connections must be an array")
+    if len(raw_connections) > 256:
+        raise SpecError("spec connections exceeds the v1 limit of 256")
+    connections = tuple(_parse_connection(item, index, aliases) for index, item in enumerate(raw_connections))
+    if len({(item.destination.node, item.destination.port) for item in connections}) != len(connections):
+        raise SpecError("a destination input port may appear only once")
+    validate_connections(template, nodes, connections)
+    return EditorGraphSpec(
+        version=version, template=template, nodes=nodes, connections=connections,
+        primitives_version=primitives_version,
+    )
+
+
+def _parse_template(value: Any) -> TemplateSpec:
+    obj = object_dict(value, "template")
+    reject_unknown(obj, _TEMPLATE_KEYS, "template")
+    guid = require_string(obj.get("guid"), "template guid", 32)
+    if not _GUID.fullmatch(guid):
+        raise SpecError("template guid must be exactly 32 hexadecimal characters")
+    shader_name = safe_text(obj.get("shader_name"), "template shader_name", 255, False)
+    if any(char in shader_name for char in ('"', "'", ";", "\\")):
+        raise SpecError("template shader_name contains a forbidden quote, separator, or escape")
+    return TemplateSpec(guid=guid.lower(), shader_name=shader_name)
+
+
+def _parse_node(value: Any, index: int, version: int) -> NodeSpec:
+    label = f"nodes[{index}]"
+    obj = object_dict(value, label)
+    kind = obj.get("kind")
+    if version == 3:
+        node_keys = _NODE_KEYS_V3
+    elif version == 2:
+        node_keys = _NODE_KEYS_V2
+    else:
+        node_keys = _NODE_KEYS_V1
+    if kind not in node_keys:
+        raise SpecError(f"{label} has unknown kind {kind!r}")
+    reject_unknown(obj, node_keys[kind], label)
+    alias = require_string(obj.get("alias"), f"{label} alias", 64)
+    if not _ALIAS.fullmatch(alias):
+        raise SpecError(f"{label} alias must match {_ALIAS.pattern}")
+    if alias == "master":
+        raise SpecError(f"{label} alias 'master' is reserved")
+    node_position = position(obj.get("position"), f"{label} position")
+    precision = parse_precision(obj, label)
+    if kind == "node":
+        node_type = require_string(obj.get("type"), f"{label} type", 64)
+        if node_type not in GENERIC_NODE_TYPES:
+            raise SpecError(f"{label} type is not in the generic-node allowlist")
+        return NodeSpec(alias, kind, node_position, type=node_type, precision=precision)
+    if kind in {"property", "sampler"}:
+        return _parse_property_node(obj, label, alias, kind, node_position, version, precision)
+    if kind == "primitive":
+        return parse_primitive(obj, label, alias, node_position)
+    if kind == "recipe":
+        return parse_recipe(obj, label, alias, node_position)
+    name = safe_text(obj.get("name"), f"{label} name", 128, False)
+    code = safe_text(obj.get("code"), f"{label} code", 65535, True)
+    if any(char in code for char in ("@", "$")) or _CSHARP_MARKERS.search(code):
+        raise SpecError(f"{label} code contains an ASE delimiter or forbidden C# runtime marker")
+    output_type = obj.get("output_type")
+    if output_type not in OUTPUT_TYPES:
+        raise SpecError(f"{label} output_type must be one of {sorted(OUTPUT_TYPES)}")
+    raw_inputs = obj.get("inputs")
+    if not isinstance(raw_inputs, list) or not raw_inputs or len(raw_inputs) > 32:
+        raise SpecError(f"{label} inputs must contain 1 through 32 entries")
+    inputs = tuple(parse_input(item, label, i) for i, item in enumerate(raw_inputs))
+    if len({item.name for item in inputs}) != len(inputs):
+        raise SpecError(f"{label} input name must be unique")
+    return NodeSpec(alias, kind, node_position, name=name, code=code, output_type=output_type, inputs=inputs)
+
+
+def _parse_property_node(
+    obj: dict,
+    label: str,
+    alias: str,
+    kind: str,
+    node_position: tuple[float, float],
+    version: int,
+    precision: str | None,
+) -> NodeSpec:
+    node_type = "SamplerNode" if kind == "sampler" else require_string(obj.get("type"), f"{label} type", 64)
+    allowed = {"SamplerNode"} if kind == "sampler" else PROPERTY_NODE_TYPES
+    if node_type not in allowed:
+        raise SpecError(f"{label} type is not in the property-node allowlist")
+    property_name = require_string(obj.get("property_name"), f"{label} property_name", 127)
+    if not _PROPERTY_NAME.fullmatch(property_name):
+        raise SpecError(f"{label} property_name must be an underscored identifier")
+    inspector_name = safe_text(obj.get("inspector_name"), f"{label} inspector_name", 128, False)
+    tooltip_text = None
+    help_text = None
+    enabled_if = None
+    if version >= 2:
+        if not contains_han(inspector_name):
+            raise SpecError(f"{label} inspector_name must contain Chinese characters")
+        if "tooltip" in obj:
+            tooltip_text = safe_text(obj.get("tooltip"), f"{label} tooltip", 4096, True)
+            if "help" in obj:
+                help_text = safe_text(obj.get("help"), f"{label} help", 4096, True)
+        else:
+            tooltip_text = safe_text(obj.get("help"), f"{label} tooltip", 4096, True)
+        if not contains_han(tooltip_text):
+            raise SpecError(f"{label} tooltip must contain Chinese characters")
+        if "enabled_if" in obj:
+            try:
+                enabled_if = validate_enable_if(obj["enabled_if"])
+            except ValueError as exc:
+                raise SpecError(f"{label} {exc}") from exc
+    parameter_type = obj.get("parameter_type")
+    if parameter_type not in PROPERTY_TYPES:
+        raise SpecError(f"{label} parameter_type must be one of {sorted(PROPERTY_TYPES)}")
+    default, minimum, maximum = parse_property_semantics(obj, label, kind, node_type)
+    return NodeSpec(alias, kind, node_position, type=None if kind == "sampler" else node_type,
+                    property_name=property_name, inspector_name=inspector_name,
+                    tooltip=tooltip_text, help=help_text, enabled_if=enabled_if,
+                    parameter_type=parameter_type, precision=precision,
+                    default=default, min=minimum, max=maximum)
+
+
+def _parse_connection(value: Any, index: int, aliases: set[str]) -> ConnectionSpec:
+    label = f"connections[{index}]"
+    obj = object_dict(value, label)
+    reject_unknown(obj, frozenset({"from", "to"}), label)
+    source = _parse_endpoint(obj.get("from"), f"{label}.from", aliases)
+    destination = _parse_endpoint(obj.get("to"), f"{label}.to", aliases)
+    if source.node == "master":
+        raise SpecError(f"{label} cannot use master as a source")
+    return ConnectionSpec(source=source, destination=destination)
+
+
+def _parse_endpoint(value: Any, label: str, aliases: set[str]) -> EndpointSpec:
+    obj = object_dict(value, label)
+    reject_unknown(obj, frozenset({"node", "port"}), label)
+    node = require_string(obj.get("node"), f"{label} node", 64)
+    if node != "master" and node not in aliases:
+        raise SpecError(f"{label} references unknown node alias {node!r}")
+    port = obj.get("port")
+    if isinstance(port, bool) or not isinstance(port, int) or not 0 <= port <= 63:
+        raise SpecError(f"{label} port must be an integer from 0 through 63")
+    return EndpointSpec(node=node, port=port)

asecli/bridge/_gui_handoff_store.py

@@ -0,0 +1,78 @@
+"""Descriptor-scoped reversible disable/restore for a known GUI fallback."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+
+from ._gui_project import UnityProject
+from ._gui_resource_store import (
+    close_descriptors,
+    open_support_directory,
+    read_regular_resource,
+    require_secure_directory_operations,
+)
+
+
+def handoff_backup_path(target: Path, digest: str) -> Path:
+    return target.with_name(f"{target.name}.asecli-handoff-{digest[:12]}.disabled")
+
+
+def disable_known_fallback(
+    project: UnityProject, expected_digest: str, known_digests: set[str]
+) -> Path:
+    if expected_digest not in known_digests:
+        raise FileExistsError("fallback digest is not eligible for native handoff")
+    return _rename_verified(project, project.target, handoff_backup_path(project.target, expected_digest), expected_digest)
+
+
+def restore_known_fallback(
+    project: UnityProject, backup: Path, expected_digest: str, known_digests: set[str]
+) -> Path:
+    if expected_digest not in known_digests:
+        raise FileExistsError("fallback digest is not eligible for handoff restore")
+    return _rename_verified(project, backup, project.target, expected_digest)
+
+
+def remove_known_resource(project: UnityProject, target: Path, expected_digest: str) -> None:
+    require_secure_directory_operations()
+    descriptors = open_support_directory(project)
+    parent = descriptors[-1]
+    try:
+        content, opened = read_regular_resource(parent, target.name)
+        if hashlib.sha256(content).hexdigest() != expected_digest:
+            raise FileExistsError(f"GUI handoff resource changed; refusing to remove: {target}")
+        current = os.stat(target.name, dir_fd=parent, follow_symlinks=False)
+        if (current.st_dev, current.st_ino) != (opened.st_dev, opened.st_ino):
+            raise FileExistsError(f"GUI handoff resource changed; refusing to remove: {target}")
+        os.unlink(target.name, dir_fd=parent)
+        os.fsync(parent)
+    finally:
+        close_descriptors(descriptors)
+
+
+def _rename_verified(
+    project: UnityProject, source: Path, destination: Path, expected_digest: str
+) -> Path:
+    require_secure_directory_operations()
+    descriptors = open_support_directory(project)
+    parent = descriptors[-1]
+    try:
+        content, opened = read_regular_resource(parent, source.name)
+        if hashlib.sha256(content).hexdigest() != expected_digest:
+            raise FileExistsError(f"GUI handoff source changed; refusing to move: {source}")
+        try:
+            os.stat(destination.name, dir_fd=parent, follow_symlinks=False)
+        except FileNotFoundError:
+            pass
+        else:
+            raise FileExistsError(f"GUI handoff destination already exists: {destination}")
+        current = os.stat(source.name, dir_fd=parent, follow_symlinks=False)
+        if (current.st_dev, current.st_ino) != (opened.st_dev, opened.st_ino):
+            raise FileExistsError(f"GUI handoff source changed; refusing to move: {source}")
+        os.rename(source.name, destination.name, src_dir_fd=parent, dst_dir_fd=parent)
+        os.fsync(parent)
+        return destination
+    finally:
+        close_descriptors(descriptors)

asecli/bridge/_gui_project.py

@@ -0,0 +1,35 @@
+"""Validated Unity project paths used by GUI support operations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class UnityProject:
+    root: Path
+    assets: Path
+    target: Path
+
+
+def unity_project(project_root: str | Path, asset_path: str) -> UnityProject:
+    root = Path(project_root).expanduser().resolve()
+    if not root.is_dir():
+        raise FileNotFoundError(f"Unity project root not found: {root}")
+    assets = root / "Assets"
+    settings = root / "ProjectSettings"
+    if not assets.is_dir() or not settings.is_dir():
+        raise ValueError("project root must contain Assets and ProjectSettings directories")
+    _assert_inside_project(assets, root)
+    target = root / asset_path
+    _assert_inside_project(target, root)
+    return UnityProject(root=root, assets=assets, target=target)
+
+
+def _assert_inside_project(path: Path, project_root: Path) -> None:
+    resolved = path.resolve(strict=False)
+    try:
+        resolved.relative_to(project_root)
+    except ValueError as exc:
+        raise ValueError(f"project path escapes through a symbolic link: {path}") from exc

asecli/bridge/_gui_resource_store.py

@@ -0,0 +1,159 @@
+"""Descriptor-scoped file operations for the installed GUI resource."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import stat
+
+from ._gui_project import UnityProject
+
+
+SECURE_DIRECTORY_OPERATIONS_AVAILABLE = (
+    os.open in os.supports_dir_fd
+    and os.mkdir in os.supports_dir_fd
+    and hasattr(os, "O_NOFOLLOW")
+)
+
+
+def install_gui_resource(project: UnityProject, source: bytes) -> None:
+    """Create the resource through verified directory descriptors only."""
+    require_secure_directory_operations()
+    descriptors: list[int] = []
+    try:
+        root_descriptor = open_directory(project.root)
+        descriptors.append(root_descriptor)
+        assets_descriptor = open_directory_at(root_descriptor, "Assets")
+        descriptors.append(assets_descriptor)
+        editor_descriptor = open_or_create_directory(assets_descriptor, "Editor")
+        descriptors.append(editor_descriptor)
+        support_descriptor = open_or_create_directory(editor_descriptor, "ASECLI")
+        descriptors.append(support_descriptor)
+        create_resource(support_descriptor, project.target, source)
+        os.fsync(support_descriptor)
+    finally:
+        close_descriptors(descriptors)
+
+
+def open_support_directory(project: UnityProject) -> list[int]:
+    descriptors = [open_directory(project.root)]
+    try:
+        descriptors.append(open_directory_at(descriptors[-1], "Assets"))
+        descriptors.append(open_directory_at(descriptors[-1], "Editor"))
+        descriptors.append(open_directory_at(descriptors[-1], "ASECLI"))
+        return descriptors
+    except BaseException:
+        close_descriptors(descriptors)
+        raise
+
+
+def close_descriptors(descriptors: list[int]) -> None:
+    for descriptor in reversed(descriptors):
+        os.close(descriptor)
+
+
+def read_regular_resource(parent_descriptor: int, name: str) -> tuple[bytes, os.stat_result]:
+    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | os.O_NOFOLLOW
+    descriptor = os.open(name, flags, dir_fd=parent_descriptor)
+    opened_stat = os.fstat(descriptor)
+    if not stat.S_ISREG(opened_stat.st_mode):
+        os.close(descriptor)
+        raise FileExistsError(f"ASECLI GUI support path is not a regular file: {name}")
+    with os.fdopen(descriptor, "rb") as handle:
+        return handle.read(), opened_stat
+
+
+def create_exclusive_resource(
+    parent_descriptor: int, name: str, content: bytes, mode: int
+) -> os.stat_result:
+    flags = (
+        os.O_WRONLY
+        | os.O_CREAT
+        | os.O_EXCL
+        | getattr(os, "O_CLOEXEC", 0)
+        | os.O_NOFOLLOW
+    )
+    descriptor = os.open(name, flags, mode, dir_fd=parent_descriptor)
+    opened_stat = os.fstat(descriptor)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+    except BaseException:
+        unlink_created_resource(parent_descriptor, name, opened_stat)
+        raise
+    return opened_stat
+
+
+def create_resource(parent_descriptor: int, target: Path, source: bytes) -> None:
+    try:
+        create_exclusive_resource(parent_descriptor, target.name, source, 0o644)
+    except FileExistsError as exc:
+        raise FileExistsError(
+            f"ASECLI GUI support target appeared during installation; refusing to overwrite: {target}"
+        ) from exc
+    except FileNotFoundError as exc:
+        raise RuntimeError(
+            f"ASECLI GUI support directory changed during installation; refusing to write: {target}"
+        ) from exc
+
+
+def unlink_created_resource(
+    parent_descriptor: int, name: str, opened_stat: os.stat_result
+) -> None:
+    try:
+        current_stat = os.stat(name, dir_fd=parent_descriptor, follow_symlinks=False)
+        if (current_stat.st_dev, current_stat.st_ino) == (
+            opened_stat.st_dev,
+            opened_stat.st_ino,
+        ):
+            os.unlink(name, dir_fd=parent_descriptor)
+    except FileNotFoundError:
+        pass
+
+
+def require_secure_directory_operations() -> None:
+    if not SECURE_DIRECTORY_OPERATIONS_AVAILABLE:
+        raise RuntimeError(
+            "secure ASECLI GUI installation requires dir_fd and O_NOFOLLOW support on this platform"
+        )
+
+
+def open_directory(path: Path) -> int:
+    descriptor = os.open(path, _directory_flags())
+    _require_directory(descriptor, path)
+    return descriptor
+
+
+def open_directory_at(parent_descriptor: int, name: str) -> int:
+    descriptor = os.open(name, _directory_flags(), dir_fd=parent_descriptor)
+    _require_directory(descriptor, Path(name))
+    return descriptor
+
+
+def open_or_create_directory(parent_descriptor: int, name: str) -> int:
+    try:
+        return open_directory_at(parent_descriptor, name)
+    except FileNotFoundError:
+        try:
+            os.mkdir(name, mode=0o755, dir_fd=parent_descriptor)
+        except FileExistsError:
+            pass
+        return open_directory_at(parent_descriptor, name)
+
+
+def _directory_flags() -> int:
+    return (
+        os.O_RDONLY
+        | getattr(os, "O_DIRECTORY", 0)
+        | getattr(os, "O_CLOEXEC", 0)
+        | os.O_NOFOLLOW
+    )
+
+
+def _require_directory(descriptor: int, path: Path) -> None:
+    if stat.S_ISDIR(os.fstat(descriptor).st_mode):
+        return
+    os.close(descriptor)
+    raise NotADirectoryError(f"ASECLI GUI support directory is not a directory: {path}")

asecli/bridge/_gui_resource_upgrade.py

@@ -0,0 +1,122 @@
+"""Recoverable atomic upgrade for known ASECLI GUI resource revisions."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+import stat
+
+from ._gui_project import UnityProject
+from ._gui_resource_store import (
+    close_descriptors,
+    create_exclusive_resource,
+    open_support_directory,
+    read_regular_resource,
+    require_secure_directory_operations,
+    unlink_created_resource,
+)
+
+
+def upgrade_backup_path(
+    target: Path, digest: str | None, known_previous: dict[str, str]
+) -> Path | None:
+    if digest not in known_previous:
+        return None
+    return target.with_name(f"{target.name}.asecli-backup-{digest[:12]}")
+
+
+def upgrade_gui_resource(
+    project: UnityProject,
+    source: bytes,
+    expected_digest: str | None,
+    known_previous: dict[str, str],
+) -> Path:
+    """Back up one known resource, revalidate it, then atomically replace it."""
+    if expected_digest not in known_previous:
+        raise FileExistsError(
+            f"ASECLI GUI support target is not a known upgrade source: {project.target}"
+        )
+    require_secure_directory_operations()
+    descriptors = open_support_directory(project)
+    parent_descriptor = descriptors[-1]
+    temporary_name = project.target.name + ".asecli-upgrade.tmp"
+    temporary_stat: os.stat_result | None = None
+    try:
+        original, original_stat = read_regular_resource(
+            parent_descriptor, project.target.name
+        )
+        _require_digest(project.target, original, expected_digest)
+        backup_path = upgrade_backup_path(
+            project.target, expected_digest, known_previous
+        )
+        assert backup_path is not None
+        _create_or_verify_backup(
+            parent_descriptor,
+            backup_path.name,
+            original,
+            original_stat,
+            expected_digest,
+        )
+        os.fsync(parent_descriptor)
+        try:
+            temporary_stat = create_exclusive_resource(
+                parent_descriptor,
+                temporary_name,
+                source,
+                stat.S_IMODE(original_stat.st_mode),
+            )
+        except FileExistsError as exc:
+            raise FileExistsError(
+                f"ASECLI GUI support upgrade temporary already exists; refusing to overwrite: {temporary_name}"
+            ) from exc
+        current, current_stat = read_regular_resource(
+            parent_descriptor, project.target.name
+        )
+        _require_digest(project.target, current, expected_digest)
+        if (current_stat.st_dev, current_stat.st_ino) != (
+            original_stat.st_dev,
+            original_stat.st_ino,
+        ):
+            raise FileExistsError(
+                f"ASECLI GUI support target changed during upgrade; refusing to overwrite: {project.target}"
+            )
+        os.replace(
+            temporary_name,
+            project.target.name,
+            src_dir_fd=parent_descriptor,
+            dst_dir_fd=parent_descriptor,
+        )
+        temporary_stat = None
+        os.fsync(parent_descriptor)
+        return backup_path
+    finally:
+        if temporary_stat is not None:
+            unlink_created_resource(parent_descriptor, temporary_name, temporary_stat)
+        close_descriptors(descriptors)
+
+
+def _require_digest(target: Path, content: bytes, expected_digest: str) -> None:
+    if hashlib.sha256(content).hexdigest() != expected_digest:
+        raise FileExistsError(
+            f"ASECLI GUI support target changed during upgrade; refusing to overwrite: {target}"
+        )
+
+
+def _create_or_verify_backup(
+    parent_descriptor: int,
+    name: str,
+    content: bytes,
+    source_stat: os.stat_result,
+    expected_digest: str,
+) -> None:
+    try:
+        create_exclusive_resource(
+            parent_descriptor, name, content, stat.S_IMODE(source_stat.st_mode)
+        )
+    except FileExistsError:
+        existing, _ = read_regular_resource(parent_descriptor, name)
+        if hashlib.sha256(existing).hexdigest() != expected_digest:
+            raise FileExistsError(
+                f"ASECLI GUI support backup already exists with different content: {name}"
+            )