"""Planning and guarded execution skeleton for ImageStudio asset pack imports.""" from __future__ import annotations import json import hashlib from pathlib import Path from typing import Any from backend.dto.common import ApiError, ErrorCode from backend.services.material_service import MaterialService from core.config_service import ConfigService from core.identity import RequestContext from core.storage import VfsStorage _MANIFEST_FILENAMES = {"manifest.json", "imagestudio-pack.json", "pack.json"} _MANIFEST_FILENAME_PRIORITY = { "imagestudio-pack.json": 0, "manifest.json": 1, "pack.json": 2, } class AssetImportService: def __init__( self, config_service: ConfigService | None = None, material_service: MaterialService | None = None, ): self.storage = VfsStorage(config_service) self.material_service = material_service def plan_import_pack( self, package_uri: str, *, dry_run: bool = True, allow_overwrite: bool = False, ctx: RequestContext | None = None, ) -> dict[str, Any]: root, relative = self.storage.split_uri(package_uri) package_path = self.storage.resolve_uri(package_uri) if not package_path.exists(): raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "asset pack not found", {"uri": package_uri}) files, total_bytes = _path_file_stats(package_path) manifest_candidates = _manifest_candidates(root, relative, package_path) manifest_summary = _manifest_summary(package_path, manifest_candidates) applied = {"materials": 0, "styles": 0, "material_ids": [], "created": 0, "updated": 0} unsupported_features = [] if manifest_summary["styles"]: unsupported_features.append( { "code": "STYLE_IMPORT_UNSUPPORTED", "message": "style entries are not imported by the current asset-pack service", "count": manifest_summary["styles"], } ) if not dry_run and not manifest_summary["valid"]: raise ApiError( ErrorCode.VALIDATION_FAILED, "asset pack manifest is invalid", {"field": "manifest", "errors": manifest_summary["errors"]}, ) if not dry_run and unsupported_features: raise ApiError( ErrorCode.VALIDATION_FAILED, "asset pack contains unsupported entries", {"field": "styles", "unsupported_features": unsupported_features}, ) if not dry_run: if self.material_service is None or ctx is None: raise ApiError( ErrorCode.VALIDATION_FAILED, "asset pack import execution is unavailable", {"field": "material_service"}, ) applied = self._apply_manifest( package_uri, root, relative, package_path, manifest_candidates[0], ctx, allow_overwrite=allow_overwrite, ) return { "dry_run": dry_run, "status": "planned" if dry_run else "applied", "package_uri": package_uri, "files": files, "bytes": total_bytes, "manifest_candidates": [item["uri"] for item in manifest_candidates], "manifest": manifest_summary, "import_enabled": manifest_summary["valid"] and not unsupported_features, "execution_enabled": manifest_summary["valid"] and not unsupported_features, "unsupported_features": unsupported_features, "applied": applied, } def _apply_manifest( self, package_uri: str, root: str, relative: Path, package_path: Path, manifest: dict[str, Any], ctx: RequestContext, *, allow_overwrite: bool = False, ) -> dict[str, Any]: payload = _load_manifest_payload(manifest["path"]) if _list_count(payload.get("styles")): raise ApiError( ErrorCode.VALIDATION_FAILED, "style entries are not supported by asset pack import", {"field": "styles"}, ) material_ids: list[str] = [] created_count = 0 updated_count = 0 base_relative = relative if package_path.is_dir() else relative.parent planned_materials: list[tuple[dict[str, Any], bool]] = [] planned_material_ids: set[str] = set() for index, item in enumerate(payload.get("materials") or []): if not isinstance(item, dict): raise ApiError( ErrorCode.VALIDATION_FAILED, "asset pack material entries must be objects", {"field": f"materials[{index}]"}, ) material_payload = _material_payload_from_manifest_item( item, root=root, base_relative=base_relative, package_uri=package_uri, manifest_uri=manifest["uri"], index=index, ) material_id = str(material_payload["material_id"]) if material_id in planned_material_ids: raise ApiError( ErrorCode.VALIDATION_FAILED, "asset pack contains duplicate material IDs", {"field": f"materials[{index}].material_id", "material_id": material_id}, ) planned_material_ids.add(material_id) self.storage.ensure_file(material_payload["image_uri"]) if material_payload.get("thumbnail_uri"): self.storage.ensure_file(material_payload["thumbnail_uri"]) existing = self.material_service.repository.get_material(material_payload["material_id"]) if existing is not None: self.material_service.get_material(material_payload["material_id"]) self.material_service.validate_material_payload(material_payload, creating=existing is None) planned_materials.append((material_payload, existing is None)) # An asset pack whose manifest reuses an existing material_id used to # silently rewrite that material -- image, tags, category and all -- # with no confirmation and no way to tell it had happened. Collect every # collision first so the caller sees the whole blast radius in one # response rather than discovering it one failed import at a time. conflicts = [ str(payload_item["material_id"]) for payload_item, creating in planned_materials if not creating ] if conflicts and not allow_overwrite: raise ApiError( ErrorCode.VALIDATION_FAILED, "asset pack would overwrite existing materials; retry with allow_overwrite=true to replace them", { "field": "materials", "conflicting_material_ids": sorted(conflicts), "conflicts": len(conflicts), }, ) for material_payload, creating in planned_materials: if creating: material = self.material_service.create_material(material_payload, ctx) created_count += 1 else: material = self.material_service.update_material(material_payload["material_id"], material_payload, ctx) updated_count += 1 material_ids.append(material.material_id) return { "materials": len(material_ids), "styles": 0, "material_ids": material_ids, "created": created_count, "updated": updated_count, } def _manifest_candidates(root: str, relative: Path, package_path: Path) -> list[dict[str, Any]]: if package_path.is_file(): return ( [{"uri": _storage_uri(root, relative), "path": package_path, "relative": Path(package_path.name)}] if package_path.name in _MANIFEST_FILENAMES else [] ) candidates: list[dict[str, Any]] = [] for child in package_path.rglob("*"): if child.is_file() and child.name in _MANIFEST_FILENAMES: pack_relative = child.relative_to(package_path) child_relative = relative / pack_relative candidates.append({"uri": _storage_uri(root, child_relative), "path": child, "relative": pack_relative}) return sorted(candidates, key=_manifest_sort_key) def _manifest_sort_key(item: dict[str, Any]) -> tuple[int, int, str]: relative = item["relative"] filename = relative.name return ( len(relative.parts), _MANIFEST_FILENAME_PRIORITY.get(filename, 99), item["uri"], ) def _manifest_summary(package_path: Path, candidates: list[dict[str, Any]]) -> dict[str, Any]: if not candidates: return { "present": False, "valid": False, "uri": None, "name": None, "version": None, "materials": 0, "styles": 0, "errors": [{"code": "MANIFEST_MISSING", "message": "asset pack manifest was not found"}], } selected = candidates[0] try: payload = json.loads(selected["path"].read_text(encoding="utf-8")) except json.JSONDecodeError as exc: return { "present": True, "valid": False, "uri": selected["uri"], "name": None, "version": None, "materials": 0, "styles": 0, "errors": [{"code": "MANIFEST_INVALID_JSON", "message": exc.msg, "line": exc.lineno}], } if not isinstance(payload, dict): return { "present": True, "valid": False, "uri": selected["uri"], "name": None, "version": None, "materials": 0, "styles": 0, "errors": [{"code": "MANIFEST_NOT_OBJECT", "message": "asset pack manifest must be a JSON object"}], } errors = _manifest_entry_errors(payload, package_path=package_path, manifest_path=selected["path"]) return { "present": True, "valid": not errors, "uri": selected["uri"], "name": _optional_text(payload.get("name")), "version": _optional_text(payload.get("version")), "materials": _list_count(payload.get("materials")), "styles": _list_count(payload.get("styles")), "errors": errors, } def _load_manifest_payload(path: Path) -> dict[str, Any]: payload = json.loads(path.read_text(encoding="utf-8")) if not isinstance(payload, dict): raise ApiError(ErrorCode.VALIDATION_FAILED, "asset pack manifest must be a JSON object", {"field": "manifest"}) return payload def _manifest_entry_errors(payload: dict[str, Any], *, package_path: Path, manifest_path: Path) -> list[dict[str, Any]]: errors: list[dict[str, Any]] = [] materials = payload.get("materials") if materials is not None and not isinstance(materials, list): errors.append( { "code": "MATERIALS_NOT_LIST", "message": "asset pack materials must be a list", "field": "materials", } ) return errors for index, item in enumerate(materials or []): field = f"materials[{index}]" if not isinstance(item, dict): errors.append( { "code": "MATERIAL_ENTRY_NOT_OBJECT", "message": "asset pack material entries must be objects", "field": field, } ) continue image_value = _optional_text(item.get("image_uri") or item.get("uri") or item.get("image") or item.get("file")) if not image_value: errors.append( { "code": "MATERIAL_IMAGE_MISSING", "message": "asset pack material entry must include image_uri, uri, image, or file", "field": f"{field}.image_uri", } ) elif _is_missing_relative_asset(image_value, package_path, manifest_path): errors.append( { "code": "MATERIAL_FILE_MISSING", "message": "asset pack material image file was not found", "field": f"{field}.image_uri", } ) thumbnail_value = _optional_text(item.get("thumbnail_uri") or item.get("thumbnail")) if thumbnail_value and _is_missing_relative_asset(thumbnail_value, package_path, manifest_path): errors.append( { "code": "MATERIAL_THUMBNAIL_MISSING", "message": "asset pack material thumbnail file was not found", "field": f"{field}.thumbnail_uri", } ) return errors def _is_missing_relative_asset(value: str, package_path: Path, manifest_path: Path) -> bool: if value.startswith("storage://"): return False base_path = package_path if package_path.is_dir() else manifest_path.parent candidate = (base_path / value).resolve() try: candidate.relative_to(base_path.resolve()) except ValueError: return True return not candidate.is_file() def _material_payload_from_manifest_item( item: dict[str, Any], *, root: str, base_relative: Path, package_uri: str, manifest_uri: str, index: int, ) -> dict[str, Any]: image_uri = _asset_uri(item.get("image_uri") or item.get("uri") or item.get("image") or item.get("file"), root, base_relative) if not image_uri: raise ApiError(ErrorCode.VALIDATION_FAILED, "material image uri is required", {"field": f"materials[{index}].image_uri"}) thumbnail_uri = _asset_uri(item.get("thumbnail_uri") or item.get("thumbnail"), root, base_relative) display_name = _optional_text(item.get("display_name") or item.get("name") or item.get("title")) or Path(image_uri).stem metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else {} material_id = _material_id(item, package_uri, manifest_uri, index, image_uri) return { "material_id": material_id, "category_id": _optional_text(item.get("category_id")), "display_name": display_name, "image_uri": image_uri, "thumbnail_uri": thumbnail_uri, "prompt": _optional_text(item.get("prompt")), "negative_prompt": _optional_text(item.get("negative_prompt")), "tags": _normalize_tags(item.get("tags")), # An imported pack is an untrusted document: letting its manifest # declare "confirmed" would let a pack author skip recognition and human # review entirely, landing unvetted material straight in the confirmed # library. Only states that still require review are honoured. "recognition_status": _importable_recognition_status(item.get("recognition_status")), "metadata": { **metadata, "asset_pack": { "package_uri": package_uri, "manifest_uri": manifest_uri, "index": index, }, }, } # Recognition states an imported manifest is allowed to request. "confirmed" # and "archived" are review *outcomes* and must be reached through the normal # recognise -> confirm flow, not asserted by the pack being imported. IMPORTABLE_RECOGNITION_STATUSES = {"pending_upload", "pending_recognition", "pending_confirm"} def _importable_recognition_status(value: Any) -> str: requested = _optional_text(value) if requested in IMPORTABLE_RECOGNITION_STATUSES: return requested return "pending_recognition" def _asset_uri(value: Any, root: str, base_relative: Path) -> str | None: text = _optional_text(value) if text is None: return None if text.startswith("storage://"): return text return _storage_uri(root, base_relative / text) def _material_id(item: dict[str, Any], package_uri: str, manifest_uri: str, index: int, image_uri: str) -> str: explicit = _optional_text(item.get("material_id") or item.get("id")) if explicit: return explicit digest = hashlib.sha1(f"{package_uri}|{manifest_uri}|{index}|{image_uri}".encode("utf-8")).hexdigest() return f"mat_pack_{digest[:24]}" def _storage_uri(root: str, relative: Path) -> str: return f"storage://{root}/{relative.as_posix()}" def _optional_text(value: Any) -> str | None: text = str(value or "").strip() return text or None def _list_count(value: Any) -> int: return len(value) if isinstance(value, list) else 0 def _normalize_tags(value: Any) -> list[str]: if isinstance(value, str): candidates = value.split(",") elif isinstance(value, list): candidates = value else: candidates = [] tags: list[str] = [] for item in candidates: tag = str(item or "").strip() if tag and tag not in tags: tags.append(tag) return tags def _path_file_stats(path: Path) -> tuple[int, int]: if path.is_file(): return 1, path.stat().st_size files = 0 total = 0 for child in path.rglob("*"): if child.is_file(): files += 1 total += child.stat().st_size return files, total