licos-platform-cli 0.2.14__tar.gz → 0.3.1__tar.gz

{licos_platform_cli-0.2.14 → licos_platform_cli-0.3.1}/.gitignore

@@ -12,6 +12,7 @@ packages/*/dist/
 .vscode/
 *.swp
 *.swo
+*.pyc
 
 # OS
 .DS_Store
@@ -33,12 +34,13 @@ crates/industrial/industrial-stack.env
 # Build
 *.log
 *.pid
-crates/industrial/bin/
 .licos
 .tmp
 .playwright-cli
 
 /tmp
+crates/industrial/bin/
+
 tools/android-sdk-cache/*.zip
 tools/codegraph-cache/*.tgz
 tools/codegraph-cache/*.tgz

{licos_platform_cli-0.2.14 → licos_platform_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: licos-platform-cli
-Version: 0.2.14
+Version: 0.3.1
 Summary: LICOS platform CLI
 Requires-Python: >=3.10
-Requires-Dist: licos-platform-sdk>=0.3.0
+Requires-Dist: licos-platform-sdk>=0.4.1

{licos_platform_cli-0.2.14 → licos_platform_cli-0.3.1}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "licos-platform-cli"
-version = "0.2.14"
+version = "0.3.1"
 description = "LICOS platform CLI"
 requires-python = ">=3.10"
 dependencies = [
-    "licos-platform-sdk>=0.3.0",
+    "licos-platform-sdk>=0.4.1",
 ]
 
 [project.scripts]

{licos_platform_cli-0.2.14 → licos_platform_cli-0.3.1}/src/licos_platform_cli/help_commands.py

@@ -451,7 +451,7 @@ KNOWLEDGE_HELP = {
 }
 
 
-OAUTH_HELP = {
+OAUTH_HELP = {
     "topic": "oauth",
     "description": "Manage LICOS OAuth2/OIDC login applications from trusted project runtime code.",
     "runtime": RUNTIME_ENV,
@@ -495,14 +495,201 @@ OAUTH_HELP = {
         "grants": {"description": "List application grants.", "parameters": [], "example": "licos-platform oauth grants app-id"},
         "revoke-grant": {"description": "Revoke one grant.", "parameters": [], "example": "licos-platform oauth revoke-grant grant-id"},
     },
-}
-
-
-HELP_TOPICS = {
+}
+
+
+UNS_HELP = {
+    "topic": "uns",
+    "description": "Project-scoped UNS generation, reconciliation, resource search, and business runtime access.",
+    "runtime": RUNTIME_ENV,
+    "rules": [
+        "Runtime identity selects the project; never pass tenant, workspace, project, external service URL, or token arguments.",
+        "Query only the blocks and protocols needed for the current document.",
+        "discover, validate, plan, and finalize are read-only for external systems; apply performs writes.",
+        "Run apply only after reviewing the current plan, and pass its exact documentHash and planHash with --confirm.",
+        "UNS.json must not contain platform IDs, external IDs, credentials, MQTT infrastructure IDs, or credential-bearing RTSP URLs.",
+        "Use resource-search before reference bindings; a reference selector must resolve exactly one existing resource.",
+        "Use either a current-project node code or --path for business access. Data writes/deletions, point control, and video control require explicit confirmation.",
+    ],
+    "sdk": {
+        "python": "from licos_platform_sdk import uns\nplanned = uns.plan(document)\nresult = uns.apply(document, expected_document_hash=planned['documentHash'], expected_plan_hash=planned['planHash'], confirmed=True)",
+    },
+    "commands": {
+        "schema-current": {
+            "description": "Get the current complete UNS Schema and block index.",
+            "parameters": [],
+            "example": "licos-platform uns schema-current",
+        },
+        "schema": {
+            "description": "Get a complete versioned UNS Schema.",
+            "parameters": [{"name": "--version", "required": False, "description": "Schema version, default 1.0."}],
+            "example": "licos-platform uns schema --version 1.0",
+        },
+        "schema-blocks": {
+            "description": "List available blocks for one Schema version.",
+            "parameters": [{"name": "--version", "required": False, "description": "Schema version, default 1.0."}],
+            "example": "licos-platform uns schema-blocks",
+        },
+        "schema-block": {
+            "description": "Get one block and optionally its direct dependencies.",
+            "parameters": [
+                {"name": "block_code", "required": True, "description": "Block code such as collection-point or uns-node."},
+                {"name": "--depth", "required": False, "description": "Dependency depth from 0 to 3."},
+            ],
+            "example": "licos-platform uns schema-block collection-point --depth 1",
+        },
+        "protocol-schema": {
+            "description": "Get one protocol-specific collection-point Schema and capability status.",
+            "parameters": [{"name": "protocol", "required": True, "description": "Protocol code such as opcua."}],
+            "example": "licos-platform uns protocol-schema opcua",
+        },
+        "discover": {
+            "description": "Read a redacted snapshot of reusable industrial resources for the runtime project.",
+            "parameters": [
+                {"name": "--resource-type", "required": False, "description": "Resource block to return; can repeat."},
+                {"name": "--protocol", "required": False, "description": "Protocol capability detail to query; can repeat."},
+            ],
+            "example": "licos-platform uns discover --resource-type connections --protocol opcua",
+        },
+        "resource-search": {
+            "description": "Search reusable points, video channels, or other resources and return a manifestSelector without external IDs.",
+            "parameters": [
+                {"name": "--resource-type", "required": True, "description": "Resource type such as collectionPoints or videoChannels."},
+                {"name": "--protocol", "required": False, "description": "Optional protocol filter."},
+                {"name": "--keyword", "required": False, "description": "Name or business-code search text."},
+                {"name": "--selector-json", "required": False, "description": "Exact business selector JSON object."},
+            ],
+            "example": "licos-platform uns resource-search --resource-type collectionPoints --protocol opcua --keyword TEMP",
+        },
+        "bindings": {
+            "description": "List project UNS node codes, field contracts, and available runtime capabilities.",
+            "parameters": [],
+            "example": "licos-platform uns bindings",
+        },
+        "path-resolve": {
+            "description": "Resolve an authorized absolute or relative enterprise UNS path.",
+            "parameters": [{"name": "path", "required": True, "description": "UNS absolute or relative path."}],
+            "example": "licos-platform uns path-resolve project:/AREA_01/TEMP_01",
+        },
+        "validate": {
+            "description": "Validate a local JSON document in the runtime project scope.",
+            "parameters": [{"name": "--file", "required": True, "description": "Local UNS JSON file."}],
+            "example": "licos-platform uns validate --file UNS.json.candidate",
+        },
+        "plan": {
+            "description": "Create a deterministic read-only reconciliation plan for a local JSON document.",
+            "parameters": [{"name": "--file", "required": True, "description": "Local UNS JSON file."}],
+            "example": "licos-platform uns plan --file UNS.json",
+        },
+        "apply": {
+            "description": "Execute a previously reviewed plan after explicit confirmation and hash verification.",
+            "parameters": [
+                {"name": "--file", "required": True, "description": "The exact local UNS JSON document that was planned."},
+                {"name": "--document-hash", "required": True, "description": "documentHash returned by the reviewed plan."},
+                {"name": "--plan-hash", "required": True, "description": "planHash returned by the reviewed plan."},
+                {"name": "--confirm", "required": True, "description": "Explicitly confirm external writes."},
+            ],
+            "example": "licos-platform uns apply --file UNS.json --document-hash <documentHash> --plan-hash <planHash> --confirm",
+        },
+        "finalize": {
+            "description": "Validate and atomically install a candidate as project-root UNS.json, revalidate it, and return a read-only plan.",
+            "parameters": [{"name": "--file", "required": True, "description": "Candidate JSON file inside LICOS_PROJECT_PATH."}],
+            "example": "licos-platform uns finalize --file .UNS.json.candidate",
+        },
+        "data-query": {
+            "description": "Query stored rows through a data or point UNS node.",
+            "parameters": [
+                {"name": "node_code", "required": False, "description": "Current-project UNS node code; mutually exclusive with --path."},
+                {"name": "--path", "required": False, "description": "Authorized UNS path; mutually exclusive with node_code."},
+            ],
+            "example": "licos-platform uns data-query ORDERS --page-size 50",
+        },
+        "data-write": {
+            "description": "Write structured fields through a UNS node after explicit confirmation.",
+            "parameters": [
+                {"name": "node_code", "required": False, "description": "Current-project UNS node code; mutually exclusive with --path."},
+                {"name": "--path", "required": False, "description": "Authorized UNS path; mutually exclusive with node_code."},
+                {"name": "--fields-json", "required": True, "description": "Field-value JSON object."},
+                {"name": "--confirm", "required": True, "description": "Explicitly confirm the write."},
+            ],
+            "example": "licos-platform uns data-write ORDERS --fields-json '{\"amount\":12}' --confirm",
+        },
+        "data-delete": {
+            "description": "Delete exact rows returned by a prior UNS query after explicit confirmation.",
+            "parameters": [
+                {"name": "node_code", "required": False, "description": "Current-project UNS node code; mutually exclusive with --path."},
+                {"name": "--path", "required": False, "description": "Authorized UNS path; mutually exclusive with node_code."},
+                {"name": "--rows-json", "required": True, "description": "Non-empty JSON array containing exact queried row objects."},
+                {"name": "--confirm", "required": True, "description": "Explicitly confirm the deletion."},
+            ],
+            "example": "licos-platform uns data-delete ORDERS --rows-json '[{\"orderNo\":\"SO-1\"}]' --confirm",
+        },
+        "point-current": {
+            "description": "Read the current value of a bound UNS point.",
+            "parameters": [
+                {"name": "node_code", "required": False, "description": "Current-project point code; mutually exclusive with --path."},
+                {"name": "--path", "required": False, "description": "Authorized point path; mutually exclusive with node_code."},
+            ],
+            "example": "licos-platform uns point-current TEMP_01",
+        },
+        "point-history": {
+            "description": "Read an ISO-8601 time range of historical point values.",
+            "parameters": [
+                {"name": "node_code", "required": False, "description": "Current-project point code; mutually exclusive with --path."},
+                {"name": "--path", "required": False, "description": "Authorized point path; mutually exclusive with node_code."},
+                {"name": "--start-time / --end-time", "required": True, "description": "UTC ISO-8601 range."},
+            ],
+            "example": "licos-platform uns point-history TEMP_01 --start-time 2026-07-13T00:00:00Z --end-time 2026-07-14T00:00:00Z",
+        },
+        "point-write": {
+            "description": "Dry-run or explicitly confirm a writable point control with audit reason and ticket.",
+            "parameters": [
+                {"name": "node_code", "required": False, "description": "Current-project point code; mutually exclusive with --path."},
+                {"name": "--path", "required": False, "description": "Authorized point path; mutually exclusive with node_code."},
+                {"name": "--value-json", "required": True, "description": "Typed JSON scalar or value."},
+                {"name": "--reason / --ticket", "required": True, "description": "Audit context."},
+                {"name": "--request-id", "required": False, "description": "Idempotency/correlation key; generated by the platform when omitted."},
+                {"name": "--dry-run / --confirm", "required": True, "description": "Dry-run or explicit execution confirmation."},
+            ],
+            "example": "licos-platform uns point-write MOTOR_START --value-json true --reason 'start line' --ticket WO-100 --dry-run",
+        },
+        "video-stream": {
+            "description": "Get credential-safe playback options for a UNS video node.",
+            "parameters": [
+                {"name": "node_code", "required": False, "description": "Current-project video code; mutually exclusive with --path."},
+                {"name": "--path", "required": False, "description": "Authorized video path; mutually exclusive with node_code."},
+            ],
+            "example": "licos-platform uns video-stream CAMERA_01",
+        },
+        "video-snapshot": {
+            "description": "Capture a snapshot from a UNS video node.",
+            "parameters": [
+                {"name": "node_code", "required": False, "description": "Current-project video code; mutually exclusive with --path."},
+                {"name": "--path", "required": False, "description": "Authorized video path; mutually exclusive with node_code."},
+            ],
+            "example": "licos-platform uns video-snapshot CAMERA_01",
+        },
+        "video-control": {
+            "description": "Execute an explicitly confirmed PTZ or preset action.",
+            "parameters": [
+                {"name": "node_code", "required": False, "description": "Current-project video code; mutually exclusive with --path."},
+                {"name": "--path", "required": False, "description": "Authorized video path; mutually exclusive with node_code."},
+                {"name": "--action", "required": True, "description": "move, stop, preset-set, or preset-goto."},
+                {"name": "--parameters-json", "required": False, "description": "Action-specific JSON parameters."},
+                {"name": "--confirm", "required": True, "description": "Explicitly confirm video control."},
+            ],
+            "example": "licos-platform uns video-control CAMERA_01 --action move --parameters-json '{\"direction\":\"left\"}' --confirm",
+        },
+    },
+}
+
+
+HELP_TOPICS = {
     "storage": STORAGE_HELP,
     "database": DATABASE_HELP,
     "knowledge": KNOWLEDGE_HELP,
-    "oauth": OAUTH_HELP,
+    "oauth": OAUTH_HELP,
+    "uns": UNS_HELP,
 }
 
 
@@ -514,20 +701,22 @@ def _cmd_help(args: argparse.Namespace) -> dict[str, Any]:
     if not args.topic:
         return {
             "description": "Structured help for LICOS platform CLI topics.",
-            "usage": [
-                "licos-platform help storage",
-                "licos-platform help storage upload-file",
-            "licos-platform help database",
-            "licos-platform help database query",
-            "licos-platform help database export-orm",
-            "licos-platform help database studio-ensure",
-            "licos-platform help knowledge",
-            "licos-platform help knowledge search",
-            "licos-platform help oauth",
-            "licos-platform help oauth configure-project",
-        ],
-            "topics": sorted(HELP_TOPICS),
-        }
+            "usage": [
+                "licos-platform help storage",
+                "licos-platform help storage upload-file",
+                "licos-platform help database",
+                "licos-platform help database query",
+                "licos-platform help database export-orm",
+                "licos-platform help database studio-ensure",
+                "licos-platform help knowledge",
+                "licos-platform help knowledge search",
+                "licos-platform help oauth",
+                "licos-platform help oauth configure-project",
+                "licos-platform help uns",
+                "licos-platform help uns protocol-schema",
+            ],
+            "topics": sorted(HELP_TOPICS),
+        }
     topic = HELP_TOPICS[args.topic]
     if not args.command:
         return topic

{licos_platform_cli-0.2.14 → licos_platform_cli-0.3.1}/src/licos_platform_cli/main.py

@@ -11,7 +11,8 @@ from .database_commands import add_database_parser
 from .help_commands import add_help_parser
 from .knowledge_commands import add_knowledge_parser
 from .oauth_commands import add_oauth_parser
-from .storage_commands import add_storage_parser
+from .storage_commands import add_storage_parser
+from .uns_commands import add_uns_parser
 
 
 def _print_json(value: Any) -> None:
@@ -33,7 +34,8 @@ def _build_parser() -> argparse.ArgumentParser:
     add_storage_parser(subparsers)
     add_database_parser(subparsers)
     add_knowledge_parser(subparsers)
-    add_oauth_parser(subparsers)
+    add_oauth_parser(subparsers)
+    add_uns_parser(subparsers)
     return parser
 
 

{licos_platform_cli-0.2.14 → licos_platform_cli-0.3.1}/src/licos_platform_cli/oauth_commands.py

@@ -137,12 +137,12 @@ def _cmd_revoke_grant(args: argparse.Namespace) -> Any:
     return oauth.revoke_grant(args.grant_id)
 
 
-def _cmd_configure_project(args: argparse.Namespace) -> dict[str, Any]:
-    public_base_url = (
-        args.public_base_url
-        or os.environ.get("LICOS_PLATFORM_PUBLIC_BASE_URL")
-        or os.environ.get("LICOS_OAUTH_PUBLIC_BASE_URL")
-    )
+def _cmd_configure_project(args: argparse.Namespace) -> dict[str, Any]:
+    public_base_url = (
+        args.public_base_url
+        or os.environ.get("LICOS_PLATFORM_PUBLIC_BASE_URL")
+        or os.environ.get("LICOS_OAUTH_PUBLIC_BASE_URL")
+    )
     if not public_base_url:
         raise argparse.ArgumentTypeError(
             "--public-base-url, LICOS_PLATFORM_PUBLIC_BASE_URL, or LICOS_OAUTH_PUBLIC_BASE_URL is required"

licos_platform_cli-0.3.1/src/licos_platform_cli/uns_commands.py

@@ -0,0 +1,427 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Callable
+
+from licos_platform_sdk import PlatformSdkError, uns
+
+
+Handler = Callable[[argparse.Namespace], Any]
+
+
+def _set_handler(parser: argparse.ArgumentParser, handler: Handler) -> None:
+    parser.set_defaults(handler=handler)
+
+
+def _document(path: str) -> dict[str, Any]:
+    file_path = Path(path)
+    try:
+        payload = json.loads(file_path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise argparse.ArgumentTypeError(f"cannot read UNS file: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(
+            f"invalid JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}"
+        ) from exc
+    if not isinstance(payload, dict):
+        raise argparse.ArgumentTypeError("UNS document root must be an object")
+    return payload
+
+
+def _json_object(value: str | None, label: str) -> dict[str, Any]:
+    if value is None:
+        return {}
+    try:
+        payload = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(f"{label} must be valid JSON: {exc.msg}") from exc
+    if not isinstance(payload, dict):
+        raise argparse.ArgumentTypeError(f"{label} must be a JSON object")
+    return payload
+
+
+def _json_value(value: str, label: str) -> Any:
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(f"{label} must be valid JSON: {exc.msg}") from exc
+
+
+def _json_object_array(value: str, label: str) -> list[dict[str, Any]]:
+    payload = _json_value(value, label)
+    if not isinstance(payload, list) or not payload:
+        raise argparse.ArgumentTypeError(f"{label} must be a non-empty JSON array")
+    if any(not isinstance(item, dict) or not item for item in payload):
+        raise argparse.ArgumentTypeError(f"{label} must contain only non-empty JSON objects")
+    return payload
+
+
+def _cmd_schema_current(_args: argparse.Namespace) -> Any:
+    return uns.schema_current()
+
+
+def _cmd_schema(args: argparse.Namespace) -> Any:
+    return uns.schema(args.version)
+
+
+def _cmd_schema_blocks(args: argparse.Namespace) -> Any:
+    return uns.schema_blocks(args.version)
+
+
+def _cmd_schema_block(args: argparse.Namespace) -> Any:
+    return uns.schema_block(args.block_code, version=args.version, depth=args.depth)
+
+
+def _cmd_protocol_schema(args: argparse.Namespace) -> Any:
+    return uns.protocol_schema(args.protocol, version=args.version)
+
+
+def _cmd_discover(args: argparse.Namespace) -> Any:
+    return uns.discover(resource_types=args.resource_types, protocols=args.protocols)
+
+
+def _cmd_resource_search(args: argparse.Namespace) -> Any:
+    return uns.search_resources(
+        args.resource_type,
+        protocol=args.protocol,
+        keyword=args.keyword,
+        selector=_json_object(args.selector_json, "selector"),
+        page=args.page,
+        page_size=args.page_size,
+    )
+
+
+def _cmd_bindings(_args: argparse.Namespace) -> Any:
+    return uns.bindings()
+
+
+def _cmd_path_resolve(args: argparse.Namespace) -> Any:
+    return uns.resolve_path(args.path)
+
+
+def _target(args: argparse.Namespace) -> tuple[str, bool]:
+    node_code = getattr(args, "node_code", None)
+    path = getattr(args, "path", None)
+    if bool(node_code) == bool(path):
+        raise argparse.ArgumentTypeError("provide exactly one node_code or --path")
+    return (path, True) if path else (node_code, False)
+
+
+def _cmd_validate(args: argparse.Namespace) -> Any:
+    return uns.validate(_document(args.file))
+
+
+def _cmd_plan(args: argparse.Namespace) -> Any:
+    return uns.plan(_document(args.file))
+
+
+def _cmd_apply(args: argparse.Namespace) -> Any:
+    if not args.confirm:
+        raise argparse.ArgumentTypeError("UNS apply requires --confirm")
+    if not args.document_hash.strip() or not args.plan_hash.strip():
+        raise argparse.ArgumentTypeError("UNS apply requires non-empty document and plan hashes")
+    return uns.apply(
+        _document(args.file),
+        expected_document_hash=args.document_hash,
+        expected_plan_hash=args.plan_hash,
+        confirmed=True,
+    )
+
+
+def _cmd_data_query(args: argparse.Namespace) -> Any:
+    target, by_path = _target(args)
+    handler = uns.query_path_data if by_path else uns.query_node_data
+    return handler(
+        target,
+        page_num=args.page_num,
+        page_size=args.page_size,
+        pagination_mode=args.pagination_mode,
+        page_token=args.page_token,
+    )
+
+
+def _cmd_data_write(args: argparse.Namespace) -> Any:
+    if not args.confirm:
+        raise argparse.ArgumentTypeError("UNS data write requires --confirm")
+    target, by_path = _target(args)
+    handler = uns.write_path_data if by_path else uns.write_node_data
+    return handler(
+        target,
+        _json_object(args.fields_json, "field values"),
+        confirmed=True,
+    )
+
+
+def _cmd_data_delete(args: argparse.Namespace) -> Any:
+    if not args.confirm:
+        raise argparse.ArgumentTypeError("UNS data deletion requires --confirm")
+    target, by_path = _target(args)
+    handler = uns.delete_path_data if by_path else uns.delete_node_data
+    return handler(
+        target,
+        _json_object_array(args.rows_json, "rows"),
+        confirmed=True,
+    )
+
+
+def _cmd_point_current(args: argparse.Namespace) -> Any:
+    target, by_path = _target(args)
+    return uns.path_point_current(target) if by_path else uns.point_current(target)
+
+
+def _cmd_point_history(args: argparse.Namespace) -> Any:
+    target, by_path = _target(args)
+    handler = uns.path_point_history if by_path else uns.point_history
+    return handler(
+        target,
+        start_time=args.start_time,
+        end_time=args.end_time,
+        page=args.page,
+        page_size=args.page_size,
+    )
+
+
+def _cmd_point_write(args: argparse.Namespace) -> Any:
+    if not args.dry_run and not args.confirm:
+        raise argparse.ArgumentTypeError("UNS point write requires --confirm unless --dry-run is used")
+    target, by_path = _target(args)
+    handler = uns.write_path_point if by_path else uns.write_point
+    return handler(
+        target,
+        _json_value(args.value_json, "point value"),
+        reason=args.reason,
+        ticket=args.ticket,
+        request_id=args.request_id,
+        dry_run=args.dry_run,
+        confirmed=args.confirm,
+    )
+
+
+def _cmd_video_stream(args: argparse.Namespace) -> Any:
+    target, by_path = _target(args)
+    return uns.path_video_stream_options(target) if by_path else uns.video_stream_options(target)
+
+
+def _cmd_video_snapshot(args: argparse.Namespace) -> Any:
+    target, by_path = _target(args)
+    return uns.path_video_snapshot(target) if by_path else uns.video_snapshot(target)
+
+
+def _cmd_video_control(args: argparse.Namespace) -> Any:
+    if not args.confirm:
+        raise argparse.ArgumentTypeError("UNS video control requires --confirm")
+    target, by_path = _target(args)
+    handler = uns.control_path_video if by_path else uns.control_video
+    return handler(
+        target,
+        args.action,
+        parameters=_json_object(args.parameters_json, "video control parameters"),
+        confirmed=True,
+    )
+
+
+def _cmd_finalize(args: argparse.Namespace) -> Any:
+    project_root = Path(os.environ.get("LICOS_PROJECT_PATH", "/workspace/projects")).resolve()
+    candidate = Path(args.file).resolve()
+    target = project_root / "UNS.json"
+    if not candidate.is_relative_to(project_root):
+        raise argparse.ArgumentTypeError("candidate file must be inside LICOS_PROJECT_PATH")
+    if candidate == target:
+        raise argparse.ArgumentTypeError("candidate file must not already be UNS.json")
+
+    document = _document(str(candidate))
+    validation = uns.validate(document)
+    if not validation.get("valid"):
+        raise PlatformSdkError("candidate validation failed; inspect `licos-platform uns validate` output")
+
+    project_root.mkdir(parents=True, exist_ok=True)
+    previous = target.read_bytes() if target.exists() else None
+    staging_path: Path | None = None
+    target_replaced = False
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb", prefix=".UNS.json.", suffix=".tmp", dir=project_root, delete=False
+        ) as staging:
+            staging.write(candidate.read_bytes())
+            staging.flush()
+            os.fsync(staging.fileno())
+            staging_path = Path(staging.name)
+        os.replace(staging_path, target)
+        staging_path = None
+        target_replaced = True
+
+        final_document = _document(str(target))
+        final_validation = uns.validate(final_document)
+        if not final_validation.get("valid"):
+            raise PlatformSdkError("final UNS.json validation failed; the previous file was restored")
+        plan = uns.plan(final_document)
+        candidate.unlink(missing_ok=True)
+        return {
+            "installed": True,
+            "target": "UNS.json",
+            "validation": final_validation,
+            "plan": plan,
+        }
+    except BaseException:
+        if staging_path is not None:
+            staging_path.unlink(missing_ok=True)
+        if target_replaced:
+            _restore_target(target, previous)
+        raise
+
+
+def _restore_target(target: Path, previous: bytes | None) -> None:
+    if previous is None:
+        target.unlink(missing_ok=True)
+        return
+    with tempfile.NamedTemporaryFile(
+        mode="wb", prefix=".UNS.restore.", suffix=".tmp", dir=target.parent, delete=False
+    ) as restore:
+        restore.write(previous)
+        restore.flush()
+        os.fsync(restore.fileno())
+        restore_path = Path(restore.name)
+    os.replace(restore_path, target)
+
+
+def add_uns_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("uns", help="Inspect, validate, plan, and apply project UNS manifests")
+    commands = parser.add_subparsers(dest="uns_command", required=True)
+
+    _set_handler(commands.add_parser("schema-current", help="Get the current UNS Schema"), _cmd_schema_current)
+
+    schema = commands.add_parser("schema", help="Get a complete versioned UNS Schema")
+    schema.add_argument("--version", default="1.0")
+    _set_handler(schema, _cmd_schema)
+
+    blocks = commands.add_parser("schema-blocks", help="List versioned UNS Schema blocks")
+    blocks.add_argument("--version", default="1.0")
+    _set_handler(blocks, _cmd_schema_blocks)
+
+    block = commands.add_parser("schema-block", help="Get one UNS Schema block")
+    block.add_argument("block_code")
+    block.add_argument("--version", default="1.0")
+    block.add_argument("--depth", type=int, default=1, choices=range(0, 4))
+    _set_handler(block, _cmd_schema_block)
+
+    protocol = commands.add_parser("protocol-schema", help="Get one collection-point protocol Schema")
+    protocol.add_argument("protocol")
+    protocol.add_argument("--version", default="1.0")
+    _set_handler(protocol, _cmd_protocol_schema)
+
+    discover = commands.add_parser("discover", help="Discover reusable project industrial resources without writes")
+    discover.add_argument("--resource-type", action="append", dest="resource_types", default=None)
+    discover.add_argument("--protocol", action="append", dest="protocols", default=None)
+    _set_handler(discover, _cmd_discover)
+
+    search = commands.add_parser("resource-search", help="Search reusable resources with a manifest selector")
+    search.add_argument("--resource-type", required=True)
+    search.add_argument("--protocol")
+    search.add_argument("--keyword")
+    search.add_argument("--selector-json")
+    search.add_argument("--page", type=int, default=1)
+    search.add_argument("--page-size", type=int, default=20)
+    _set_handler(search, _cmd_resource_search)
+
+    _set_handler(commands.add_parser("bindings", help="List project UNS business bindings"), _cmd_bindings)
+
+    path_resolve = commands.add_parser(
+        "path-resolve", help="Resolve an absolute or relative enterprise UNS path"
+    )
+    path_resolve.add_argument("path")
+    _set_handler(path_resolve, _cmd_path_resolve)
+
+    validate = commands.add_parser("validate", help="Validate one local UNS JSON document")
+    validate.add_argument("--file", required=True)
+    _set_handler(validate, _cmd_validate)
+
+    plan = commands.add_parser("plan", help="Create a read-only reconciliation plan for one UNS JSON document")
+    plan.add_argument("--file", required=True)
+    _set_handler(plan, _cmd_plan)
+
+    apply_command = commands.add_parser(
+        "apply", help="Apply one previously reviewed UNS reconciliation plan"
+    )
+    apply_command.add_argument("--file", required=True)
+    apply_command.add_argument("--document-hash", required=True)
+    apply_command.add_argument("--plan-hash", required=True)
+    apply_command.add_argument("--confirm", action="store_true")
+    _set_handler(apply_command, _cmd_apply)
+
+    finalize = commands.add_parser(
+        "finalize", help="Validate and atomically install a candidate as project UNS.json, then create a plan"
+    )
+    finalize.add_argument("--file", required=True)
+    _set_handler(finalize, _cmd_finalize)
+
+    data_query = commands.add_parser("data-query", help="Query stored data through a UNS node")
+    data_query.add_argument("node_code", nargs="?")
+    data_query.add_argument("--path")
+    data_query.add_argument("--page-num", type=int, default=1)
+    data_query.add_argument("--page-size", type=int, default=50)
+    data_query.add_argument("--pagination-mode", choices=("OFFSET", "CURSOR"), default="OFFSET")
+    data_query.add_argument("--page-token")
+    _set_handler(data_query, _cmd_data_query)
+
+    data_write = commands.add_parser("data-write", help="Write structured data through a UNS node")
+    data_write.add_argument("node_code", nargs="?")
+    data_write.add_argument("--path")
+    data_write.add_argument("--fields-json", required=True)
+    data_write.add_argument("--confirm", action="store_true")
+    _set_handler(data_write, _cmd_data_write)
+
+    data_delete = commands.add_parser("data-delete", help="Delete exact stored rows through a UNS node")
+    data_delete.add_argument("node_code", nargs="?")
+    data_delete.add_argument("--path")
+    data_delete.add_argument("--rows-json", required=True)
+    data_delete.add_argument("--confirm", action="store_true")
+    _set_handler(data_delete, _cmd_data_delete)
+
+    point_current = commands.add_parser("point-current", help="Read the current value of a UNS point")
+    point_current.add_argument("node_code", nargs="?")
+    point_current.add_argument("--path")
+    _set_handler(point_current, _cmd_point_current)
+
+    point_history = commands.add_parser("point-history", help="Read historical values of a UNS point")
+    point_history.add_argument("node_code", nargs="?")
+    point_history.add_argument("--path")
+    point_history.add_argument("--start-time", required=True)
+    point_history.add_argument("--end-time", required=True)
+    point_history.add_argument("--page", type=int, default=1)
+    point_history.add_argument("--page-size", type=int, default=100)
+    _set_handler(point_history, _cmd_point_history)
+
+    point_write = commands.add_parser("point-write", help="Write or dry-run a controllable UNS point")
+    point_write.add_argument("node_code", nargs="?")
+    point_write.add_argument("--path")
+    point_write.add_argument("--value-json", required=True)
+    point_write.add_argument("--reason", required=True)
+    point_write.add_argument("--ticket", required=True)
+    point_write.add_argument("--request-id")
+    point_write.add_argument("--dry-run", action="store_true")
+    point_write.add_argument("--confirm", action="store_true")
+    _set_handler(point_write, _cmd_point_write)
+
+    video_stream = commands.add_parser("video-stream", help="Get playback options for a UNS video node")
+    video_stream.add_argument("node_code", nargs="?")
+    video_stream.add_argument("--path")
+    _set_handler(video_stream, _cmd_video_stream)
+
+    video_snapshot = commands.add_parser("video-snapshot", help="Capture a snapshot from a UNS video node")
+    video_snapshot.add_argument("node_code", nargs="?")
+    video_snapshot.add_argument("--path")
+    _set_handler(video_snapshot, _cmd_video_snapshot)
+
+    video_control = commands.add_parser("video-control", help="Run an explicitly confirmed video control")
+    video_control.add_argument("node_code", nargs="?")
+    video_control.add_argument("--path")
+    video_control.add_argument(
+        "--action", required=True, choices=("move", "stop", "preset-set", "preset-goto")
+    )
+    video_control.add_argument("--parameters-json")
+    video_control.add_argument("--confirm", action="store_true")
+    _set_handler(video_control, _cmd_video_control)

{licos_platform_cli-0.2.14 → licos_platform_cli-0.3.1}/tests/test_cli.py

@@ -14,8 +14,8 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "licos-platform-sdk
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 
 from licos_platform_cli import main as cli_main
-from licos_platform_cli import database_commands, knowledge_commands, oauth_commands, storage_commands
-from licos_platform_sdk import ApiError
+from licos_platform_cli import database_commands, knowledge_commands, oauth_commands, storage_commands, uns_commands
+from licos_platform_sdk import ApiError, PlatformSdkError
 
 
 def run_cli(*args: str) -> tuple[int, str, str]:
@@ -46,7 +46,7 @@ class PlatformCliTests(unittest.TestCase):
         self.assertEqual(code, 0)
         self.assertEqual(stderr, "")
         payload = json.loads(stdout)
-        self.assertEqual(payload["topics"], ["database", "knowledge", "oauth", "storage"])
+        self.assertEqual(payload["topics"], ["database", "knowledge", "oauth", "storage", "uns"])
         self.assertIn("licos-platform help storage", payload["usage"])
 
     def test_structured_help_storage_command_describes_parameters(self) -> None:
@@ -74,17 +74,321 @@ class PlatformCliTests(unittest.TestCase):
         self.assertIn("studio-ensure", payload["commands"])
         self.assertNotIn("LICOS_DATABASE_ENVIRONMENT", {item["name"] for item in payload["runtime"]})
 
-    def test_structured_help_knowledge_topic_describes_default_search(self) -> None:
+    def test_structured_help_knowledge_topic_describes_default_search(self) -> None:
         code, stdout, stderr = run_cli("help", "knowledge")
 
         self.assertEqual(code, 0)
         self.assertEqual(stderr, "")
         payload = json.loads(stdout)
         self.assertEqual(payload["topic"], "knowledge")
-        self.assertIn("search", payload["commands"])
-        self.assertTrue(any("Search all accessible datasets by default" in rule for rule in payload["rules"]))
-
-    def test_storage_files_wraps_sdk_and_outputs_json(self) -> None:
+        self.assertIn("search", payload["commands"])
+        self.assertTrue(any("Search all accessible datasets by default" in rule for rule in payload["rules"]))
+
+    def test_structured_help_uns_exposes_only_confirmed_apply(self) -> None:
+        code, stdout, stderr = run_cli("help", "uns")
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        payload = json.loads(stdout)
+        self.assertIn("apply", payload["commands"])
+        parameters = {item["name"] for item in payload["commands"]["apply"]["parameters"]}
+        self.assertEqual(parameters, {"--file", "--document-hash", "--plan-hash", "--confirm"})
+
+    def test_uns_validate_loads_json_and_calls_sdk(self) -> None:
+        document = {"schemaVersion": "1.0", "resources": {}, "uns": {"nodes": []}}
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "UNS.json"
+            path.write_text(json.dumps(document), encoding="utf-8")
+            with mock.patch.object(uns_commands.uns, "validate", return_value={"valid": True}) as validate:
+                code, stdout, stderr = run_cli("uns", "validate", "--file", str(path))
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        self.assertEqual(json.loads(stdout), {"valid": True})
+        validate.assert_called_once_with(document)
+
+    def test_uns_discover_forwards_only_filters(self) -> None:
+        with mock.patch.object(uns_commands.uns, "discover", return_value={"resources": {}}) as discover:
+            code, stdout, stderr = run_cli(
+                "uns", "discover", "--resource-type", "connections", "--protocol", "opcua"
+            )
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        self.assertEqual(json.loads(stdout), {"resources": {}})
+        discover.assert_called_once_with(resource_types=["connections"], protocols=["opcua"])
+
+    def test_uns_resource_search_forwards_structured_selector(self) -> None:
+        with mock.patch.object(uns_commands.uns, "search_resources", return_value={"items": []}) as search:
+            code, stdout, stderr = run_cli(
+                "uns", "resource-search",
+                "--resource-type", "collectionPoints",
+                "--protocol", "opcua",
+                "--selector-json", '{"tagCode":"TEMP_01"}',
+            )
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        self.assertEqual(json.loads(stdout), {"items": []})
+        search.assert_called_once_with(
+            "collectionPoints",
+            protocol="opcua",
+            keyword=None,
+            selector={"tagCode": "TEMP_01"},
+            page=1,
+            page_size=20,
+        )
+
+    def test_uns_point_write_allows_dry_run_without_execution_confirmation(self) -> None:
+        with mock.patch.object(uns_commands.uns, "write_point", return_value={"dryRun": True}) as write:
+            code, stdout, stderr = run_cli(
+                "uns", "point-write", "MOTOR_START",
+                "--value-json", "true",
+                "--reason", "validate control",
+                "--ticket", "WO-100",
+                "--dry-run",
+            )
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        self.assertEqual(json.loads(stdout), {"dryRun": True})
+        write.assert_called_once_with(
+            "MOTOR_START",
+            True,
+            reason="validate control",
+            ticket="WO-100",
+            request_id=None,
+            dry_run=True,
+            confirmed=False,
+        )
+
+    def test_uns_path_resolve_calls_sdk_without_creating_a_manifest(self) -> None:
+        path = "workspace:/project/project-2/FACTORY/TEMP"
+        with mock.patch.object(
+            uns_commands.uns,
+            "resolve_path",
+            return_value={"canonicalPath": "uns://enterprise/tenant-1/organization/org-1/"
+                                          "workspace/workspace-1/project/project-2/FACTORY/TEMP"},
+        ) as resolve:
+            code, stdout, stderr = run_cli("uns", "path-resolve", path)
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        self.assertIn("canonicalPath", json.loads(stdout))
+        resolve.assert_called_once_with(path)
+
+    def test_uns_data_query_accepts_enterprise_path_instead_of_node_code(self) -> None:
+        path = "enterprise:/organization/org-1/workspace/workspace-2/project/project-2/ORDERS"
+        with mock.patch.object(
+            uns_commands.uns, "query_path_data", return_value={"rows": []}
+        ) as query:
+            code, stdout, stderr = run_cli("uns", "data-query", "--path", path)
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        self.assertEqual(json.loads(stdout), {"rows": []})
+        query.assert_called_once_with(
+            path,
+            page_num=1,
+            page_size=50,
+            pagination_mode="OFFSET",
+            page_token=None,
+        )
+
+    def test_uns_data_query_rejects_node_code_and_path_together(self) -> None:
+        with mock.patch.object(uns_commands.uns, "query_path_data") as query:
+            code, stdout, stderr = run_cli(
+                "uns", "data-query", "ORDERS", "--path", "project:/ORDERS"
+            )
+
+        self.assertEqual(code, 2)
+        self.assertEqual(stdout, "")
+        self.assertIn("exactly one", stderr)
+        query.assert_not_called()
+
+    def test_uns_data_delete_requires_confirmation_and_forwards_rows(self) -> None:
+        rows = [{"recordId": "row-1", "amount": 12}]
+        with mock.patch.object(
+            uns_commands.uns, "delete_node_data", return_value={"deletedCount": 1}
+        ) as delete:
+            code, stdout, stderr = run_cli(
+                "uns", "data-delete", "ORDERS",
+                "--rows-json", json.dumps(rows),
+                "--confirm",
+            )
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        self.assertEqual(json.loads(stdout), {"deletedCount": 1})
+        delete.assert_called_once_with("ORDERS", rows, confirmed=True)
+
+    def test_uns_data_delete_does_not_call_sdk_without_confirmation(self) -> None:
+        with mock.patch.object(uns_commands.uns, "delete_node_data") as delete:
+            code, stdout, stderr = run_cli(
+                "uns", "data-delete", "ORDERS",
+                "--rows-json", '[{"recordId":"row-1"}]',
+            )
+
+        self.assertEqual(code, 2)
+        self.assertEqual(stdout, "")
+        self.assertIn("requires --confirm", stderr)
+        delete.assert_not_called()
+
+    def test_uns_apply_requires_confirmation_and_forwards_reviewed_hashes(self) -> None:
+        document = {"schemaVersion": "1.0", "resources": {}, "uns": {"nodes": []}}
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "UNS.json"
+            path.write_text(json.dumps(document), encoding="utf-8")
+            with mock.patch.object(uns_commands.uns, "apply", return_value={"status": "SUCCESS"}) as apply:
+                code, stdout, stderr = run_cli(
+                    "uns", "apply",
+                    "--file", str(path),
+                    "--document-hash", "document-hash",
+                    "--plan-hash", "plan-hash",
+                    "--confirm",
+                )
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr, "")
+        self.assertEqual(json.loads(stdout), {"status": "SUCCESS"})
+        apply.assert_called_once_with(
+            document,
+            expected_document_hash="document-hash",
+            expected_plan_hash="plan-hash",
+            confirmed=True,
+        )
+
+    def test_uns_apply_does_not_write_without_confirmation(self) -> None:
+        document = {"schemaVersion": "1.0", "resources": {}, "uns": {"nodes": []}}
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "UNS.json"
+            path.write_text(json.dumps(document), encoding="utf-8")
+            with mock.patch.object(uns_commands.uns, "apply") as apply:
+                code, stdout, stderr = run_cli(
+                    "uns", "apply",
+                    "--file", str(path),
+                    "--document-hash", "document-hash",
+                    "--plan-hash", "plan-hash",
+                )
+
+        self.assertEqual(code, 2)
+        self.assertEqual(stdout, "")
+        self.assertIn("requires --confirm", stderr)
+        apply.assert_not_called()
+
+    def test_uns_finalize_atomically_replaces_target_after_validation(self) -> None:
+        document = {"schemaVersion": "1.0", "resources": {}, "uns": {"nodes": []}}
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            candidate = root / ".UNS.json.candidate"
+            candidate.write_text(json.dumps(document), encoding="utf-8")
+            with mock.patch.dict(os.environ, {"LICOS_PROJECT_PATH": tmp}, clear=False):
+                with mock.patch.object(uns_commands.uns, "validate", return_value={"valid": True}) as validate:
+                    with mock.patch.object(uns_commands.uns, "plan", return_value={"planHash": "hash"}) as plan:
+                        code, stdout, stderr = run_cli("uns", "finalize", "--file", str(candidate))
+
+            self.assertEqual(code, 0)
+            self.assertEqual(stderr, "")
+            self.assertFalse(candidate.exists())
+            self.assertEqual(json.loads((root / "UNS.json").read_text(encoding="utf-8")), document)
+            self.assertEqual(json.loads(stdout)["plan"], {"planHash": "hash"})
+            self.assertEqual(validate.call_count, 2)
+            plan.assert_called_once_with(document)
+
+    def test_uns_finalize_keeps_existing_file_when_candidate_is_invalid(self) -> None:
+        existing = {"schemaVersion": "1.0", "metadata": {"name": "existing"}}
+        candidate_document = {"schemaVersion": "1.0", "metadata": {"name": "candidate"}}
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            target = root / "UNS.json"
+            candidate = root / ".UNS.json.candidate"
+            target.write_text(json.dumps(existing), encoding="utf-8")
+            candidate.write_text(json.dumps(candidate_document), encoding="utf-8")
+            with mock.patch.dict(os.environ, {"LICOS_PROJECT_PATH": tmp}, clear=False):
+                with mock.patch.object(uns_commands.uns, "validate", return_value={"valid": False}):
+                    with mock.patch.object(uns_commands.uns, "plan") as plan:
+                        code, stdout, stderr = run_cli("uns", "finalize", "--file", str(candidate))
+
+            self.assertEqual(code, 1)
+            self.assertEqual(stdout, "")
+            self.assertIn("candidate validation failed", stderr)
+            self.assertEqual(json.loads(target.read_text(encoding="utf-8")), existing)
+            self.assertTrue(candidate.exists())
+            plan.assert_not_called()
+
+    def test_uns_finalize_restores_existing_file_when_final_validation_fails(self) -> None:
+        existing = {"schemaVersion": "1.0", "metadata": {"name": "existing"}}
+        candidate_document = {"schemaVersion": "1.0", "metadata": {"name": "candidate"}}
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            target = root / "UNS.json"
+            candidate = root / ".UNS.json.candidate"
+            target.write_text(json.dumps(existing), encoding="utf-8")
+            candidate.write_text(json.dumps(candidate_document), encoding="utf-8")
+            with mock.patch.dict(os.environ, {"LICOS_PROJECT_PATH": tmp}, clear=False):
+                with mock.patch.object(
+                    uns_commands.uns,
+                    "validate",
+                    side_effect=[{"valid": True}, {"valid": False}],
+                ):
+                    with mock.patch.object(uns_commands.uns, "plan") as plan:
+                        code, stdout, stderr = run_cli("uns", "finalize", "--file", str(candidate))
+
+            self.assertEqual(code, 1)
+            self.assertEqual(stdout, "")
+            self.assertIn("previous file was restored", stderr)
+            self.assertEqual(json.loads(target.read_text(encoding="utf-8")), existing)
+            self.assertTrue(candidate.exists())
+            plan.assert_not_called()
+
+    def test_uns_finalize_restores_existing_file_when_final_validation_raises(self) -> None:
+        existing = {"schemaVersion": "1.0", "metadata": {"name": "existing"}}
+        candidate_document = {"schemaVersion": "1.0", "metadata": {"name": "candidate"}}
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            target = root / "UNS.json"
+            candidate = root / ".UNS.json.candidate"
+            target.write_text(json.dumps(existing), encoding="utf-8")
+            candidate.write_text(json.dumps(candidate_document), encoding="utf-8")
+            with mock.patch.dict(os.environ, {"LICOS_PROJECT_PATH": tmp}, clear=False):
+                with mock.patch.object(
+                    uns_commands.uns,
+                    "validate",
+                    side_effect=[{"valid": True}, PlatformSdkError("validation unavailable")],
+                ):
+                    code, stdout, stderr = run_cli("uns", "finalize", "--file", str(candidate))
+
+            self.assertEqual(code, 1)
+            self.assertEqual(stdout, "")
+            self.assertIn("validation unavailable", stderr)
+            self.assertEqual(json.loads(target.read_text(encoding="utf-8")), existing)
+            self.assertTrue(candidate.exists())
+
+    def test_uns_finalize_restores_existing_file_when_plan_raises(self) -> None:
+        existing = {"schemaVersion": "1.0", "metadata": {"name": "existing"}}
+        candidate_document = {"schemaVersion": "1.0", "metadata": {"name": "candidate"}}
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            target = root / "UNS.json"
+            candidate = root / ".UNS.json.candidate"
+            target.write_text(json.dumps(existing), encoding="utf-8")
+            candidate.write_text(json.dumps(candidate_document), encoding="utf-8")
+            with mock.patch.dict(os.environ, {"LICOS_PROJECT_PATH": tmp}, clear=False):
+                with mock.patch.object(uns_commands.uns, "validate", return_value={"valid": True}):
+                    with mock.patch.object(
+                        uns_commands.uns,
+                        "plan",
+                        side_effect=PlatformSdkError("planning unavailable"),
+                    ):
+                        code, stdout, stderr = run_cli("uns", "finalize", "--file", str(candidate))
+
+            self.assertEqual(code, 1)
+            self.assertEqual(stdout, "")
+            self.assertIn("planning unavailable", stderr)
+            self.assertEqual(json.loads(target.read_text(encoding="utf-8")), existing)
+            self.assertTrue(candidate.exists())
+
+    def test_storage_files_wraps_sdk_and_outputs_json(self) -> None:
         with mock.patch.object(storage_commands.storage, "list_files", return_value=[{"id": "file-1"}]) as list_files:
             code, stdout, stderr = run_cli("storage", "files")
 
@@ -291,12 +595,12 @@ class PlatformCliTests(unittest.TestCase):
             "clientId": "client-3",
         }
         with tempfile.TemporaryDirectory() as tmp:
-            env = {
-                "LICOS_PROJECT_PATH": tmp,
-                "AGENT_PROJECT_ID": "project/1",
-                "LICOS_PLATFORM_PUBLIC_BASE_URL": "https://platform.example",
-                "LICOS_DEPLOY_PUBLIC_BASE_URL": "https://deploy.example",
-            }
+            env = {
+                "LICOS_PROJECT_PATH": tmp,
+                "AGENT_PROJECT_ID": "project/1",
+                "LICOS_PLATFORM_PUBLIC_BASE_URL": "https://platform.example",
+                "LICOS_DEPLOY_PUBLIC_BASE_URL": "https://deploy.example",
+            }
             with mock.patch.dict(os.environ, env, clear=False):
                 with mock.patch.object(oauth_commands.oauth, "ensure_project_app", return_value=app) as ensure:
                     code, stdout, stderr = run_cli(
@@ -332,8 +636,8 @@ class PlatformCliTests(unittest.TestCase):
             )
             config = json.loads((Path(tmp) / "config" / "licos-oauth.json").read_text(encoding="utf-8"))
             self.assertEqual(config["redirectUriConfigs"], redirects)
-            self.assertEqual(config["publicBaseUrl"], "https://platform.example")
-            self.assertEqual(json.loads(stdout)["selectionMode"], "auto-apply")
+            self.assertEqual(config["publicBaseUrl"], "https://platform.example")
+            self.assertEqual(json.loads(stdout)["selectionMode"], "auto-apply")
 
     def test_oauth_configure_without_redirect_requires_stable_project_metadata(self) -> None:
         with tempfile.TemporaryDirectory() as tmp: