logion-cli 0.1.0__py3-none-any.whl

cli/_errors.py

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: MIT
+"""CLI error handling — map SDK errors to exit codes."""
+
+from __future__ import annotations
+
+import json
+import sys
+from uuid import UUID
+
+from logion import APIError, LogionError
+
+ALLOWED_ERROR_CODES = frozenset({
+    "auth_missing",
+    "entitlement_missing",
+    "entitlement_expired",
+    "unsafe_identifier",
+    "not_found",
+    "validation_failed",
+    "server_error",
+    "confirmation_required",
+    "top_up_timeout",
+})
+
+
+def handle_error(exc: Exception) -> int:
+    """Map an exception to an exit code and print a user-facing message."""
+    if isinstance(exc, APIError):
+        detail = getattr(exc, "detail", str(exc))
+        if isinstance(detail, list):
+            detail = "; ".join(str(d) for d in detail)
+        status_code = getattr(exc, "status_code", "?")
+        print(f"API error {status_code}: {detail}", file=sys.stderr)
+        return 1
+    if isinstance(exc, LogionError):
+        print(f"Logion error: {exc}", file=sys.stderr)
+        return 1
+    raise exc
+
+
+def print_err(msg: str) -> None:
+    """Print a user-facing message to stderr."""
+    print(msg, file=sys.stderr)
+
+
+def emit_error_json(code: str, message: str, exit_code: int) -> None:
+    """Emit a v1 JSON error envelope to stderr."""
+    payload = {
+        "version": "v1",
+        "kind": "logion.error",
+        "data": {"code": code, "message": message, "exit_code": exit_code},
+    }
+    print(json.dumps(payload, indent=2, sort_keys=True), file=sys.stderr)
+
+
+def require_non_empty_id(value: str, label: str) -> int | None:
+    """Return ``2`` if *value* is empty/whitespace, else ``None``."""
+    if not value or not value.strip():
+        print_err(f"Error: {label} must not be empty.")
+        return 2
+    return None
+
+
+def validate_uuid(value: str, label: str) -> int | None:
+    """Return ``2`` if *value* is not a valid UUID, else ``None``."""
+    try:
+        UUID(value)
+    except ValueError:
+        print_err(f"Error: {label} must be a valid UUID (got: {value!r}).")
+        return 2
+    return None
+
+
+def validate_uuid_id(value: str, label: str) -> int | None:
+    """Check *value* is non-empty and a valid UUID.
+
+    Combines :func:`require_non_empty_id` and :func:`validate_uuid`
+    into a single call for positional-ID validation.
+    """
+    empty = require_non_empty_id(value, label)
+    if empty is not None:
+        return empty
+    return validate_uuid(value, label)

cli/_first_run.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+"""First-run onboarding trigger.
+
+Decides whether to run onboarding before dispatching a command. The
+matrix is deliberately conservative: never hijack help/version/docs,
+never prompt in CI/non-interactive shells, always respect --no-onboarding.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from dataclasses import dataclass
+
+from cli._credentials import is_onboarded
+
+# Commands that must never trigger onboarding (read-only / informational).
+SKIP_COMMANDS: frozenset[str] = frozenset({"docs", "onboarding"})
+
+# Commands that need identity/companion/local-state to be useful.
+# ``listings`` is excluded because search/browse is public and read-only —
+# forcing onboarding before a prospective user can explore the marketplace
+# adds friction without value.
+NEEDS_SETUP_COMMANDS: frozenset[str] = frozenset({
+    "courses",
+    "credits",
+    "payments",
+    "referrals",
+    "reports",
+    "course-reviews",
+    "bounties",
+    "skills",
+    "recall",
+})
+
+
+@dataclass(frozen=True)
+class TriggerDecision:
+    should_run: bool
+    reason: str  # "already-onboarded" | "no-tty" | "noninteractive-env" |
+    # "no-onboarding-flag" | "skip-command" | "help-version" |
+    # "command-needs-setup" | "unknown-command"
+
+
+def is_noninteractive() -> bool:
+    """True in CI / piped / explicitly-flagged non-interactive shells."""
+    if os.getenv("LOGION_NONINTERACTIVE"):
+        return True
+    return not sys.stdin.isatty() or not sys.stdout.isatty()
+
+
+def _is_help_or_version(argv: list[str]) -> bool:
+    """True if argv contains a flag-level ``--help``/``-h``/``--version``.
+
+    Only tokens that start with ``-`` are considered, so a positional
+    value (e.g. a search query literally equal to ``--help``) does not
+    trigger a false positive.
+    """
+    help_flags = {"--help", "-h", "--version"}
+    return any(tok in help_flags for tok in argv if tok.startswith("-"))
+
+
+def decide(argv: list[str], args: argparse.Namespace) -> TriggerDecision:
+    """Pure decision: given parsed args + raw argv, run onboarding?"""
+    if _is_help_or_version(argv):
+        return TriggerDecision(should_run=False, reason="help-version")
+    # ``--no-onboarding`` may appear before or after the subcommand;
+    # argparse only populates ``args.no_onboarding`` when it precedes
+    # the subcommand, so check the raw argv too.
+    if "--no-onboarding" in argv or getattr(args, "no_onboarding", False):
+        return TriggerDecision(should_run=False, reason="no-onboarding-flag")
+    if os.getenv("LOGION_NO_ONBOARDING"):
+        return TriggerDecision(should_run=False, reason="no-onboarding-flag")
+    command = getattr(args, "command", None)
+    if not isinstance(command, str):
+        return TriggerDecision(should_run=False, reason="unknown-command")
+    if command in SKIP_COMMANDS:
+        return TriggerDecision(should_run=False, reason="skip-command")
+    if command not in NEEDS_SETUP_COMMANDS:
+        return TriggerDecision(should_run=False, reason="unknown-command")
+    if is_onboarded():
+        return TriggerDecision(should_run=False, reason="already-onboarded")
+    if is_noninteractive():
+        return TriggerDecision(should_run=False, reason="noninteractive-env")
+    # ``--json`` means a machine consumer is piping stdout; never
+    # hijack it with onboarding prompts or JSON of our own.
+    if getattr(args, "json_output", False):
+        return TriggerDecision(should_run=False, reason="json-output")
+    return TriggerDecision(should_run=True, reason="command-needs-setup")

cli/_harness/__init__.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: MIT
+"""Harness adapter registry.
+
+To support a new agent harness (Codex, OpenCode, Amp, ...), implement a
+:class:`~cli._harness.base.HarnessAdapter` and add it to
+:data:`_ADAPTER_TYPES`.  Nothing else changes — the onboarding flow and
+``--harness`` selection discover adapters through this registry.
+"""
+
+from __future__ import annotations
+
+from cli._harness.base import (
+    AUTOPOST_COMMAND,
+    GrantResult,
+    HarnessAdapter,
+    HarnessConfigError,
+)
+from cli._harness.claude_code import ClaudeCodeAdapter
+from cli._harness.codex import CodexAdapter
+from cli._harness.hermes import HermesAdapter
+from cli._harness.opencode import OpenCodeAdapter
+
+# Ordered registry of known adapter types.  Append new harnesses here.
+_ADAPTER_TYPES: tuple[type[HarnessAdapter], ...] = (
+    ClaudeCodeAdapter,
+    CodexAdapter,
+    OpenCodeAdapter,
+    HermesAdapter,
+)
+
+
+def all_adapters() -> list[HarnessAdapter]:
+    """Instantiate every registered adapter (production defaults)."""
+    return [cls() for cls in _ADAPTER_TYPES]
+
+
+def adapter_names() -> list[str]:
+    """Return the stable names of all registered harnesses."""
+    return [a.name for a in all_adapters()]
+
+
+def get_adapter(name: str) -> HarnessAdapter | None:
+    """Return the adapter with *name*, or ``None`` if unknown."""
+    for adapter in all_adapters():
+        if adapter.name == name:
+            return adapter
+    return None
+
+
+def detect_present() -> list[HarnessAdapter]:
+    """Return adapters whose harness appears installed on this machine."""
+    return [a for a in all_adapters() if a.is_present()]
+
+
+__all__ = [
+    "AUTOPOST_COMMAND",
+    "ClaudeCodeAdapter",
+    "CodexAdapter",
+    "GrantResult",
+    "HarnessAdapter",
+    "HarnessConfigError",
+    "HermesAdapter",
+    "OpenCodeAdapter",
+    "adapter_names",
+    "all_adapters",
+    "detect_present",
+    "get_adapter",
+]

cli/_harness/base.py

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: MIT
+"""Harness adapter contract.
+
+A *harness* is whatever agent runtime the user drives Logion from —
+Claude Code, Codex, OpenCode, Amp, and so on.  Each one gates (or does
+not gate) the commands an agent may run, and each expresses those
+permissions in its own config format.
+
+Logion cannot pre-authorize an outward-facing command across every
+harness from one place — that protection belongs to each tool's
+operator.  What Logion *can* do is translate a single, well-scoped
+grant ("let the agent run ``logion courses report-usage`` without
+prompting") into whatever native config the harness on this machine
+understands.
+
+Each harness gets one :class:`HarnessAdapter`.  Supporting a new harness
+is a new adapter added to the registry in ``__init__.py`` — no caller
+changes.  The grant itself is defined once, here, as
+:data:`AUTOPOST_COMMAND`; adapters render it into their own syntax.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+# The command whose autonomous execution the autopost grant authorizes.
+# Defined once; each adapter renders it into its harness's permission
+# syntax (e.g. Claude Code's ``Bash(logion courses report-usage:*)``).
+AUTOPOST_COMMAND: tuple[str, ...] = ("logion", "courses", "report-usage")
+
+# Permission scopes an adapter must understand.
+VALID_SCOPES: frozenset[str] = frozenset({"project", "global"})
+
+
+class HarnessConfigError(RuntimeError):
+    """Raised when a harness config exists but cannot be safely edited.
+
+    Surfaced (never swallowed) so the caller refuses to clobber a config
+    file it could not parse, rather than overwriting the user's settings.
+    """
+
+
+@dataclass(frozen=True)
+class GrantResult:
+    """Outcome of a grant/revoke on one harness at one scope."""
+
+    harness: str  # adapter ``name`` (e.g. "claude-code")
+    scope: str  # "project" | "global"
+    path: Path  # config file inspected/edited
+    changed: bool  # True if the file was actually written
+    already: bool  # grant: rule was already present; revoke: already absent
+
+    def to_dict(self) -> dict[str, object]:
+        """JSON-safe view for ``--json`` output."""
+        return {
+            "harness": self.harness,
+            "scope": self.scope,
+            "path": str(self.path),
+            "changed": self.changed,
+            "already": self.already,
+        }
+
+
+class HarnessAdapter(ABC):
+    """Bridges the Logion autopost grant to one harness's permission model."""
+
+    #: Stable machine id, used by ``--harness`` (e.g. "claude-code").
+    name: str = "unnamed"
+    #: Human-facing label (e.g. "Claude Code").
+    display_name: str = "Unnamed harness"
+
+    @abstractmethod
+    def is_present(self) -> bool:
+        """True if this harness appears installed/configured for the user."""
+        ...
+
+    @abstractmethod
+    def config_path(self, scope: str) -> Path:
+        """Resolve the settings file for *scope* ("project" | "global")."""
+        ...
+
+    @abstractmethod
+    def is_granted(self, scope: str) -> bool:
+        """True if the autopost grant is already present at *scope*."""
+        ...
+
+    @abstractmethod
+    def grant(self, scope: str) -> GrantResult:
+        """Add the autopost permission at *scope*.  Idempotent."""
+        ...
+
+    @abstractmethod
+    def revoke(self, scope: str) -> GrantResult:
+        """Remove the autopost permission at *scope*.  Idempotent."""
+        ...
+
+    @abstractmethod
+    def skill_dir(self) -> Path:
+        """Absolute dir this harness loads skills from.
+
+        e.g. Claude Code → ``~/.claude/skills``.  The onboarding
+        companion step writes/symlinks the companion SKILL bundle here.
+        """
+        ...

cli/_harness/claude_code.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: MIT
+"""Claude Code harness adapter.
+
+Claude Code gates a model's tool calls with an auto-mode classifier and
+a ``permissions.allow`` list in ``settings.json``.  An explicit ``allow``
+rule that matches a command pre-approves it, so the classifier never has
+to judge it.  This adapter inserts exactly the autopost grant — nothing
+broader — into that list.
+
+Scopes map to the two settings files Claude Code reads:
+
+* ``project`` → ``<cwd>/.claude/settings.json``
+* ``global``  → ``~/.claude/settings.json``
+
+Claude Code is the only harness using this ``permissions.allow`` + Bash
+matcher format (Codex/Hermes use no per-command allow list; OpenCode
+uses its own ``permission.bash`` patterns), so this adapter owns the
+JSON read/write/grant/revoke logic directly rather than sharing a base.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from cli._harness.base import (
+    AUTOPOST_COMMAND,
+    VALID_SCOPES,
+    GrantResult,
+    HarnessAdapter,
+    HarnessConfigError,
+)
+from cli._local_state import _atomic_write_text
+
+
+def _autopost_matcher() -> str:
+    """Render :data:`AUTOPOST_COMMAND` as a Bash matcher.
+
+    ``("logion", "courses", "report-usage")`` →
+    ``Bash(logion courses report-usage:*)``.
+    """
+    return f"Bash({' '.join(AUTOPOST_COMMAND)}:*)"
+
+
+class ClaudeCodeAdapter(HarnessAdapter):
+    """Grants the autopost command in Claude Code's ``settings.json``."""
+
+    name = "claude-code"
+    display_name = "Claude Code"
+
+    def __init__(
+        self,
+        *,
+        project_dir: Path | None = None,
+        home_dir: Path | None = None,
+    ) -> None:
+        self._project_dir = project_dir
+        self._home_dir = home_dir
+
+    # -- path resolution ---------------------------------------------------
+
+    def _project(self) -> Path:
+        return (
+            self._project_dir if self._project_dir is not None else Path.cwd()
+        )
+
+    def _home(self) -> Path:
+        return self._home_dir if self._home_dir is not None else Path.home()
+
+    def config_path(self, scope: str) -> Path:
+        if scope not in VALID_SCOPES:
+            raise ValueError(f"unknown scope: {scope!r}")
+        base = self._home() if scope == "global" else self._project()
+        return base / ".claude" / "settings.json"
+
+    def skill_dir(self) -> Path:
+        return self._home() / ".claude" / "skills"
+
+    # -- detection ---------------------------------------------------------
+
+    def is_present(self) -> bool:
+        """True if a ``.claude`` dir (home/project) or ``claude`` on PATH."""
+        if (self._home() / ".claude").is_dir():
+            return True
+        if (self._project() / ".claude").is_dir():
+            return True
+        return shutil.which("claude") is not None
+
+    # -- config read/write -------------------------------------------------
+
+    def _read_settings(self, path: Path) -> dict[str, Any]:
+        if not path.is_file():
+            return {}
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            raise HarnessConfigError(
+                f"cannot parse {path} — refusing to overwrite: {exc}"
+            ) from exc
+        if not isinstance(raw, dict):
+            raise HarnessConfigError(
+                f"{path} is not a JSON object — refusing to overwrite"
+            )
+        return raw
+
+    def _allow_list(self, settings: dict[str, Any], path: Path) -> list[Any]:
+        perms = settings.setdefault("permissions", {})
+        if not isinstance(perms, dict):
+            raise HarnessConfigError(
+                f"{path}: 'permissions' is not an object — refusing to edit"
+            )
+        allow = perms.setdefault("allow", [])
+        if not isinstance(allow, list):
+            raise HarnessConfigError(
+                f"{path}: 'permissions.allow' is not a list — refusing to edit"
+            )
+        return allow
+
+    def _write_settings(self, path: Path, settings: dict[str, Any]) -> None:
+        _atomic_write_text(
+            path,
+            json.dumps(settings, indent=2, ensure_ascii=False) + "\n",
+        )
+
+    # -- grant / revoke / query -------------------------------------------
+
+    def is_granted(self, scope: str) -> bool:
+        path = self.config_path(scope)
+        settings = self._read_settings(path)
+        perms = settings.get("permissions")
+        if not isinstance(perms, dict):
+            return False
+        allow = perms.get("allow")
+        if not isinstance(allow, list):
+            return False
+        return _autopost_matcher() in allow
+
+    def grant(self, scope: str) -> GrantResult:
+        path = self.config_path(scope)
+        settings = self._read_settings(path)
+        allow = self._allow_list(settings, path)
+        matcher = _autopost_matcher()
+        if matcher in allow:
+            return GrantResult(
+                self.name, scope, path, changed=False, already=True
+            )
+        allow.append(matcher)
+        self._write_settings(path, settings)
+        return GrantResult(self.name, scope, path, changed=True, already=False)
+
+    def revoke(self, scope: str) -> GrantResult:
+        path = self.config_path(scope)
+        if not path.is_file():
+            return GrantResult(
+                self.name, scope, path, changed=False, already=True
+            )
+        settings = self._read_settings(path)
+        allow = self._allow_list(settings, path)
+        matcher = _autopost_matcher()
+        if matcher not in allow:
+            return GrantResult(
+                self.name, scope, path, changed=False, already=True
+            )
+        settings["permissions"]["allow"] = [m for m in allow if m != matcher]
+        self._write_settings(path, settings)
+        return GrantResult(self.name, scope, path, changed=True, already=False)

cli/_harness/codex.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+"""Codex harness adapter.
+
+Codex stores its configuration in ``~/.codex/config.toml`` (TOML, not
+JSON) and loads skills from ``~/.codex/skills/``.  Permission gating in
+Codex is controlled by ``approval_policy`` and ``sandbox_mode`` /
+``default_permissions`` — there is no per-command allow list like
+Claude Code's ``permissions.allow``.  Codex uses a sandbox model that
+controls *what* can run (filesystem + network), not *which* specific
+commands are pre-approved.
+
+Therefore the autopost grant is a **no-op** for Codex: ``grant`` and
+``revoke`` report ``already=True`` without writing anything, and
+``is_granted`` always returns ``False``.  The companion skill directory
+is correct so the symlink step works.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cli._harness.base import GrantResult, HarnessAdapter
+
+
+class CodexAdapter(HarnessAdapter):
+    """Codex agent harness.
+
+    Companion install is supported (symlink into ``~/.codex/skills``);
+    autopost grant is a no-op because Codex has no per-command
+    permission list.
+    """
+
+    name = "codex"
+    display_name = "Codex"
+
+    def __init__(
+        self,
+        *,
+        project_dir: Path | None = None,  # noqa: ARG002
+        home_dir: Path | None = None,
+    ) -> None:
+        self._home_dir = home_dir
+
+    def _home(self) -> Path:
+        return self._home_dir if self._home_dir is not None else Path.home()
+
+    def skill_dir(self) -> Path:
+        return self._home() / ".codex" / "skills"
+
+    def is_present(self) -> bool:
+        import shutil
+
+        return (self._home() / ".codex").is_dir() or (
+            shutil.which("codex") is not None
+        )
+
+    def config_path(self, scope: str) -> Path:  # noqa: ARG002
+        return self._home() / ".codex" / "config.toml"
+
+    def is_granted(self, scope: str) -> bool:  # noqa: ARG002
+        return False
+
+    def grant(self, scope: str) -> GrantResult:
+        return GrantResult(
+            self.name,
+            scope,
+            self.config_path(scope),
+            changed=False,
+            already=True,
+        )
+
+    def revoke(self, scope: str) -> GrantResult:
+        return GrantResult(
+            self.name,
+            scope,
+            self.config_path(scope),
+            changed=False,
+            already=True,
+        )

cli/_harness/custom.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: MIT
+"""Custom-path harness for explicit ``--agent-dir`` targets.
+
+A ``CustomPathHarness`` is constructed on demand with an explicit
+``skill_dir`` path (from ``--agent-dir`` or a prompt).  It is never
+auto-detected, and its grant/revoke are no-ops because a bare directory
+has no known permission format.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cli._harness.base import GrantResult, HarnessAdapter
+
+
+class CustomPathHarness(HarnessAdapter):
+    """Harness backed by an explicit skill directory."""
+
+    name = "custom"
+    display_name = "Custom path"
+
+    def __init__(self, skill_dir_path: Path) -> None:
+        self._skill_dir = Path(skill_dir_path)
+
+    def skill_dir(self) -> Path:
+        return self._skill_dir
+
+    def is_present(self) -> bool:
+        return False
+
+    def config_path(self, scope: str) -> Path:  # noqa: ARG002
+        # No settings file for a custom directory.
+        return self._skill_dir / "settings.json"
+
+    def is_granted(self, scope: str) -> bool:  # noqa: ARG002
+        return False
+
+    def grant(self, scope: str) -> GrantResult:
+        return GrantResult(
+            self.name,
+            scope,
+            self.config_path(scope),
+            changed=False,
+            already=True,
+        )
+
+    def revoke(self, scope: str) -> GrantResult:
+        return GrantResult(
+            self.name,
+            scope,
+            self.config_path(scope),
+            changed=False,
+            already=True,
+        )