unicad-kit 0.1.0__py3-none-any.whl

convert/Security/LexicalBoundary.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from os import PathLike as PathLikeValue
+from os.path import abspath as AbsolutePath
+from pathlib import Path as PathInfo
+
+
+# lexical containment blocks traversal before candidate paths reach filesystem operations
+def ResolveLexical(PathValue: str | PathLikeValue[str], RootPath: PathInfo) -> PathInfo:
+    CandidatePath = PathInfo(PathValue)
+    if not CandidatePath.is_absolute():
+        CandidatePath = RootPath / CandidatePath
+    LexicalPath = PathInfo(AbsolutePath(CandidatePath))
+    _ = LexicalPath.relative_to(RootPath)
+    return LexicalPath

convert/Security/PathBoundary.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from __future__ import annotations as Annotations
+
+from os import PathLike as PathLikeValue
+from pathlib import Path as PathInfo
+import tempfile as Tempfile
+
+from convert.Security.LexicalBoundary import ResolveLexical
+
+# command argument paths permit only inert characters after fixed root resolution
+KCommandPathCharacters = frozenset(" ._-/\\:")
+
+
+# unsafe filesystem selections need a distinct failure contract at trust boundaries
+class UnsafePath(ValueError):
+    __slots__ = ()
+
+
+# canonical containment prevents traversal and symlink escapes before protected filesystem operations
+def ResolveWithin(
+    PathValue: str | PathLikeValue[str],
+    RootValue: str | PathLikeValue[str],
+    RequireFile: bool = False,
+) -> PathInfo:
+    RootPath = PathInfo(RootValue).resolve(strict=True)
+    try:
+        CandidatePath = ResolveLexical(PathValue, RootPath)
+    except ValueError as ErrorInfo:
+        raise UnsafePath(f"path escapes trusted root {str(RootPath)!r}") from ErrorInfo
+    ResultPath = CandidatePath.resolve(strict=RequireFile)
+    try:
+        _ = ResultPath.relative_to(RootPath)
+    except ValueError as ErrorInfo:
+        raise UnsafePath(f"path escapes trusted root {str(RootPath)!r}") from ErrorInfo
+    if RequireFile and not ResultPath.is_file():
+        raise FileNotFoundError(ResultPath)
+    return ResultPath
+
+
+# local paths need one containment primitive before applying file type rules
+def ResolveLocal(PathValue: str | PathLikeValue[str]) -> PathInfo:
+    return ResolveWithin(PathValue, PathInfo.cwd())
+
+
+# tool inputs stay inside the operator selected working directory
+def ResolveInput(PathValue: str | PathLikeValue[str]) -> PathInfo:
+    return ResolveWithin(PathValue, PathInfo.cwd(), True)
+
+
+# subprocess file arguments need containment plus a command inert absolute spelling
+def ResolveArgPath(PathValue: str | PathLikeValue[str]) -> PathInfo:
+    ResultPath = ResolveInput(PathValue)
+    if any(
+        not CharText.isalnum() and CharText not in KCommandPathCharacters
+        for CharText in str(ResultPath)
+    ):
+        raise UnsafePath("command argument path contains unsafe characters")
+    return ResultPath
+
+
+# tool output paths stay inside the operator selected working directory
+def ResolveOutput(PathValue: str | PathLikeValue[str]) -> PathInfo:
+    return ResolveLocal(PathValue)
+
+
+# tool directory inputs stay inside the operator selected working directory
+def ResolveFolder(PathValue: str | PathLikeValue[str]) -> PathInfo:
+    ResultPath = ResolveWithin(PathValue, PathInfo.cwd())
+    if not ResultPath.is_dir():
+        raise NotADirectoryError(ResultPath)
+    return ResultPath
+
+
+# test artifacts stay inside the operating system managed temporary root
+def ResolveTemp(PathValue: str | PathLikeValue[str]) -> PathInfo:
+    return ResolveWithin(PathValue, Tempfile.gettempdir())
+
+
+# debugger labels enter command scripts so their character set must stay inert
+def ValidateLabel(LabelText: str) -> str:
+    IsSafe = 1 <= len(LabelText) <= 64 and all(
+        (CharText.isalnum() or CharText in "-_") for CharText in LabelText
+    )
+    if not IsSafe:
+        raise ValueError("debugger label contains unsafe command characters")
+    return LabelText

convert/Security/ProgramBoundary.py

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from __future__ import annotations as Annotations
+
+import os as OsLayer
+from pathlib import Path as PathInfo
+
+from convert.Security.PathBoundary import ResolveArgPath, ResolveWithin, UnsafePath
+
+# exact executable names prevent the oracle setting from selecting another program
+KFreecadNames = frozenset(("FreeCADCmd", "FreeCADCmd.exe", "freecadcmd"))
+
+# administrator controlled install roots keep executable selection outside writable worktrees
+KFreecadRoots = (
+    PathInfo("C:/Program Files"),
+    PathInfo("C:/Program Files (x86)"),
+    PathInfo("/Applications/FreeCAD.app/Contents/MacOS"),
+    PathInfo("/opt"),
+    PathInfo("/usr/bin"),
+    PathInfo("/usr/local/bin"),
+)
+
+
+# subprocess file arguments need a contained absolute path before list based execution
+def GetArgPath(PathValue: str | OsLayer.PathLike[str]) -> PathInfo:
+    return ResolveArgPath(PathValue)
+
+
+# oracle execution is optional but any configured program must cross a strict allowlist
+def GetFreecadPath() -> PathInfo:
+    RawText = OsLayer.environ.get("KIT_FREECAD_ORACLE", "").strip()
+    if not RawText:
+        return PathInfo()
+    Candidate = PathInfo(OsLayer.path.realpath(RawText))
+    if Candidate.name not in KFreecadNames:
+        raise UnsafePath("freecad oracle executable name is not allowed")
+    for RootPath in KFreecadRoots:
+        if not RootPath.is_dir():
+            continue
+        try:
+            return ResolveWithin(Candidate, RootPath, True)
+        except (FileNotFoundError, UnsafePath):
+            continue
+    raise UnsafePath("freecad oracle executable is outside trusted install roots")

convert/Security/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from convert.Security.PathBoundary import (
+    ResolveArgPath,
+    ResolveFolder,
+    ResolveInput,
+    ResolveLocal,
+    ResolveOutput,
+    ResolveTemp,
+    ResolveWithin,
+    UnsafePath,
+    ValidateLabel,
+)
+from convert.Security.ProgramBoundary import GetArgPath, GetFreecadPath
+
+# callers need one explicit public surface for repository security boundaries
+__all__ = [
+    "GetArgPath",
+    "GetFreecadPath",
+    "ResolveArgPath",
+    "ResolveFolder",
+    "ResolveInput",
+    "ResolveLocal",
+    "ResolveOutput",
+    "ResolveTemp",
+    "ResolveWithin",
+    "UnsafePath",
+    "ValidateLabel",
+]

convert/__init__.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from .api import (
+    available_adapters as AvailableAdapters,
+    convert as ConvertDoc,
+    extract_brep as ExtractBrep,
+    open_document as OpenDoc,
+    registry as RegistryValue,
+    write_document as WriteDoc,
+)
+from .adapters import ApplicationUsabilityError, CarrierReason
+
+# this binding preserves the documented public package export surface
+__all__ = [
+    "available_adapters",
+    "ApplicationUsabilityError",
+    "CarrierReason",
+    "convert",
+    "extract_brep",
+    "open_document",
+    "registry",
+    "write_document",
+]
+
+# this binding preserves the historical public adapter listing name
+available_adapters = AvailableAdapters
+
+# this binding preserves the historical public conversion name
+convert = ConvertDoc
+
+# this binding preserves the historical public boundary extraction name
+extract_brep = ExtractBrep
+
+# this binding preserves the historical public document reader name
+open_document = OpenDoc
+
+# this binding preserves the historical public registry name
+registry = RegistryValue
+
+# this binding preserves the historical public document writer name
+write_document = WriteDoc

convert/adapters/Fusion/Adapter.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+
+from convert.adapters.base.AdapterInfo import AdapterInfo
+from convert.adapters.base.ContractTypes import KSourceType
+from convert.adapters.base.ProbeResult import ProbeResult
+from convert.adapters.base.ReadOptions import ReadOptions
+from convert.adapters.Fusion.AdapterInfo import KReaderInfo
+from convert.adapters.Fusion.ArchiveProbe import ProbeFusion
+from convert.adapters.Fusion.ReaderOptions import GetFusionOpts
+from convert.adapters.Fusion.StreamRead import ReadSourceMut
+from convert.formats.Fusion.DocumentRead import ReadFusionDoc
+from interchange.document.models.DocumentFilter import FilterDocument
+from interchange.document.models.DocumentModel import CadDocument
+
+
+# the structural reader exposes the qualified projection through adapter discovery
+class FusionReader:
+
+    # the registry needs format metadata without opening a source document
+    @property
+    def Info(self) -> AdapterInfo:
+        return KReaderInfo
+
+    info = Info
+
+    # the reader can rank native archives without consuming stream content
+    def Probe(self, SourceData: KSourceType) -> ProbeResult:
+        return ProbeFusion(SourceData)
+
+    # public probe keywords match the registry reader protocol
+    def probe(self, source: KSourceType) -> ProbeResult:
+        return self.Probe(source)
+
+    # explicit options allow callers to select and filter one native history
+    def Read(
+        self, SourceData: KSourceType, Options: ReadOptions | None = None
+    ) -> CadDocument:
+        Settings = Options if Options is not None else ReadOptions()
+        HistoryId, Inflate = GetFusionOpts(Settings)
+        Document = ReadFusionDoc(
+            ReadSourceMut(SourceData),
+            HistoryId=HistoryId,
+            InflateZstd=Inflate,
+        )
+        return FilterDocument(
+            Document,
+            IncludeBrep=Settings.include_brep,
+            IncludeMesh=Settings.include_tessellation,
+        )
+
+    # public read keywords match the registry reader protocol
+    def read(
+        self, source: KSourceType, options: ReadOptions | None = None
+    ) -> CadDocument:
+        return self.Read(source, options)

convert/adapters/Fusion/AdapterInfo.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+
+from convert.adapters.base.AdapterInfo import AdapterInfo
+from interchange.enums.EnumDocument import Capability
+
+# registration advertises only categories represented in the partial native reader
+KReaderInfo = AdapterInfo(
+    format_id="fusion.f3d",
+    name="Autodesk Fusion",
+    version="1.0",
+    aliases=("f3d",),
+    extensions=(".f3d",),
+    part_extensions=(".f3d",),
+    assembly_extensions=(".f3d",),
+    capabilities=frozenset(
+        {
+            Capability.KParameters,
+            Capability.KSupportPlanes,
+            Capability.KSelections,
+            Capability.KBodyStructure,
+            Capability.KBrep,
+            Capability.KAssemblies,
+            Capability.KComponentDocs,
+            Capability.KNativePayloads,
+            Capability.KProvenance,
+        }
+    ),
+)

convert/adapters/Fusion/ArchiveProbe.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+
+from io import BytesIO
+from pathlib import Path as FilePath
+from struct import error as StructError
+from typing import BinaryIO, cast as CastType
+from zipfile import BadZipFile, ZipFile
+
+from convert.adapters.base.ContractTypes import KSourceType
+from convert.adapters.base.ProbeResult import ProbeResult
+from convert.adapters.Fusion.AdapterInfo import KReaderInfo
+from convert.formats.Fusion.ArchiveRead.ArchiveBounds import (
+    CheckZipTailMut,
+    KArchiveLimit,
+)
+from convert.adapters.staging.SourceReplay import ReplaySource
+from convert.formats.Fusion.DesignZip import KDesignPrefix
+from convert.formats.Fusion.ZipItems import IndexZipItems
+
+
+# discovery validates owned design names without inflating archive members
+def CheckDesignMut(Handle: BinaryIO) -> None:
+    StartOffset = Handle.tell()
+    try:
+        DeclaredCount = CheckZipTailMut(Handle, StartOffset)
+        with ZipFile(Handle) as Archive:
+            Entries = IndexZipItems(Archive.infolist())
+            if len(Entries) != DeclaredCount:
+                raise ValueError("Fusion ZIP central directory entry count disagrees")
+            CentralOffset = Archive.start_dir
+            if any(
+                not StartOffset <= Entry.header_offset < CentralOffset
+                for Entry in Entries.values()
+            ):
+                raise ValueError("Fusion ZIP member lies outside the source archive")
+            for NameValue in ("BulkStream.dat", "MetaStream.dat"):
+                Entry = Entries.get(KDesignPrefix + NameValue)
+                if Entry is None or Entry.is_dir():
+                    raise ValueError(f"Missing active Fusion design {NameValue}")
+    finally:
+        _ = Handle.seek(StartOffset)
+
+
+# stream probing only borrows sources that can restore the original position
+def ProbeFusion(SourceData: KSourceType) -> ProbeResult:
+    FormatId = KReaderInfo.format_id
+    try:
+        if isinstance(SourceData, (str, FilePath)):
+            with FilePath(SourceData).expanduser().open("rb") as Handle:
+                CheckDesignMut(Handle)
+        elif isinstance(SourceData, (bytes, bytearray)):
+            if len(SourceData) > KArchiveLimit:
+                raise ValueError("Fusion ZIP exceeds input size limit")
+            with BytesIO(SourceData) as Handle:
+                CheckDesignMut(Handle)
+        elif isinstance(SourceData, ReplaySource):
+            CheckDesignMut(CastType(BinaryIO, SourceData))
+        else:
+            raise ValueError("Fusion probing requires a seekable binary stream")
+    except (BadZipFile, OSError, StructError, TypeError, ValueError) as ErrorInfo:
+        return ProbeResult(FormatId, 0.0, str(ErrorInfo))
+    return ProbeResult(FormatId, 1.0, "Active Fusion design streams in ZIP archive")

convert/adapters/Fusion/ReaderOptions.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+
+from collections.abc import Callable, Mapping
+from typing import cast as CastValue
+
+from convert.adapters.base.ReadOptions import ReadOptions
+
+# source object identities occupy one unsigned field in the native history table
+KMaxHistoryId = (1 << 64) - 1
+
+
+# adapter options keep incomplete coverage and native history selection explicit
+def GetFusionOpts(
+    Options: ReadOptions,
+) -> tuple[int | None, Callable[[bytes, int], bytes] | None]:
+    if Options.strict is not False:
+        raise ValueError("Fusion F3D reading is partial. Pass strict=False to opt in.")
+    if not isinstance(CastValue(object, Options.values), Mapping):
+        raise TypeError("Fusion read option values must be a mapping")
+    ConfigId = None
+    ConfigText = CastValue(object, Options.configuration)
+    if ConfigText is not None:
+        if (
+            not isinstance(ConfigText, str)
+            or not 1 <= len(ConfigText) <= 20
+            or not ConfigText.isascii()
+            or not ConfigText.isdecimal()
+            or not 1 <= int(ConfigText) <= KMaxHistoryId
+        ):
+            raise ValueError(
+                "Fusion configuration must be a positive decimal native history ID"
+            )
+        ConfigId = int(ConfigText)
+    HistoryId = ConfigId
+    if "fusion.history_id" in Options.values:
+        NativeId = Options.values["fusion.history_id"]
+        if type(NativeId) is not int or not 1 <= NativeId <= KMaxHistoryId:
+            raise ValueError(
+                "fusion.history_id must be a positive integer native history ID"
+            )
+        HistoryId = NativeId
+    if ConfigId is not None and ConfigId != HistoryId:
+        raise ValueError("Fusion configuration and fusion.history_id disagree")
+    if "fusion.inflate_zstd" not in Options.values:
+        return HistoryId, None
+    Inflate = Options.values["fusion.inflate_zstd"]
+    if not callable(Inflate):
+        raise ValueError("fusion.inflate_zstd must be callable")
+    return HistoryId, CastValue(Callable[[bytes, int], bytes], Inflate)

convert/adapters/Fusion/StreamRead.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+
+from io import BytesIO
+from pathlib import Path as FilePath
+
+from convert.adapters.base.ContractTypes import KSourceType
+from convert.formats.Fusion.ArchiveRead.ArchiveBounds import KArchiveLimit
+
+
+# memory and stream sources share the parser bound while paths retain source identity
+def ReadSourceMut(SourceData: KSourceType) -> str | FilePath | bytes:
+    if isinstance(SourceData, (str, FilePath)):
+        return SourceData
+    if isinstance(SourceData, (bytes, bytearray)):
+        if len(SourceData) > KArchiveLimit:
+            raise ValueError("Fusion ZIP exceeds input size limit")
+        return bytes(SourceData)
+    Buffer = BytesIO()
+    while True:
+        Block = SourceData.read(min(65536, KArchiveLimit + 1 - Buffer.tell()))
+        if not isinstance(Block, bytes):
+            raise TypeError("Fusion F3D source must be a binary stream")
+        if not Block:
+            return Buffer.getvalue()
+        if len(Block) > KArchiveLimit - Buffer.tell():
+            raise ValueError("Fusion ZIP exceeds input size limit")
+        _ = Buffer.write(Block)

convert/adapters/Fusion/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+
+from convert.adapters.Fusion.Adapter import FusionReader
+
+# the package exposes its reader through one stable import
+__all__ = ("FusionReader",)

convert/adapters/__init__.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: Copyright (c) 2026 Parashell, Odin Glynn-Martin, Stephen Harcourt
+
+from .base import AdapterInfo
+from .base import CarrierReason
+from .base import CadAdapter
+from .base import CadReaderAdapter
+from .base import CadWriterAdapter
+from .base import CapabilityTransfer
+from .base import Destination
+from .base import ProbeResult
+from .base import ReadOptions
+from .base import Source
+from .base import TransferMode
+from .base import WriteOptions
+from .base import WriteResult
+from .base import is_windows_device_name as IsDeviceName
+from .registry import AdapterRegistry
+from .registry.RegistryBinding import AdapterBinding
+from .registry.RegistryErrors import AdapterDiscoveryError
+from .registry.RegistryErrors import AdapterNotFoundError
+from .registry.RegistryErrors import AdapterRegistryError
+from .registry.RegistryErrors import AmbiguousAdapterError
+from .registry.RegistryErrors import CapabilityLossError
+from .base.UsabilityError import ApplicationUsabilityError
+
+# legacy helper spelling remains available because payload validation imports this public name
+is_windows_device_name = IsDeviceName
+
+# package exports stay explicit so split implementation modules never leak into wildcard imports
+__all__ = (
+    "AdapterBinding",
+    "AdapterDiscoveryError",
+    "AdapterInfo",
+    "AdapterNotFoundError",
+    "AdapterRegistry",
+    "AdapterRegistryError",
+    "AmbiguousAdapterError",
+    "ApplicationUsabilityError",
+    "CadAdapter",
+    "CadReaderAdapter",
+    "CadWriterAdapter",
+    "CapabilityLossError",
+    "CapabilityTransfer",
+    "CarrierReason",
+    "Destination",
+    "ProbeResult",
+    "ReadOptions",
+    "Source",
+    "TransferMode",
+    "WriteOptions",
+    "WriteResult",
+    "is_windows_device_name",
+)
+
+del IsDeviceName
+
+for ModuleName in tuple(globals()):
+    if ModuleName not in __all__ and ModuleName not in {
+        "__builtins__",
+        "__all__",
+        "__cached__",
+        "__doc__",
+        "__file__",
+        "__loader__",
+        "__name__",
+        "__package__",
+        "__path__",
+        "__spec__",
+        "base",
+        "catia",
+        "freecad",
+        "json",
+        "registry",
+    }:
+        globals().pop(ModuleName, None)