sprucelab 0.1.0__py3-none-any.whl

sprucelab/__init__.py

@@ -0,0 +1,19 @@
+"""sprucelab — agent-first surface for the Sprucelab platform.
+
+Ships two transports — both designed for agents to drive fast, both
+usable by humans at the terminal when they want to:
+
+- ``spruce`` — typed CLI. Terminal-resident agents (Claude Code,
+  Aider, anything that drives a shell) bash-call ``spruce …`` and
+  read structured JSON / SSE off stdout. Humans get the same
+  commands with ``--help`` and pretty rendering.
+- ``sprucelab-mcp`` — MCP server over stdio. Host-resident agents
+  (Claude Desktop, Cursor, Continue) launch this as a subprocess
+  and call the same operations as typed tool calls.
+
+Both wrap the same public HTTP surface advertised at
+``/api/capabilities/``. The web app at sprucelab.io is the
+human-first surface; these are the agent-first ones.
+"""
+
+__version__ = "0.1.0"

sprucelab/cli/__init__.py

@@ -0,0 +1,3 @@
+"""Spruce CLI - Automation pipeline runner for Sprucelab."""
+
+__version__ = "0.1.0"

sprucelab/cli/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for running as python -m sprucelab.cli."""
+from .app import app
+
+if __name__ == "__main__":
+    app()

sprucelab/cli/_auth.py

@@ -0,0 +1,44 @@
+"""
+Single source of truth for resolving the CLI's API token.
+
+Resolution order (first hit wins):
+  1. Explicit ``--token`` flag passed to a command.
+  2. ``SPRUCELAB_ADMIN_TOKEN`` environment variable (CI/scripts path).
+  3. ``keyring`` (set by ``spruce auth register --token ...``).
+
+This unifies the previously fragmented behavior where command modules
+(``models``, ``verify``, ``types``, …) read only the env var while the
+``auth``/``capabilities`` modules read only the keyring. After this
+helper, every command honors all three paths.
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+
+def resolve_token(override: Optional[str] = None) -> Optional[str]:
+    """Return the API token to use, or None if nothing is configured."""
+    if override:
+        return override
+    env_token = os.environ.get('SPRUCELAB_ADMIN_TOKEN')
+    if env_token:
+        return env_token
+    try:
+        from .config import get_api_key
+        kr_token = get_api_key()
+        if kr_token:
+            return kr_token
+    except Exception:
+        # Keyring backend missing or locked — fall through to None.
+        pass
+    return None
+
+
+def auth_headers(override: Optional[str] = None) -> dict:
+    """Standard JSON request headers including Authorization if we have a token."""
+    headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
+    token = resolve_token(override)
+    if token:
+        headers['Authorization'] = f'Bearer {token}'
+    return headers

sprucelab/cli/_errors.py

@@ -0,0 +1,174 @@
+"""
+Verbatim "Try: ..." next-command hints for CLI errors.
+
+Design rule (`feedback-agent-first-or-die`): error messages should suggest
+the next command verbatim. Agents learn faster from
+``Try: spruce auth register --token <KEY>`` than from a bare
+``401 Unauthorized``.
+
+Each command module passes a short ``command_context`` string (e.g.
+``"models list"``, ``"types classify"``, ``"webhooks deliveries"``) so we can
+tailor the suggestion to the noun the user was working with.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional
+
+import httpx
+import typer
+
+
+# Map (command_context_prefix -> noun used in `spruce <noun> list` hints).
+# The first key whose prefix matches command_context wins. Fall back to the
+# raw context string for the 5xx/network case where the hint isn't about a
+# specific noun.
+_NOUN_FOR_404 = {
+    'models': 'models list',
+    'types': 'types list --model <MODEL_UUID>',
+    'verify': 'models list',
+    'scripts run': 'scripts list',
+    'scripts': 'scripts list',
+    'webhooks deliveries': 'webhooks deliveries',
+    'webhooks redeliver': 'webhooks deliveries',
+    'webhooks test': 'webhooks list',
+    'webhooks': 'webhooks list',
+    'embed pass revoke': 'embed pass list',
+    'embed pass refresh': 'embed pass list',
+    'embed': 'embed pass list',
+    'files show': 'files list',
+    'files download': 'files list',
+    'files reprocess': 'files list',
+    'files versions': 'files list',
+    'files upload': 'files list  # confirm the project id',
+    'files': 'files list',
+    'log': 'log list',
+}
+
+
+def format_http_error_hint(status: int, command_context: str) -> Optional[str]:
+    """
+    Return a verbatim ``Try: ...`` suggestion for ``status`` in ``command_context``.
+
+    Returns ``None`` when no useful hint applies (e.g. unrecognized status).
+    The returned string does NOT include the ``Try: `` prefix or trailing
+    newline — caller decides framing (Rich vs JSON).
+    """
+    if status in (401, 403):
+        return (
+            'spruce auth register --token <KEY>  '
+            '# or: spruce auth status'
+        )
+
+    if status == 404:
+        for prefix, suggestion in _NOUN_FOR_404.items():
+            if command_context.startswith(prefix):
+                return f'spruce {suggestion}  # confirm the ID exists'
+        return 'spruce capabilities  # confirm the endpoint exists on this backend'
+
+    if status == 400 or status == 422:
+        # Validation errors. Echo the field error then nudge to re-read help.
+        return (
+            f'spruce {command_context} --help  '
+            '# field error in payload above; check required flags'
+        )
+
+    if status >= 500:
+        return (
+            f'spruce {command_context} --json | jq .body  '
+            '# inspect the server response in full'
+        )
+
+    if status == 405:
+        return 'spruce capabilities  # this action may not be implemented on this backend yet'
+
+    return None
+
+
+def format_request_error_hint() -> str:
+    """
+    Hint for connection / DNS / timeout errors (httpx.RequestError).
+
+    Always returns a non-empty string. Agents/users can't recover without
+    pointing at the URL config, so we always offer the same two breadcrumbs.
+    """
+    return (
+        'spruce config show  '
+        '# verify api_url; override with $SPRUCE_API_URL or `spruce auth register --url <URL>`'
+    )
+
+
+def print_http_error(
+    console,
+    err: httpx.HTTPStatusError,
+    *,
+    json_out: bool,
+    command_context: str,
+) -> None:
+    """
+    Pretty-print an httpx.HTTPStatusError with a verbatim next-command hint.
+
+    Always raises ``typer.Exit(1)``. Caller supplies a Rich Console for human
+    output and a short ``command_context`` (e.g. ``"models list"``) so the
+    hint can be scoped.
+
+    JSON shape (preserved from the previous unstructured handlers, plus
+    ``hint`` and ``body`` keys):
+
+        {
+            "error": "HTTP <status>",
+            "status": <status>,
+            "body": <parsed JSON body or raw text>,
+            "hint": "<verbatim next command>" | null
+        }
+    """
+    body_text = err.response.text
+    parsed = None
+    try:
+        parsed = err.response.json()
+    except Exception:
+        pass
+
+    hint = format_http_error_hint(err.response.status_code, command_context)
+    body_payload = parsed if parsed is not None else body_text
+
+    if json_out:
+        payload = {
+            'error': f'HTTP {err.response.status_code}',
+            'status': err.response.status_code,
+            'body': body_payload,
+            'hint': hint,
+        }
+        sys.stdout.write(json.dumps(payload) + '\n')
+    else:
+        body_pretty = json.dumps(parsed, indent=2) if parsed is not None else body_text
+        console.print(f'[red]HTTP {err.response.status_code}[/red]\n{body_pretty}')
+        if hint:
+            console.print(f'[yellow]Try:[/yellow] [cyan]{hint}[/cyan]')
+    raise typer.Exit(1)
+
+
+def print_request_error(
+    console,
+    err: httpx.RequestError,
+    *,
+    json_out: bool,
+    command_context: str,
+) -> None:
+    """
+    Pretty-print a connection / DNS / timeout error with a config hint.
+
+    Always raises ``typer.Exit(1)``.
+    """
+    hint = format_request_error_hint()
+    if json_out:
+        sys.stdout.write(json.dumps({
+            'error': 'request_failed',
+            'detail': str(err),
+            'hint': hint,
+        }) + '\n')
+    else:
+        console.print(f'[red]Request failed:[/red] {err}')
+        console.print(f'[yellow]Try:[/yellow] [cyan]{hint}[/cyan]')
+    raise typer.Exit(1)

sprucelab/cli/api_client.py

@@ -0,0 +1,226 @@
+"""HTTP client for Sprucelab API communication."""
+from typing import Optional, Dict, Any, List
+import httpx
+
+from .config import get_api_url, get_api_key, get_agent_id, get_hostname
+
+
+class SprucelabClient:
+    """Client for Sprucelab automation API."""
+
+    def __init__(self, api_url: Optional[str] = None, api_key: Optional[str] = None):
+        self.api_url = api_url or get_api_url()
+        self.api_key = api_key or get_api_key()
+        self.agent_id = get_agent_id()
+        self.hostname = get_hostname()
+
+    def _headers(self) -> Dict[str, str]:
+        """Get request headers with authentication."""
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _url(self, path: str) -> str:
+        """Build full URL for API path."""
+        return f"{self.api_url}/api/automation{path}"
+
+    # Pipeline endpoints
+
+    def list_pipelines(self) -> List[Dict[str, Any]]:
+        """List all available pipelines."""
+        with httpx.Client() as client:
+            response = client.get(
+                self._url("/pipelines/"),
+                headers=self._headers()
+            )
+            response.raise_for_status()
+            return response.json()
+
+    def get_pipeline(self, pipeline_id: str) -> Dict[str, Any]:
+        """Get pipeline details."""
+        with httpx.Client() as client:
+            response = client.get(
+                self._url(f"/pipelines/{pipeline_id}/"),
+                headers=self._headers()
+            )
+            response.raise_for_status()
+            return response.json()
+
+    def trigger_run(
+        self,
+        pipeline_id: str,
+        project_id: Optional[str] = None,
+        parameters: Optional[Dict] = None
+    ) -> Dict[str, Any]:
+        """Trigger a pipeline run."""
+        data = {
+            "triggered_by": f"cli:{self.hostname}"
+        }
+        if project_id:
+            data["project_id"] = project_id
+        if parameters:
+            data["parameters"] = parameters
+
+        with httpx.Client() as client:
+            response = client.post(
+                self._url(f"/pipelines/{pipeline_id}/run/"),
+                headers=self._headers(),
+                json=data
+            )
+            response.raise_for_status()
+            return response.json()
+
+    # Run endpoints
+
+    def list_runs(
+        self,
+        pipeline_id: Optional[str] = None,
+        project_id: Optional[str] = None,
+        status: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """List pipeline runs."""
+        params = {}
+        if pipeline_id:
+            params["pipeline"] = pipeline_id
+        if project_id:
+            params["project"] = project_id
+        if status:
+            params["status"] = status
+
+        with httpx.Client() as client:
+            response = client.get(
+                self._url("/runs/"),
+                headers=self._headers(),
+                params=params
+            )
+            response.raise_for_status()
+            return response.json()
+
+    def get_run(self, run_id: str) -> Dict[str, Any]:
+        """Get run details."""
+        with httpx.Client() as client:
+            response = client.get(
+                self._url(f"/runs/{run_id}/"),
+                headers=self._headers()
+            )
+            response.raise_for_status()
+            return response.json()
+
+    def get_run_logs(self, run_id: str) -> Dict[str, Any]:
+        """Get run logs."""
+        with httpx.Client() as client:
+            response = client.get(
+                self._url(f"/runs/{run_id}/logs/"),
+                headers=self._headers()
+            )
+            response.raise_for_status()
+            return response.json()
+
+    # Agent endpoints
+
+    def register_agent(self, name: str) -> Dict[str, Any]:
+        """Register this machine as an agent."""
+        with httpx.Client() as client:
+            response = client.post(
+                self._url("/agent/register/"),
+                headers=self._headers(),
+                json={
+                    "name": name,
+                    "hostname": self.hostname,
+                    "capabilities": ["ifcopenshell", "python"]
+                }
+            )
+            response.raise_for_status()
+            return response.json()
+
+    def heartbeat(self) -> bool:
+        """Send agent heartbeat."""
+        if not self.agent_id:
+            return False
+
+        with httpx.Client() as client:
+            try:
+                response = client.post(
+                    self._url("/agent/heartbeat/"),
+                    headers=self._headers(),
+                    json={
+                        "agent_id": self.agent_id,
+                        "hostname": self.hostname
+                    }
+                )
+                return response.status_code == 200
+            except Exception:
+                return False
+
+    def poll_jobs(self) -> List[Dict[str, Any]]:
+        """Poll for pending jobs."""
+        if not self.agent_id:
+            return []
+
+        with httpx.Client() as client:
+            response = client.get(
+                self._url("/agent/jobs/"),
+                headers=self._headers(),
+                params={"agent_id": self.agent_id}
+            )
+            response.raise_for_status()
+            return response.json().get("jobs", [])
+
+    def claim_job(self, run_id: str) -> bool:
+        """Claim a job for execution."""
+        with httpx.Client() as client:
+            response = client.post(
+                self._url(f"/agent/jobs/{run_id}/claim/"),
+                headers=self._headers(),
+                json={
+                    "agent_id": self.agent_id,
+                    "agent_hostname": self.hostname
+                }
+            )
+            return response.status_code == 200
+
+    def step_start(self, run_id: str, step_id: str) -> bool:
+        """Mark a step as started."""
+        with httpx.Client() as client:
+            response = client.post(
+                self._url(f"/agent/jobs/{run_id}/step/{step_id}/start/"),
+                headers=self._headers()
+            )
+            return response.status_code == 200
+
+    def step_complete(
+        self,
+        run_id: str,
+        step_id: str,
+        status: str,
+        output_log: str = "",
+        result_data: Optional[Dict] = None,
+        error_message: str = "",
+        output_files: Optional[List[str]] = None
+    ) -> bool:
+        """Mark a step as completed."""
+        with httpx.Client() as client:
+            response = client.post(
+                self._url(f"/agent/jobs/{run_id}/step/{step_id}/complete/"),
+                headers=self._headers(),
+                json={
+                    "status": status,
+                    "output_log": output_log,
+                    "result_data": result_data or {},
+                    "error_message": error_message,
+                    "output_files": output_files or []
+                }
+            )
+            return response.status_code == 200
+
+    def run_complete(self, run_id: str, error_message: str = "") -> Dict[str, Any]:
+        """Mark a run as completed."""
+        with httpx.Client() as client:
+            response = client.post(
+                self._url(f"/agent/jobs/{run_id}/complete/"),
+                headers=self._headers(),
+                json={"error_message": error_message}
+            )
+            response.raise_for_status()
+            return response.json()