honcho-cli 0.1.0__py3-none-any.whl

honcho_cli/commands/workspace.py

@@ -0,0 +1,322 @@
+"""Workspace commands: list, inspect, create, delete, search, queue-status."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import typer
+
+from honcho import (
+    APIError,
+    AuthenticationError,
+    Honcho,
+    NotFoundError,
+    PermissionDeniedError,
+    ServerError,
+)
+
+from honcho_cli.output import print_error, print_result, status, use_json
+from honcho_cli.validation import validate_resource_id
+
+from honcho_cli._help import HonchoTyperGroup
+from honcho_cli.common import add_common_options, get_client, get_resolved_config, handle_cmd_flags
+
+app = typer.Typer(cls=HonchoTyperGroup, help="List, create, inspect, delete, and search workspaces.")
+add_common_options(app)
+
+
+def _get_workspace_id(workspace_id: str | None) -> str:
+
+    config = get_resolved_config()
+    wid = workspace_id or config.workspace_id
+    if not wid:
+        print_error("NO_WORKSPACE", "No workspace ID provided. Pass --workspace/-w or set HONCHO_WORKSPACE_ID.")
+        raise typer.Exit(1)
+    return validate_resource_id(wid, "workspace")
+
+
+def _raw_list(page) -> list:
+    """Collect all raw API response items across all pages of a SyncPage."""
+    items = list(page._raw_items)
+    while page.has_next_page():
+        page = page.get_next_page()
+        if page is None:
+            break
+        items.extend(page._raw_items)
+    return items
+
+
+@app.command("list")
+def list_workspaces(
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """List all accessible workspaces."""
+
+    handle_cmd_flags(json_output=json_output)
+    client, config = get_client(require_workspace=False)
+
+    try:
+        workspaces = list(client.workspaces())
+        items = [{"id": w} for w in workspaces]
+        print_result(items, columns=["id"], title="Workspaces")
+    except Exception as e:
+        _handle_error(e, "workspace", "list")
+
+
+@app.command("create")
+def create_workspace(
+    workspace_id: str = typer.Argument(help="Workspace ID to create or get"),
+    metadata: Optional[str] = typer.Option(None, "--metadata", help="JSON metadata to associate with the workspace"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Create or get a workspace."""
+    handle_cmd_flags(json_output=json_output)
+    wid = validate_resource_id(workspace_id, "workspace")
+    client, config = get_client(require_workspace=False)
+    ws_client = _with_workspace(client, wid)
+
+    parsed_metadata = None
+    if metadata:
+        try:
+            parsed_metadata = json.loads(metadata)
+        except json.JSONDecodeError as e:
+            print_error("INVALID_JSON", f"--metadata must be valid JSON: {e}", {})
+            raise typer.Exit(1)
+
+    try:
+        # Trigger get-or-create via the workspace ensure mechanism
+        ws_client.get_configuration()
+        result: dict[str, object] = {"workspace_id": wid}
+        if parsed_metadata is not None:
+            ws_client.set_metadata(parsed_metadata)
+            result["metadata"] = parsed_metadata
+        print_result(result)
+    except Exception as e:
+        _handle_error(e, "workspace", wid)
+
+
+@app.command()
+def inspect(
+    workspace_id: Optional[str] = typer.Argument(None, help="Workspace ID (uses default if omitted)"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Inspect a workspace: peers, sessions, config."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace)
+
+    wid = _get_workspace_id(workspace_id)
+    client, config = get_client(require_workspace=False)
+
+    # Override workspace if positional arg given
+    if workspace_id:
+        client = _with_workspace(client, workspace_id)
+
+    try:
+        ws_config = client.get_configuration()
+        ws_metadata = client.get_metadata()
+        peer_page = client.peers()
+        session_page = client.sessions()
+
+        raw_peers = peer_page._raw_items
+        raw_sessions = session_page._raw_items
+
+        result = {
+            "workspace_id": wid,
+            "metadata": ws_metadata,
+            "configuration": _config_to_dict(ws_config) if ws_config else None,
+            "peer_count": peer_page.total,
+            "session_count": session_page.total,
+            "peers": [
+                {"id": p.id, "metadata": p.metadata, "created_at": str(p.created_at)}
+                for p in raw_peers[:20]
+            ],
+            "sessions": [
+                {"id": s.id, "is_active": s.is_active, "metadata": s.metadata, "created_at": str(s.created_at)}
+                for s in raw_sessions[:20]
+            ],
+        }
+        print_result(result)
+    except Exception as e:
+        _handle_error(e, "workspace", wid)
+
+
+@app.command()
+def delete(
+    workspace_id: str = typer.Argument(help="Workspace ID to delete"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt (for scripted/agent use)"),
+    cascade: bool = typer.Option(False, "--cascade", help="Delete all sessions before deleting the workspace"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be deleted without deleting"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Delete a workspace. Use --dry-run first to see what will be deleted.
+
+    Requires --yes to skip confirmation, or will prompt interactively.
+    If sessions exist, requires --cascade to delete them first.
+    """
+
+    handle_cmd_flags(json_output=json_output)
+
+    validate_resource_id(workspace_id, "workspace")
+    # workspace_id is a required positional and we rebuild the client with it
+    # immediately, so the default-workspace guard isn't needed here.
+    client, config = get_client(require_workspace=False)
+    ws_client = _with_workspace(client, workspace_id)
+
+    # Verify workspace exists before prompting for confirmation
+    try:
+        ws_client.get_metadata()
+    except Exception as e:
+        _handle_error(e, "workspace", workspace_id)
+        return
+
+    # Always fetch sessions for dry-run or cascade
+    raw_sessions = _raw_list(ws_client.sessions()) if (dry_run or cascade) else []
+
+    if dry_run:
+        print_result({
+            "dry_run": True,
+            "workspace_id": workspace_id,
+            "sessions_to_delete": len(raw_sessions),
+            "session_ids": [s.id for s in raw_sessions],
+            "warning": "This action cannot be undone.",
+        })
+        return
+
+    if not yes:
+        if cascade and raw_sessions:
+            typer.confirm(
+                f"Delete workspace '{workspace_id}' and {len(raw_sessions)} session(s)? This cannot be undone.",
+                abort=True,
+            )
+        else:
+            typer.confirm(f"Delete workspace '{workspace_id}'? This cannot be undone.", abort=True)
+
+    try:
+        deleted_sessions = []
+        if cascade and raw_sessions:
+            for s in raw_sessions:
+                ws_client.session(s.id).delete()
+                deleted_sessions.append(s.id)
+                status(f"Deleted session '{s.id}'")
+
+        ws_client.delete_workspace(workspace_id)
+        status(f"Workspace '{workspace_id}' deletion accepted (processing in background)")
+        result = {"deleted_workspace": workspace_id, "status": "accepted"}
+        if cascade:
+            result["deleted_sessions"] = deleted_sessions
+        print_result(result)
+    except Exception as e:
+        _handle_error(e, "workspace", workspace_id)
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(help="Search query"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    limit: int = typer.Option(10, help="Max results"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Search messages across workspace."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace)
+
+    wid = _get_workspace_id(None)
+    client, config = get_client()
+
+    try:
+        results = client.search(query, limit=limit)
+        items = [
+            {
+                "id": m.id,
+                "content": m.content if use_json() else m.content[:200],
+                "peer_id": m.peer_id,
+                "session_id": m.session_id,
+                "created_at": str(m.created_at),
+            }
+            for m in results
+        ]
+        print_result(items, columns=["id", "peer_id", "session_id", "content"], title=f"Search: {query}")
+    except Exception as e:
+        _handle_error(e, "workspace", wid)
+
+
+@app.command("queue-status")
+def queue_status(
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    observer: Optional[str] = typer.Option(None, help="Filter by observer peer"),
+    sender: Optional[str] = typer.Option(None, help="Filter by sender peer"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Get queue processing status."""
+
+    handle_cmd_flags(json_output=json_output, workspace=workspace, session=session)
+
+    _get_workspace_id(None)
+    client, config = get_client()
+
+    try:
+        result = client.queue_status(observer=observer, sender=sender, session=config.session_id or None)
+        print_result(result.__dict__ if hasattr(result, "__dict__") else result)
+    except Exception as e:
+        _handle_error(e, "queue", "status")
+
+
+def _with_workspace(client, workspace_id: str):
+    """Return a new client pointed at a different workspace."""
+    return Honcho(
+        base_url=str(client.base_url),
+        api_key=client._http.api_key if hasattr(client._http, "api_key") else None,
+        workspace_id=workspace_id,
+    )
+
+
+def _config_to_dict(config) -> dict:
+    """Convert a config object to a dict, handling nested objects."""
+    if hasattr(config, "__dict__"):
+        result = {}
+        for k, v in config.__dict__.items():
+            if k.startswith("_"):
+                continue
+            result[k] = _config_to_dict(v) if hasattr(v, "__dict__") and not isinstance(v, str) else v
+        return result
+    return config
+
+
+def _handle_error(e: Exception, resource: str, resource_id: str) -> None:
+    """Handle SDK exceptions with structured error output.
+
+    Dispatches on the SDK's typed exception hierarchy
+    (``honcho.http.exceptions``) and falls back to its ``status`` field for
+    any APIError subclass we don't enumerate. Substring matching on the
+    message is used only as a last-ditch fallback for non-SDK exceptions.
+    """
+    if isinstance(e, NotFoundError):
+        print_error(
+            f"{resource.upper()}_NOT_FOUND",
+            f"{resource.title()} '{resource_id}' not found",
+            {resource: resource_id},
+        )
+        raise typer.Exit(1)
+    if isinstance(e, AuthenticationError):
+        print_error("AUTH_ERROR", f"Authentication failed: {e}", {})
+        raise typer.Exit(3)
+    if isinstance(e, PermissionDeniedError):
+        print_error("PERMISSION_ERROR", f"Permission denied: {e}", {})
+        raise typer.Exit(3)
+    if isinstance(e, ServerError):
+        print_error("SERVER_ERROR", f"Server error: {e}", {resource: resource_id})
+        raise typer.Exit(2)
+    if isinstance(e, APIError):
+        # Catch-all for typed API errors we haven't special-cased
+        # (BadRequest, Conflict, UnprocessableEntity, RateLimit, ...).
+        print_error(
+            "API_ERROR",
+            f"API error ({e.status}): {e}",
+            {resource: resource_id, "status": e.status},
+        )
+        raise typer.Exit(1)
+    print_error("UNKNOWN_ERROR", str(e), {resource: resource_id})
+    raise typer.Exit(1)

honcho_cli/common.py

@@ -0,0 +1,112 @@
+"""Shared runtime state, client factory, and command-level flag helpers.
+
+Flags --json, -w, -p, -s are documented at **command-level** (the canonical
+form demonstrated in the welcome panel, README, and skill files):
+
+    honcho workspace list -w granola --json
+
+They also parse at group-level and top-level for flexibility. All three
+positions resolve identically and are idempotent — command-level is a
+no-op if the same flag was already set at an outer level.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from honcho import Honcho
+
+from honcho_cli.config import CLIConfig, get_client_kwargs
+from honcho_cli.output import print_error, set_json_mode
+from honcho_cli.validation import validate_resource_id
+
+
+# Global overrides from flags (commands read these)
+_global_overrides: dict[str, str | None] = {
+    "workspace": None,
+    "peer": None,
+    "session": None,
+}
+
+
+def get_resolved_config():
+    """Get config with global flag overrides applied.
+
+    Overrides flow through ``validate_resource_id`` so that a malformed
+    ``-w``/``-p``/``-s`` value fails fast with a structured error rather than
+    reaching the API and surfacing as an opaque ``UNKNOWN_ERROR``.
+    """
+    config = CLIConfig.load()
+
+    if _global_overrides["workspace"]:
+        config.workspace_id = validate_resource_id(_global_overrides["workspace"], "workspace")
+    if _global_overrides["peer"]:
+        config.peer_id = validate_resource_id(_global_overrides["peer"], "peer")
+    if _global_overrides["session"]:
+        config.session_id = validate_resource_id(_global_overrides["session"], "session")
+
+    return config
+
+
+def get_client(*, require_workspace: bool = True):
+    """Create a Honcho client from resolved config.
+
+    By default, refuses to build a client when no workspace is scoped — the
+    SDK's get-or-create semantics would otherwise silently operate on an empty
+    workspace. Commands that legitimately run without a workspace (e.g.
+    ``workspace list``) pass ``require_workspace=False``.
+    """
+    config = get_resolved_config()
+    if require_workspace and not config.workspace_id:
+        print_error(
+            "NO_WORKSPACE",
+            "No workspace scoped. Pass --workspace/-w or set HONCHO_WORKSPACE_ID.",
+        )
+        raise typer.Exit(1)
+    return Honcho(**get_client_kwargs(config)), config
+
+
+def handle_cmd_flags(
+    json_output: bool = False,
+    workspace: str | None = None,
+    peer: str | None = None,
+    session: str | None = None,
+    **_kwargs,
+) -> None:
+    """Apply command-level flags. Idempotent if already set by group callback."""
+    if json_output:
+        set_json_mode(True)
+
+    if workspace:
+        _global_overrides["workspace"] = workspace
+    if peer:
+        _global_overrides["peer"] = peer
+    if session:
+        _global_overrides["session"] = session
+
+
+def add_common_options(app: typer.Typer) -> None:
+    """Add a callback to a sub-app that accepts --json, -w, -p, -s."""
+
+    @app.callback(invoke_without_command=True)
+    def _callback(
+        ctx: typer.Context,
+        json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+        workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+        peer: Optional[str] = typer.Option(None, "--peer", "-p", help="Override peer ID"),
+        session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    ) -> None:
+        if json_output:
+            set_json_mode(True)
+
+        if workspace:
+            _global_overrides["workspace"] = workspace
+        if peer:
+            _global_overrides["peer"] = peer
+        if session:
+            _global_overrides["session"] = session
+
+        if ctx.invoked_subcommand is None:
+            typer.echo(ctx.get_help())

honcho_cli/config.py

@@ -0,0 +1,150 @@
+"""Configuration management for Honcho CLI.
+
+Config stored at ``~/.honcho/config.json`` with env var overrides.
+
+The CLI owns exactly two top-level keys in that file:
+
+    apiKey          -- Honcho admin JWT
+    environmentUrl  -- Honcho API URL (full URL, e.g. https://api.honcho.dev)
+
+All other top-level keys (``hosts``, ``sessions``, ``saveMessages``,
+``sessionStrategy``, …) are written by sibling Honcho tools and are
+preserved untouched on save.
+
+Workspace / peer / session scoping is intentionally *not* persisted here —
+pass ``-w`` / ``-p`` / ``-s`` flags or set ``HONCHO_WORKSPACE_ID`` /
+``HONCHO_PEER_ID`` / ``HONCHO_SESSION_ID`` per command instead.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, fields
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".honcho"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+DEFAULT_BASE_URL = "https://api.honcho.dev"
+
+# Env var mapping for runtime overrides.
+#
+# Resolution order: flag > env var > config file > default.
+ENV_MAP: dict[str, str] = {
+    "api_key": "HONCHO_API_KEY",
+    "base_url": "HONCHO_BASE_URL",
+    "workspace_id": "HONCHO_WORKSPACE_ID",
+    "peer_id": "HONCHO_PEER_ID",
+    "session_id": "HONCHO_SESSION_ID",
+}
+
+
+@dataclass
+class CLIConfig:
+    """CLI configuration with layered resolution: flag > env > file > default.
+
+    ``workspace_id`` / ``peer_id`` / ``session_id`` exist on this dataclass so
+    flag/env overrides flow through ``get_client_kwargs()``, but they are
+    never read from or written to the config file — they're per-command.
+    """
+
+    base_url: str = DEFAULT_BASE_URL
+    api_key: str = ""
+    workspace_id: str = ""
+    peer_id: str = ""
+    session_id: str = ""
+
+    @classmethod
+    def load(cls) -> CLIConfig:
+        """Load config from file, then overlay env vars."""
+        config = cls()
+
+        if CONFIG_FILE.exists():
+            try:
+                with open(CONFIG_FILE, encoding="utf-8") as f:
+                    data = json.load(f)
+            except (json.JSONDecodeError, OSError):
+                data = {}
+
+            if isinstance(data, dict):
+                url = data.get("environmentUrl")
+                if isinstance(url, str) and url:
+                    config.base_url = url
+                key = data.get("apiKey")
+                if isinstance(key, str):
+                    config.api_key = key
+
+        for fld_name, env_var in ENV_MAP.items():
+            val = os.environ.get(env_var)
+            if val:
+                setattr(config, fld_name, val)
+            elif val == "":
+                # SDK reads these env vars directly and crashes on empty
+                # strings with a Pydantic ValidationError. Drop them so the
+                # SDK falls back to kwargs / defaults.
+                os.environ.pop(env_var, None)
+
+        return config
+
+    def save(self) -> None:
+        """Write ``apiKey`` + ``environmentUrl`` to config.json.
+
+        Preserves unrelated top-level keys (``hosts``, ``sessions``,
+        ``saveMessages``, ``sessionStrategy``, …) that other tools write.
+        """
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+        data: dict = {}
+        if CONFIG_FILE.exists():
+            try:
+                with open(CONFIG_FILE, encoding="utf-8") as f:
+                    loaded = json.load(f)
+                if isinstance(loaded, dict):
+                    data = loaded
+            except (json.JSONDecodeError, OSError):
+                data = {}
+
+        data["environmentUrl"] = self.base_url
+        if self.api_key:
+            data["apiKey"] = self.api_key
+        else:
+            data.pop("apiKey", None)
+
+        CONFIG_FILE.write_text(json.dumps(data, indent=2) + "\n")
+        # API key in plaintext — restrict to the owner on multi-user hosts.
+        try:
+            os.chmod(CONFIG_FILE, 0o600)
+        except OSError:
+            pass
+
+    def redacted(self) -> dict[str, str]:
+        """Return config dict with api_key redacted.
+
+        Only includes fields that have a value set — per-command fields
+        (workspace_id, peer_id, session_id) are omitted when empty.
+        """
+        d: dict[str, str] = {}
+        for fld in fields(self):
+            val = getattr(self, fld.name)
+            if not val:
+                continue
+            if fld.name == "api_key":
+                # Show ``***<last4>`` only — enough to compare keys without
+                # leaking the header or body of the JWT.
+                d[fld.name] = "***" + val[-4:] if len(val) > 4 else "***"
+            else:
+                d[fld.name] = val
+        return d
+
+
+def get_client_kwargs(config: CLIConfig) -> dict:
+    """Build kwargs for Honcho client from config."""
+    kwargs: dict = {}
+    if config.base_url:
+        kwargs["base_url"] = config.base_url
+    if config.api_key:
+        kwargs["api_key"] = config.api_key
+    if config.workspace_id:
+        kwargs["workspace_id"] = config.workspace_id
+    return kwargs

honcho_cli/main.py

@@ -0,0 +1,96 @@
+"""Honcho CLI — a terminal for Honcho.
+
+Entry point and top-level command group.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import typer
+from rich.console import Console
+
+from honcho_cli import __version__
+from honcho_cli._help import HonchoTyperGroup, print_welcome
+from honcho_cli.branding import BANNER
+from honcho_cli.output import set_json_mode
+
+
+app = typer.Typer(
+    name="honcho",
+    cls=HonchoTyperGroup,
+    help="A terminal for Honcho — memory that reasons.",
+    invoke_without_command=True,
+    pretty_exceptions_enable=False,
+    add_completion=False,
+)
+
+
+def _json_requested_early() -> bool:
+    """Best-effort JSON detection before Typer parses flags.
+
+    version_callback is eager and fires before set_json_mode() runs, so we
+    can't call use_json() here. Mirror its logic against argv/env/TTY.
+    """
+    return (
+        "--json" in sys.argv
+        or os.environ.get("HONCHO_JSON", "").lower() in ("1", "true")
+        or not sys.stdout.isatty()
+    )
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        if not _json_requested_early():
+            print(BANNER)
+        print(f"  honcho-cli {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+    version: bool = typer.Option(False, "--version", "-V", callback=version_callback, is_eager=True, help="Show version"),
+) -> None:
+    """Honcho CLI — admin & debugging tool for Honcho workspaces."""
+    set_json_mode(json_output)
+
+    if ctx.invoked_subcommand is None:
+        print_welcome(Console())
+        raise typer.Exit()
+
+
+# Register top-level commands
+from honcho_cli.commands.setup import doctor, init
+
+app.command()(init)
+app.command()(doctor)
+
+
+@app.command("help", hidden=True)
+def help_cmd(ctx: typer.Context) -> None:
+    """Show help message."""
+    Console().print(ctx.parent.get_help() if ctx.parent else "")
+    raise typer.Exit()
+
+
+# Register command groups
+from honcho_cli.commands.config_cmd import app as config_app
+from honcho_cli.commands.conclusion import app as conclusion_app
+from honcho_cli.commands.message import app as message_app
+from honcho_cli.commands.peer import app as peer_app
+from honcho_cli.commands.session import app as session_app
+from honcho_cli.commands.workspace import app as workspace_app
+
+app.add_typer(peer_app,       name="peer")
+app.add_typer(session_app,    name="session")
+app.add_typer(message_app,    name="message")
+app.add_typer(conclusion_app, name="conclusion")
+app.add_typer(workspace_app,  name="workspace")
+app.add_typer(config_app,     name="config")
+
+
+if __name__ == "__main__":
+    app()