ndi-cli 0.4.0__py3-none-any.whl

ndi_cli/__init__.py

@@ -0,0 +1,9 @@
+"""``ndi`` — the NDI platform CLI.
+
+Document operations, jobs, and workspace lifecycle wrap ``ndi-sdk`` ``/v1``
+methods. The six workspace tools (``folder-metadata``, ``file-metadata``,
+``read-file``, ``ask-file``, ``run-sql``, ``hybrid-search``) remain the
+in-sandbox surface.
+"""
+
+__version__ = "0.4.0"

ndi_cli/_cli.py

@@ -0,0 +1,166 @@
+"""``ndi`` entry point: workspace tools plus the platform verbs.
+
+The six workspace tools stay available inside an agent sandbox. Every other
+verb is refused when ``$NDI_CLI_SOCKET`` is set, before any client is built.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from ndi_sdk.client import NdiClient
+from ndi_sdk.errors import NdiError, NdiStatusError
+from ndi_sdk.resources.tools import SyncTools
+
+from ndi_cli import _docops, _jobs, _login, _tools, _workspace
+from ndi_cli._config import ConfigError, resolve_settings
+from ndi_cli._local import SOCKET_ENV, TOKEN_ENV, LocalTransport
+from ndi_cli._tools import parse_pages
+
+# qa-file runs a durable workflow that legitimately takes minutes; the metadata,
+# read, and run-sql tools answer in seconds but share the generous bound.
+DEFAULT_TIMEOUT_SECONDS = 900.0
+_VALIDATION_ERROR_LIMIT = 5
+_VALIDATION_ERROR_CHARS = 500
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 2
+    family = getattr(args, "family", None)
+    socket_path = os.environ.get(SOCKET_ENV)
+    # Presence, not truthiness: an empty $NDI_CLI_SOCKET still means "inside an
+    # agent run", and must not silently unlock the full platform CLI.
+    in_agent_run = socket_path is not None
+    workspace_flag = getattr(args, "workspace", None)
+    if workspace_flag is not None and not workspace_flag.strip():
+        print("error: --workspace needs a workspace id", file=sys.stderr)
+        return 2
+    if in_agent_run:
+        if family != "tool":
+            print(f"error: {args.command} is not available in an agent run", file=sys.stderr)
+            return 2
+        if workspace_flag:
+            print(
+                "error: --workspace is not permitted in an agent run — the run is pinned to $NDI_WORKSPACE_ID.", file=sys.stderr
+            )
+            return 2
+        if not socket_path:
+            print(f"error: ${SOCKET_ENV} is set but empty; the agent run has no CLI socket to talk to.", file=sys.stderr)
+            return 2
+    if family == "standalone":
+        try:
+            return args.run(args)
+        except ConfigError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        except ValueError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+    try:
+        if os.environ.get("NDI_JOB_ID") and not in_agent_run:
+            raise ConfigError("The internal NDI CLI execution context is unavailable.")
+        if in_agent_run:
+            workspace_id = os.environ.get("NDI_WORKSPACE_ID", "")
+            transport = LocalTransport(socket_path, args.timeout, os.environ.get(TOKEN_ENV, ""))
+            response = args.run(SyncTools(transport), workspace_id, args)
+            return _print_tool(args, response)
+        settings = resolve_settings(
+            workspace_override=workspace_flag,
+            require_workspace=getattr(args, "needs_workspace", True),
+        )
+        timeout = getattr(args, "timeout", DEFAULT_TIMEOUT_SECONDS)
+        with NdiClient(api_key=settings.api_key, base_url=settings.base_url, timeout=timeout) as client:
+            if family == "tool":
+                return _print_tool(args, args.run(client.tools, settings.workspace_id, args))
+            return args.run(client, settings.workspace_id, args)
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except NdiStatusError as exc:
+        code = f" [{exc.code}]" if exc.code else ""
+        print(f"error: {exc.status_code}{code} {exc.message}", file=sys.stderr)
+        for line in _validation_error_lines(exc.body.detail if exc.body else None):
+            print(f"  - {line}", file=sys.stderr)
+        return 1
+    except NdiError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _print_tool(args: argparse.Namespace, response) -> int:
+    if args.json:
+        print(response.model_dump_json(indent=2, exclude_none=True))
+        return 0
+    print(args.render(response))
+    return 0
+
+
+def _validation_error_lines(detail: object) -> list[str]:
+    """Keep field constraints actionable without echoing request inputs or arbitrary detail."""
+    errors = detail.get("errors") if isinstance(detail, dict) else None
+    if not isinstance(errors, list):
+        return []
+    lines = []
+    for error in errors[:_VALIDATION_ERROR_LIMIT]:
+        if not isinstance(error, dict) or not isinstance(message := error.get("msg"), str) or not message.strip():
+            continue
+        location = error.get("loc")
+        if isinstance(location, (list, tuple)) and all(isinstance(part, (str, int)) for part in location):
+            if location and location[0] == "body":
+                location = location[1:]
+            field = ".".join(str(part) for part in location)
+        else:
+            field = ""
+        line = f"{field}: {message}" if field else message
+        truncated = len(line) > _VALIDATION_ERROR_CHARS
+        clipped = line[: _VALIDATION_ERROR_CHARS - 1] if truncated else line
+        clean = " ".join("".join(char if char.isprintable() else " " for char in clipped).split())
+        lines.append(clean + ("…" if truncated else ""))
+    if lines and len(errors) > _VALIDATION_ERROR_LIMIT:
+        lines.append(f"(+{len(errors) - _VALIDATION_ERROR_LIMIT} more validation errors)")
+    return lines
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ndi",
+        description=(
+            "NDI platform CLI. Login, document operations, jobs, and workspace lifecycle talk to /v1; "
+            "the six workspace tools also run inside an agent sandbox. Credentials come from "
+            "$NDI_API_KEY / $NDI_BASE_URL or ~/.ndi/config.toml."
+        ),
+    )
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", help="Print the raw response JSON instead of the text rendering.")
+    common.add_argument("--workspace", metavar="ID", default=None, help="Override $NDI_WORKSPACE_ID for this call.")
+    common.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        metavar="SECONDS",
+        help=f"Per-request HTTP timeout (default {DEFAULT_TIMEOUT_SECONDS:.0f}s; ask-file and job waits can take minutes).",
+    )
+    sub = parser.add_subparsers(dest="command")
+    _login.add_parsers(sub)
+    _tools.add_parsers(sub, common)
+    _docops.add_parsers(sub, common)
+    _jobs.add_parsers(sub, common)
+    _workspace.add_parsers(sub, common)
+    return parser
+
+
+def _parse_pages(spec: str | None) -> list[int] | None:
+    return parse_pages(spec)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ndi_cli/_config.py

@@ -0,0 +1,94 @@
+"""Resolve the API key, base URL, and workspace the CLI talks to.
+
+The agent-facing contract is that credentials never travel on the command line:
+
+- ``$NDI_API_KEY`` — else ``api_key`` in ``~/.ndi/config.toml`` (the file
+  ``ndi login`` / ``ndi-mcp login`` writes; ``$NDI_CONFIG_PATH`` overrides its location).
+- ``$NDI_BASE_URL`` — else ``base_url`` in the same file, else the SDK default.
+- ``$NDI_WORKSPACE_ID`` — else ``workspace_id`` in the same file (``--workspace``
+  overrides either for one call). A missing workspace is a startup failure
+  with a hint, not a 404 on the first call.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from ndi_sdk.client import API_KEY_ENV, BASE_URL_ENV
+
+WORKSPACE_ENV = "NDI_WORKSPACE_ID"
+CONFIG_PATH_ENV = "NDI_CONFIG_PATH"
+DEFAULT_CONFIG_PATH = Path.home() / ".ndi" / "config.toml"
+
+_CONFIG_KEYS = ("api_key", "base_url", "workspace_id")
+
+
+class ConfigError(ValueError):
+    """A required setting could not be resolved."""
+
+
+@dataclass(frozen=True)
+class Settings:
+    api_key: str
+    workspace_id: str
+    base_url: str | None = None
+
+
+def config_path() -> Path:
+    override = os.environ.get(CONFIG_PATH_ENV)
+    return Path(override) if override else DEFAULT_CONFIG_PATH
+
+
+def resolve_settings(*, workspace_override: str | None = None, require_workspace: bool = True) -> Settings:
+    """Environment first, then the config file.
+
+    Raises:
+        ConfigError: When the API key or a required workspace id is missing.
+    """
+    api_key = os.environ.get(API_KEY_ENV)
+    base_url = os.environ.get(BASE_URL_ENV)
+    workspace_id = workspace_override or os.environ.get(WORKSPACE_ENV)
+    # A broken config file only matters when a required value has to come from
+    # it — then the error names the real cause instead of "no API key".
+    file_error: ConfigError | None = None
+    if not api_key or not base_url or not workspace_id:
+        try:
+            file_values = _read_config(config_path())
+        except ConfigError as exc:
+            file_error = exc
+            file_values = {}
+        api_key = api_key or file_values.get("api_key")
+        base_url = base_url or file_values.get("base_url")
+        workspace_id = workspace_id or file_values.get("workspace_id")
+    if not api_key:
+        raise file_error or ConfigError(f"no API key: set ${API_KEY_ENV} or run `ndi login` (or api_key in {config_path()})")
+    if require_workspace and not workspace_id:
+        raise file_error or ConfigError(f"no workspace: set ${WORKSPACE_ENV} (or workspace_id in {config_path()})")
+    return Settings(api_key=api_key, workspace_id=workspace_id or "", base_url=base_url)
+
+
+def read_config_values(path: Path) -> dict[str, str]:
+    """The config file's own settings, or {} when it is missing or unreadable."""
+    try:
+        return _read_config(path)
+    except ConfigError:
+        return {}
+
+
+def _read_config(path: Path) -> dict[str, str]:
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as handle:
+            parsed = tomllib.load(handle)
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError, OSError) as exc:
+        raise ConfigError(f"config file {path} is unreadable: {exc}") from exc
+    values: dict[str, str] = {}
+    for key in _CONFIG_KEYS:
+        value = parsed.get(key)
+        if isinstance(value, str) and value:
+            values[key] = value
+    return values