diff --git a/backend/snapstudio_api/routes_creative.py b/backend/snapstudio_api/routes_creative.py index 35ca7fb4..f1ca2fa2 100644 --- a/backend/snapstudio_api/routes_creative.py +++ b/backend/snapstudio_api/routes_creative.py @@ -1,22 +1,25 @@ -"""Routes of the Creative track: inspect one local creative project (3MF) and say what Studio read. +"""Routes of the Creative track: inspect a local creative project (3MF), list the supported formats, +and write a prepared copy with a verification of what the copy kept. - POST /creative/inspect {path, format?} -> {origin, understood, passed_through, could_not_interpret, - missing, diagnostics, recipes, source, evidence, advisory} + POST /creative/inspect {path, format?} -> what Studio read (origin, facts, kept, not understood) + POST /creative/formats {} -> SUPPORTED_FORMATS: what each format reads and does not + POST /creative/prepare {path, format?, out_dir?} -> a NEW prepared file, member-by-member comparison with + the original, and a re-hash of the original -The handler opens the file for reading only. It never writes, renames or deletes anything, never -slices, never contacts a printer and makes no network request of its own (the local-path check is -best-effort, see snapstudio_core/localpath.py). `source` carries the SHA-256 of the -file before the readers ran and again afterwards, so the response itself shows the original is -unchanged. Recipes are simulated: `execution_supported` is False and nothing here runs them. An -unrecognised generator is reported as origin "unknown", never guessed. +Inspect opens the file for reading only. Prepare calls the existing Prepare service, which writes one new +file, never over or in place of the original, into `out_dir` (a local directory) or, when none is given, +into the `creative-prepared` folder of Studio's own data directory. Nothing slices, nothing contacts a +printer, and this module makes no network request of its own (the local-path check is best-effort, see +snapstudio_core/localpath.py). Recipes are simulated: `execution_supported` is False. An unrecognised or +ambiguous generator is reported as such and is never guessed, and Prepare refuses it with an explanation. """ from __future__ import annotations import hashlib import os -from snapstudio_core import localpath -from snapstudio_core.creative import container, readers +from snapstudio_core import localpath, paths +from snapstudio_core.creative import container, formats, generators, readers from . import ext_routes from . import request_validation as rv @@ -24,20 +27,35 @@ #: Same ceiling the 3MF reader enforces; a larger file is refused before it is read. MAX_FILE_BYTES = container.MAX_ARCHIVE_BYTES MAX_PATH_CHARS = 1024 +#: Longest list of names put into one comparison answer. +MAX_LISTED = 200 EVIDENCE = "fixture-tested; fixtures are hand-written to published shapes, not captures" ADVISORY = ("Advisory read of one project file. Studio does not slice, does not run recipes and " "does not change the file. What it could not interpret is listed, not guessed.") +PREPARE_ADVISORY = ("Advisory comparison by part name and content hash. A prepared copy is a new file; it is " + "checked here only for what it kept, changed, dropped and added, not for how it slices " + "or prints. Review it in Snapmaker Orca before slicing.") -#: format hint -> reader. "auto" picks by the keys the project settings contain. +#: format hint -> reader. "auto" picks by the markers or keys the project contains. _READERS = { + "ditherforge": generators.read_ditherforge, + "kromacut": generators.read_kromacut, + "sindricad": generators.read_sindricad, "forcaslicer": readers.read_forca, "lixnix": readers.read_lixnix, "fullspectrum": readers.read_fullspectrum, "imagemap": readers.read_imagemap, "lumina": readers.read_lumina, } -_FORMATS = ("auto",) + tuple(_READERS) +_FORMATS = ("auto",) + formats.KEYS +#: Key-identified formats: a chosen format whose published keys are all absent is the wrong shape. +_KEY_FORMATS = { + "forcaslicer": readers._FORCA_KEYS, + "lixnix": readers._LIX_KEYS, + "fullspectrum": readers._FULLSPECTRUM_KEYS, +} +_FORMAT_BY_KEY = {f["key"]: f for f in formats.SUPPORTED_FORMATS} _ERROR_TEXT = { "bad_zip": "That file is not a readable 3MF archive.", @@ -90,10 +108,10 @@ def _read_source(path: str) -> bytes: return blob -def _detect(settings: dict) -> list[str]: - """Formats whose published keys are present. Several can match; none means unknown.""" - keys = set(settings) - found = [] +def _detect(manifest: container.ThreeMFManifest) -> list[str]: + """Formats whose published keys or markers are present. Several can match; none means unknown.""" + keys = set(manifest.project_settings or {}) + found = list(generators.detect(manifest)) if keys & readers._FORCA_KEYS: found.append("forcaslicer") if keys & readers._LIX_KEYS: @@ -108,10 +126,47 @@ def _wrap(exc: container.ContainerError) -> rv.ValidationError: return rv.ValidationError(_ERROR_TEXT.get(code, "That file could not be read as a 3MF project.")) -@ext_routes.route("/creative/inspect") -def inspect(data: dict) -> tuple[int, dict]: - path = _path(data) - hint = _format(data) +def _seen_sentence(manifest: container.ThreeMFManifest) -> str: + app = "" + try: + app = generators._model_metadata(generators._xml(manifest.model_xml)).get("Application", "") + except container.ContainerError: + pass + keys = len(manifest.project_settings or {}) + text = f"a 3MF project with {len(manifest.members)} parts and {keys} project settings keys" + return text + (f", Application tag `{app[:60]}`" if app else ", no Application tag") + + +def _wrong_shape_message(key: str, manifest: container.ThreeMFManifest, expected: list[str]) -> str: + label = formats.LABELS[key] + return (f"That file does not carry what Studio reads for {label}. Studio looks for: " + f"{'; '.join(expected)}. This file is {_seen_sentence(manifest)}. " + "What to do: choose Detect from markers and settings, pick the format of the tool that wrote the file, " + "or open it in that tool. Studio does not guess a format.") + + +def _explain(origin: dict, manifest: container.ThreeMFManifest) -> dict | None: + """Plain explanation for an origin Studio could not decide: what was seen, what is not supported, what to do.""" + seen = _seen_sentence(manifest) + if origin["status"] == "unknown": + return {"kind": "unknown_origin", "seen": f"This file is {seen}.", + "not_supported": "None of the supported tools' markers or settings keys were found, so Studio " + "does not say which tool wrote it and does not read it as one of them.", + "what_to_do": ["If you know which tool wrote the file, choose its format from the list and inspect again. " + "Choosing a manual-only format (ImageMap or Lumina) prepares the file as a generic 3MF " + "with no shape check.", + "Otherwise the file is still listed part by part below, untouched."]} + if origin["status"] == "ambiguous": + names = " and ".join(formats.LABELS.get(c, c) for c in origin["candidates"]) + return {"kind": "ambiguous_origin", "seen": f"This file is {seen}.", + "not_supported": f"Markers of more than one tool are present ({names}), so Studio does not decide " + "which one wrote it.", + "what_to_do": ["Choose the format you know it came from and inspect again."]} + return None + + +def _inspect(path: str, hint: str): + """Shared by inspect and prepare. Returns (body, blob, manifest). Reads only.""" blob = _read_source(path) before = hashlib.sha256(blob).hexdigest() try: @@ -120,13 +175,17 @@ def inspect(data: dict) -> tuple[int, dict]: raise _wrap(exc) from None settings = manifest.project_settings or {} - names = [hint] if hint != "auto" else _detect(settings) + if hint in _KEY_FORMATS and not (set(settings) & _KEY_FORMATS[hint]): + raise rv.ValidationError(_wrong_shape_message(hint, manifest, list(_FORMAT_BY_KEY[hint]["identified_by"]))) + names = [hint] if hint != "auto" else _detect(manifest) projects = [] try: for name in names: projects.append(_READERS[name](blob)) except container.ContainerError as exc: raise _wrap(exc) from None + except generators.WrongShape as exc: + raise rv.ValidationError(_wrong_shape_message(exc.generator, manifest, exc.expected)) from None if not projects: # Unknown generator: container identity only. Every part is preserved, nothing is interpreted. @@ -139,6 +198,7 @@ def inspect(data: dict) -> tuple[int, dict]: diagnostics = ["generator_not_recognized"] recipes: list = [] slots = None + facts: dict = {} else: status = "detected" if len(projects) == 1 else "ambiguous" origin = {"generator": projects[0].source_format if len(projects) == 1 else "unknown", @@ -160,21 +220,216 @@ def inspect(data: dict) -> tuple[int, dict]: diagnostics = [d for p in projects for d in p.diagnostics] recipes = [r.to_dict() for p in projects for r in p.recipes] slots = next((p.physical_slots_needed for p in projects if p.recipes), None) + facts = {p.source_format: p.understood for p in projects if p.source_format in generators.GENERATORS} after = _read_source(path) after_hash = hashlib.sha256(after).hexdigest() - return 200, { + candidates = origin["candidates"] if origin["status"] != "unknown" else [] + body = { "origin": origin, "understood": list(understood), + "facts": facts, "passed_through": passed, "could_not_interpret": list(unknown), "missing": list(missing), "diagnostics": list(diagnostics), "recipes": recipes, "physical_slots_needed": slots, - "source": {"name": os.path.basename(path), "size_bytes": len(blob), - "sha256_before": before, "sha256_after": after_hash, - "unchanged": before == after_hash}, + "format_info": [_FORMAT_BY_KEY[c] for c in candidates if c in _FORMAT_BY_KEY], + "explanation": _explain(origin, manifest), + "source": {"name": os.path.basename(path), "size_bytes": len(blob), "sha256_before": before, + "sha256_after": after_hash, "unchanged": before == after_hash}, "evidence": EVIDENCE, "advisory": ADVISORY, } + return body, blob, manifest + + +@ext_routes.route("/creative/inspect") +def inspect(data: dict) -> tuple[int, dict]: + body, _blob, _manifest = _inspect(_path(data), _format(data)) + return 200, body + + +@ext_routes.route("/creative/formats") +def supported_formats(data: dict) -> tuple[int, dict]: + return 200, {"formats": [dict(f) for f in formats.SUPPORTED_FORMATS], "evidence": EVIDENCE, + "manual_only": list(formats.MANUAL_ONLY), + "note": "Support is listed per format. Studio does not infer support from the fact that a file is a ZIP."} + + +# -- prepare -------------------------------------------------------------------------------- + +DEFAULT_OUT_FOLDER = "creative-prepared" + + +def _out_dir(data: dict) -> tuple[str, str]: + """(directory, kind). A given directory must be an existing local one; otherwise Studio's own folder.""" + raw = data.get("out_dir") + if raw is None or raw == "": + target = os.path.join(paths.data_dir(), DEFAULT_OUT_FOLDER) + os.makedirs(target, exist_ok=True) + return target, "studio_default" + if not isinstance(raw, str) or len(raw) > MAX_PATH_CHARS or "\x00" in raw: + raise rv.ValidationError("Invalid 'out_dir'") + if localpath.is_network_or_device_path(raw) or not localpath.is_local_directory(raw): + raise rv.ValidationError("That output folder is not an existing local folder Studio can write to.") + return raw, "chosen" + + +def _refusal(kind: str, body: dict, explanation: dict) -> tuple[int, dict]: + return 200, {"prepared": False, "refusal": {"kind": kind, **explanation}, + "origin": body["origin"], "source": body["source"], "advisory": PREPARE_ADVISORY} + + +def _model_parts(parts: dict) -> list[bytes]: + names = ["3D/3dmodel.model"] + sorted(n for n in parts if n.startswith("3D/Objects/") and n.endswith(".model")) + return [parts[n] for n in names if n in parts] + + +def _paint_count(parts: dict) -> int | None: + """Painted triangles over the root model and the object part files; None when a part cannot be parsed.""" + total = 0 + try: + for blob in _model_parts(parts): + total += generators._mesh_stats(generators._xml(blob))["painted"] + except container.ContainerError: + return None + return total + + +def compare_members(original: container.ThreeMFManifest, exported: container.ThreeMFManifest) -> dict: + """Name-based comparison of two archives' non-directory members.""" + old = {m.name: m.sha256 for m in original.members} + new = {m.name: m.sha256 for m in exported.members} + return { + "preserved": sorted(n for n in old if n in new and old[n] == new[n]), + "modified": sorted(n for n in old if n in new and old[n] != new[n]), + "dropped": sorted(n for n in old if n not in new), + "added": sorted(n for n in new if n not in old), + } + + +def _settings_delta(original: dict | None, exported: dict | None) -> dict: + a, b = original or {}, exported or {} + removed = sorted(k for k in a if k not in b) + changed = sorted(k for k in a if k in b and a[k] != b[k]) + return {"removed_keys": removed[:MAX_LISTED], "removed_count": len(removed), + "changed_keys": changed[:MAX_LISTED], "changed_count": len(changed), + "added_key_count": sum(1 for k in b if k not in a)} + + +def _verify(original: container.ThreeMFManifest, out_path: str) -> dict: + """Open the exported archive and compare it with the original. Never raises on a bad export.""" + try: + blob = _read_source(out_path) + exported = container.read_3mf(blob) + except (rv.ValidationError, container.ContainerError) as exc: + return {"opens_as_zip": False, "problem": str(exc) if isinstance(exc, rv.ValidationError) + else _ERROR_TEXT.get(str(exc), "The exported file could not be read.")} + diff = compare_members(original, exported) + before, after = _paint_count(original.parts), _paint_count(exported.parts) + return { + "opens_as_zip": True, "size_bytes": len(blob), "sha256": hashlib.sha256(blob).hexdigest(), + "members": [{"name": m.name, "sha256": m.sha256} for m in exported.members], + "comparison": {k: v[:MAX_LISTED] for k, v in diff.items()}, + "counts": {k: len(v) for k, v in diff.items()}, + "settings": _settings_delta(original.project_settings, exported.project_settings), + "per_face_paint": {"original_triangles": before, "exported_triangles": after, + "kept": None if before is None or after is None else after >= before}, + } + + +def _loss_notes(verify: dict) -> list[str]: + notes = [] + counts = verify["counts"] + if counts["dropped"]: + notes.append(f"{counts['dropped']} part(s) of the original are not in the copy: " + + ", ".join(verify["comparison"]["dropped"][:6]) + ".") + if counts["modified"]: + notes.append(f"{counts['modified']} part(s) differ from the original: " + + ", ".join(verify["comparison"]["modified"][:6]) + ".") + paint = verify["per_face_paint"] + if paint["kept"] is False: + notes.append(f"Per-face paint: the original has {paint['original_triangles']} painted triangle(s), " + f"the copy has {paint['exported_triangles']}.") + if paint["kept"] is None: + notes.append("Per-face paint could not be counted in one of the two files.") + removed = verify["settings"]["removed_count"] + if removed: + notes.append(f"{removed} project setting(s) of the original are not in the copy.") + if not notes: + notes.append("By part name and content hash, nothing was dropped and nothing differs except the parts " + "listed as modified or added.") + return notes + + +def _summary_subset(result: dict) -> dict: + summary = result.get("settings_summary") or {} + pick = lambda key: [i if isinstance(i, (str, int, float)) else dict(i) for i in (summary.get(key) or [])][:MAX_LISTED] # noqa: E731 + return {"compat_changed": pick("compat_changed"), "mapped_to_u1": pick("mapped_to_u1"), + "could_not_carry": pick("could_not_carry"), "warnings": pick("warnings")} + + +@ext_routes.route("/creative/prepare") +def prepare(data: dict) -> tuple[int, dict]: + from snapstudio_core.errors import SnapStudioError + + from . import service + + path = _path(data) + hint = _format(data) + body, blob, manifest = _inspect(path, hint) + explanation = body["explanation"] + if explanation is not None: + return _refusal(explanation["kind"], body, { + "seen": explanation["seen"], + "not_supported": explanation["not_supported"] + " Nothing was prepared.", + "what_to_do": explanation["what_to_do"]}) + out_dir, out_kind = _out_dir(data) + original_sha = hashlib.sha256(blob).hexdigest() + try: + result = service.convert(path, out_dir, "preserve") + except SnapStudioError as exc: + problems = list(getattr(exc, "problems", [])) + return _refusal("prepare_refused", body, { + "seen": f"This file was read as {formats.LABELS.get(body['origin']['generator'], body['origin']['generator'])}.", + "not_supported": f"Studio's Prepare could not produce a copy it can vouch for. {exc}", + "what_to_do": ["Open the original in Snapmaker Orca to check it, or re-export it from the tool that wrote it.", + "Nothing was written and the original was not changed."], + "problems": problems[:20]}) + except ValueError as exc: + return _refusal("prepare_refused", body, { + "seen": "The file was read, but Prepare refused it.", "not_supported": str(exc), + "what_to_do": ["Nothing was written and the original was not changed."]}) + if result.get("blocked") or not result.get("output_path"): + return _refusal("prepare_blocked", body, { + "seen": "The file was read, but Prepare did not write a copy.", + "not_supported": " ".join(str(e) for e in result.get("errors") or []) or "Prepare wrote no file.", + "what_to_do": ["Nothing was written and the original was not changed."]}) + + out_path = result["output_path"] + verify = _verify(manifest, out_path) + after = hashlib.sha256(_read_source(path)).hexdigest() + same_place = os.path.dirname(os.path.abspath(out_path)) == os.path.dirname(os.path.abspath(path)) + return 200, { + "prepared": True, + "origin": body["origin"], + # File name and a generic label for display: no message, note or label names a directory. The one field that + # carries a path is `local_path`, the new copy's location, so the local UI can link it to its job the way it + # links /convert's `output_path`. It is never shown as text and never appears anywhere else in the body. + "output": {"name": os.path.basename(out_path), "local_path": os.path.abspath(out_path), "location": out_kind, + "location_label": ("Studio's creative-prepared folder" if out_kind == "studio_default" + else "the folder you chose"), + "in_source_folder": same_place}, + "prepare": {"mode": result.get("prepare_mode"), "validated_ok": bool(result.get("validated_ok")), + "errors": [str(e) for e in result.get("errors") or []][:MAX_LISTED], + **_summary_subset(result)}, + "verification": verify, + "loss_notes": _loss_notes(verify) if verify.get("opens_as_zip") else + ["The exported file could not be re-read, so nothing can be said about what it kept."], + "original": {"name": os.path.basename(path), "sha256_before": original_sha, "sha256_after": after, + "original_unchanged": original_sha == after}, + "source": body["source"], + "advisory": PREPARE_ADVISORY, + } diff --git a/backend/snapstudio_api/routes_engines.py b/backend/snapstudio_api/routes_engines.py new file mode 100644 index 00000000..c941002e --- /dev/null +++ b/backend/snapstudio_api/routes_engines.py @@ -0,0 +1,254 @@ +"""Routes of the Engines track: an optional, user-configured local Lumina-compatible service. + + POST /engines/lumina/formats {} -> {formats, ...} + POST /engines/lumina/status {service_url} -> {status, ...} + POST /engines/lumina/generate {service_url, image_path, lut_name, format, out_dir?} -> {generated, ...} + +Studio does not slice and does not control anything here. The service is whatever local address the user +typed; it is reached only through `foundation.netguard` (loopback / LAN, no redirects, bounded). The +generated artifact is written as a NEW file in a Studio-owned folder (or a local folder the user chose), +never over or next to the input image. No response carries a filesystem path or a service response body. +Progress and cancel are `unknown`: the saved Lumina research publishes neither, so none is invented. + +Evidence: mock-service-tested. No real Lumina installation has been exercised. +""" +from __future__ import annotations + +import os +import re + +from snapstudio_core import paths +from snapstudio_core.engines import local_input +from snapstudio_core.engines.lumina import MAX_INPUT_BYTES, LuminaClient, LuminaError +from snapstudio_core.foundation.netguard import NetguardRefused + +from . import ext_routes +from . import request_validation as rv + +EVIDENCE = "mock-service-tested" +GENERATED_BY = "a user-configured local Lumina-compatible service (not verified)" +ADVISORY = ("Studio did not watch this file being made. It came from a service you configured, which " + "Studio has not verified. Inspect it before you use it; Studio does not slice or print it.") +DEFAULT_OUT_FOLDER = "lumina-output" +MAX_PATH_CHARS = 4096 +MAX_URL_CHARS = 512 + +#: The explicit list. A format is never inferred; anything else is refused. +SUPPORTED_FORMATS: tuple[dict, ...] = ( + {"kind": "3mf", "meaning": "A 3MF model file returned by the service.", "evidence": EVIDENCE}, + {"kind": "png", "meaning": "A PNG preview image returned by the service.", "evidence": EVIDENCE}, + {"kind": "glb", "meaning": "A binary glTF (GLB) preview model returned by the service.", "evidence": EVIDENCE}, +) +FORMAT_KINDS = tuple(f["kind"] for f in SUPPORTED_FORMATS) + +_FILE_URL = re.compile(r"\A/api/files/([A-Za-z0-9_-]{1,128})\Z") +_EXT = re.compile(r"\A\.[A-Za-z0-9]{1,8}\Z") + +#: Plain explanations per adapter error code. Never a service body, URL or path. +LUMINA_MESSAGES = { + "invalid_service_url": "Enter only the service address, for example http://192.168.1.20:8000, with no path.", + "discovery_failed": "The service did not answer its description request. Check the address and that it is running.", + "malformed_discovery": "The service described itself in a shape Studio does not recognise.", + "malformed_json": "The service answered with something Studio could not read.", + "unknown_version": "The service did not say which API version it speaks, so Studio will not use it.", + "unsupported_version": "The service speaks an API version Studio has not been tested with.", + "health_failed": "The service did not pass its identity check, so Studio did not send anything to it.", + "malformed_health": "The service identity check answered in a shape Studio does not recognise.", + "route_unavailable": "The service does not offer a route Studio needs.", + "identity_not_confirmed": "The service identity was not confirmed, so Studio did not send anything to it.", + "preview_failed": "The service refused or failed the request.", + "malformed_preview": "The service answered in a shape Studio does not recognise.", + "unknown_preview_locator": "The service pointed at a file location Studio does not recognise.", + "artifact_unavailable": "The service did not provide the file it announced.", + "invalid_file_id": "The service named a file in a form Studio will not fetch.", + "invalid_input": "The image is empty or larger than Studio will send.", + "invalid_lut": "Enter a LUT name of up to 256 characters.", + "progress_unknown": "Progress is unknown: the service does not publish a progress route Studio can rely on.", + "cancel_unknown": "Cancel is unknown: the service does not publish a cancel route Studio can rely on.", +} +_GENERIC_ENGINE = "The service could not be used." + + +def _refusal(code: str, message: str) -> tuple[int, dict]: + return 422, {"error": "refusal", "code": code, "message": message} + + +def _lumina_refusal(exc: LuminaError) -> tuple[int, dict]: + return _refusal(exc.code, LUMINA_MESSAGES.get(exc.code, _GENERIC_ENGINE)) + + +def _netguard_refusal(exc: NetguardRefused) -> tuple[int, dict]: + return _refusal(f"network_{exc.code}", str(exc)) + + +def _service_url(data: dict) -> str: + return rv.require_bounded_str(data, "service_url", MAX_URL_CHARS).strip() + + +def _format_list_text() -> str: + return ", ".join(FORMAT_KINDS) + + +@ext_routes.route("/engines/lumina/formats") +def formats(data: dict) -> tuple[int, dict]: + return 200, { + "formats": [dict(f) for f in SUPPORTED_FORMATS], + "evidence": EVIDENCE, + "progress": "unknown", + "cancel": "unknown", + "note": ("Formats are listed explicitly and chosen by you; Studio never infers one. " + "Evidence is a synthetic loopback mock: no real Lumina installation was exercised."), + } + + +@ext_routes.route("/engines/lumina/status") +def status(data: dict) -> tuple[int, dict]: + url = _service_url(data) + client = None + try: + client = LuminaClient(url) + discovery = client.discover() + client.health_check() + return 200, { + "status": "ok", + "api_version": discovery.api_version, + "can_generate": {"/api/convert/preview", "/api/files/{file_id}"} <= set(discovery.paths), + "progress": "unknown", + "cancel": "unknown", + "evidence": EVIDENCE, + "note": ("That answer is not proof of what the service is or " + "that it will produce a good result."), + } + except NetguardRefused as exc: + if exc.code in ("syntax", "off_network", "public_address", "unresolvable"): + return _netguard_refusal(exc) + return 200, {"status": "unknown", "code": f"network_{exc.code}", "message": str(exc), + "progress": "unknown", "cancel": "unknown", "evidence": EVIDENCE} + except LuminaError as exc: + if exc.code == "invalid_service_url": + return _lumina_refusal(exc) + return 200, {"status": "unknown", "code": exc.code, + "message": LUMINA_MESSAGES.get(exc.code, _GENERIC_ENGINE), + "progress": "unknown", "cancel": "unknown", "evidence": EVIDENCE} + finally: + if client is not None: + client.close() + + +def _image_path(data: dict) -> str: + raw = rv.require_bounded_str(data, "image_path", MAX_PATH_CHARS) + if "\x00" in raw: + raise rv.ValidationError("Invalid 'image_path'") + if local_input.is_network_or_device_path(raw) or local_input.reaches_network(raw): + raise rv.ValidationError("That image path is a network or device location. Choose a file on this computer.") + if not os.path.exists(raw): + raise rv.ValidationError("That image file was not found.") + if not local_input.is_local_regular_file(raw, max_bytes=MAX_INPUT_BYTES): + raise rv.ValidationError("That is not a regular image file Studio can send " + f"(it must be a file of at most {MAX_INPUT_BYTES // (1024 * 1024)} MB).") + return raw + + +def _out_dir(data: dict, image_path: str) -> tuple[str, str]: + """(directory, location label). The folder must be Studio's own or an existing local one.""" + raw = data.get("out_dir") + if raw is None or raw == "": + target = os.path.join(paths.data_dir(), DEFAULT_OUT_FOLDER) + os.makedirs(target, exist_ok=True) + label = "Studio's lumina-output folder" + else: + if not isinstance(raw, str) or len(raw) > MAX_PATH_CHARS or "\x00" in raw: + raise rv.ValidationError("Invalid 'out_dir'") + if not local_input.is_local_directory(raw): + raise rv.ValidationError("That output folder is not an existing local folder Studio can write to.") + target = raw + label = "the folder you chose" + try: + if os.path.samefile(target, os.path.dirname(os.path.abspath(image_path))): + raise rv.ValidationError("Choose an output folder other than the image's own folder, so the " + "original is never written next to.") + except OSError: + raise rv.ValidationError("That output folder is not an existing local folder Studio can write to.") from None + return target, label + + +def _write_new(directory: str, kind: str, sha256: str, data: bytes) -> str: + """Create a new file, never replacing one. Returns the file name only.""" + for n in range(1, 1000): + name = f"lumina-{sha256[:12]}.{kind}" if n == 1 else f"lumina-{sha256[:12]}-{n}.{kind}" + try: + fd = os.open(os.path.join(directory, name), os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0), 0o600) + except FileExistsError: + continue + with os.fdopen(fd, "wb") as handle: + handle.write(data) + return name + raise rv.ValidationError("The output folder already holds too many files with this name.") + + +def _read_input(path: str) -> bytes: + with open(path, "rb") as handle: + blob = handle.read(MAX_INPUT_BYTES + 1) + if not blob or len(blob) > MAX_INPUT_BYTES: + raise rv.ValidationError("The image is empty or larger than Studio will send.") + return blob + + +@ext_routes.route("/engines/lumina/generate") +def generate(data: dict) -> tuple[int, dict]: + url = _service_url(data) + fmt = data.get("format") + if not isinstance(fmt, str) or fmt not in FORMAT_KINDS: + raise rv.ValidationError(f"Choose one of the supported formats: {_format_list_text()}. " + "Studio does not guess a format.") + lut = rv.require_bounded_str(data, "lut_name", 256) + image_path = _image_path(data) + out_dir, location = _out_dir(data, image_path) + image = _read_input(image_path) + suffix = os.path.splitext(image_path)[1] + upload_name = "input" + (suffix if _EXT.match(suffix) else "") + + client = None + try: + client = LuminaClient(url) + client.discover() + client.health_check() + preview = client.preview(image, upload_name, lut_name=lut) + locators = [preview.get("preview_url"), preview.get("preview_glb_url")] + seen: list[str] = [] + artifact = None + for locator in locators: + match = _FILE_URL.match(locator) if isinstance(locator, str) else None + if match is None: + continue + candidate = client.fetch_artifact(match.group(1)) + seen.append(candidate.kind) + if candidate.kind == fmt: + artifact = candidate + break + if artifact is None: + produced = ", ".join(sorted(set(seen))) if seen else "no file" + return _refusal("format_not_produced", + f"You asked for {fmt}, but the service returned {produced}. Nothing was saved. " + f"Choose a format the service produced, from: {_format_list_text()}.") + name = _write_new(out_dir, artifact.kind, artifact.sha256, artifact.data) + return 200, { + "generated": True, + "file_name": name, + "sha256": artifact.sha256, + "size_bytes": artifact.size_bytes, + "kind": artifact.kind, + "generated_by": GENERATED_BY, + "location_label": location, + "advisory": ADVISORY, + "progress": "unknown", + "cancel": "unknown", + "evidence": EVIDENCE, + } + except NetguardRefused as exc: + return _netguard_refusal(exc) + except LuminaError as exc: + return _lumina_refusal(exc) + finally: + if client is not None: + client.close() diff --git a/backend/snapstudio_core/creative/container.py b/backend/snapstudio_core/creative/container.py index b285ae0a..0e0820f6 100644 --- a/backend/snapstudio_core/creative/container.py +++ b/backend/snapstudio_core/creative/container.py @@ -10,7 +10,7 @@ import posixpath import zipfile import zlib -from dataclasses import dataclass +from dataclasses import dataclass, field from xml.etree import ElementTree CORE_NS = "http://schemas.microsoft.com/3dmanufacturing/core/2015/02" @@ -38,6 +38,9 @@ class ThreeMFManifest: passed_through: tuple[MemberDigest, ...] model_xml: bytes project_settings: dict | None + #: Member bytes already read under the container limits; lets format readers look inside + #: named parts without opening the archive a second time. Never serialized. + parts: dict = field(default_factory=dict, repr=False, compare=False) def to_dict(self) -> dict: """Serialize member identity only; original archive payloads stay untouched.""" @@ -58,8 +61,8 @@ def _safe_name(name: str) -> str: return normalized -def _check_model(xml: bytes) -> None: - # UTF-8 only. A byte-substring DOCTYPE check is bypassed by UTF-16/UTF-32 (NUL-interleaved), which expat +def parse_xml(xml: bytes) -> ElementTree.Element: + # The one guarded XML parse for every part of an archive (model, object parts, settings). UTF-8 only. A byte-substring DOCTYPE check is bypassed by UTF-16/UTF-32 (NUL-interleaved), which expat # auto-detects and then expands entities from, so the text is decoded first and anything else is refused. try: text = xml.decode("utf-8-sig") @@ -74,6 +77,11 @@ def _check_model(xml: bytes) -> None: root = ElementTree.fromstring(text.encode("utf-8")) except ElementTree.ParseError as exc: raise ContainerError("bad_xml") from exc + return root + + +def _check_model(xml: bytes) -> None: + root = parse_xml(xml) if root.tag != f"{{{CORE_NS}}}model": raise ContainerError("unsupported_3mf_version") @@ -139,4 +147,4 @@ def read_3mf(data: bytes) -> ThreeMFManifest: understood.append("Metadata/project_settings.config") records = tuple(MemberDigest(n, hashlib.sha256(blobs[n]).hexdigest()) for n in sorted(blobs)) passed = tuple(rec for rec in records if rec.name not in understood) - return ThreeMFManifest(records, tuple(understood), passed, model, settings) + return ThreeMFManifest(records, tuple(understood), passed, model, settings, blobs) diff --git a/backend/snapstudio_core/creative/formats.py b/backend/snapstudio_core/creative/formats.py new file mode 100644 index 00000000..b409b2f8 --- /dev/null +++ b/backend/snapstudio_core/creative/formats.py @@ -0,0 +1,71 @@ +"""The explicit list of input formats the Creative inspector supports, and what each one reads. + +This table is the contract returned by `POST /creative/formats` and mirrored in +docs/internal/CREATIVE_COMPAT.md. Support is never inferred from generic ZIP inspection: a format is +listed only with the carrier, the documented markers or keys, what is established and what is not. +""" +from __future__ import annotations + +from . import generators, readers + +EVIDENCE = "fixture-tested" +_CARRIER = "3MF (ZIP) with 3D/3dmodel.model in the 3MF core namespace" + +SUPPORTED_FORMATS: tuple[dict, ...] = ( + {"key": "ditherforge", "label": "DitherForge", "carrier": _CARRIER, "selection": "automatic", + "identified_by": list(generators.MARKERS["ditherforge"]), + "reads": ["application tag and variant", "object part files", "triangle and painted-triangle counts", + "paint extruders used (documented 1-2 character paint_color values)", + "object names and extruders from model_settings.config", + "filament_colour, filament_type, printer_settings_id, print_settings_id"], + "kept_untouched": ["every other part and settings key, by name and SHA-256"], + "not_read": ["geometry beyond counts", "longer paint_color strings (split-triangle encoding)", + "settings JSON and collection TXT written beside the 3MF"], + "prepare_limits": ["Prepare works on the Bambu-path export (Application tag BambuStudio-+ditherforge-).", + "The generic-path export writes part id 1 under a component with objectid 2 or more. Studio's " + "structure check does not accept that, so such a file is inspect-only: Prepare refuses it and " + "writes nothing."], + "upstream": "rtwfroody/ditherforge (MIT) 4d3552a434e8084d9b5fe573959a3493325be29f"}, + {"key": "kromacut", "label": "Kromacut", "carrier": _CARRIER, "selection": "automatic", + "identified_by": list(generators.MARKERS["kromacut"]), + "reads": ["layer height and first layer height metadata", "colour layer object count and assembly object", + "parts and their extruders from model_settings.config", "base material colours", + "filament_colour, layer_height, initial_layer_print_height"], + "kept_untouched": ["Metadata/kromacut.config and every other part, by name and SHA-256"], + "not_read": ["the payload of Metadata/kromacut.config", "mesh geometry", + "optional custom metadata files"], + "upstream": "vycdev/Kromacut (AGPL-3.0, format only) 94874755426ee7f33b3684a5544e7fab0e2e73f7"}, + {"key": "sindricad", "label": "SindriCAD", "carrier": _CARRIER, "selection": "automatic", + "identified_by": list(generators.MARKERS["sindricad"]), + "reads": ["named bodies with palette slot (pindex) and extruder", "palette base materials", + "per-face paint (documented 1-2 character paint_color values)", + "filament_colour and filament_type"], + "kept_untouched": ["every other part and settings key, by name and SHA-256"], + "not_read": ["mesh geometry beyond counts", "longer paint_color strings"], + "upstream": "MakerViking/sindricad (AGPL-3.0, format only) 8b2e9dc4f82fba58b39c206c993534c487cc1eab"}, + {"key": "forcaslicer", "label": "FOrcaSlicer", "carrier": _CARRIER, "selection": "automatic", + "identified_by": ["published fos_*, mms_* and color_patch_* keys in project_settings.config"], + "reads": sorted(readers._FORCA_KEYS), "kept_untouched": ["all other keys and parts"], + "not_read": ["unknown fos_* keys", "plain nozzle_diameter as a physical value"], "upstream": None}, + {"key": "lixnix", "label": "LixNix Full Multi-Nozzle", "carrier": _CARRIER, "selection": "automatic", + "identified_by": sorted(readers._LIX_KEYS), "reads": sorted(readers._LIX_KEYS), + "kept_untouched": ["all other keys and parts"], "not_read": ["effective heights", "unpublished variants"], + "upstream": None}, + {"key": "fullspectrum", "label": "FullSpectrum 0.9.12", "carrier": _CARRIER, "selection": "automatic", + "identified_by": sorted(readers._FULLSPECTRUM_KEYS), "reads": ["mixed_filament_definitions rows (simulated recipes)"], + "kept_untouched": ["all other keys and parts"], + "not_read": ["ratios", "pattern semantics", "execution", "the draft vnext schema"], "upstream": None}, + {"key": "imagemap", "label": "OrcaSlicer ImageMap", "carrier": _CARRIER, "selection": "manual only", + "identified_by": [], "reads": ["3MF artifact identity (size, SHA-256, member list)"], + "kept_untouched": ["every part, by name and SHA-256"], + "not_read": ["the zone shape: the exact serialized carrier is not established, so no zone claim is made"], + "upstream": None}, + {"key": "lumina", "label": "Lumina Layers", "carrier": _CARRIER, "selection": "manual only", + "identified_by": [], "reads": ["3MF artifact identity (size, SHA-256, member list)"], + "kept_untouched": ["every part, by name and SHA-256"], + "not_read": ["generation provenance", "session behaviour", "file-ID lifetime"], "upstream": None}, +) + +KEYS = tuple(f["key"] for f in SUPPORTED_FORMATS) +MANUAL_ONLY = tuple(f["key"] for f in SUPPORTED_FORMATS if f["selection"] == "manual only") +LABELS = {f["key"]: f["label"] for f in SUPPORTED_FORMATS} diff --git a/backend/snapstudio_core/creative/generators.py b/backend/snapstudio_core/creative/generators.py new file mode 100644 index 00000000..eed3d970 --- /dev/null +++ b/backend/snapstudio_core/creative/generators.py @@ -0,0 +1,306 @@ +"""Readers for 3MF projects written by DitherForge, Kromacut and SindriCAD. + +Each reader is built only from the output shape its upstream exporter source documents (commits +and paths are listed in tests/fixtures/creative/PROVENANCE.md and docs/internal/CREATIVE_COMPAT.md). +Kromacut and SindriCAD are AGPL-3.0: only the output FORMAT (member names, element and attribute +names, JSON keys) was learned from them; no code, comment or sample was copied. + +A generator is identified from its documented markers, never from "it is a ZIP". When markers of +more than one generator are present the caller reports the origin as ambiguous. Anything beyond the +named facts is passed through by name and SHA-256 or listed as could-not-interpret. +""" +from __future__ import annotations + +from typing import Any +from xml.etree import ElementTree + +from .container import CORE_NS, ContainerError, ThreeMFManifest, parse_xml, read_3mf +from .readers import CreativeProject, _digest_obj + +_C = f"{{{CORE_NS}}}" +_P = "{http://schemas.microsoft.com/3dmanufacturing/production/2015/06}" +_M = "{http://schemas.microsoft.com/3dmanufacturing/material/2015/02}" + +GENERATORS = ("ditherforge", "kromacut", "sindricad") +SETTINGS_PART = "Metadata/project_settings.config" +MODEL_SETTINGS_PART = "Metadata/model_settings.config" +KROMACUT_CONFIG_PART = "Metadata/kromacut.config" +_KROMACUT_NS = b'xmlns:Kromacut="https://github.com/vycdev/Kromacut"' + +#: Parts each generator is documented to write. Absent ones are reported as missing, not guessed. +_EXPECTED_PARTS = { + "ditherforge": (MODEL_SETTINGS_PART, SETTINGS_PART), + "kromacut": (MODEL_SETTINGS_PART, KROMACUT_CONFIG_PART, SETTINGS_PART), + "sindricad": (MODEL_SETTINGS_PART, SETTINGS_PART), +} +#: Metadata keys of model_settings.config each exporter writes. Others are listed as not interpreted. +_KNOWN_MODEL_SETTINGS_KEYS = { + "ditherforge": {"name", "extruder", "face_count", "source_file", "subtype"}, + "kromacut": {"name", "extruder", "plater_id", "plater_name", "locked", "object_id", "instance_id"}, + "sindricad": {"name", "extruder"}, +} +#: project_settings.config keys each reader names. Every other key is passed through by digest. +_KNOWN_SETTINGS_KEYS = { + "ditherforge": ("filament_colour", "filament_type", "printer_settings_id", "print_settings_id"), + "kromacut": ("filament_colour", "layer_height", "initial_layer_print_height"), + "sindricad": ("filament_colour", "filament_type"), +} + +MARKERS = { + "ditherforge": ("model metadata Application starting `ditherforge-` or containing `+ditherforge-`",), + "kromacut": ("model metadata Application `Kromacut_Print`", "model namespace `xmlns:Kromacut`", + f"archive member `{KROMACUT_CONFIG_PART}`"), + "sindricad": ("model metadata Application `SindriCAD`",), +} + + +class WrongShape(ValueError): + """The file does not carry the documented markers of the format that was asked for.""" + + def __init__(self, generator: str, seen: list[str]): + super().__init__(generator) + self.generator = generator + self.expected = list(MARKERS[generator]) + self.seen = seen + + +def _xml(blob: bytes) -> ElementTree.Element: + return parse_xml(blob) # decode-first guard shared with the container (UTF-16/32 entity bypass, OP144-1) + + +def _model_metadata(root: ElementTree.Element) -> dict[str, str]: + return {el.get("name", ""): (el.text or "") for el in root if el.tag == f"{_C}metadata"} + + +def markers_present(manifest: ThreeMFManifest) -> dict[str, list[str]]: + """generator -> markers that matched. Pure inspection of the already-read container.""" + root = _xml(manifest.model_xml) + meta = _model_metadata(root) + app = meta.get("Application", "") + found: dict[str, list[str]] = {} + if app.startswith("ditherforge-") or "+ditherforge-" in app: + found["ditherforge"] = [MARKERS["ditherforge"][0]] + kro = [] + if app == "Kromacut_Print": + kro.append(MARKERS["kromacut"][0]) + if _KROMACUT_NS in manifest.model_xml: + kro.append(MARKERS["kromacut"][1]) + if KROMACUT_CONFIG_PART in manifest.parts: + kro.append(MARKERS["kromacut"][2]) + if kro: + found["kromacut"] = kro + if app == "SindriCAD": + found["sindricad"] = [MARKERS["sindricad"][0]] + return found + + +def detect(manifest: ThreeMFManifest) -> list[str]: + return sorted(markers_present(manifest)) + + +def _decode_paint(value: str) -> int | None: + """1-based extruder for a documented 1-2 character `paint_color`, else None (not decoded).""" + if value == "4": + return 1 + if value == "8": + return 2 + if len(value) == 2 and value.endswith("C") and value[0] in "0123456789ABCDEF": + return int(value[0], 16) + 3 + return None + + +def _mesh_stats(root: ElementTree.Element) -> dict[str, Any]: + triangles = painted = 0 + values: dict[str, int] = {} + for tri in root.iter(f"{_C}triangle"): + triangles += 1 + value = tri.get("paint_color") or "" + if value: + painted += 1 + values[value] = values.get(value, 0) + 1 + return {"triangles": triangles, "painted": painted, "values": values} + + +def _objects(root: ElementTree.Element) -> list[dict[str, Any]]: + out = [] + for obj in root.iter(f"{_C}object"): + comps = [{"objectid": c.get("objectid"), "path": c.get(f"{_P}path")} + for c in obj.iter(f"{_C}component")] + out.append({"id": obj.get("id"), "name": obj.get("name"), "pid": obj.get("pid"), + "pindex": obj.get("pindex"), "has_mesh": obj.find(f"{_C}mesh") is not None, + "components": comps}) + return out + + +def _metadata_rows(el: ElementTree.Element) -> dict[str, str]: + return {m.get("key", ""): m.get("value", "") for m in el.findall("metadata") if m.get("key")} + + +def _model_settings(blob: bytes) -> tuple[list[dict[str, Any]], set[str]]: + """Objects (and their parts) with name and extruder, plus every metadata key seen.""" + root = _xml(blob) + if root.tag != "config": + raise ContainerError("bad_xml") + keys: set[str] = set() + objects = [] + for obj in root.findall("object"): + rows = _metadata_rows(obj) + keys |= set(rows) + parts = [] + for part in obj.findall("part"): + prow = _metadata_rows(part) + keys |= set(prow) + parts.append({"id": part.get("id"), "name": prow.get("name"), "extruder": _int(prow.get("extruder"))}) + objects.append({"id": obj.get("id"), "name": rows.get("name"), "extruder": _int(rows.get("extruder")), + "parts": parts}) + for plate in root.findall("plate"): + keys |= set(_metadata_rows(plate)) + for inst in plate.findall("model_instance"): + keys |= set(_metadata_rows(inst)) + return objects, keys + + +def _int(value: Any) -> int | None: + try: + return int(str(value)) + except (TypeError, ValueError): + return None + + +def _palette(root: ElementTree.Element) -> list[dict[str, str]]: + bases = [b for b in root.iter() if b.tag in (f"{_C}base", f"{_M}base")] + return [{"name": b.get("name", ""), "colour": b.get("displaycolor", "")} for b in bases] + + +def _str_list(value: Any) -> list[str] | None: + return [x for x in value] if isinstance(value, list) and all(isinstance(x, str) for x in value) else None + + +def _build(generator: str, data: bytes) -> CreativeProject: + manifest = read_3mf(data) + markers = markers_present(manifest) + if generator not in markers: + raise WrongShape(generator, sorted(manifest.parts)) + root = _xml(manifest.model_xml) + meta = _model_metadata(root) + settings = manifest.project_settings or {} + facts: dict[str, Any] = {"application": meta.get("Application", ""), "markers_matched": markers[generator]} + unknown: list[str] = [] + diagnostics: list[str] = [] + other = sorted(g for g in markers if g != generator) + if other: + diagnostics.append("markers_of_other_generators_present:" + ",".join(other)) + + # -- geometry facts: main model plus every object part file (DitherForge keeps meshes there) + models = [("3D/3dmodel.model", root)] + unreadable_models = 0 + for name in sorted(manifest.parts): + if name.startswith("3D/Objects/") and name.endswith(".model"): + try: + models.append((name, _xml(manifest.parts[name]))) + except ContainerError: + unreadable_models += 1 + diagnostics.append(f"object_model_unreadable:{name}") + stats = {"triangles": 0, "painted": 0, "values": {}} + for _, tree in models: + part = _mesh_stats(tree) + stats["triangles"] += part["triangles"] + stats["painted"] += part["painted"] + for key, count in part["values"].items(): + stats["values"][key] = stats["values"].get(key, 0) + count + objects = _objects(root) + mesh_objects = [o for o in objects if o["has_mesh"]] + decoded = {k: _decode_paint(k) for k in stats["values"]} + undecoded = sorted(k for k, v in decoded.items() if v is None) + slots_used = sorted({v for v in decoded.values() if v is not None}) + # An unreadable object part may hold the only painted or counted geometry, so the aggregates built + # from the remaining parts are incomplete: report them as unknown, never as a measured zero/absence. + incomplete = unreadable_models > 0 + if incomplete: + unknown.append(f"geometry totals incomplete: {unreadable_models} object part(s) could not be read") + + # -- model_settings.config + ms_objects: list[dict[str, Any]] = [] + if MODEL_SETTINGS_PART in manifest.parts: + try: + ms_objects, ms_keys = _model_settings(manifest.parts[MODEL_SETTINGS_PART]) + for key in sorted(ms_keys - _KNOWN_MODEL_SETTINGS_KEYS[generator]): + unknown.append(f"{MODEL_SETTINGS_PART} metadata key {key}") + except ContainerError: + diagnostics.append("model_settings_unreadable") + missing = [p for p in _EXPECTED_PARTS[generator] if p not in manifest.parts] + + if generator == "ditherforge": + app = facts["application"] + facts["variant"] = "bambu_project" if app.startswith("BambuStudio-") else "generic" + facts["designer"] = meta.get("Designer", "") + facts["build_item_count"] = len(list(root.iter(f"{_C}item"))) + facts["object_part_files"] = [n for n, _ in models[1:]] + facts["triangle_count"] = None if incomplete else stats["triangles"] + facts["per_face_paint"] = None if incomplete else stats["painted"] > 0 + facts["painted_triangle_count"] = None if incomplete else stats["painted"] + facts["paint_extruders_used"] = None if incomplete else slots_used + facts["objects"] = [{"name": o["name"], "extruder": o["extruder"]} for o in ms_objects] + elif generator == "kromacut": + facts["layer_object_count"] = len(mesh_objects) + facts["assembly_present"] = any(o["components"] for o in objects) + for key, fact in (("slic3rpe:layer_height", "layer_height"), + ("slic3rpe:first_layer_height", "first_layer_height"), + ("Kromacut:SmoothMeshingStrength", "smooth_meshing_strength")): + if key in meta: + facts[fact] = meta[key] + parts = [part for o in ms_objects for part in o["parts"]] + facts["parts"] = [{"name": p["name"], "extruder": p["extruder"]} for p in parts] + facts["palette"] = _palette(root) + facts["per_face_paint"] = None if incomplete else stats["painted"] > 0 + if KROMACUT_CONFIG_PART in manifest.parts: + unknown.append(f"{KROMACUT_CONFIG_PART} payload (format not documented in the exporter output)") + else: # sindricad + bodies = [] + for o in mesh_objects: + ext = next((m["extruder"] for m in ms_objects if m["id"] == o["id"]), None) + slot = _int(o["pindex"]) + bodies.append({"name": o["name"], "palette_slot": slot, "extruder": ext}) + if ext is not None and slot is not None and ext != slot + 1: + diagnostics.append(f"extruder_disagrees_with_palette_slot:{o['name']}") + facts["body_count"] = len(mesh_objects) + facts["bodies"] = bodies + facts["palette"] = _palette(root) + facts["per_face_paint"] = None if incomplete else stats["painted"] > 0 + facts["painted_triangle_count"] = None if incomplete else stats["painted"] + facts["paint_extruders_used"] = None if incomplete else slots_used + if undecoded: + unknown.append("paint_color values not decoded: " + ", ".join(undecoded[:8])) + + known_keys = _KNOWN_SETTINGS_KEYS[generator] + understood: dict[str, Any] = dict(facts) + for key in known_keys: + if key in settings: + value = settings[key] + if key in ("filament_colour", "filament_type"): + value = _str_list(value) + if value is None: + unknown.append(f"{key} (not a list of strings)") + continue + understood[key] = value + passed = tuple({"name": m.name, "sha256": m.sha256} for m in manifest.passed_through) + passed += tuple({"name": k, "sha256": _digest_obj({k: v})["sha256"]} + for k, v in sorted(settings.items()) if k not in understood) + project = CreativeProject(generator, _digest_obj(settings), understood, passed, tuple(unknown), + tuple(missing), tuple(diagnostics)) + return project + + +def read_ditherforge(data: bytes) -> CreativeProject: + """DitherForge 3MF: Application `ditherforge-` (generic) or `BambuStudio-+ditherforge-`.""" + return _build("ditherforge", data) + + +def read_kromacut(data: bytes) -> CreativeProject: + """Kromacut 3MF: Application `Kromacut_Print`, `xmlns:Kromacut`, or `Metadata/kromacut.config`.""" + return _build("kromacut", data) + + +def read_sindricad(data: bytes) -> CreativeProject: + """SindriCAD 3MF: Application `SindriCAD`; bodies with `pindex` and extruder rows.""" + return _build("sindricad", data) diff --git a/backend/snapstudio_core/engines/__init__.py b/backend/snapstudio_core/engines/__init__.py new file mode 100644 index 00000000..e2c8b0ba --- /dev/null +++ b/backend/snapstudio_core/engines/__init__.py @@ -0,0 +1 @@ +"""Explicit local engine integrations.""" diff --git a/backend/snapstudio_core/engines/cli_runner.py b/backend/snapstudio_core/engines/cli_runner.py new file mode 100644 index 00000000..b633516a --- /dev/null +++ b/backend/snapstudio_core/engines/cli_runner.py @@ -0,0 +1,518 @@ +"""Constrained execution for a user-configured local engine executable.""" +from __future__ import annotations + +import hashlib +import json +import os +import re +import signal +import shutil +import stat +import subprocess +import sys +import threading +import time +import uuid +from dataclasses import dataclass +from pathlib import Path +from typing import Mapping, Sequence + + +_PLACEHOLDER = re.compile(r"\{(?:job_dir|output_dir|input)\}") +_FORBIDDEN = re.compile(r"[{}\x00\r\n]") + + +def _template_ok(arg: object) -> bool: + """Only the three known placeholders may contain braces. Linear time: the previous single pattern had the (a*)+ + shape and backtracked exponentially on a long argument that failed late.""" + return isinstance(arg, str) and not _FORBIDDEN.search(_PLACEHOLDER.sub("", arg)) +_SAFE_NAME = re.compile(r"\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\Z") +_KIND = {".3mf": "3mf", ".stl": "stl", ".obj": "obj", ".glb": "glb", ".png": "png", ".json": "json"} +_MAX_SCAN_ENTRIES = 10000 +_MAX_SCAN_DEPTH = 32 +_REPARSE_POINT = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400) +_SLICER_NAMES = {"orca", "snapmaker-orca", "bambu", "prusa", "slic3r", "superslicer", "cura", "kiri"} +_WINDOWS_LAUNCHER = ( + "import json,subprocess,sys; command=json.loads(sys.argv[1]); " + "sys.exit(subprocess.call(command, stdin=subprocess.DEVNULL, shell=False)) " + "if sys.stdin.buffer.read(1) == b'\\x01' else sys.exit(125)" +) + + +def _resolve_existing(path: str | os.PathLike[str]) -> Path: + """Resolve a path that must exist. Windows app-execution aliases (the Microsoft Store's python.exe) are reparse + points that strict resolution cannot read (WinError 1920) although they run normally; for those, fall back to + ordinary resolution and require that stat succeeds. A path that does not exist still raises FileNotFoundError. + stat on such an alias reports the link itself, so a dangling alias is not detected here: admission is by path + identity or pinned bytes (an alias cannot be hashed), and a dangling one fails at launch.""" + candidate = Path(path).expanduser() + try: + return candidate.resolve(strict=True) + except FileNotFoundError: + raise + except OSError: + resolved = candidate.resolve() + os.stat(resolved) # must succeed; for a Store alias it describes the link itself (see above) + return resolved + + +def _is_own_interpreter(path: Path) -> bool: + try: + return path == _resolve_existing(sys.executable) + except OSError: + return False + + +def _hash_approved(path: Path, approved: Sequence[str]) -> bool: + """True when the file's SHA-256 is one the caller pinned. Hash comparison is done on the bytes read now.""" + pins = {item.lower() for item in approved if isinstance(item, str) and re.fullmatch(r"[0-9a-fA-F]{64}", item)} + if not pins: + return False + digest = hashlib.sha256() + try: + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(1024 * 1024), b""): + digest.update(chunk) + except OSError: + return False + return digest.hexdigest() in pins + + +def _executable_policy_refused(path: Path) -> bool: + name = path.name.lower() + if name.endswith(".exe"): + name = name[:-4] + tokens = [token for token in re.split(r"[-_. ]+", name) if token] + return name in _SLICER_NAMES or "slicer" in name or any(token in _SLICER_NAMES for token in tokens) + + +class _WindowsJob: + """A kill-on-close Job Object containing this runner's child process tree.""" + + def __init__(self, process: subprocess.Popen[bytes]) -> None: + import ctypes + + from ctypes import wintypes + + class IO_COUNTERS(ctypes.Structure): + _fields_ = [(name, ctypes.c_ulonglong) for name in ( + "ReadOperationCount", "WriteOperationCount", "OtherOperationCount", + "ReadTransferCount", "WriteTransferCount", "OtherTransferCount")] + + class BASIC_LIMIT(ctypes.Structure): + _fields_ = [ + ("PerProcessUserTimeLimit", ctypes.c_longlong), + ("PerJobUserTimeLimit", ctypes.c_longlong), + ("LimitFlags", wintypes.DWORD), + ("MinimumWorkingSetSize", ctypes.c_size_t), + ("MaximumWorkingSetSize", ctypes.c_size_t), + ("ActiveProcessLimit", wintypes.DWORD), + ("Affinity", ctypes.c_size_t), + ("PriorityClass", wintypes.DWORD), + ("SchedulingClass", wintypes.DWORD), + ] + + class EXTENDED_LIMIT(ctypes.Structure): + _fields_ = [ + ("BasicLimitInformation", BASIC_LIMIT), + ("IoInfo", IO_COUNTERS), + ("ProcessMemoryLimit", ctypes.c_size_t), + ("JobMemoryLimit", ctypes.c_size_t), + ("PeakProcessMemoryUsed", ctypes.c_size_t), + ("PeakJobMemoryUsed", ctypes.c_size_t), + ] + + self._kernel32 = ctypes.WinDLL("kernel32", use_last_error=True) + kernel32 = self._kernel32 + kernel32.CreateJobObjectW.restype = wintypes.HANDLE + kernel32.CreateJobObjectW.argtypes = (ctypes.c_void_p, wintypes.LPCWSTR) + kernel32.SetInformationJobObject.argtypes = (wintypes.HANDLE, ctypes.c_int, + ctypes.c_void_p, wintypes.DWORD) + kernel32.AssignProcessToJobObject.argtypes = (wintypes.HANDLE, wintypes.HANDLE) + kernel32.CloseHandle.argtypes = (wintypes.HANDLE,) + self.handle = kernel32.CreateJobObjectW(None, None) + if not self.handle: + raise OSError(ctypes.get_last_error(), "CreateJobObjectW failed") + limits = EXTENDED_LIMIT() + limits.BasicLimitInformation.LimitFlags = 0x00002000 # JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE + if not kernel32.SetInformationJobObject(self.handle, 9, ctypes.byref(limits), ctypes.sizeof(limits)): + error = ctypes.get_last_error() + self.close() + raise OSError(error, "SetInformationJobObject failed") + if not kernel32.AssignProcessToJobObject(self.handle, wintypes.HANDLE(process._handle)): + error = ctypes.get_last_error() + self.close() + raise OSError(error, "AssignProcessToJobObject failed") + + def close(self) -> None: + if self.handle: + self._kernel32.CloseHandle(self.handle) + self.handle = None + + +class RunnerError(Exception): + """Safe runner refusal or bounded execution failure.""" + + def __init__(self, code: str, *, stdout: bytes = b"") -> None: + self.code = code + self.stdout = stdout + super().__init__(code) + + +@dataclass(frozen=True) +class RunnerResult: + job_dir: Path + returncode: int + stdout: bytes + artifacts: tuple[dict[str, object], ...] + + +class _Capture: + def __init__(self, cap: int, stop: threading.Event, lock: threading.Lock, + total: list[int]) -> None: + self.cap = cap + self.stop = stop + self.lock = lock + self.shared_total = total + self.data = bytearray() + self.total = 0 + + def drain(self, stream: object) -> None: + while True: + try: + chunk = stream.read(4096) # type: ignore[attr-defined] + except OSError: + return + if not chunk: + return + with self.lock: + room = max(0, self.cap - self.shared_total[0]) + self.shared_total[0] += len(chunk) + self.total += len(chunk) + self.data.extend(chunk[:room]) + if self.shared_total[0] > self.cap: + self.stop.set() + return + + +class CliRunner: + """Run a fixed executable and argument template without a shell. + + Every run gets a fresh directory created beneath `job_root`. Processes run in a + private process group (POSIX) or kill-on-close Job Object (Windows), so stop + operations only affect the tree this runner started. The executable-name policy + is a safety rail, not a sandbox or a guarantee. + """ + + def __init__(self, executable: str | os.PathLike[str], job_root: str | os.PathLike[str], + argument_template: Sequence[str], *, timeout_s: float = 300.0, + output_limit: int = 1024 * 1024, + artifact_limit: int = 512 * 1024 * 1024, + approved_sha256: Sequence[str] = ()) -> None: + self.executable = _resolve_existing(executable) + if not self.executable.is_file(): + raise RunnerError("executable_invalid") + if self.executable.suffix.lower() in {".bat", ".cmd"}: + raise RunnerError("executable_script_refused") + if _executable_policy_refused(self.executable): + raise RunnerError("executable_policy_refused") + # Admission is by identity, not by name: the caller pins the SHA-256 of the one executable it approves. + # Only the interpreter running Studio is admitted without a pin. A renamed copy of anything else has a + # different path and, unless its bytes were pinned, no approval. + if not _is_own_interpreter(self.executable) and not _hash_approved(self.executable, approved_sha256): + raise RunnerError("executable_not_approved") + self.job_root = Path(job_root).expanduser().resolve(strict=True) + if not self.job_root.is_dir(): + raise RunnerError("job_root_invalid") + if not isinstance(argument_template, (tuple, list)) or not all( + _template_ok(arg) for arg in argument_template): + raise RunnerError("argument_template_invalid") + if isinstance(timeout_s, bool) or not isinstance(timeout_s, (int, float)) or not 0 < timeout_s <= 3600: + raise RunnerError("timeout_invalid") + if isinstance(output_limit, bool) or not isinstance(output_limit, int) or not 1024 <= output_limit <= 64 * 1024 * 1024: + raise RunnerError("output_limit_invalid") + if isinstance(artifact_limit, bool) or not isinstance(artifact_limit, int) \ + or not 1 <= artifact_limit <= 2 * 1024 * 1024 * 1024: + raise RunnerError("artifact_limit_invalid") + self.argument_template = tuple(argument_template) + self.timeout_s = float(timeout_s) + self.output_limit = output_limit + self.artifact_limit = artifact_limit + self._lock = threading.Lock() + self._active: dict[int, tuple[subprocess.Popen[bytes], _WindowsJob | None]] = {} + + def run(self, *, inputs: Mapping[str, str] | None = None, + cancel_event: threading.Event | None = None) -> RunnerResult: + if inputs is None: + inputs = {} + if not isinstance(inputs, Mapping) or any(not _SAFE_NAME.fullmatch(k) or not isinstance(v, str) for k, v in inputs.items()): + raise RunnerError("input_invalid") + run_id = uuid.uuid4().hex + job_dir = (self.job_root / run_id).resolve() + if not job_dir.is_relative_to(self.job_root): + raise RunnerError("job_path_invalid") + try: + return self._run_job(job_dir, inputs, cancel_event) + except BaseException: + self._remove_job_dir(job_dir) + raise + + def _run_job(self, job_dir: Path, inputs: Mapping[str, str], + cancel_event: threading.Event | None) -> RunnerResult: + job_dir.mkdir(mode=0o700) + output_dir = job_dir / "output" + output_dir.mkdir() + input_paths: dict[str, str] = {} + for name, value in inputs.items(): + source = Path(value).expanduser().resolve(strict=True) + if not source.is_file(): + raise RunnerError("input_invalid") + staged = job_dir / "input" / name + staged.parent.mkdir(exist_ok=True) + shutil.copyfile(source, staged) + input_paths[name] = str(staged) + values = {"job_dir": str(job_dir), "output_dir": str(output_dir), + "input": next(iter(input_paths.values()), "")} + for arg in self.argument_template: + if "{input}" in arg and len(input_paths) != 1: + raise RunnerError("input_placeholder_ambiguous") + rendered = [re.sub(r"\{(job_dir|output_dir|input)\}", + lambda match: values[match.group(1)], arg) + for arg in self.argument_template] + command = [str(self.executable), *rendered] + windows_job: _WindowsJob | None = None + try: + launch_command = command + launch_stdin = subprocess.DEVNULL + if os.name == "nt": + # The helper waits before starting the configured engine. This lets + # the runner assign the helper to its Job Object first, so even a + # fast engine cannot spawn a descendant outside that job. + if getattr(sys, "frozen", False): + # The launcher needs a plain interpreter; a packaged sidecar would start itself instead. + raise RunnerError("windows_launcher_unavailable_in_packaged_app") + launch_command = [sys.executable, "-I", "-c", _WINDOWS_LAUNCHER, json.dumps(command)] + launch_stdin = subprocess.PIPE + process = subprocess.Popen(launch_command, cwd=str(job_dir), shell=False, + stdin=launch_stdin, stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + start_new_session=(os.name != "nt")) + if os.name == "nt": + try: + windows_job = _WindowsJob(process) + except OSError: + self._stop_owned(process, windows_job) + raise RunnerError("process_job_assignment_failed") from None + try: + assert process.stdin is not None + process.stdin.write(b"\x01") + process.stdin.flush() + process.stdin.close() + except OSError: + self._stop_owned(process, windows_job) + raise RunnerError("process_start_failed") from None + except OSError: + raise RunnerError("process_start_failed") from None + try: + with self._lock: + self._active[process.pid] = (process, windows_job) + overflow = threading.Event() + budget_lock = threading.Lock() + output_total = [0] + stdout = _Capture(self.output_limit, overflow, budget_lock, output_total) + stderr = _Capture(self.output_limit, overflow, budget_lock, output_total) + readers = [threading.Thread(target=stdout.drain, args=(process.stdout,), daemon=True), + threading.Thread(target=stderr.drain, args=(process.stderr,), daemon=True)] + for reader in readers: + reader.start() + deadline = time.monotonic() + self.timeout_s + while process.poll() is None: + if cancel_event is not None and cancel_event.is_set(): + self._stop_owned(process, windows_job) + raise RunnerError("cancelled", stdout=bytes(stdout.data)) + if overflow.is_set(): + self._stop_owned(process, windows_job) + raise RunnerError("output_limit_exceeded", stdout=bytes(stdout.data)) + try: + output_size = self._output_size(output_dir) + except RunnerError: + self._stop_owned(process, windows_job) + raise + if output_size > self.artifact_limit: + self._stop_owned(process, windows_job) + raise RunnerError("artifact_output_limit_exceeded", stdout=bytes(stdout.data)) + if time.monotonic() >= deadline: + self._stop_owned(process, windows_job) + raise RunnerError("timeout", stdout=bytes(stdout.data)) + time.sleep(0.02) + # The direct process can exit while a descendant still holds inherited + # pipes or continues writing. Close the runner-owned tree before scanning. + self._stop_owned(process, windows_job) + for reader in readers: + reader.join(timeout=0.1) + if overflow.is_set(): + raise RunnerError("output_limit_exceeded", stdout=bytes(stdout.data)) + code = process.returncode + if code != 0: + raise RunnerError("process_failed", stdout=bytes(stdout.data)) + return RunnerResult(job_dir, int(code), bytes(stdout.data), self._manifest(output_dir)) + finally: + self._stop_owned(process, windows_job) + if windows_job is not None: + windows_job.close() + with self._lock: + self._active.pop(process.pid, None) + # A descendant may still hold an inherited pipe. Closing its BufferedReader + # while a daemon reader is blocked in read() waits on that reader's lock. + # Leave ownership with the reader; it closes when EOF arrives. + + def cancel(self, pid: int) -> bool: + """Terminate a process only when its PID maps to this runner's live Popen handle.""" + with self._lock: + active = self._active.get(pid) + if active is None: + return False + self._stop_owned(*active) + return True + + @staticmethod + def _stop_owned(process: subprocess.Popen[bytes], windows_job: _WindowsJob | None = None) -> None: + if os.name == "nt": + if windows_job is not None: + windows_job.close() + if process.poll() is None: + if windows_job is None: + try: + process.terminate() + except OSError: + pass + try: + process.wait(timeout=1.0) + except (OSError, subprocess.TimeoutExpired): + try: + process.kill() + except OSError: + pass + try: + process.wait(timeout=1.0) + except subprocess.TimeoutExpired: + pass + return + try: + os.killpg(process.pid, signal.SIGTERM) + except ProcessLookupError: + pass + except OSError: + if process.poll() is None: + process.terminate() + try: + process.wait(timeout=1.0) + except subprocess.TimeoutExpired: + pass + try: + os.killpg(process.pid, signal.SIGKILL) + except (ProcessLookupError, OSError): + pass + if process.poll() is None: + try: + process.wait(timeout=1.0) + except subprocess.TimeoutExpired: + # Cleanup remains bounded even if the OS cannot stop the child. + pass + + def cleanup(self, result: RunnerResult) -> None: + """Remove a successful run's job directory after its caller has read artifacts.""" + if not isinstance(result, RunnerResult): + raise RunnerError("result_invalid") + self._remove_job_dir(result.job_dir) + + def _remove_job_dir(self, job_dir: Path) -> None: + try: + resolved = job_dir.resolve(strict=False) + if resolved.parent != self.job_root or not re.fullmatch(r"[0-9a-f]{32}", resolved.name): + return + shutil.rmtree(resolved, ignore_errors=True) + except OSError: + # Cleanup is best effort and must not mask the original engine outcome. + pass + + @staticmethod + def _iter_output_files(output_dir: Path): + stack: list[tuple[Path, int]] = [(output_dir, 0)] + visited = 0 + try: + # The root is checked like every entry: an engine that swaps its (initially empty) output + # directory for a link or junction must not make an outside tree look like job output. + root = os.lstat(output_dir) + if (output_dir.is_symlink() or getattr(output_dir, "is_junction", lambda: False)() + or getattr(root, "st_file_attributes", 0) & _REPARSE_POINT): + raise RunnerError("artifact_symlink_refused") + if not stat.S_ISDIR(root.st_mode): + raise RunnerError("artifact_scan_failed") + while stack: + directory, depth = stack.pop() + with os.scandir(directory) as entries: + for entry in entries: + visited += 1 + if visited > _MAX_SCAN_ENTRIES: + raise RunnerError("artifact_scan_limit_exceeded") + path = Path(entry.path) + try: + info = entry.stat(follow_symlinks=False) + junction = getattr(path, "is_junction", lambda: False)() + symlink = path.is_symlink() + except OSError: + raise RunnerError("artifact_scan_failed") from None + if symlink or junction or getattr(info, "st_file_attributes", 0) & _REPARSE_POINT: + raise RunnerError("artifact_symlink_refused") + if stat.S_ISDIR(info.st_mode): + if depth >= _MAX_SCAN_DEPTH: + raise RunnerError("artifact_scan_limit_exceeded") + stack.append((path, depth + 1)) + elif stat.S_ISREG(info.st_mode): + yield path, info.st_size + except OSError: + raise RunnerError("artifact_scan_failed") from None + + def _output_size(self, output_dir: Path) -> int: + total = 0 + for _, size in self._iter_output_files(output_dir): + total += size + if total > self.artifact_limit: + return total + return total + + def _manifest(self, output_dir: Path) -> tuple[dict[str, object], ...]: + entries: list[dict[str, object]] = [] + total = 0 + try: + base = output_dir.resolve(strict=True) + except OSError: + raise RunnerError("artifact_scan_failed") from None + for path, observed_size in sorted(self._iter_output_files(output_dir), key=lambda item: item[0]): + try: + if not path.resolve(strict=True).is_relative_to(base): + raise RunnerError("artifact_path_escape") + except OSError: + raise RunnerError("artifact_scan_failed") from None + name = path.relative_to(output_dir).as_posix() + parts = name.split("/") + if any(part in ("", ".", "..") or not _SAFE_NAME.fullmatch(part) for part in parts): + raise RunnerError("artifact_name_invalid") + digest = hashlib.sha256() + size = 0 + try: + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(1024 * 1024), b""): + size += len(chunk) + total += len(chunk) + if size > self.artifact_limit or total > self.artifact_limit: + raise RunnerError("artifact_too_large") + digest.update(chunk) + except OSError: + raise RunnerError("artifact_scan_failed") from None + if size != observed_size: + raise RunnerError("artifact_scan_failed") + entries.append({"name": name, "sha256": digest.hexdigest(), "size_bytes": size, + "kind": _KIND.get(path.suffix.lower(), "unknown")}) + return tuple(entries) diff --git a/backend/snapstudio_core/engines/local_input.py b/backend/snapstudio_core/engines/local_input.py new file mode 100644 index 00000000..073fa7d1 --- /dev/null +++ b/backend/snapstudio_core/engines/local_input.py @@ -0,0 +1,95 @@ +"""Best-effort guard for a user-supplied local input file or output folder. + +Interim private helper for the engines track. The shared guard lives in the #140 work +(`snapstudio_core.localpath`); this module should be replaced by it once both land. + +It refuses a network (UNC) path in any slash style, a Windows device path, a symlink or +junction chain that reaches one of those, anything that is not a regular file, and a file +over the caller's size cap. The checks are lexical first; the link walk then `lstat`s each +component (never following the one being examined) and reads a link's target text with +`readlink`, so a link to a network share is rejected without connecting to it. + +This is best-effort, not a sandbox: the check and the later open are separate steps, so a +process that can change the path in between can redirect the operation. A mapped network +drive letter looks like a local volume and is allowed; it is the user's own storage. +""" +from __future__ import annotations + +import os +import stat + +_MAX_LINK_DEPTH = 8 +_REDIRECTING_REPARSE_TAGS = {0xA000000C, 0xA0000003} # symlink, junction + + +def is_network_or_device_path(path: object) -> bool: + """UNC shares and the device namespaces, in any mix of slash styles.""" + if not isinstance(path, str): + return False + normal = path.replace("/", "\\") + # `\\host\share`, `\\?\...`, `\\.\...` and the NT passthrough prefix `\??\...` (one leading backslash). + return normal.startswith("\\\\") or normal.startswith("\\??\\") + + +def _plain_drive_target(target: str) -> str: + # Windows readlink returns a link to C:\x as \\?\C:\x: a local drive, not a device namespace. + if len(target) >= 7 and target[:4] == "\\\\?\\" and "A" <= target[4].upper() <= "Z" and target[5:7] == ":\\": + return target[4:] + return target + + +def _is_redirect(info: os.stat_result) -> bool: + return stat.S_ISLNK(info.st_mode) or getattr(info, "st_reparse_tag", 0) in _REDIRECTING_REPARSE_TAGS + + +def reaches_network(path: str, depth: int = 0) -> bool: + """True when the path, or any link on the way to it, names a network or device location.""" + if is_network_or_device_path(path): + return True + if depth > _MAX_LINK_DEPTH: + return True + absolute = os.path.abspath(path) + if is_network_or_device_path(absolute): + return True + drive, rest = os.path.splitdrive(absolute) + current = drive + os.sep + for part in [piece for piece in rest.split(os.sep) if piece]: + current = os.path.join(current, part) + try: + info = os.lstat(current) + except FileNotFoundError: + return False + except (OSError, ValueError): + return True + if _is_redirect(info): + try: + target = os.readlink(current) + except (OSError, ValueError): + return True + target = _plain_drive_target(target) + if not os.path.isabs(target) and not is_network_or_device_path(target): + target = os.path.join(os.path.dirname(current), target) + if reaches_network(target, depth + 1): + return True + return False + + +def is_local_regular_file(path: object, *, max_bytes: int) -> bool: + """True only for a regular local file no larger than `max_bytes`. Never raises.""" + if not isinstance(path, str) or not path or "\x00" in path or reaches_network(path): + return False + try: + info = os.stat(path) + except (OSError, ValueError): + return False + return stat.S_ISREG(info.st_mode) and info.st_size <= max_bytes + + +def is_local_directory(path: object) -> bool: + """True only for an existing local directory. Never raises.""" + if not isinstance(path, str) or not path or "\x00" in path or reaches_network(path): + return False + try: + return stat.S_ISDIR(os.stat(path).st_mode) + except (OSError, ValueError): + return False diff --git a/backend/snapstudio_core/engines/lumina.py b/backend/snapstudio_core/engines/lumina.py new file mode 100644 index 00000000..c3151b0a --- /dev/null +++ b/backend/snapstudio_core/engines/lumina.py @@ -0,0 +1,190 @@ +"""Bounded client for the documented Lumina Layers local API (API 2.0).""" +from __future__ import annotations + +import hashlib +import json +import re +import uuid +from dataclasses import dataclass +from typing import Any, Callable, Mapping +from urllib.parse import urlsplit + +from snapstudio_core.foundation.netguard import ( + NetguardRefused, + Response, + confirm_write_origin, + local_request, + require_local_url, + revoke_write_origin, +) + +SUPPORTED_API_VERSION = "2.0" +MAX_JSON_BYTES = 2 * 1024 * 1024 +MAX_ARTIFACT_BYTES = 512 * 1024 * 1024 +MAX_INPUT_BYTES = 128 * 1024 * 1024 +_FILE_ID = re.compile(r"\A[A-Za-z0-9_-]{1,128}\Z") +_REQUEST: Callable[..., Response] = local_request + + +class LuminaError(Exception): + """A safe, bounded error without response bodies or configured URLs.""" + + def __init__(self, code: str) -> None: + self.code = code + super().__init__(code) + + +@dataclass(frozen=True) +class Discovery: + api_version: str + paths: frozenset[str] + evidence: str = "mock-service-tested" + + +@dataclass(frozen=True) +class Artifact: + sha256: str + size_bytes: int + kind: str + data: bytes + + +class LuminaClient: + """Talk to a user-supplied local Lumina service through foundation netguard.""" + + def __init__(self, service_url: str, *, timeout: float = 15.0, + request: Callable[..., Response] | None = None) -> None: + require_local_url(service_url) + parts = urlsplit(service_url if "://" in service_url else "http://" + service_url) + if parts.path not in ("", "/") or parts.query or parts.fragment: + raise LuminaError("invalid_service_url") + self.origin = f"{parts.scheme}://{parts.netloc}" + self.timeout = timeout + self._request = request or _REQUEST + self._discovery: Discovery | None = None + self._write_enabled = False + + def discover(self) -> Discovery: + """Read the captured FastAPI OpenAPI document and require its known API version.""" + response = self._request("GET", self.origin + "/openapi.json", timeout=self.timeout, + max_bytes=MAX_JSON_BYTES) + data = self._json(response, "discovery") + info = data.get("info") + paths = data.get("paths") + if not isinstance(info, dict) or not isinstance(paths, dict): + raise LuminaError("malformed_discovery") + version = info.get("version") + if not isinstance(version, str) or not version: + raise LuminaError("unknown_version") + if version != SUPPORTED_API_VERSION: + raise LuminaError("unsupported_version") + self._discovery = Discovery(version, frozenset(p for p in paths if isinstance(p, str))) + return self._discovery + + def health_check(self) -> Mapping[str, Any]: + """Confirm the documented identity route before enabling API writes. + + The health response schema is absent from the saved research. It is retained opaquely + and never interpreted as proof of a version or capability. + """ + if self._discovery is None: + self.discover() + self._require_discovery("/api/health") + response = self._request("GET", self.origin + "/api/health", timeout=self.timeout, + max_bytes=MAX_JSON_BYTES) + payload = self._json(response, "health") + if not isinstance(payload, dict): + raise LuminaError("malformed_health") + confirm_write_origin(self.origin) + self._write_enabled = True + return payload + + def preview(self, image: bytes, filename: str, *, lut_name: str, + fields: Mapping[str, str] | None = None) -> Mapping[str, Any]: + """Submit the documented multipart preview form; no parameters are inferred.""" + self._require_discovery("/api/convert/preview") + if not self._write_enabled: + raise LuminaError("identity_not_confirmed") + if not isinstance(image, bytes) or not image or len(image) > MAX_INPUT_BYTES: + raise LuminaError("invalid_input") + if not isinstance(filename, str) or not filename or any(c in filename for c in "\r\n\x00\"\\"): + raise LuminaError("invalid_filename") + if not isinstance(lut_name, str) or not lut_name or len(lut_name) > 256: + raise LuminaError("invalid_lut") + form = {"lut_name": lut_name} + for key, value in (fields or {}).items(): + if not isinstance(key, str) or not re.fullmatch(r"[a-z_]{1,64}", key) or key in {"image", "lut_name"}: + raise LuminaError("invalid_form") + if not isinstance(value, str) or len(value) > 1024: + raise LuminaError("invalid_form") + form[key] = value + boundary = "sslumina" + uuid.uuid4().hex + body = bytearray() + for key, value in form.items(): + body.extend(f"--{boundary}\r\nContent-Disposition: form-data; name=\"{key}\"\r\n\r\n{value}\r\n".encode()) + body.extend((f"--{boundary}\r\nContent-Disposition: form-data; name=\"image\"; filename=\"{filename}\"\r\n" + "Content-Type: application/octet-stream\r\n\r\n").encode()) + body.extend(image) + body.extend(f"\r\n--{boundary}--\r\n".encode()) + response = self._request("POST", self.origin + "/api/convert/preview", + headers={"Content-Type": f"multipart/form-data; boundary={boundary}"}, + body=bytes(body), timeout=self.timeout, max_bytes=MAX_JSON_BYTES, + max_request_bytes=MAX_INPUT_BYTES + 128 * 1024, + write_ok=True, origin=self.origin) + data = self._json(response, "preview") + session_id = data.get("session_id") + status = data.get("status") + preview_url = data.get("preview_url") + if not isinstance(session_id, str) or not isinstance(status, str) or not isinstance(preview_url, str): + raise LuminaError("malformed_preview") + if not preview_url.startswith("/api/files/"): + raise LuminaError("unknown_preview_locator") + return data + + def fetch_artifact(self, file_id: str) -> Artifact: + """Fetch a documented registered file and derive identity from returned bytes.""" + self._require_discovery("/api/files/{file_id}") + if not isinstance(file_id, str) or not _FILE_ID.fullmatch(file_id): + raise LuminaError("invalid_file_id") + response = self._request("GET", self.origin + f"/api/files/{file_id}", + timeout=self.timeout, max_bytes=MAX_ARTIFACT_BYTES) + if response.status < 200 or response.status >= 300 or response.body is None: + raise LuminaError("artifact_unavailable") + content_type = response.headers.get("content-type", "").split(";", 1)[0].lower() + kind = {"model/3mf": "3mf", "application/vnd.ms-package.3dmanufacturing-3dmodel+xml": "3mf", + "model/gltf-binary": "glb", "image/png": "png"}.get(content_type, "unknown") + raw = response.body + return Artifact(hashlib.sha256(raw).hexdigest(), len(raw), kind, raw) + + def progress(self, *_: Any, **__: Any) -> None: + """Progress is unknown: the saved Lumina research publishes no progress route or shape.""" + self._require_discovery() + raise LuminaError("progress_unknown") + + def cancel(self, *_: Any, **__: Any) -> None: + """Cancellation is unknown: the saved Lumina research publishes no cancel route or shape.""" + self._require_discovery() + raise LuminaError("cancel_unknown") + + def close(self) -> None: + if self._write_enabled: + revoke_write_origin(self.origin) + self._write_enabled = False + + def _require_discovery(self, path: str | None = None) -> None: + if self._discovery is None: + self.discover() + if path and path not in self._discovery.paths: + raise LuminaError("route_unavailable") + + @staticmethod + def _json(response: Response, operation: str) -> dict[str, Any]: + if response.status < 200 or response.status >= 300 or response.body is None: + raise LuminaError(f"{operation}_failed") + try: + data = json.loads(response.body.decode("utf-8")) + except (UnicodeDecodeError, json.JSONDecodeError): + raise LuminaError("malformed_json") from None + if not isinstance(data, dict): + raise LuminaError("malformed_json") + return data diff --git a/backend/snapstudio_core/multipart.py b/backend/snapstudio_core/multipart.py index cadeb1de..31aa43b2 100644 --- a/backend/snapstudio_core/multipart.py +++ b/backend/snapstudio_core/multipart.py @@ -455,6 +455,81 @@ def _parts_by_object(settings_xml: str) -> dict: _OBJECT_TAG = re.compile(r']") +_TRIANGLE_START = re.compile(r" container +_COMPONENT_TAG = re.compile(r"]*>") +_PATH_ATTR = re.compile(r'\bp:path="([^"]*)"') +_OBJECTID_ATTR = re.compile(r'\bobjectid="(\d+)"') + + +def _component_refs(block: str) -> list[tuple]: + """(p:path or None, objectid or None) for each component tag, whatever order its attributes come in.""" + refs = [] + for tag in _COMPONENT_TAG.findall(block): + path = _PATH_ATTR.search(tag) + object_id = _OBJECTID_ATTR.search(tag) + refs.append((path.group(1) if path else None, object_id.group(1) if object_id else None)) + return refs + + +def _scan_objects(body: str, where: str) -> tuple[dict, list[str]]: + """Every `` in one model part, read the same way for the root model and a p:path file. + + One linear pass with str.find: regexes over a many-megabyte mesh (a lazy `.*?`, or a search + per object from the top of the file) made the Doctor several times slower. Returns + ({id: {type, mesh, geometry, valid}}, problems). An object that is not closed, or that holds + another object, is `valid` False: it earns no geometry and cannot satisfy a reference, because + whatever lies inside it belongs to something else. A repeated id keeps its first definition. + """ + if "", "", body, flags=re.S) + objects: dict[str, dict] = {} + problems: list[str] = [] + pos = 0 + visited = 0 + truncated = False + while True: + start = body.find('", start) + if tag_end < 0: + problems.append(f"an object tag in {where} is not closed") + truncated = True + break + pos = tag_end + tag = _OBJECT_TAG.match(body, start, tag_end) + if not tag: + problems.append(f"an object in {where} has an id that is not a number") + continue + object_id = tag.group(1) + if object_id in objects: + problems.append(f"object {object_id} is defined more than once in {where}") + continue + kind = _TYPE_ATTR.search(body, start, tag_end) + entry = {"type": kind.group(1) if kind else None, "mesh": False, "geometry": False, "valid": True} + objects[object_id] = entry + if body[tag_end - 1] == "/": # self-closing: no body, no geometry + continue + end = body.find("", tag_end) + if end < 0: + problems.append(f"object {object_id} in {where} is not closed") + entry["valid"] = False + continue + if _NESTED_OBJECT.search(body, tag_end, end): + # 3MF Core does not nest objects; a mesh found inside one belongs to the inner object + problems.append(f"object {object_id} in {where} contains another object") + entry["valid"] = False + continue + entry["mesh"] = body.find("= 0 + entry["geometry"] = _TRIANGLE_START.search(body, tag_end, end) is not None + pos = end + if not truncated and len(_NESTED_OBJECT.findall(body)) > visited: + # an object opened some other way (another attribute first, single quotes) is never scanned, + # so nothing would check it: refuse rather than let it pass unread + problems.append(f"{where} has an object tag the scan cannot read (`id` must be the first attribute, double-quoted)") + return objects, problems def _object_label(body: str) -> str: @@ -513,11 +588,12 @@ def validate_archive(tm) -> dict: lose the file. """ problems: list[str] = [] - mesh_types: dict[str, str] = {} def read(name: str) -> str: try: - return tm.read_part(name).decode("utf-8", "ignore") if tm.has_part(name) else "" + text = tm.read_part(name).decode("utf-8", "ignore") if tm.has_part(name) else "" + # comments are not structure: no reader below may see a commented-out tag + return re.sub(r"", "", text, flags=re.S) if "{obj(1)}' + result = multipart.validate_archive(build({A: commented}, [(A, 1)])) + assert result["ok"] is True, result["problems"] + + +def test_a_comment_in_the_root_model_does_not_refuse_a_valid_root_mesh(): + archive = build({A: model(obj(1))}, [(None, 2), (A, 1)], root_objects=[ + f' {MESH}'], parts=[(2, "normal_part"), (1, "normal_part")]) + assert multipart.validate_archive(archive)["ok"] is True + + +# -- the p:path scan now has the nested / unclosed handling the root scan has --------------------------------- + +def test_an_object_nested_in_a_file_object_is_not_credited_to_the_outer_object(): + nested = model(f'{MESH}') + result = multipart.validate_archive(build({A: nested}, [(A, 1)])) + assert result["ok"] is False + assert any("object 1 in /3D/Objects/a.model contains another object" in p for p in result["problems"]) + assert any("no file defines" in p and "'1'" in p for p in result["problems"]) + + +def test_an_unclosed_file_object_is_refused_not_ignored(): + unclosed = f'{MESH}' + result = multipart.validate_archive(build({A: unclosed}, [(A, 1)])) + assert result["ok"] is False + assert any("object 1 in /3D/Objects/a.model is not closed" in p for p in result["problems"]) + assert any("no file defines" in p for p in result["problems"]) + + +def test_an_unclosed_file_object_does_not_borrow_the_next_objects_geometry(): + """Object 1 has no mesh and no close tag; object 2's closing tag must not make it look like geometry.""" + xml = f'{MESH}' + result = multipart.validate_archive(build({A: xml}, [(A, 1)])) + assert result["ok"] is False + assert any("contains another object" in p for p in result["problems"]) + + +def test_an_empty_triangles_container_in_a_file_is_not_geometry(): + result = multipart.validate_archive(build({A: model(obj(1, body=EMPTY_MESH))}, [(A, 1)])) + assert result["ok"] is False + assert any("object 1 in /3D/Objects/a.model carries no geometry" in p for p in result["problems"]) + + +def test_an_empty_triangles_container_in_the_root_is_not_geometry(): + archive = build({A: model(obj(1))}, [(None, 2), (A, 1)], root_objects=[obj(2, body=EMPTY_MESH)], + parts=[(2, "normal_part"), (1, "normal_part")]) + assert any("object 2 in the root model carries no geometry" in p for p in problems_of(archive)) + + +def test_a_self_closing_file_object_carries_no_geometry(): + result = multipart.validate_archive(build({A: model('')}, [(A, 1)])) + assert result["ok"] is False + assert any("object 1 in /3D/Objects/a.model carries no geometry" in p for p in result["problems"]) + + +# -- ids: duplicates, cross-file reuse, missing references ---------------------------------------------------- + +def test_a_duplicate_id_inside_one_file_is_refused(): + result = multipart.validate_archive(build({A: model(obj(1), obj(1))}, [(A, 1)])) + assert result["ok"] is False + assert any("object 1 is defined more than once in /3D/Objects/a.model" in p for p in result["problems"]) + + +def test_a_duplicate_id_in_the_root_model_is_refused(): + archive = build({A: model(obj(1))}, [(None, 2), (A, 1)], root_objects=[obj(2), obj(2)], + parts=[(2, "normal_part"), (1, "normal_part")]) + assert any("object 2 is defined more than once in the root model" in p for p in problems_of(archive)) + + +def test_a_reference_resolves_in_its_own_file_not_in_another_file_with_that_id(): + """Component names file A object 2, which only file B defines: it is missing, not satisfied by B.""" + archive = build({A: model(obj(1)), B: model(obj(2))}, [(A, 2), (B, 2)]) + result = multipart.validate_archive(archive) + assert result["ok"] is False + assert any("no file defines" in p and "'2'" in p for p in result["problems"]) + + +def test_a_pathed_reference_is_not_satisfied_by_a_root_object_with_that_id(): + archive = build({A: model(obj(5))}, [(A, 1)], root_objects=[obj(1)]) + assert any("no file defines" in p and "'1'" in p for p in problems_of(archive)) + + +def test_a_missing_file_object_is_reported_when_the_file_exists_but_lacks_the_id(): + assert any("no file defines" in p and "'7'" in p + for p in problems_of(build({A: model(obj(1))}, [(A, 7)]))) + + +def test_type_is_checked_against_the_named_file_object_when_another_file_reuses_the_id(): + """Both files define object 1; the one the component names is typed 'other' under a normal_part.""" + archive = build({A: model(obj(1, "other")), B: model(obj(1, "model"))}, [(A, 1)]) + assert any("is a normal_part and the geometry under it is typed 'other'" in p for p in problems_of(archive)) + + +def test_type_in_an_unreferenced_file_does_not_cause_a_false_mismatch(): + archive = build({A: model(obj(1, "model")), B: model(obj(1, "other"))}, [(A, 1)]) + assert multipart.validate_archive(archive)["ok"] is True + + +def test_two_files_that_disagree_on_an_ids_type_in_one_assembly_are_refused(): + archive = build({A: model(obj(1, "model")), B: model(obj(1, "other"))}, [(A, 1), (B, 1)], + parts=[(1, "normal_part"), (1, "normal_part")]) + assert any("several files that disagree" in p for p in problems_of(archive)) + + +def test_two_files_that_agree_on_an_ids_type_in_one_assembly_stay_valid(): + archive = build({A: model(obj(1)), B: model(obj(1))}, [(A, 1), (B, 1)], + parts=[(1, "normal_part"), (1, "normal_part")]) + assert multipart.validate_archive(archive)["ok"] is True + + +# -- malformed objects and components ------------------------------------------------------------------------ + +def test_a_non_numeric_object_id_in_a_file_is_refused(): + xml = model(f'{MESH}', obj(1)) + assert any("has an id that is not a number" in p for p in problems_of(build({A: xml}, [(A, 1)]))) + + +def test_a_truncated_object_tag_is_refused(): + xml = f'{obj(1)}", f'', 1) + archive.parts["3D/3dmodel.model"] = root.encode() + assert any("has no object id" in p for p in problems_of(archive)) + + +def test_component_attribute_order_does_not_matter(): + archive = build({A: model(obj(1))}, [(A, 1)]) + root = archive.parts["3D/3dmodel.model"].decode().replace( + f'', f'') + archive.parts["3D/3dmodel.model"] = root.encode() + assert multipart.validate_archive(archive)["ok"] is True + + +def test_an_unclosed_root_mesh_object_is_refused(): + archive = build({A: model(obj(1))}, [(None, 2), (A, 1)], parts=[(2, "normal_part"), (1, "normal_part")], + root_objects=[f'{MESH}']) + # no closing tag: the next belongs to the assembly, so object 2 holds another object + assert any("object 2 in the root model" in p for p in problems_of(archive)) + + +# -- same-id root/file assembly stays refused (Sol R5-F1) ------------------------------------------------------ + +def test_one_assembly_still_may_not_mix_root_and_file_components_with_the_same_id(): + archive = build({A: model(obj(1, "other"))}, [(A, 1), (None, 1)], root_objects=[obj(1, "model")], + parts=[(1, "normal_part"), (1, "normal_part")]) + assert any("referenced both from the root model and from a file" in p for p in problems_of(archive)) + + +# -- Sol R7-F1 / R7-F2 --------------------------------------------------------------------------------------- + +def test_a_commented_out_component_in_the_root_model_does_not_refuse_a_valid_archive(): + archive = build({A: model(obj(1))}, [(A, 1)]) + root = archive.parts["3D/3dmodel.model"].decode().replace( + "", '', 1) + archive.parts["3D/3dmodel.model"] = root.encode() + assert multipart.validate_archive(archive)["ok"] is True + + +def test_a_commented_out_assembly_is_not_read_as_structure(): + archive = build({A: model(obj(1))}, [(A, 1)]) + root = archive.parts["3D/3dmodel.model"].decode().replace( + "", + '', 1) + archive.parts["3D/3dmodel.model"] = root.encode() + assert multipart.validate_archive(archive)["ok"] is True + + +def test_an_omitted_object_type_equals_an_explicit_model_across_files(): + untyped = f'{MESH}' + archive = build({A: model(untyped), B: model(obj(1, "model"))}, [(A, 1), (B, 1)], + parts=[(1, "normal_part"), (1, "normal_part")]) + assert multipart.validate_archive(archive)["ok"] is True + + +def test_an_omitted_object_type_still_disagrees_with_an_explicit_other_across_files(): + untyped = f'{MESH}' + archive = build({A: model(untyped), B: model(obj(1, "other"))}, [(A, 1), (B, 1)], + parts=[(1, "normal_part"), (1, "normal_part")]) + assert any("several files that disagree" in p for p in problems_of(archive)) + + +def test_an_object_written_with_id_not_first_is_refused_not_skipped(): + """Opus O-R7-F1: an unreadable object spelling must not hide a nested object from the scan.""" + xml = model(f'{MESH}') + result = multipart.validate_archive(build({A: xml}, [(A, 9)])) + assert result["ok"] is False + assert any("object tag the scan cannot read" in p for p in result["problems"]) diff --git a/backend/tests/test_routes_engines_lumina.py b/backend/tests/test_routes_engines_lumina.py new file mode 100644 index 00000000..c5345903 --- /dev/null +++ b/backend/tests/test_routes_engines_lumina.py @@ -0,0 +1,350 @@ +"""Engines track routes for a user-configured Lumina-compatible service. + +The service in every test is the synthetic loopback `LuminaHttpMock`, not Lumina: evidence is +mock-service-tested and no real Lumina installation is exercised. +""" +from __future__ import annotations + +import hashlib +import json +import os +import sys + +import pytest + +from snapstudio_api import ext_routes, routes_engines +from snapstudio_core.foundation.netguard import clear_write_origins +from tests.mocks.lumina_server import HTTP_ARTIFACTS, LuminaHttpMock + +IMAGE_BYTES = b"synthetic-image-bytes-not-a-real-picture" + + +class FakeHandler: + def __init__(self): + self.sent = [] + + def _send(self, code, obj): + self.sent.append((code, obj)) + + +def call(path, data): + handler = FakeHandler() + assert ext_routes.dispatch(handler, path, data) is True + assert len(handler.sent) == 1 + return handler.sent[0] + + +@pytest.fixture +def data_dir(tmp_path, monkeypatch): + target = tmp_path / "studio-data" + target.mkdir() + monkeypatch.setenv("SNAPSTUDIO_DATA_DIR", str(target)) + return target + + +@pytest.fixture +def image(tmp_path): + folder = tmp_path / "inputs" + folder.mkdir() + path = folder / "synthetic.png" + path.write_bytes(IMAGE_BYTES) + return path + + +@pytest.fixture +def service(): + with LuminaHttpMock() as mock: + yield mock + clear_write_origins() + + +def assert_no_path(body, *roots): + text = json.dumps(body) + for root in roots: + for form in (str(root), str(root).replace("\\", "\\\\"), root.as_posix()): + assert form not in text + assert "\\Users\\" not in text and "\\\\Users\\\\" not in text and "/Users/" not in text + + +def request(service, image, fmt, **extra): + return {"service_url": service.url, "image_path": str(image), "lut_name": "Default", "format": fmt, **extra} + + +# -- registration ---------------------------------------------------------------- + +def test_routes_are_registered_under_engines_through_dispatch(): + for suffix in ("formats", "status", "generate"): + assert f"/engines/lumina/{suffix}" in ext_routes.ROUTES + assert ext_routes.ROUTES[f"/engines/lumina/{suffix}"].__module__.endswith("routes_engines") + handled = ext_routes.dispatch(FakeHandler(), "/engines/lumina/nothing", {}) + assert handled is False + + +def test_dispatch_rejects_a_non_object_body(): + handler = FakeHandler() + ext_routes.dispatch(handler, "/engines/lumina/formats", []) + assert handler.sent[0][0] == 400 + + +# -- formats --------------------------------------------------------------------- + +def test_formats_list_is_explicit_and_labelled(): + status, body = call("/engines/lumina/formats", {}) + assert status == 200 + assert [f["kind"] for f in body["formats"]] == ["3mf", "png", "glb"] + assert all(f["evidence"] == "mock-service-tested" and f["meaning"] for f in body["formats"]) + assert body["progress"] == "unknown" and body["cancel"] == "unknown" + assert "no real Lumina" in body["note"] + + +# -- status ---------------------------------------------------------------------- + +def test_status_ok_reports_only_what_was_read(service): + status, body = call("/engines/lumina/status", {"service_url": service.url}) + assert status == 200 + assert body["status"] == "ok" and body["api_version"] == "2.0" and body["can_generate"] is True + assert body["progress"] == "unknown" and body["cancel"] == "unknown" + assert "not proof" in body["note"] + + +def test_status_unknown_for_unsupported_version_without_body_echo(): + with LuminaHttpMock(version="9.9") as mock: + status, body = call("/engines/lumina/status", {"service_url": mock.url}) + clear_write_origins() + assert status == 200 and body["status"] == "unknown" and body["code"] == "unsupported_version" + assert "9.9" not in json.dumps(body) + + +def test_status_unknown_when_nothing_is_listening(): + with LuminaHttpMock() as mock: + url = mock.url + status, body = call("/engines/lumina/status", {"service_url": url}) + assert status == 200 and body["status"] == "unknown" + assert body["code"].startswith("network_") + + +def test_status_refuses_a_non_local_address(): + status, body = call("/engines/lumina/status", {"service_url": "http://8.8.8.8:8000"}) + assert status == 422 and body["error"] == "refusal" and body["code"] == "network_off_network" + + +def test_status_rejects_a_service_url_with_a_path(service): + status, body = call("/engines/lumina/status", {"service_url": service.url + "/x"}) + assert status == 422 and body["code"] == "invalid_service_url" + + +def test_status_requires_a_service_url(): + status, body = call("/engines/lumina/status", {}) + assert status == 400 and body["error"] == "invalid" + + +# -- generate: success ----------------------------------------------------------- + +@pytest.mark.parametrize("fmt,preview_id,glb_id,artifact", [ + ("3mf", "mfile", None, "mfile"), + ("png", "pngfile", "glbfile", "pngfile"), + ("glb", "pngfile", "glbfile", "glbfile"), +]) +def test_generate_writes_the_exact_bytes_as_a_new_file(tmp_path, data_dir, image, fmt, preview_id, glb_id, artifact): + before = hashlib.sha256(image.read_bytes()).hexdigest() + with LuminaHttpMock(preview_id=preview_id, glb_id=glb_id) as mock: + status, body = call("/engines/lumina/generate", request(mock, image, fmt)) + uploaded = mock.uploads[0]["bytes"] + clear_write_origins() + expected = HTTP_ARTIFACTS[artifact][1] + assert status == 200 and body["generated"] is True + assert body["kind"] == fmt + assert body["sha256"] == hashlib.sha256(expected).hexdigest() and body["size_bytes"] == len(expected) + written = data_dir / "lumina-output" / body["file_name"] + assert written.read_bytes() == expected + assert os.path.dirname(body["file_name"]) == "" + assert body["generated_by"] == "a user-configured local Lumina-compatible service (not verified)" + assert body["location_label"] == "Studio's lumina-output folder" + assert "did not watch" in body["advisory"] + assert body["progress"] == "unknown" and body["cancel"] == "unknown" + assert hashlib.sha256(image.read_bytes()).hexdigest() == before + assert sorted(p.name for p in image.parent.iterdir()) == ["synthetic.png"] + assert IMAGE_BYTES in uploaded + assert_no_path(body, tmp_path, data_dir) + + +def test_generate_into_a_chosen_folder_and_never_overwrites(tmp_path, data_dir, image): + chosen = tmp_path / "chosen" + chosen.mkdir() + with LuminaHttpMock() as mock: + s1, b1 = call("/engines/lumina/generate", request(mock, image, "png", out_dir=str(chosen))) + s2, b2 = call("/engines/lumina/generate", request(mock, image, "png", out_dir=str(chosen))) + clear_write_origins() + assert s1 == s2 == 200 + assert b1["location_label"] == "the folder you chose" + assert b1["file_name"] != b2["file_name"] + assert len(list(chosen.iterdir())) == 2 + assert_no_path(b1, tmp_path, data_dir) + assert_no_path(b2, tmp_path, data_dir) + + +def test_generate_refuses_the_images_own_folder_as_output(tmp_path, data_dir, service, image): + status, body = call("/engines/lumina/generate", request(service, image, "png", out_dir=str(image.parent))) + assert status == 400 and "other than the image's own folder" in body["message"] + assert service.requests == [] + assert_no_path(body, tmp_path, data_dir) + + +# -- generate: refusals ---------------------------------------------------------- + +@pytest.mark.parametrize("fmt", ["", "stl", "PNG", "obj", None, 3, ["png"]]) +def test_generate_refuses_an_unlisted_format_before_any_request(data_dir, service, image, fmt): + status, body = call("/engines/lumina/generate", request(service, image, fmt)) + assert status == 400 and body["error"] == "invalid" + assert "3mf, png, glb" in body["message"] + assert service.requests == [] + assert not (data_dir / "lumina-output").exists() or not list((data_dir / "lumina-output").iterdir()) + + +def test_generate_requires_a_format(data_dir, service, image): + payload = request(service, image, "png") + del payload["format"] + status, body = call("/engines/lumina/generate", payload) + assert status == 400 and "3mf, png, glb" in body["message"] + assert service.requests == [] + + +def test_generate_refuses_a_non_local_service_url(tmp_path, data_dir, image): + payload = {"service_url": "http://8.8.8.8:8000", "image_path": str(image), "lut_name": "Default", "format": "png"} + status, body = call("/engines/lumina/generate", payload) + assert status == 422 and body["code"] == "network_off_network" + assert "local network" in body["message"] or "own network" in body["message"] + assert_no_path(body, tmp_path, data_dir) + assert not (data_dir / "lumina-output").exists() or not list((data_dir / "lumina-output").iterdir()) + + +@pytest.mark.parametrize("path", [ + "\\\\server\\share\\a.png", "//server/share/a.png", "\\/server/share/a.png", + "\\\\?\\UNC\\server\\share\\a.png", "\\\\?\\C:\\a.png", "\\\\.\\pipe\\a", + "\\??\\UNC\\server\\share\\a.png", "/??/UNC/server/share/a.png", +]) +def test_generate_refuses_unc_and_device_paths_in_any_slash_style(data_dir, service, path): + status, body = call("/engines/lumina/generate", { + "service_url": service.url, "image_path": path, "lut_name": "Default", "format": "png"}) + assert status == 400 and "network or device" in body["message"] + assert service.requests == [] + + +def test_generate_refuses_a_directory_and_a_missing_file(tmp_path, data_dir, service): + for target in (tmp_path, tmp_path / "missing.png"): + status, body = call("/engines/lumina/generate", { + "service_url": service.url, "image_path": str(target), "lut_name": "Default", "format": "png"}) + assert status == 400 + assert_no_path(body, tmp_path) + assert service.requests == [] + + +def test_generate_refuses_an_oversize_image(tmp_path, data_dir, service, image, monkeypatch): + monkeypatch.setattr(routes_engines, "MAX_INPUT_BYTES", 8) + status, body = call("/engines/lumina/generate", request(service, image, "png")) + assert status == 400 and "at most" in body["message"] + assert service.requests == [] + assert_no_path(body, tmp_path, data_dir) + + +def test_generate_refuses_a_link_to_a_network_target(tmp_path, data_dir, service): + link = tmp_path / "linked.png" + try: + os.symlink("\\\\server\\share\\a.png", link) + except (OSError, NotImplementedError): + pytest.skip("symlink creation is not permitted here") + status, body = call("/engines/lumina/generate", { + "service_url": service.url, "image_path": str(link), "lut_name": "Default", "format": "png"}) + assert status == 400 and "network or device" in body["message"] + assert service.requests == [] + + +def test_generate_refuses_a_missing_or_overlong_lut(data_dir, service, image): + payload = request(service, image, "png") + del payload["lut_name"] + assert call("/engines/lumina/generate", payload)[0] == 400 + payload["lut_name"] = "x" * 257 + assert call("/engines/lumina/generate", payload)[0] == 400 + assert service.requests == [] + + +def test_generate_refuses_an_out_dir_that_is_not_a_local_folder(tmp_path, data_dir, service, image): + for target in ("\\\\server\\share", str(tmp_path / "nope"), str(image)): + status, body = call("/engines/lumina/generate", request(service, image, "png", out_dir=target)) + assert status == 400 and "output folder" in body["message"] + assert_no_path(body, tmp_path) + assert service.requests == [] + + +# -- generate: engine behaviour -------------------------------------------------- + +def test_generate_names_what_the_service_returned_when_the_format_differs(tmp_path, data_dir, image): + with LuminaHttpMock(preview_id="pngfile", glb_id=None) as mock: + status, body = call("/engines/lumina/generate", request(mock, image, "3mf")) + clear_write_origins() + assert status == 422 and body["code"] == "format_not_produced" + assert "png" in body["message"] and "Nothing was saved" in body["message"] + assert not (data_dir / "lumina-output").exists() or not list((data_dir / "lumina-output").iterdir()) + + +def test_generate_maps_engine_error_codes_without_body_echo(tmp_path, data_dir, image): + with LuminaHttpMock(version="9.9") as mock: + status, body = call("/engines/lumina/generate", request(mock, image, "png")) + clear_write_origins() + assert status == 422 and body["code"] == "unsupported_version" + assert "9.9" not in json.dumps(body) + with LuminaHttpMock(artifacts={}) as mock: + status, body = call("/engines/lumina/generate", request(mock, image, "png")) + clear_write_origins() + assert status == 422 and body["code"] == "artifact_unavailable" + assert_no_path(body, tmp_path, data_dir) + + +@pytest.mark.parametrize("locator", ["bad.id", "..%2Fx", "a b", "x" * 129]) +def test_generate_never_fetches_an_invalid_file_id(data_dir, image, locator): + with LuminaHttpMock(preview_id=locator, glb_id=None) as mock: + status, body = call("/engines/lumina/generate", request(mock, image, "png")) + fetched = [r for r in mock.requests if r[1].startswith("/api/files/")] + clear_write_origins() + assert status == 422 and body["code"] == "format_not_produced" + assert fetched == [] + + +def test_write_origin_is_revoked_after_generate(data_dir, image): + from snapstudio_core.foundation import netguard + + with LuminaHttpMock() as mock: + call("/engines/lumina/generate", request(mock, image, "png")) + assert netguard._WRITE_ORIGINS == set() + clear_write_origins() + + +@pytest.mark.skipif(sys.platform != "win32", reason="Windows path styles") +def test_generate_response_never_holds_a_windows_path(tmp_path, data_dir, image): + with LuminaHttpMock() as mock: + status, body = call("/engines/lumina/generate", request(mock, image, "png")) + clear_write_origins() + assert status == 200 + assert ":\\" not in json.dumps(body).replace("\\\\", "\\") + + +def test_link_walk_refuses_a_link_whose_target_is_a_network_path(tmp_path, monkeypatch): + """Exercised with a faked link so it runs where symlinks cannot be created.""" + import stat as stat_module + + from snapstudio_core.engines import local_input + + fake = str(tmp_path / "linked.png") + real_lstat = os.lstat + + def fake_lstat(path, *a, **k): + if os.fspath(path) == fake: + info = real_lstat(tmp_path) + return os.stat_result((stat_module.S_IFLNK | 0o777,) + tuple(info)[1:]) + return real_lstat(path, *a, **k) + + monkeypatch.setattr(os, "lstat", fake_lstat) + monkeypatch.setattr(os, "readlink", lambda p: r"\\server\share\a.png") + assert local_input.reaches_network(fake) is True + monkeypatch.setattr(os, "readlink", lambda p: str(tmp_path)) + assert local_input.reaches_network(fake) is False diff --git a/desktop/src/components/creative/CreativeFormatChooser.tsx b/desktop/src/components/creative/CreativeFormatChooser.tsx new file mode 100644 index 00000000..0644ac9a --- /dev/null +++ b/desktop/src/components/creative/CreativeFormatChooser.tsx @@ -0,0 +1,53 @@ +import { CREATIVE_FORMATS, GENERATOR_LABEL, type CreativeFormat, type CreativeFormatInfo } from "@/lib/creativeApi"; + +const field = "h-9 rounded-md border border-border bg-card px-3 text-sm outline-none focus-visible:ring-2 focus-visible:ring-primary/50"; + +/** Format choice. When detection could not decide, the person picks one and is told plainly what is read for it. */ +export default function CreativeFormatChooser({ value, onChange, formats, needsChoice }: { + value: CreativeFormat; + onChange: (f: CreativeFormat) => void; + formats: CreativeFormatInfo[]; + needsChoice: boolean; +}) { + const info = formats.find((f) => f.key === value); + return ( +
+
+ + {needsChoice && value === "auto" && ( +

Studio could not decide the tool. Choose the format you know this file came from, then inspect again.

+ )} +
+ {info && ( +
+

{info.label}: {info.selection === "manual only" ? "read only when you choose it" : "identified automatically only when its markers are present in the file"}.

+

Carrier: {info.carrier}.

+
+
+

Studio reads

+
    {info.reads.map((r) =>
  • {r}
  • )}
+
+
+

Studio does not read

+
    {info.not_read.map((r) =>
  • {r}
  • )}
+
+
+ {info.prepare_limits && info.prepare_limits.length > 0 && ( +
+

Prepare limits

+
    {info.prepare_limits.map((r) =>
  • {r}
  • )}
+
+ )} + {info.identified_by.length === 0 && ( +

This format leaves no identifying marker in the file, so Studio cannot confirm the file really came from this tool.

+ )} +
+ )} + {value === "auto" && !needsChoice && ( +

Studio does not guess the tool: when the markers and settings do not identify it, the origin is reported as unknown.

+ )} +
+ ); +} diff --git a/desktop/src/components/creative/CreativePreparePanel.tsx b/desktop/src/components/creative/CreativePreparePanel.tsx new file mode 100644 index 00000000..edcfa844 --- /dev/null +++ b/desktop/src/components/creative/CreativePreparePanel.tsx @@ -0,0 +1,84 @@ +import type { ReactNode } from "react"; +import { comparisonBuckets, settingsTotals, type CreativePrepareResponse, type CreativeVerification } from "@/lib/creativeApi"; + +function Box({ title, note, children }: { title: string; note?: string; children: ReactNode }) { + return ( +
+

{title}

+ {note &&

{note}

} + {children} +
+ ); +} + +/** Members kept, changed, dropped and added between the original and the new copy, by part name and content hash. */ +export function ExportVerification({ verification, lossNotes }: { verification: CreativeVerification; lossNotes: string[] }) { + if (!verification.opens_as_zip) { + return

The exported file could not be re-read: {verification.problem ?? "unknown problem"}. Nothing can be said about what it kept.

; + } + const paint = verification.per_face_paint; + return ( + +
+ {comparisonBuckets(verification).map((b) => ( +
+

{b.title} ({b.total})

+

{b.note}

+ {b.truncated &&

showing {b.items.length} of {b.total}

} + {b.items.length === 0 + ?

None.

+ :
    {b.items.map((i) =>
  • {i}
  • )}
} +
+ ))} +
+ {paint && paint.original_triangles !== null && paint.exported_triangles !== null && ( +

Per-face paint: {paint.original_triangles} painted triangle(s) in the original, {paint.exported_triangles} in the copy.

+ )} + {verification.settings && (() => { + const t = settingsTotals(verification.settings); + return

Project settings: {t.removed} removed, {t.changed} changed, {t.added} added.

; + })()} +
    {lossNotes.map((n) =>
  • {n}
  • )}
+
+ ); +} + +/** Result of "Prepare a U1 copy": either an explanation of why nothing was written, or the verified new file. */ +export default function CreativePreparePanel({ result }: { result: CreativePrepareResponse }) { + if (!result.prepared) { + const r = result.refusal; + return ( +
+

No copy was written

+

What Studio saw. {r.seen}

+

What is not supported. {r.not_supported}

+
What to do. +
    {r.what_to_do.map((w) =>
  • {w}
  • )}
+
+ {r.problems && r.problems.length > 0 && ( +

What the check found

+
    {r.problems.map((p) =>
  • {p}
  • )}
+
+ )} +

{result.advisory}

+
+ ); + } + const unchanged = result.original.original_unchanged; + return ( +
+ +

Copy: {result.output.name}

+

Saved in: {result.output.location_label}.{result.output.in_source_folder ? " This is the same folder as the original, because you chose it." : " It is not next to the original."}

+

Review it in Snapmaker Orca before slicing. Studio does not slice.

+
+ +
+

{unchanged + ? "Original unchanged: its fingerprint is identical before and after Prepare." + : "The original's fingerprint differs between the two reads. Something outside Studio changed the file while it was being prepared."}

+

{result.original.name}. before {result.original.sha256_before.slice(0, 16)}, after {result.original.sha256_after.slice(0, 16)}

+
+
+ ); +} diff --git a/desktop/src/components/creative/CreativeReportView.tsx b/desktop/src/components/creative/CreativeReportView.tsx index 8ed1d3f5..af726c34 100644 --- a/desktop/src/components/creative/CreativeReportView.tsx +++ b/desktop/src/components/creative/CreativeReportView.tsx @@ -1,5 +1,5 @@ import type { ReactNode } from "react"; -import { originSentence, type CreativeInspectResponse } from "@/lib/creativeApi"; +import { factLines, GENERATOR_LABEL, originSentence, type CreativeInspectResponse } from "@/lib/creativeApi"; function Section({ title, note, children }: { title: string; note: string; children: ReactNode }) { return ( @@ -19,6 +19,7 @@ function NameList({ items, empty }: { items: string[]; empty: string }) { /** What Studio read from one project file: understood, kept untouched, could not interpret. Advisory only. */ export default function CreativeReportView({ report }: { report: CreativeInspectResponse }) { const { source } = report; + const facts = Object.values(report.facts ?? {}).flatMap((f) => factLines(f)); return (
@@ -26,6 +27,34 @@ export default function CreativeReportView({ report }: { report: CreativeInspect

{report.advisory}

Evidence: fixture-tested. The readers are tested against hand-written files shaped like the published formats, not against captured projects.

+ {report.explanation && ( +
+

{report.explanation.kind === "ambiguous_origin" ? "Studio cannot tell which tool wrote this" : "Studio does not recognise this file's tool"}

+

What Studio saw. {report.explanation.seen}

+

What is not supported. {report.explanation.not_supported}

+
What to do. +
    {report.explanation.what_to_do.map((w) =>
  • {w}
  • )}
+
+
+ )} + {facts.length > 0 && ( +
+ {Object.entries(report.facts ?? {}).map(([gen, f]) => ( +
+ {Object.keys(report.facts ?? {}).length > 1 &&

{GENERATOR_LABEL[gen] ?? gen}

} +
    {factLines(f).map((l) =>
  • {l}
  • )}
+
+ ))} +
+ )} + {(report.format_info ?? []).map((info) => ( +
+
+

Read

+

Not read

+
+
+ ))}
diff --git a/desktop/src/components/creative/CreativeView.tsx b/desktop/src/components/creative/CreativeView.tsx index ed9d3737..2240b883 100644 --- a/desktop/src/components/creative/CreativeView.tsx +++ b/desktop/src/components/creative/CreativeView.tsx @@ -2,26 +2,38 @@ import { useEffect, useRef, useState } from "react"; import { Palette } from "lucide-react"; import { Button } from "@/components/ui/button"; import { PageHeader } from "@/components/ui/layout"; -import { CREATIVE_FORMATS, inspectCreative, type CreativeFormat, type CreativeInspectResponse } from "@/lib/creativeApi"; +import { + fetchCreativeFormats, inspectCreative, normalizedProjectPath, prepareCreative, + type CreativeFormat, type CreativeFormatInfo, type CreativeInspectResponse, type CreativePrepareResponse, +} from "@/lib/creativeApi"; +import { beginPrepare, linkPreparedCopy, useUnlinkedCopies } from "@/store/job"; +import CreativeFormatChooser from "./CreativeFormatChooser"; +import CreativePreparePanel from "./CreativePreparePanel"; import CreativeReportView from "./CreativeReportView"; -/** Inspect one local creative project file. The path is sent to the local Studio service only, which - * opens the file for reading, never writes it, and never slices or contacts a printer. */ -export default function CreativeView() { +/** Inspect one local creative project file, then optionally write a prepared copy. The path is sent to the local + * Studio service only. Inspecting never writes anything; Prepare writes one new file and never the original. */ +export default function CreativeView({ initialFormats = [] }: { initialFormats?: CreativeFormatInfo[] }) { const [path, setPath] = useState(""); const [format, setFormat] = useState("auto"); + const [outDir, setOutDir] = useState(""); + const [formats, setFormats] = useState(initialFormats); const [busy, setBusy] = useState(false); const [error, setError] = useState(null); const [report, setReport] = useState(null); + const [prepared, setPrepared] = useState(null); + const [linkNote, setLinkNote] = useState(null); + const unlinked = useUnlinkedCopies((state) => state.items); const alive = useRef(true); useEffect(() => { alive.current = true; + fetchCreativeFormats().then((r) => { if (alive.current) setFormats(r.formats); }).catch(() => undefined); return () => { alive.current = false; }; }, []); const run = async () => { // A failed inspection must not leave the previous file's report under the new path. - setBusy(true); setError(null); setReport(null); + setBusy(true); setError(null); setReport(null); setPrepared(null); try { const res = await inspectCreative(path, format); if (alive.current) setReport(res); @@ -32,21 +44,60 @@ export default function CreativeView() { } }; + const prepare = async () => { + setBusy(true); setError(null); setPrepared(null); setLinkNote(null); + const started = beginPrepare(); + try { + const res = await prepareCreative(path, format, outDir); + // A written copy that passed validation joins this project's job (original -> prepared) so Recovery and Passport can + // use it, unless a newer Prepare or project change took over the job meanwhile. A refusal wrote nothing. + let note: string | null = null; + if (res.prepared && res.output.local_path) { + if (!res.prepare.validated_ok) note = "This copy did not pass Studio's validation, so it was not linked to the job: Recovery and Passport will not track it."; + else if (!linkPreparedCopy(normalizedProjectPath(path), res.output.local_path, res.prepare.mode || "creative", started)) { + note = "This copy was written, but a newer Prepare or project change happened while it ran, so it was not linked to the current job."; + } + } + if (note && res.prepared) useUnlinkedCopies.getState().add(`${res.output.name}: ${note}`); + if (alive.current) { setPrepared(res); setLinkNote(note); } + } catch (e) { + if (alive.current) setError(e instanceof Error ? e.message : "Prepare failed."); + } finally { + if (alive.current) setBusy(false); + } + }; + const field = "h-9 rounded-md border border-border bg-card px-3 text-sm outline-none focus-visible:ring-2 focus-visible:ring-primary/50"; + const undecided = report !== null && (report.origin.status === "unknown" || report.origin.status === "ambiguous"); return (
- +
setPath(e.target.value)} onKeyDown={(e) => { if (e.key === "Enter" && !busy && path.trim() !== "") void run(); }} /> -
-

Studio does not guess the generator: when the settings do not identify it, the origin is reported as unknown.

+ {error &&

{error}

} {report && } + {report && ( +
+

Prepare a U1 copy

+

Writes a new file with Studio's Prepare and never touches the original. The copy is then compared with the original part by part. Studio refuses a file whose tool it cannot identify.

+
+ setOutDir(e.target.value)} /> + +
+
+ )} + {unlinked.length > 0 &&
+

Written earlier but not linked to the job:

+
    {unlinked.map((t, i) =>
  • {t}
  • )}
+ +
} + {linkNote &&

{linkNote}

} + {prepared && }
); } diff --git a/desktop/src/components/creative/creative.test.tsx b/desktop/src/components/creative/creative.test.tsx index 955c3ed3..466f42f5 100644 --- a/desktop/src/components/creative/creative.test.tsx +++ b/desktop/src/components/creative/creative.test.tsx @@ -2,9 +2,11 @@ import { describe, expect, it } from "vitest"; import { renderToStaticMarkup } from "react-dom/server"; import CreativeReportView from "./CreativeReportView"; import CreativeView from "./CreativeView"; +import CreativeFormatChooser from "./CreativeFormatChooser"; +import CreativePreparePanel, { ExportVerification } from "./CreativePreparePanel"; import creativeRoute from "@/routes/ext/creative.route"; import creativeMeta from "@/routes/ext/creative.meta"; -import type { CreativeInspectResponse } from "@/lib/creativeApi"; +import type { CreativeFormatInfo, CreativeInspectResponse, CreativePrepareResponse } from "@/lib/creativeApi"; const HASH = "a".repeat(64); @@ -85,7 +87,161 @@ describe("creative view", () => { it("renders the path input, format choice and a disabled inspect button", () => { const html = renderToStaticMarkup(); expect(html).toContain("Project file path"); - expect(html).toContain("Detect from settings"); + expect(html).toContain("Detect from markers and settings"); expect(html).toMatch(/]*disabled[^>]*>Inspect project/); }); + + it("offers every supported tool in the format list, including the three new readers", () => { + const html = renderToStaticMarkup(); + for (const label of ["DitherForge", "Kromacut", "SindriCAD", "OrcaSlicer ImageMap", "Lumina Layers"]) expect(html).toContain(label); + }); +}); + +const FORMAT: CreativeFormatInfo = { + key: "imagemap", label: "OrcaSlicer ImageMap", carrier: "3MF (ZIP) with 3D/3dmodel.model", selection: "manual only", + identified_by: [], reads: ["3MF artifact identity (size, SHA-256, member list)"], kept_untouched: ["every part"], + not_read: ["the zone shape: not established"], upstream: null, +}; + +describe("format chooser", () => { + it("says plainly what is and is not read for a manual-only format", () => { + const html = renderToStaticMarkup( undefined} formats={[FORMAT]} needsChoice={false} />); + expect(html).toContain("read only when you choose it"); + expect(html).toContain("Studio reads"); + expect(html).toContain("3MF artifact identity"); + expect(html).toContain("Studio does not read"); + expect(html).toContain("the zone shape: not established"); + expect(html).toContain("cannot confirm the file really came from this tool"); + }); + + it("words automatic identification as conditional on markers being present", () => { + const html = renderToStaticMarkup( undefined} formats={[{ ...FORMAT, key: "sindricad", label: "SindriCAD", selection: "automatic", identified_by: ["model metadata Application `SindriCAD`"] }]} needsChoice={false} />); + expect(html).toContain("identified automatically only when its markers are present in the file"); + expect(html).not.toContain("detected automatically"); + expect(html).not.toContain("Prepare limits"); + }); + + it("states a format's Prepare limits when the engine lists them", () => { + const html = renderToStaticMarkup( undefined} formats={[{ ...FORMAT, key: "ditherforge", label: "DitherForge", selection: "automatic", prepare_limits: ["The generic-path export is inspect-only."] }]} needsChoice={false} />); + expect(html).toContain("Prepare limits"); + expect(html).toContain("The generic-path export is inspect-only."); + }); + + it("asks for a choice when detection could not decide, and not otherwise", () => { + const ask = renderToStaticMarkup( undefined} formats={[]} needsChoice />); + expect(ask).toContain("Studio could not decide the tool"); + const quiet = renderToStaticMarkup( undefined} formats={[]} needsChoice={false} />); + expect(quiet).not.toContain("Studio could not decide the tool"); + expect(quiet).toContain("does not guess the tool"); + }); +}); + +describe("inspection of the new tools", () => { + it("shows facts read from a SindriCAD file and its read and not-read lists", () => { + const html = renderToStaticMarkup(); + expect(html).toContain("Looks like SindriCAD"); + expect(html).toContain("Body count: 2"); + expect(html).toContain("Bodies: Plate (extruder 1), Lid (extruder 2)"); + expect(html).toContain("Per-face paint: 2 painted triangle(s)"); + expect(html).toContain("SindriCAD: what is and is not read"); + expect(html).toContain("mesh geometry beyond counts"); + }); + + it("explains an undecided origin: what was seen, what is not supported, what to do", () => { + const html = renderToStaticMarkup(); + expect(html).toContain("does not recognise this file's tool"); + expect(html).toContain("What Studio saw."); + expect(html).toContain("What is not supported."); + expect(html).toContain("What to do."); + expect(html).toContain("Choose the format you know it came from."); + }); +}); + +const BASE_SOURCE = { name: "x.3mf", size_bytes: 1, sha256_before: HASH, sha256_after: HASH, unchanged: true }; + +describe("prepare panel", () => { + const done: CreativePrepareResponse = { + prepared: true, origin: { generator: "sindricad", status: "detected", candidates: ["sindricad"] }, + output: { name: "x_SnapmakerU1.3mf", local_path: "synthetic/prepared-copy.3mf", location: "studio_default", location_label: "Studio's creative-prepared folder", in_source_folder: false }, + prepare: { mode: "preserve", validated_ok: true, errors: [], compat_changed: [], mapped_to_u1: [], could_not_carry: [], warnings: [] }, + verification: { opens_as_zip: true, members: [{ name: "a", sha256: HASH }, { name: "b", sha256: HASH }], + comparison: { preserved: ["3D/3dmodel.model"], modified: ["Metadata/project_settings.config"], dropped: ["Metadata/gone.bin"], added: ["Metadata/new.bin"] }, + settings: { removed_keys: [], changed_keys: ["layer_height"], added_key_count: 64 }, + per_face_paint: { original_triangles: 2, exported_triangles: 2, kept: true } }, + loss_notes: ["1 part(s) of the original are not in the copy: Metadata/gone.bin."], + original: { name: "x.3mf", sha256_before: HASH, sha256_after: HASH, original_unchanged: true }, + source: BASE_SOURCE, advisory: "Advisory comparison by part name and content hash.", + }; + + it("shows the four export buckets, paint count, loss notes and the unchanged original", () => { + const html = renderToStaticMarkup(); + expect(html).toContain("Kept identical (1)"); + expect(html).toContain("Changed (1)"); + expect(html).toContain("Dropped (1)"); + expect(html).toContain("Added (1)"); + expect(html).toContain("Metadata/gone.bin"); + expect(html).toContain("2 painted triangle(s) in the original, 2 in the copy"); + expect(html).toContain("Project settings: 0 removed, 1 changed, 64 added"); + expect(html).toContain("It is not next to the original."); + expect(html).toContain("Original unchanged"); + expect(html).toContain("Review it in Snapmaker Orca before slicing"); + }); + + it("headings use the engine totals and say 'showing N of M' when a name list is capped", () => { + const names = Array.from({ length: 200 }, (_, i) => `Metadata/p${i}.bin`); + const html = renderToStaticMarkup(); + expect(html).toContain("Kept identical (250)"); + expect(html).toContain("showing 200 of 250"); + expect(html).not.toContain("showing 0 of"); + expect(html).toContain("Project settings: 300 removed, 0 changed, 2 added"); + }); + + it("names the saved location with a label only, never a folder path", () => { + const html = renderToStaticMarkup(); + expect(html).toContain("Saved in: the folder you chose."); + expect(html).not.toMatch(/[A-Za-z]:\\|\/Users\/|\/home\//); + }); + + it("does not claim the original is unchanged when its fingerprint moved", () => { + const html = renderToStaticMarkup(); + expect(html).not.toContain("Original unchanged"); + expect(html).toContain("differs between the two reads"); + }); + + it("says when the exported file could not be re-read", () => { + const html = renderToStaticMarkup(); + expect(html).toContain("could not be re-read"); + expect(html).toContain("not a readable 3MF archive"); + }); + + it("explains a refusal and says nothing was written", () => { + const html = renderToStaticMarkup(); + expect(html).toContain("No copy was written"); + expect(html).toContain("This file was read as Kromacut."); + expect(html).toContain("can vouch for"); + expect(html).toContain("What the check found"); + expect(html).toContain("reference an object that no file defines"); + }); + + it("uses no readiness or guarantee wording in prepare copy", () => { + const all = (renderToStaticMarkup() + renderToStaticMarkup() + + renderToStaticMarkup( undefined} formats={[]} needsChoice />)).toLowerCase(); + for (const banned of ["ready", "coming soon", "guarantee", "100%", "print success", "printer doctor"]) expect(all).not.toContain(banned); + }); }); diff --git a/desktop/src/lib/creativeApi.test.ts b/desktop/src/lib/creativeApi.test.ts index 94938a0d..ca3de6be 100644 --- a/desktop/src/lib/creativeApi.test.ts +++ b/desktop/src/lib/creativeApi.test.ts @@ -1,5 +1,8 @@ import { afterEach, describe, expect, it, vi } from "vitest"; -import { buildInspectBody, inspectCreative, originSentence } from "./creativeApi"; +import { + buildInspectBody, buildPrepareBody, comparisonBuckets, factLines, fetchCreativeFormats, inspectCreative, + originSentence, prepareCreative, settingsTotals, +} from "./creativeApi"; vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn().mockResolvedValue({ port: 4321, token: "test-token" }) })); const originalFetch = globalThis.fetch; @@ -36,7 +39,55 @@ describe("creative API client", () => { it("keeps an unknown origin unknown and an ambiguous one undecided", () => { expect(originSentence({ generator: "unknown", status: "unknown", candidates: [] })).toContain("Origin unknown"); expect(originSentence({ generator: "unknown", status: "ambiguous", candidates: ["forcaslicer", "lixnix"] })) - .toBe("Origin not decided: the settings match FOrcaSlicer and LixNix Full Multi-Nozzle."); + .toBe("Origin not decided: the file's markers or settings match FOrcaSlicer and LixNix Full Multi-Nozzle."); expect(originSentence({ generator: "fullspectrum", status: "detected", candidates: ["fullspectrum"] })).toContain("Looks like FullSpectrum"); + expect(originSentence({ generator: "sindricad", status: "detected", candidates: ["sindricad"] })).toContain("Looks like SindriCAD"); + }); + + it("builds the prepare body with an output folder only when one was typed", () => { + expect(buildPrepareBody("a.3mf")).toEqual({ path: "a.3mf" }); + expect(buildPrepareBody(" a.3mf ", "sindricad", ' "D:\\out" ')).toEqual({ path: "a.3mf", format: "sindricad", out_dir: "D:\\out" }); + expect(() => buildPrepareBody("", "auto", "x")).toThrow("Enter the path"); + }); + + it("posts to /creative/prepare and /creative/formats", async () => { + const fetchMock = vi.fn().mockImplementation(() => Promise.resolve(new Response(JSON.stringify({ prepared: false, formats: [] }), { + status: 200, headers: { "Content-Type": "application/json" } }))); + globalThis.fetch = fetchMock; + await prepareCreative("a.3mf", "kromacut"); + await fetchCreativeFormats(); + expect(fetchMock).toHaveBeenNthCalledWith(1, "http://127.0.0.1:4321/creative/prepare", expect.objectContaining({ + method: "POST", body: JSON.stringify({ path: "a.3mf", format: "kromacut" }) })); + expect(fetchMock).toHaveBeenNthCalledWith(2, "http://127.0.0.1:4321/creative/formats", expect.objectContaining({ method: "POST", body: "{}" })); + }); + + it("turns reader facts into plain lines and skips facts that are absent", () => { + const lines = factLines({ application: "SindriCAD", body_count: 2, painted_triangle_count: 0, + bodies: [{ name: "Plate", extruder: 1 }], filament_colour: ["#FF0000", "#0000FF"], paint_extruders_used: [] }); + expect(lines).toContain("Written by (Application tag): SindriCAD"); + expect(lines).toContain("Body count: 2"); + expect(lines).toContain("Per-face paint: none found"); + expect(lines).toContain("Bodies: Plate (extruder 1)"); + expect(lines).toContain("Filament colours: #FF0000, #0000FF"); + expect(lines.some((l) => l.startsWith("Extruders used by paint"))).toBe(false); + expect(factLines(undefined)).toEqual([]); + }); + + it("orders the comparison buckets kept, changed, dropped, added", () => { + const buckets = comparisonBuckets({ opens_as_zip: true, comparison: { preserved: ["a"], modified: ["b"], dropped: ["c"], added: ["d"] } }); + expect(buckets.map((b) => `${b.key}:${b.items.join("")}`)).toEqual(["preserved:a", "modified:b", "dropped:c", "added:d"]); + expect(buckets.every((b) => b.total === 1 && !b.truncated)).toBe(true); + }); + + it("uses the engine totals for the bucket headings and flags a capped list", () => { + const buckets = comparisonBuckets({ opens_as_zip: true, comparison: { preserved: ["a", "b"], modified: [], dropped: [], added: [] }, + counts: { preserved: 250, modified: 0, dropped: 0, added: 0 } }); + expect(buckets[0]).toMatchObject({ total: 250, truncated: true }); + expect(buckets[1]).toMatchObject({ total: 0, truncated: false }); + }); + + it("settings totals come from the counts, not from the bounded key lists", () => { + expect(settingsTotals({ removed_keys: ["a"], removed_count: 9, changed_keys: [], changed_count: 4, added_key_count: 2 })).toEqual({ removed: 9, changed: 4, added: 2 }); + expect(settingsTotals({ removed_keys: ["a"], changed_keys: ["b", "c"], added_key_count: 0 })).toEqual({ removed: 1, changed: 2, added: 0 }); }); }); diff --git a/desktop/src/lib/creativeApi.ts b/desktop/src/lib/creativeApi.ts index 12cccbb4..8e277695 100644 --- a/desktop/src/lib/creativeApi.ts +++ b/desktop/src/lib/creativeApi.ts @@ -19,21 +19,85 @@ export interface CreativeOrigin { candidates: string[]; } +/** What one supported format reads and does not read. Mirrors SUPPORTED_FORMATS in the engine. */ +export interface CreativeFormatInfo { + key: string; + label: string; + carrier: string; + selection: "automatic" | "manual only"; + identified_by: string[]; + reads: string[]; + kept_untouched: string[]; + not_read: string[]; + /** Why Prepare may refuse files of this format, when it does. Absent when there is nothing to say. */ + prepare_limits?: string[]; + upstream: string | null; +} + +export interface CreativeExplanation { + kind: "unknown_origin" | "ambiguous_origin"; + seen: string; + not_supported: string; + what_to_do: string[]; +} + +export interface CreativeSourceInfo { name: string; size_bytes: number; sha256_before: string; sha256_after: string; unchanged: boolean } + export interface CreativeInspectResponse { origin: CreativeOrigin; understood: string[]; + facts?: Record>; passed_through: CreativeNamedPart[]; could_not_interpret: string[]; missing: string[]; diagnostics: string[]; recipes: CreativeRecipe[]; physical_slots_needed: number | null; - source: { name: string; size_bytes: number; sha256_before: string; sha256_after: string; unchanged: boolean }; + format_info?: CreativeFormatInfo[]; + explanation?: CreativeExplanation | null; + source: CreativeSourceInfo; evidence: string; advisory: string; } -export const CREATIVE_FORMATS = ["auto", "forcaslicer", "lixnix", "fullspectrum", "imagemap", "lumina"] as const; +export interface CreativeComparison { preserved: string[]; modified: string[]; dropped: string[]; added: string[] } + +export interface CreativeVerification { + opens_as_zip: boolean; + problem?: string; + size_bytes?: number; + sha256?: string; + members?: CreativeNamedPart[]; + comparison?: CreativeComparison; + counts?: Record; + settings?: { removed_keys: string[]; removed_count?: number; changed_keys: string[]; changed_count?: number; added_key_count: number }; + per_face_paint?: { original_triangles: number | null; exported_triangles: number | null; kept: boolean | null }; +} + +export interface CreativePrepareDone { + prepared: true; + origin: CreativeOrigin; + /** `local_path` is the one field that names a location; the UI uses it to link the copy to its job (Passport can then show it in a path field, like every job path). */ + output: { name: string; local_path: string; location: "studio_default" | "chosen"; location_label: string; in_source_folder: boolean }; + prepare: { mode: string; validated_ok: boolean; errors: string[]; compat_changed: unknown[]; mapped_to_u1: unknown[]; could_not_carry: unknown[]; warnings: unknown[] }; + verification: CreativeVerification; + loss_notes: string[]; + original: { name: string; sha256_before: string; sha256_after: string; original_unchanged: boolean }; + source: CreativeSourceInfo; + advisory: string; +} + +export interface CreativePrepareRefused { + prepared: false; + refusal: { kind: string; seen: string; not_supported: string; what_to_do: string[]; problems?: string[] }; + origin: CreativeOrigin; + source: CreativeSourceInfo; + advisory: string; +} + +export type CreativePrepareResponse = CreativePrepareDone | CreativePrepareRefused; + +export const CREATIVE_FORMATS = ["auto", "ditherforge", "kromacut", "sindricad", "forcaslicer", "lixnix", "fullspectrum", "imagemap", "lumina"] as const; export type CreativeFormat = (typeof CREATIVE_FORMATS)[number]; /** The request body for one inspection. A blank path is a sentence for the person, not a request. */ @@ -43,12 +107,36 @@ export function buildInspectBody(path: string, format: CreativeFormat = "auto"): return format === "auto" ? { path: trimmed } : { path: trimmed, format }; } +/** The project path exactly as it is sent (surrounding quotes removed), so the job record names the file that was prepared. */ +export const normalizedProjectPath = (path: string): string => buildInspectBody(path).path; + /** Inspect one local project file through the local service. Read-only; nothing is sent off this computer. */ export function inspectCreative(path: string, format: CreativeFormat = "auto"): Promise { return callExt("/creative/inspect", buildInspectBody(path, format), "Creative project inspection"); } -const GENERATOR_LABEL: Record = { +/** The format list from the engine: what each format reads and does not. */ +export function fetchCreativeFormats(): Promise<{ formats: CreativeFormatInfo[]; manual_only: string[]; note: string }> { + return callExt("/creative/formats", {}, "Creative formats"); +} + +/** The request body for one Prepare. The output folder is sent only when the person typed one. */ +export function buildPrepareBody(path: string, format: CreativeFormat = "auto", outDir = ""): { path: string; format?: CreativeFormat; out_dir?: string } { + const body: { path: string; format?: CreativeFormat; out_dir?: string } = buildInspectBody(path, format); + const folder = outDir.trim().replace(/^"(.*)"$/, "$1"); + if (folder !== "") body.out_dir = folder; + return body; +} + +/** Write a new prepared copy through the local service and compare it with the original. */ +export function prepareCreative(path: string, format: CreativeFormat = "auto", outDir = ""): Promise { + return callExt("/creative/prepare", buildPrepareBody(path, format, outDir), "Prepare a U1 copy"); +} + +export const GENERATOR_LABEL: Record = { + ditherforge: "DitherForge", + kromacut: "Kromacut", + sindricad: "SindriCAD", forcaslicer: "FOrcaSlicer", lixnix: "LixNix Full Multi-Nozzle", fullspectrum: "FullSpectrum", @@ -60,9 +148,84 @@ const GENERATOR_LABEL: Record = { export function originSentence(origin: CreativeOrigin): string { if (origin.status === "ambiguous") { const names = origin.candidates.map((c) => GENERATOR_LABEL[c] ?? c).join(" and "); - return `Origin not decided: the settings match ${names}.`; + return `Origin not decided: the file's markers or settings match ${names}.`; } if (origin.generator === "unknown") return "Origin unknown: Studio does not recognise the generator of this project."; const name = GENERATOR_LABEL[origin.generator] ?? origin.generator; - return origin.status === "chosen" ? `Read as ${name} (your choice).` : `Looks like ${name}, from the settings it contains.`; + return origin.status === "chosen" ? `Read as ${name} (your choice).` : `Looks like ${name}, from the markers or settings it contains.`; +} + +function colours(value: unknown): string { + return Array.isArray(value) ? value.map((c) => (typeof c === "string" ? c : "?")).join(", ") : ""; +} + +function named(items: unknown, key: string): string { + if (!Array.isArray(items)) return ""; + return items.map((i) => { + const row = i as Record; + return `${String(row.name ?? "unnamed")} (${key} ${String(row[key] ?? "unknown")})`; + }).join(", "); +} + +/** Plain lines for the facts a reader proved from the file. A fact that is absent produces no line. */ +export function factLines(facts: Record | undefined): string[] { + if (!facts) return []; + const out: string[] = []; + const add = (label: string, value: unknown) => { + if (value === undefined || value === null || value === "") return; + out.push(`${label}: ${String(value)}`); + }; + add("Written by (Application tag)", facts.application); + add("Variant", facts.variant === "bambu_project" ? "Bambu-style project tag" : facts.variant); + add("Objects in the build", facts.build_item_count); + add("Body count", facts.body_count); + add("Colour layer objects", facts.layer_object_count); + if (facts.assembly_present === true) out.push("Layers are grouped in one assembly object"); + add("Layer height (mm)", facts.layer_height); + add("First layer height (mm)", facts.first_layer_height); + add("Triangles", facts.triangle_count); + if (typeof facts.painted_triangle_count === "number") { + out.push(facts.painted_triangle_count > 0 + ? `Per-face paint: ${facts.painted_triangle_count} painted triangle(s)` + : "Per-face paint: none found"); + } + if (Array.isArray(facts.paint_extruders_used) && facts.paint_extruders_used.length > 0) { + add("Extruders used by paint", facts.paint_extruders_used.join(", ")); + } + add("Objects", named(facts.objects, "extruder")); + add("Bodies", named(facts.bodies, "extruder")); + add("Parts", named(facts.parts, "extruder")); + const palette = Array.isArray(facts.palette) ? facts.palette.map((p) => `${String((p as Record).name)} ${String((p as Record).colour)}`).join(", ") : ""; + add("Base materials", palette); + add("Filament colours", colours(facts.filament_colour)); + add("Filament types", colours(facts.filament_type)); + add("Printer settings id", facts.printer_settings_id); + return out; +} + +export interface CreativeBucket { key: keyof CreativeComparison; title: string; note: string; items: string[]; total: number; truncated: boolean } + +/** + * The four buckets of the export comparison, in the order a person reads them. `total` is the engine's + * own count (verification.counts) and falls back to the listed names only when the engine sent none; + * `truncated` is true when the name list is shorter than the total. + */ +export function comparisonBuckets(v: CreativeVerification): CreativeBucket[] { + const c = v.comparison; + const bucket = (key: keyof CreativeComparison, title: string, note: string): CreativeBucket => { + const items = c?.[key] ?? []; + const total = v.counts?.[key] ?? items.length; + return { key, title, note, items, total, truncated: total > items.length }; + }; + return [ + bucket("preserved", "Kept identical", "Same part name and same content fingerprint as the original."), + bucket("modified", "Changed", "Same part name, different content."), + bucket("dropped", "Dropped", "In the original, not in the copy."), + bucket("added", "Added", "In the copy, not in the original."), + ]; +} + +/** Project-settings totals from the engine's counts; the key lists are bounded and may be shorter. */ +export function settingsTotals(s: NonNullable): { removed: number; changed: number; added: number } { + return { removed: s.removed_count ?? s.removed_keys.length, changed: s.changed_count ?? s.changed_keys.length, added: s.added_key_count }; } diff --git a/desktop/src/lib/lumina/LuminaResultCard.tsx b/desktop/src/lib/lumina/LuminaResultCard.tsx new file mode 100644 index 00000000..9cc834d9 --- /dev/null +++ b/desktop/src/lib/lumina/LuminaResultCard.tsx @@ -0,0 +1,41 @@ +import type { LuminaGenerateResponse, LuminaStatusResponse } from "./luminaApi"; + +/** The generated file, by name only. Studio shows no folder path: the label says which folder. */ +export function LuminaResultCard({ result }: { result: LuminaGenerateResponse }) { + return ( +
+

A new {result.kind} file was saved

+
+
File name
{result.file_name}
+
Kind
{result.kind}
+
Size
{result.size_bytes} bytes
+
SHA-256
{result.sha256}
+
Saved in
{result.location_label}
+
Made by
{result.generated_by}
+
Progress and cancel
Unknown: the service does not publish a route Studio can rely on.
+
+

{result.advisory}

+

Your original image was not changed. Studio does not slice this file; open it in your slicer to review it.

+
+ ); +} + +/** What the identity check said, kept to what was actually read. */ +export function LuminaStatusNote({ status }: { status: LuminaStatusResponse }) { + if (status.status === "ok") { + return ( +
+

The service answered Studio's identity check (API version {status.api_version ?? "unknown"}).

+

+ {status.can_generate ? "It offers the routes Studio uses." : "It does not offer every route Studio uses."} {status.note} +

+
+ ); + } + return ( +
+

Unknown: Studio could not confirm this service.

+

{status.message}

+
+ ); +} diff --git a/desktop/src/lib/lumina/LuminaView.tsx b/desktop/src/lib/lumina/LuminaView.tsx new file mode 100644 index 00000000..64f32790 --- /dev/null +++ b/desktop/src/lib/lumina/LuminaView.tsx @@ -0,0 +1,93 @@ +import { useEffect, useRef, useState } from "react"; +import { Layers } from "lucide-react"; +import { Button } from "@/components/ui/button"; +import { PageHeader } from "@/components/ui/layout"; +import { + buildGenerateBody, checkLuminaService, fetchLuminaFormats, generateWithLumina, + type LuminaForm, type LuminaFormat, type LuminaGenerateResponse, type LuminaStatusResponse, +} from "./luminaApi"; +import { LuminaResultCard, LuminaStatusNote } from "./LuminaResultCard"; + +const field = "h-9 rounded-md border border-border bg-card px-3 text-sm outline-none focus-visible:ring-2 focus-visible:ring-primary/50"; + +/** The inputs. The format has no default: it is chosen from the list the service layer returns. */ +export function LuminaFields({ form, formats, formatsError, busy, onChange, onCheck, onGenerate }: { + form: LuminaForm; + formats: readonly LuminaFormat[]; + formatsError: string | null; + busy: boolean; + onChange: (next: LuminaForm) => void; + onCheck: () => void; + onGenerate: () => void; +}) { + const chosen = formats.find((f) => f.kind === form.format); + const complete = form.serviceUrl.trim() !== "" && form.imagePath.trim() !== "" && form.lutName.trim() !== "" && chosen !== undefined; + return ( +
+
+ onChange({ ...form, serviceUrl: e.target.value })} /> + onChange({ ...form, imagePath: e.target.value })} /> + onChange({ ...form, lutName: e.target.value })} /> + + + +
+ {formatsError &&

{formatsError}

} + {chosen + ?

{chosen.kind}: {chosen.meaning} Tested against: {chosen.evidence}.

+ :

Studio does not guess the format: pick one from the list ({formats.map((f) => f.kind).join(", ") || "loading"}).

} +
+ ); +} + +/** Sends one image to a local Lumina-compatible service you run and saves what it returns as a new file. + * Studio does not slice and never controls a printer from here. */ +export default function LuminaView() { + const [form, setForm] = useState({ serviceUrl: "", imagePath: "", lutName: "", format: "" }); + const [formats, setFormats] = useState([]); + const [formatsError, setFormatsError] = useState(null); + const [busy, setBusy] = useState(false); + const [error, setError] = useState(null); + const [status, setStatus] = useState(null); + const [result, setResult] = useState(null); + const alive = useRef(true); + + useEffect(() => { + alive.current = true; + fetchLuminaFormats() + .then((res) => { if (alive.current) setFormats(res.formats); }) + .catch((e) => { if (alive.current) setFormatsError(e instanceof Error ? e.message : "The format list could not be loaded."); }); + return () => { alive.current = false; }; + }, []); + + const run = async (task: () => Promise) => { + setBusy(true); setError(null); setStatus(null); setResult(null); + try { await task(); } + catch (e) { if (alive.current) setError(e instanceof Error ? e.message : "The request failed."); } + finally { if (alive.current) setBusy(false); } + }; + + const check = () => run(async () => { + const res = await checkLuminaService(form.serviceUrl); + if (alive.current) setStatus(res); + }); + const generate = () => run(async () => { + const res = await generateWithLumina(buildGenerateBody(form, formats)); + if (alive.current) setResult(res); + }); + + return ( +
+ +

Tested only against a synthetic stand-in service. No real Lumina installation has been exercised, and Studio has not verified the service you point it at.

+ void check()} onGenerate={() => void generate()} /> + {error &&

{error}

} + {status && } + {result && } +
+ ); +} diff --git a/desktop/src/lib/lumina/lumina.test.tsx b/desktop/src/lib/lumina/lumina.test.tsx new file mode 100644 index 00000000..885e731a --- /dev/null +++ b/desktop/src/lib/lumina/lumina.test.tsx @@ -0,0 +1,130 @@ +import { describe, expect, it } from "vitest"; +import { renderToStaticMarkup } from "react-dom/server"; +import LuminaView, { LuminaFields } from "./LuminaView"; +import { LuminaResultCard, LuminaStatusNote } from "./LuminaResultCard"; +import { buildGenerateBody, type LuminaForm, type LuminaFormat, type LuminaGenerateResponse } from "./luminaApi"; +import luminaRoute from "@/routes/ext/lumina.route"; +import luminaMeta from "@/routes/ext/lumina.meta"; + +const HASH = "b".repeat(64); +const FORMATS: LuminaFormat[] = [ + { kind: "3mf", meaning: "A 3MF model file returned by the service.", evidence: "mock-service-tested" }, + { kind: "png", meaning: "A PNG preview image returned by the service.", evidence: "mock-service-tested" }, + { kind: "glb", meaning: "A binary glTF (GLB) preview model returned by the service.", evidence: "mock-service-tested" }, +]; +const EMPTY: LuminaForm = { serviceUrl: "", imagePath: "", lutName: "", format: "" }; +const noop = () => undefined; + +function fields(form: LuminaForm, over: Partial<{ formats: LuminaFormat[]; formatsError: string | null; busy: boolean }> = {}) { + return renderToStaticMarkup( + , + ); +} + +const RESULT: LuminaGenerateResponse = { + generated: true, file_name: "lumina-abc123.png", sha256: HASH, size_bytes: 42, kind: "png", + generated_by: "a user-configured local Lumina-compatible service (not verified)", + location_label: "Studio's lumina-output folder", + advisory: "Studio did not watch this file being made.", + progress: "unknown", cancel: "unknown", evidence: "mock-service-tested", +}; + +describe("lumina route wiring", () => { + it("route default export has the { path, Component } shape and meta agrees", () => { + expect(Object.keys(luminaRoute).sort()).toEqual(["Component", "path"]); + expect(typeof luminaRoute.Component).toBe("function"); + expect(luminaRoute.path).toBe("/lumina"); + expect(luminaMeta.path).toBe(luminaRoute.path); + expect(luminaMeta.group).toBe("Studio+"); + }); +}); + +describe("buildGenerateBody", () => { + const good: LuminaForm = { serviceUrl: " http://192.168.1.20:8000 ", imagePath: " a.png ", lutName: " Default ", format: "png" }; + + it("trims fields and sends the chosen format", () => { + expect(buildGenerateBody(good, FORMATS)).toEqual({ + service_url: "http://192.168.1.20:8000", image_path: "a.png", lut_name: "Default", format: "png", + }); + }); + + it("includes out_dir only when typed", () => { + expect(buildGenerateBody({ ...good, outDir: " " }, FORMATS)).not.toHaveProperty("out_dir"); + expect(buildGenerateBody({ ...good, outDir: " D:/out " }, FORMATS).out_dir).toBe("D:/out"); + }); + + it("never infers a format: empty or unlisted is refused and names the list", () => { + for (const format of ["", "stl", "PNG"]) { + expect(() => buildGenerateBody({ ...good, format }, FORMATS)).toThrow(/3mf, png, glb/); + } + }); + + it("refuses missing address, image or LUT", () => { + expect(() => buildGenerateBody({ ...good, serviceUrl: " " }, FORMATS)).toThrow(/address/); + expect(() => buildGenerateBody({ ...good, imagePath: "" }, FORMATS)).toThrow(/image/); + expect(() => buildGenerateBody({ ...good, lutName: "" }, FORMATS)).toThrow(/LUT/); + }); +}); + +describe("LuminaFields", () => { + it("starts empty with no preselected format and Generate disabled", () => { + const html = fields(EMPTY); + expect(html).toContain("Choose a format"); + expect(html).toContain("Studio does not guess the format"); + expect(html).toMatch(/]*disabled=""[^>]*>Generate<\/button>/); + expect(html).not.toMatch(/]*selected[^>]*>(3mf|png|glb)${f.kind}`); + }); + + it("explains the chosen format and enables Generate when complete", () => { + const html = fields({ serviceUrl: "http://127.0.0.1:8000", imagePath: "a.png", lutName: "Default", format: "glb" }); + expect(html).toContain("A binary glTF (GLB) preview model returned by the service."); + expect(html).toContain("Tested against: mock-service-tested."); + expect(html).not.toMatch(/]*disabled=""[^>]*>Generate<\/button>/); + }); + + it("shows a format-list failure plainly and disables the selector", () => { + const html = fields(EMPTY, { formats: [], formatsError: "Lumina formats failed (500)" }); + expect(html).toContain("Lumina formats failed (500)"); + expect(html).toMatch(/]*disabled=""/); + }); +}); + +describe("LuminaResultCard and LuminaStatusNote", () => { + it("shows name, hash, size, kind, label and the advisory without any folder path", () => { + const html = renderToStaticMarkup(); + for (const text of ["lumina-abc123.png", HASH, "42 bytes", "Studio's lumina-output folder", "not verified", + "did not watch", "Your original image was not changed", "does not slice"]) { + expect(html).toContain(text); + } + expect(html).not.toMatch(/[A-Za-z]:[\\/]/); + expect(html).not.toContain("Users"); + }); + + it("reports unknown status as unknown, not as failure of the image", () => { + const html = renderToStaticMarkup( + , + ); + expect(html).toContain("Unknown: Studio could not confirm this service."); + expect(html).toContain("Not tested."); + }); + + it("ok status claims only that the identity check was answered", () => { + const html = renderToStaticMarkup( + , + ); + expect(html).toContain("answered Studio's identity check (API version 2.0)"); + expect(html).toContain("not proof"); + }); +}); + +describe("LuminaView first render", () => { + it("is honest that only a synthetic stand-in was tested and offers no action beyond a local service", () => { + const html = renderToStaticMarkup(); + expect(html).toContain("synthetic stand-in"); + expect(html).toContain("No real Lumina installation has been exercised"); + expect(html).toContain("Studio does not slice"); + expect(html).not.toMatch(/guaranteed|100%|\bready\b/i); + }); +}); diff --git a/desktop/src/lib/lumina/luminaApi.ts b/desktop/src/lib/lumina/luminaApi.ts new file mode 100644 index 00000000..7dcdbc9c --- /dev/null +++ b/desktop/src/lib/lumina/luminaApi.ts @@ -0,0 +1,88 @@ +import { callExt } from "../extApi"; + +/** One artifact kind the adapter supports, with what it means and how it was tested. */ +export interface LuminaFormat { + kind: string; + meaning: string; + evidence: string; +} + +export interface LuminaFormatsResponse { + formats: LuminaFormat[]; + evidence: string; + progress: "unknown"; + cancel: "unknown"; + note: string; +} + +export interface LuminaStatusResponse { + status: "ok" | "unknown"; + api_version?: string; + can_generate?: boolean; + code?: string; + message?: string; + progress: "unknown"; + cancel: "unknown"; + evidence: string; + note?: string; +} + +export interface LuminaGenerateRequest { + service_url: string; + image_path: string; + lut_name: string; + format: string; + out_dir?: string; +} + +export interface LuminaGenerateResponse { + generated: true; + file_name: string; + sha256: string; + size_bytes: number; + kind: string; + generated_by: string; + location_label: string; + advisory: string; + progress: "unknown"; + cancel: "unknown"; + evidence: string; +} + +export interface LuminaForm { + serviceUrl: string; + imagePath: string; + lutName: string; + format: string; + outDir?: string; +} + +/** Build the request. A missing field is an error here, never a guess: the format in particular is a + * choice from the service's explicit list, never inferred from the image. */ +export function buildGenerateBody(form: LuminaForm, formats: readonly LuminaFormat[]): LuminaGenerateRequest { + const service_url = form.serviceUrl.trim(); + const image_path = form.imagePath.trim(); + const lut_name = form.lutName.trim(); + if (service_url === "") throw new Error("Enter the address of your local Lumina-compatible service."); + if (image_path === "") throw new Error("Enter the path of the image file on this computer."); + if (lut_name === "") throw new Error("Enter the LUT name the service should use."); + if (!formats.some((f) => f.kind === form.format)) { + throw new Error(`Choose a format from the list: ${formats.map((f) => f.kind).join(", ")}.`); + } + const body: LuminaGenerateRequest = { service_url, image_path, lut_name, format: form.format }; + const out = (form.outDir ?? "").trim(); + if (out !== "") body.out_dir = out; + return body; +} + +export function fetchLuminaFormats(): Promise { + return callExt("/engines/lumina/formats", {}, "Lumina formats"); +} + +export function checkLuminaService(serviceUrl: string): Promise { + return callExt("/engines/lumina/status", { service_url: serviceUrl.trim() }, "Lumina service check"); +} + +export function generateWithLumina(body: LuminaGenerateRequest): Promise { + return callExt("/engines/lumina/generate", body, "Lumina generate"); +} diff --git a/desktop/src/lib/passport/PassportView.tsx b/desktop/src/lib/passport/PassportView.tsx index b1bb8151..4eefbfc7 100644 --- a/desktop/src/lib/passport/PassportView.tsx +++ b/desktop/src/lib/passport/PassportView.tsx @@ -1,10 +1,12 @@ -import { useEffect, useRef, useState } from "react"; +import { useEffect, useState } from "react"; import { Fingerprint } from "lucide-react"; import { Button } from "@/components/ui/button"; import { PageHeader } from "@/components/ui/layout"; +import { useJob } from "@/store/job"; import { buildPassport, buildRequest, verifyPassport } from "./api"; import PassportReport from "./PassportReport"; -import type { BuildResponse, Verification } from "./types"; +import { belongsToOtherProject, fileFields, reportIsStale, usePassportSession } from "./session"; +import type { BuildResponse } from "./types"; const FIELD = "h-9 rounded-md border border-border bg-card px-3 text-sm outline-none focus-visible:ring-2 focus-visible:ring-primary/50"; const AREA = "min-h-20 w-full rounded-md border border-border bg-card p-2 font-mono text-xs outline-none focus-visible:ring-2 focus-visible:ring-primary/50"; @@ -15,43 +17,60 @@ const DIAGNOSTIC_TEXT: Record = { bad_role: "A file has a role this passport does not use.", }; -/** Builds a passport from files on this computer, then checks them against it. The files are - * only read; nothing is written, uploaded or sent to a printer. */ +const projectNow = (): string | null => useJob.getState().record?.original.path ?? null; +const nameOf = (path: string | null) => (path ? path.split(/[\\/]/).pop() || path : null); + +/** Builds a passport from files on this computer, then checks them against it. The files are only read; nothing is + * written, uploaded or sent to a printer. The fields and the report are kept while the application stays open + * (memory only), are tied to the project they were made for, and are cleared when a different project is opened. */ export default function PassportView() { - const [original, setOriginal] = useState(""); - const [prepared, setPrepared] = useState(""); - const [sliced, setSliced] = useState(""); - const [recipes, setRecipes] = useState(""); - const [mappings, setMappings] = useState(""); + const session = usePassportSession(); + const { inputs, built, verification, builtFor, notice } = session; + const record = useJob((state) => state.record); + const verified = useJob((state) => state.verified); + const current = record?.original.path ?? null; const [busy, setBusy] = useState(false); const [error, setError] = useState(null); - const [built, setBuilt] = useState(null); - const [verification, setVerification] = useState(null); - const alive = useRef(true); - useEffect(() => { alive.current = true; return () => { alive.current = false; }; }, []); + + const foreign = belongsToOtherProject(session, current); + useEffect(() => { + if (foreign) usePassportSession.getState().projectChanged("A different project is open now, so the earlier project's passport and file fields were cleared."); + }, [foreign, current]); + + const stale = reportIsStale(session); + const shown = foreign ? null : built; + const setField = (key: keyof typeof inputs) => (e: { target: { value: string } }) => session.setInput(key, e.target.value, projectNow()); const check = async (response: BuildResponse) => { if (!response.passport) return; + const gen = usePassportSession.getState().beginVerify(); const res = await verifyPassport({ passport: response.passport, paths: response.paths }); - if (alive.current) setVerification(res.verification); + // Only the latest check of the report it belongs to may land (an older answer never overwrites a newer one). + const now = usePassportSession.getState(); + if (res.verification && now.verifySeq === gen && now.built === response) now.setVerification(res.verification); }; const build = async () => { - setBusy(true); setError(null); setBuilt(null); setVerification(null); + setBusy(true); setError(null); + const startProject = projectNow(); + const snapshot = { ...usePassportSession.getState().inputs }; + usePassportSession.getState().clearBuilt(); + const buildGen = usePassportSession.getState().beginBuild(); try { - const response = await buildPassport(buildRequest({ original, prepared, sliced }, recipes, mappings)); - if (!alive.current) return; + const response = await buildPassport(buildRequest(fileFields(snapshot), snapshot.recipes, snapshot.mappings)); + // Another project was opened, or a newer build started (also from a re-entered page), while the files were read. + if (projectNow() !== startProject || usePassportSession.getState().buildSeq !== buildGen) return; if (!response.passport) { const code = response.diagnostics[0]?.code ?? ""; setError(DIAGNOSTIC_TEXT[code] ?? "The passport could not be built from those files."); return; } - setBuilt(response); + usePassportSession.getState().setBuilt(response, null, startProject, snapshot); await check(response); } catch (e) { - if (alive.current) setError(e instanceof Error ? e.message : "The passport could not be built."); + setError(e instanceof Error ? e.message : "The passport could not be built."); } finally { - if (alive.current) setBusy(false); + setBusy(false); } }; @@ -59,32 +78,42 @@ export default function PassportView() { if (!built) return; setBusy(true); setError(null); try { await check(built); } catch (e) { - if (alive.current) setError(e instanceof Error ? e.message : "The check failed."); - } finally { if (alive.current) setBusy(false); } + setError(e instanceof Error ? e.message : "The check failed."); + } finally { setBusy(false); } }; + const canBuild = inputs.original.trim() !== "" || inputs.prepared.trim() !== "" || inputs.sliced.trim() !== ""; return (
+ {notice &&

{notice}

}
- setOriginal(e.target.value)} /> - setPrepared(e.target.value)} /> - setSliced(e.target.value)} /> + + +
Recipes and material mappings (optional JSON lists)
-