deepctl-core 0.2.19__tar.gz → 0.3.1__tar.gz

{deepctl_core-0.2.19 → deepctl_core-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl-core
-Version: 0.2.19
+Version: 0.3.1
 Summary: Core components for deepctl
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>

{deepctl_core-0.2.19 → deepctl_core-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-core"
-version = "0.2.19" # x-release-please-version
+version = "0.3.1" # x-release-please-version
 description = "Core components for deepctl"
 readme = "README.md"
 license = "MIT"

{deepctl_core-0.2.19 → deepctl_core-0.3.1}/src/deepctl_core/__init__.py

@@ -5,8 +5,10 @@ from .base_command import BaseCommand
 from .base_group_command import BaseGroupCommand
 from .client import DeepgramClient
 from .config import Config
+from .hosts import CredentialHostError
 from .models import (
     BaseResult,
+    CodedErrorResult,
     ErrorResult,
     PluginInfo,
     ProfileInfo,
@@ -18,6 +20,7 @@ from .output import (
     get_output_format,
     get_status_console,
     is_agentic,
+    is_ai_agent,
     print_error,
     print_info,
     print_output,
@@ -41,7 +44,9 @@ __all__ = [
     "BaseCommand",
     "BaseGroupCommand",
     "BaseResult",
+    "CodedErrorResult",
     "Config",
+    "CredentialHostError",
     "DeepgramClient",
     "ErrorResult",
     "OutputFormatter",
@@ -56,6 +61,7 @@ __all__ = [
     "get_status_console",
     "get_timing_summary",
     "is_agentic",
+    "is_ai_agent",
     "is_timing_enabled",
     "print_error",
     "print_info",

deepctl_core-0.3.1/src/deepctl_core/_launcher.py

@@ -0,0 +1,67 @@
+"""Which wrapper, if any, started deepctl (internal; not a public API).
+
+The ``@deepgram/cli`` npm package runs deepctl from a private venv and says
+so in ``DEEPCTL_LAUNCHER``: ``npm`` for an installed package (global, or a
+project dependency: the launcher can't tell them apart), ``npx`` for
+``npx``/``npm exec``. Nothing else sets it.
+
+The variable is read once and removed from ``os.environ``, so it describes
+this process only. Anything deepctl spawns -- a starter app, a shell, another
+``dg`` -- must not inherit a claim about how *it* was installed.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+LAUNCHER_ENV_VAR = "DEEPCTL_LAUNCHER"
+NPM_LAUNCHERS = frozenset({"npm", "npx"})
+
+_captured = False
+_launcher: str | None = None
+
+
+def capture_launcher() -> str | None:
+    """The launcher that started deepctl, captured on the first call.
+
+    Reads and removes ``DEEPCTL_LAUNCHER``, unless ``deepctl.main`` already
+    did and says so with ``LAUNCHER_CAPTURED``: then its ``LAUNCHER`` is the
+    value. From 0.5.0 (#165), ``deepctl.main`` is stdlib-only and removes the
+    variable before deepctl_core is imported, so it is gone from
+    ``os.environ`` by the time this runs. A ``deepctl.main`` that calls this
+    function itself sets no flag, and the check falls through.
+    """
+    global _captured, _launcher
+    if not _captured:
+        entry = sys.modules.get("deepctl.main")
+        if entry is not None and getattr(entry, "LAUNCHER_CAPTURED", False):
+            _launcher = entry.LAUNCHER
+        else:
+            _launcher = os.environ.pop(LAUNCHER_ENV_VAR, None) or None
+        _captured = True
+    return _launcher
+
+
+def get_launcher() -> str | None:
+    """Return the launcher that started deepctl, or ``None``."""
+    return capture_launcher()
+
+
+def launched_via_npm() -> bool:
+    """Return True if the npm package (global install or npx) started deepctl."""
+    return get_launcher() in NPM_LAUNCHERS
+
+
+def npm_upgrade_command() -> str:
+    """Return the command that upgrades an npm-launched deepctl."""
+    if get_launcher() == "npx":
+        return "npx @deepgram/cli@latest"
+    return "npm install -g @deepgram/cli@latest"
+
+
+def reset_launcher_for_tests() -> None:
+    """Forget the captured value so the next call re-reads the environment."""
+    global _captured, _launcher
+    _captured = False
+    _launcher = None

deepctl_core-0.3.1/src/deepctl_core/_plugin_trust.py

@@ -0,0 +1,118 @@
+"""Trusted locations for plugin settings and the plugin venv.
+
+Built on the config module's real-home trust helpers: the account's home
+comes from the OS (``HOME`` aside, the known-folder API on Windows), and in
+an AI agent session the user config is read only through the checked open
+of the trust root (no symlinked component, owned by this user, one link, no
+group or other write).
+"""
+
+import os
+from pathlib import Path
+
+import yaml
+
+from . import config as _config
+from .output import is_ai_agent
+
+__all__ = [
+    "agent_plugin_venv",
+    "allow_override_names",
+    "contained_in",
+    "is_ai_agent",
+    "real_home_plugin_venv",
+    "trusted_user_config_file",
+]
+
+
+def _agent_trust_root() -> Path | None:
+    """The trust root's config path, unless it lies inside the working
+    directory (and that directory isn't the home itself)."""
+    location = _config._trust_root_location()
+    home = _config._real_home()
+    if location is None or home is None:
+        return None
+    real = location[1]
+    try:
+        resolved = os.path.realpath(real)
+        cwd = os.path.realpath(os.getcwd())
+        at_home = cwd == os.path.realpath(home)
+    except (OSError, ValueError):
+        return None
+    if not at_home and _under(resolved, cwd):
+        return None
+    return real
+
+
+def trusted_user_config_file() -> Path | None:
+    """The user config file at its default location. Under an AI-agent
+    signal, only the one derived from the real home directory."""
+    if is_ai_agent():
+        return _agent_trust_root()
+    return _config._default_config_file()
+
+
+def allow_override_names() -> frozenset[str]:
+    """Command paths listed in ``plugins.allow_override`` of the trusted file.
+
+    Never read from a ``--config`` file, ``deepgram.yaml`` or the environment.
+    Under an AI-agent signal the file must also pass the trust-root checks.
+    Any read or parse problem yields an empty set.
+    """
+    try:
+        if is_ai_agent():
+            if _agent_trust_root() is None:
+                return frozenset()
+            root = _config._open_trust_root()
+            data = root[1] if root is not None else None
+        else:
+            _, data = _config._read_yaml_fd(_config._default_config_file())
+    except (OSError, ValueError, yaml.YAMLError):
+        return frozenset()
+    plugins = data.get("plugins") if isinstance(data, dict) else None
+    names = plugins.get("allow_override") if isinstance(plugins, dict) else None
+    if not isinstance(names, list):
+        return frozenset()
+    return frozenset(" ".join(n.split()) for n in names if isinstance(n, str))
+
+
+def _under(path: str, directory: str) -> bool:
+    return path == directory or path.startswith(directory.rstrip(os.sep) + os.sep)
+
+
+def real_home_plugin_venv() -> Path | None:
+    """``.deepctl/plugins/venv`` under the real home directory, unchecked."""
+    home = _config._real_home()
+    return None if home is None else Path(home, ".deepctl", "plugins", "venv")
+
+
+def agent_plugin_venv() -> Path | None:
+    """The plugin venv to load under an AI-agent signal, or ``None``.
+
+    It is ``.deepctl/plugins/venv`` under the account's real home directory
+    (``HOME`` aside). ``None`` when the home can't be read, when a directory
+    below the home on the way to the venv is a symlink, or when the venv lies
+    inside the working directory and that directory isn't the home itself.
+    """
+    home = _config._real_home()
+    if home is None:
+        return None
+    try:
+        real_home = os.path.realpath(home)
+        venv = os.path.join(real_home, ".deepctl", "plugins", "venv")
+        if os.path.realpath(venv) != venv:
+            return None
+        cwd = os.path.realpath(os.getcwd())
+    except (OSError, ValueError):
+        return None
+    if cwd != real_home and _under(venv, cwd):
+        return None
+    return Path(venv)
+
+
+def contained_in(path: Path, directory: Path) -> bool:
+    """True when ``path`` resolves inside ``directory`` (resolved)."""
+    try:
+        return _under(os.path.realpath(path), os.path.realpath(directory))
+    except (OSError, ValueError):
+        return False