unique-sdk 2026.44.0.dev3__tar.gz → 2026.44.0.dev4__tar.gz

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.44.0.dev3
+Version: 2026.44.0.dev4
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.44.0.dev3"
+version = "2026.44.0.dev4"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev4}/unique_sdk/cli/cli.py

@@ -58,6 +58,9 @@ from unique_sdk.cli.commands.files import (
 from unique_sdk.cli.commands.files import (
     is_permission_denied_output as _is_permission_denied_output,
 )
+from unique_sdk.cli.commands.files import (
+    is_upload_error_output as _is_upload_error_output,
+)
 from unique_sdk.cli.commands.folders import cmd_mkdir, cmd_mvdir, cmd_rmdir
 from unique_sdk.cli.commands.folders import (
     is_mkdir_error_output as _is_mkdir_error_output,
@@ -67,6 +70,9 @@ from unique_sdk.cli.commands.mcp import (
     is_error_output as _is_mcp_error_output,
 )
 from unique_sdk.cli.commands.navigation import cmd_cd, cmd_ls, cmd_pwd
+from unique_sdk.cli.commands.navigation import (
+    is_ls_error_output as _is_ls_error_output,
+)
 from unique_sdk.cli.commands.read import cmd_read
 from unique_sdk.cli.commands.read import (
     is_error_output as _is_read_error_output,
@@ -322,23 +328,25 @@ def ls(ctx: click.Context, target: str | None) -> None:
       unique-cli ls scope_abc    List by scope ID
     """
     output = cmd_ls(LazyState.get(ctx), target)
-    emit(output)
+    emit(output, is_error=_is_ls_error_output)
 
 
 @main.command()
 @click.argument("name")
 @click.pass_context
 def mkdir(ctx: click.Context, name: str) -> None:
-    """Create a new folder under the current directory.
+    """Create a folder by relative name or absolute path.
 
     \b
-    NAME is the folder name to create. Nested paths are supported
-    (e.g., "A/B/C" creates the full hierarchy).
+    A relative NAME is created under the current directory. An absolute
+    path (starting with /) is created from the root, including under
+    /home-<userId>. Nested paths create the full hierarchy.
 
     \b
     Examples:
       unique-cli mkdir Q2
       unique-cli mkdir "2025/Q1"
+      unique-cli mkdir /home-user_1/second-brain/clients/X
     """
     output = cmd_mkdir(LazyState.get(ctx), name)
     emit(output, is_error=_is_mkdir_error_output)
@@ -421,7 +429,7 @@ def upload(ctx: click.Context, local_path: str, destination: str | None) -> None
       unique-cli upload ./report.pdf /Archive/2025/
     """
     output = cmd_upload(LazyState.get(ctx), local_path, destination)
-    emit(output)
+    emit(output, is_error=_is_upload_error_output)
 
 
 @main.command()

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev4}/unique_sdk/cli/commands/files.py

@@ -11,6 +11,7 @@ from typing import Any
 
 import unique_sdk
 from unique_sdk.cli.formatting import format_content_info
+from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.state import ShellState
 from unique_sdk.utils.file_io import download_content, upload_file
 
@@ -280,6 +281,18 @@ def _resolve_upload_destination(
         resolved_id = info.get("id")
         if not resolved_id:
             raise ValueError(f"folder not found: {folder_path}")
+        try:
+            actual = canonical_folder_path(
+                state.config.user_id,
+                state.config.company_id,
+                resolved_id,
+            )
+        except (ValueError, unique_sdk.UniqueError) as e:
+            raise ValueError(f"refused to upload to {folder_path}: {e}") from e
+        if not same_folder_path(actual, folder_path):
+            raise ValueError(
+                f"refused to upload to {folder_path}: resolved to {actual}"
+            )
         return resolved_id, display_name
 
     scope_id = state.scope_id
@@ -350,7 +363,12 @@ def cmd_upload(
             versioning_enabled=True,
         )
 
-        content_id = result.id if hasattr(result, "id") else "?"
+        content_id = getattr(result, "id", None)
+        if not content_id:
+            return (
+                f"upload: refused to upload {display_name} to {scope_id}: "
+                "no content id returned"
+            )
         folder_path = unique_sdk.Folder.get_folder_path(
             user_id=state.config.user_id,
             company_id=state.config.company_id,
@@ -358,7 +376,7 @@ def cmd_upload(
         ).get("folderPath", scope_id)
         return f"Uploaded: {display_name} ({content_id}) to {folder_path}"
 
-    except (ValueError, unique_sdk.UniqueError, OSError) as e:
+    except (ValueError, unique_sdk.UniqueError, OSError, RuntimeError) as e:
         return f"upload: {e}"
 
 
@@ -492,6 +510,15 @@ def cmd_mv_file(state: ShellState, old_name: str, new_name: str) -> str:
         return f"mv: {e}"
 
 
+def is_upload_error_output(output: str) -> bool:
+    """Return True when *output* is a ``cmd_upload`` error.
+
+    Success text is ``Uploaded: ...``. Local misses, missing destinations,
+    and API failures all start with ``upload:`` and must exit non-zero.
+    """
+    return output.startswith("upload:")
+
+
 def is_permission_denied_output(output: str) -> bool:
     """Return ``True`` when a file-op result is a permission/scope denial.
 

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev4}/unique_sdk/cli/commands/folders.py

@@ -6,6 +6,7 @@ import os
 
 import unique_sdk
 from unique_sdk.cli.formatting import format_folder_info
+from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.state import ShellState
 
 
@@ -40,8 +41,60 @@ def _metadata_filter_denies_folder(state: ShellState, scope_id: str | None) -> b
     return not state.folder_allowed_by_metadata_filter(scope_id)
 
 
+def _existing_folder_id(state: ShellState, folder_path: str) -> str | None:
+    """Return the scope id at *folder_path* when that exact folder exists."""
+    try:
+        info = unique_sdk.Folder.get_info(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            folderPath=folder_path,
+        )
+    except (ValueError, unique_sdk.UniqueError):
+        return None
+    folder_id = info.get("id")
+    if not folder_id:
+        return None
+    try:
+        actual = canonical_folder_path(
+            state.config.user_id,
+            state.config.company_id,
+            folder_id,
+        )
+    except (ValueError, unique_sdk.UniqueError):
+        return None
+    if not same_folder_path(actual, folder_path):
+        return None
+    return folder_id
+
+
+def _created_folder_error(
+    state: ShellState,
+    scope_id: str | None,
+    folder_path: str,
+) -> str | None:
+    """Return an ``mkdir:`` error when *scope_id* is not exactly *folder_path*.
+
+    ``create_paths`` can return the ``/home-<userId>`` id in place of the leaf.
+    A failed lookup is a refusal: printing ``Created:`` would claim the folder
+    exists.
+    """
+    if not scope_id:
+        return f"mkdir: refused to create {folder_path}"
+    try:
+        actual = canonical_folder_path(
+            state.config.user_id,
+            state.config.company_id,
+            scope_id,
+        )
+    except (ValueError, unique_sdk.UniqueError) as e:
+        return f"mkdir: refused to create {folder_path}: {e}"
+    if not same_folder_path(actual, folder_path):
+        return f"mkdir: refused to create {folder_path}: resolved to {actual}"
+    return None
+
+
 def cmd_mkdir(state: ShellState, name: str) -> str:
-    """Create a new folder under the current directory."""
+    """Create a folder by relative name or absolute path."""
     # A per-message metaDataFilter *replaces* the static scopeIds, so the
     # static-scope check must not over-deny an in-filter destination; the
     # normalized path is gated against the filter below. See UN-21780.
@@ -49,7 +102,7 @@ def cmd_mkdir(state: ShellState, name: str) -> str:
         state.workspace_metadata_filter is None
         and not state.is_folder_target_within_workspace(name)
     ):
-        return "mkdir: permission denied (outside workspace scope)"
+        return f"mkdir: permission denied: refused {name} (outside workspace scope)"
     # Resolve the destination (collapsing any `..`) and gate the *path*, not
     # just the current scope id: `mkdir ../../Other/X` would otherwise pass a
     # cwd-only check and create structure outside the per-message task scope.
@@ -68,9 +121,15 @@ def cmd_mkdir(state: ShellState, name: str) -> str:
         )
         created = result.get("createdFolders", [])
         if created:
-            last = created[-1]
-            return f"Created: {full_path} ({last['id']})"
-        return f"Created: {full_path}"
+            last_id = created[-1].get("id")
+            mismatch = _created_folder_error(state, last_id, full_path)
+            if mismatch:
+                return mismatch
+            return f"Created: {full_path} ({last_id})"
+        existing_id = _existing_folder_id(state, full_path)
+        if existing_id:
+            return f"Created: {full_path} ({existing_id})"
+        return f"mkdir: refused to create {full_path}"
     except (ValueError, unique_sdk.UniqueError) as e:
         return f"mkdir: {e}"
 

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev4}/unique_sdk/cli/commands/navigation.py

@@ -7,6 +7,7 @@ from typing import Any
 import unique_sdk
 from unique_sdk.cli.formatting import format_ls
 from unique_sdk.cli.metadata_filter import _collect_filter_targets
+from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.state import ShellState
 
 
@@ -23,13 +24,73 @@ def cmd_cd(state: ShellState, target: str) -> str:
         return f"cd: {e}"
 
 
+def _canonical_listing_error(
+    state: ShellState,
+    label: str,
+    claimed_path: str,
+    scope_id: str,
+) -> str | None:
+    """Return an ``ls:`` error when *scope_id* is not exactly *claimed_path*.
+
+    ``get_info`` can hand back an ancestor for ``/home-<userId>/...``. The
+    comparison runs before any rows are trusted, including when that ancestor
+    has children. A failed lookup is an error: printing ``(empty)`` would hide
+    it.
+    """
+    try:
+        actual = canonical_folder_path(
+            state.config.user_id,
+            state.config.company_id,
+            scope_id,
+        )
+    except (ValueError, unique_sdk.UniqueError) as e:
+        return f"ls: cannot list {label}: {e}"
+    if not same_folder_path(actual, claimed_path):
+        return (
+            f"ls: cannot list {label}: resolved to {actual} instead (not listable here)"
+        )
+    return None
+
+
+def _counts_without_rows_error(
+    label: str,
+    total_folders: int,
+    total_files: int,
+) -> str | None:
+    """Return an ``ls:`` error when the API reports rows it did not return."""
+    if total_folders or total_files:
+        return (
+            f"ls: cannot list {label}: listing returned no entries "
+            f"({total_folders} folder(s), {total_files} file(s) reported)"
+        )
+    return None
+
+
+def _with_unlistable_marker(output: str, unlistable: list[str]) -> str:
+    """Append folders that could not be listed, or fail when none could."""
+    if not unlistable:
+        return output
+    if output.startswith("(empty)"):
+        return "ls: cannot list " + ", ".join(unlistable) + " (not listable)"
+    return output + "\nnot listable: " + ", ".join(unlistable)
+
+
+def is_ls_error_output(output: str) -> bool:
+    """Return True when *output* is a ``cmd_ls`` error.
+
+    Success listings start with a table, ``(empty)``, or a count. Failures
+    start with ``ls:`` and must exit non-zero from the one-shot CLI.
+    """
+    return output.startswith("ls:")
+
+
 def cmd_ls(state: ShellState, target: str | None = None) -> str:
     """List folders and files at the given (or current) path."""
     try:
         if target is not None:
-            _, scope_id = state.resolve_path(target)
+            resolved_path, scope_id = state.resolve_path(target)
         else:
-            scope_id = state.scope_id
+            resolved_path, scope_id = state.cwd, state.scope_id
 
         # A non-root target must lie inside the per-message scope: without
         # this, `ls <path>` would enumerate out-of-scope folders/files that
@@ -56,6 +117,7 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
             # UN-21780.
             folder_ids = state.navigable_folder_ids()
             scoped_folders: list[Any] = []
+            unlistable_folders: list[str] = []
             for sid in folder_ids:
                 try:
                     scoped_folders.append(
@@ -66,7 +128,7 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                         )
                     )
                 except unique_sdk.UniqueError:
-                    pass
+                    unlistable_folders.append(sid)
             scoped_files: list[Any] = []
             for cid in content_ids:
                 # A contentId mentioned in the filter is not necessarily in
@@ -93,12 +155,13 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                 f"\n{len(scoped_folders)} folder(s), {len(scoped_files)} "
                 "file(s) in task scope"
             )
-            return output + summary
+            return _with_unlistable_marker(output + summary, unlistable_folders)
 
         # When at root with a workspace restriction, show only the allowed scope
         # folders — the agent must not see the full company folder tree.
         if scope_id is None and state.workspace_scope_ids:
             folders: list[Any] = []
+            unlistable_folders = []
             for ws_id in state.workspace_scope_ids:
                 try:
                     info = unique_sdk.Folder.get_info(
@@ -108,10 +171,21 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                     )
                     folders.append(info)
                 except unique_sdk.UniqueError:
-                    pass
+                    unlistable_folders.append(ws_id)
             output = format_ls(folders, [])
             summary = f"\n{len(folders)} folder(s), 0 file(s)"
-            return output + summary
+            return _with_unlistable_marker(output + summary, unlistable_folders)
+
+        if scope_id:
+            label = target if target is not None else resolved_path
+            path_error = _canonical_listing_error(
+                state,
+                label,
+                resolved_path,
+                scope_id,
+            )
+            if path_error:
+                return path_error
 
         folder_params: dict[str, Any] = {}
         content_params: dict[str, Any] = {}
@@ -136,6 +210,16 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
         total_folders = folder_result.get("totalCount", len(folders))
         total_files = content_result.get("totalCount", len(files))
 
+        if scope_id and not folders and not files:
+            label = target if target is not None else resolved_path
+            counts_error = _counts_without_rows_error(
+                label,
+                total_folders,
+                total_files,
+            )
+            if counts_error:
+                return counts_error
+
         # With a per-message filter, listing inside an allowed folder must not
         # reveal files the filter excludes (e.g. a combined folder + contentId
         # allowlist): read/cite would deny them, so ls must hide them too.

unique_sdk-2026.44.0.dev4/unique_sdk/cli/paths.py

@@ -0,0 +1,42 @@
+"""Folder-path comparisons shared by the CLI commands."""
+
+from __future__ import annotations
+
+import os
+
+import unique_sdk
+
+
+def same_folder_path(left: str, right: str) -> bool:
+    """True when two folder paths name the same location.
+
+    A missing leading slash and a trailing slash do not make two paths differ.
+    """
+
+    def norm(value: str) -> str:
+        text = value.strip()
+        if text and not text.startswith("/"):
+            text = f"/{text}"
+        return os.path.normpath(text.rstrip("/")) or "/"
+
+    return norm(left) == norm(right)
+
+
+def canonical_folder_path(user_id: str, company_id: str, scope_id: str) -> str:
+    """Return the stored path for *scope_id*.
+
+    Raises:
+        ValueError: The folder has no path.
+        unique_sdk.UniqueError: The path lookup failed.
+    """
+    actual = (
+        unique_sdk.Folder.get_folder_path(
+            user_id=user_id,
+            company_id=company_id,
+            scope_id=scope_id,
+        ).get("folderPath")
+        or ""
+    )
+    if not actual:
+        raise ValueError(f"folder {scope_id} has no path")
+    return actual

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev4}/unique_sdk/cli/shell.py

@@ -239,12 +239,13 @@ class UniqueShell(cmd.Cmd):
     # -- Folder operations --
 
     def do_mkdir(self, arg: str) -> None:
-        """Create a new folder under the current directory.
+        """Create a folder by relative name or absolute path.
 
         Usage: mkdir <name>
 
-        Creates a child folder with the given name. Nested paths are
-        supported (e.g., "A/B/C" creates the full hierarchy).
+        A relative name is created under the current directory. An absolute
+        path (starting with /) is created from the root, including under
+        /home-<userId>. Nested paths create the full hierarchy.
 
         Examples:
           /Reports> mkdir Q2
@@ -252,6 +253,9 @@ class UniqueShell(cmd.Cmd):
 
           /Reports> mkdir "2025/Q1"
           Created: /Reports/2025/Q1 (scope_xyz999)
+
+          /> mkdir /home-user_1/second-brain/clients/X
+          Created: /home-user_1/second-brain/clients/X (scope_home1)
         """
         name = arg.strip()
         if not name:

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev4}/unique_sdk/cli/state.py

@@ -10,6 +10,7 @@ from typing import Any
 import unique_sdk
 from unique_sdk.cli.config import Config
 from unique_sdk.cli.metadata_filter import MetadataFilter
+from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.workspace import manifest_path as workspace_manifest_path
 
 _SEARCH_CONFIG_FILENAME = ".unique-search.json"
@@ -561,6 +562,19 @@ class ShellState:
     def prompt(self) -> str:
         return f"{self._path}> "
 
+    def _enter_folder(self, scope_id: str, folder_path: str) -> str:
+        """Store *folder_path* only when *scope_id* is that exact folder."""
+        actual = canonical_folder_path(
+            self.config.user_id,
+            self.config.company_id,
+            scope_id,
+        )
+        if not same_folder_path(actual, folder_path):
+            raise ValueError(f"cannot change to {folder_path}: resolved to {actual}")
+        self._scope_id = scope_id
+        self._path = folder_path
+        return self._path
+
     def cd(self, target: str) -> str:
         """Change directory. Returns the new path.
 
@@ -590,8 +604,7 @@ class ShellState:
                     company_id=self.config.company_id,
                     folderPath=parent,
                 )
-                self._path = parent
-                self._scope_id = info["id"]
+                return self._enter_folder(info["id"], parent)
             return self._path
 
         if target.startswith("scope_"):
@@ -619,9 +632,7 @@ class ShellState:
             company_id=self.config.company_id,
             folderPath=resolved_path,
         )
-        self._scope_id = info["id"]
-        self._path = resolved_path
-        return self._path
+        return self._enter_folder(info["id"], resolved_path)
 
     def resolve_path(self, target: str | None) -> tuple[str, str | None]:
         """Resolve a target to (path, scope_id) without changing state.