powerbase-cli 0.1.0__py3-none-any.whl

powerbase_cli/session.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import json
+import ssl
+import time
+from contextlib import contextmanager
+from dataclasses import replace
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterator
+from urllib import request
+from urllib.error import HTTPError, URLError
+
+from .config import BUNDLED_CA_CERT_SENTINEL, AuthState, ConfigStore, env_auth_state, load_bundled_ca_cert
+
+try:
+    import fcntl
+except ModuleNotFoundError:  # pragma: no cover
+    fcntl = None  # type: ignore[assignment]
+
+
+class SessionError(RuntimeError):
+    """Raised when auth/session handling fails."""
+
+
+class SessionManager:
+    def __init__(
+        self,
+        store: ConfigStore,
+        base_url: str | None,
+        anon_key: str | None,
+        *,
+        tls_insecure: bool = False,
+        ca_cert_file: str | None = None,
+    ) -> None:
+        self.store = store
+        self.base_url = base_url
+        self.anon_key = anon_key
+        self.tls_insecure = tls_insecure
+        self.ca_cert_file = ca_cert_file
+
+    def _urlopen(self, req: request.Request):
+        if self.tls_insecure:
+            context = ssl.create_default_context()
+            context.check_hostname = False
+            context.verify_mode = ssl.CERT_NONE
+            return request.urlopen(req, context=context)
+        if self.ca_cert_file:
+            if self.ca_cert_file == BUNDLED_CA_CERT_SENTINEL:
+                bundled_ca_cert = load_bundled_ca_cert()
+                if not bundled_ca_cert:
+                    raise SessionError("Bundled test CA certificate is unavailable.")
+                context = ssl.create_default_context(cadata=bundled_ca_cert)
+            else:
+                context = ssl.create_default_context(cafile=self.ca_cert_file)
+            return request.urlopen(req, context=context)
+        return request.urlopen(req)
+
+    def get_auth_state(self) -> AuthState | None:
+        return env_auth_state() or self.store.load_auth()
+
+    def is_file_backed(self, auth: AuthState | None) -> bool:
+        return bool(auth and auth.source != "env")
+
+    def seconds_until_expiry(self, auth: AuthState | None) -> int | None:
+        if not auth or auth.session.expires_at is None:
+            return None
+        return auth.session.expires_at - int(time.time())
+
+    def ensure_valid(self, skew_seconds: int = 60) -> AuthState | None:
+        auth = self.get_auth_state()
+        if not auth:
+            return None
+        remaining = self.seconds_until_expiry(auth)
+        if remaining is None or remaining > skew_seconds:
+            return auth
+        if not auth.session.refresh_token:
+            return auth
+        return self.refresh(auth)
+
+    def refresh(self, auth: AuthState | None = None) -> AuthState:
+        auth = auth or self.get_auth_state()
+        if not auth:
+            raise SessionError("No authentication session available.")
+        if not auth.session.refresh_token:
+            raise SessionError("Current session has no refresh token. Please log in again.")
+        if not self.base_url or not self.anon_key:
+            raise SessionError("base_url and anon_key are required to refresh the session.")
+
+        payload = json.dumps({"refresh_token": auth.session.refresh_token}).encode("utf-8")
+        req = request.Request(
+            f"{self.base_url.rstrip('/')}/auth/v1/token?grant_type=refresh_token",
+            data=payload,
+            headers={
+                "apikey": self.anon_key,
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        try:
+            with self._urlopen(req) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except HTTPError as exc:  # pragma: no cover - exercised via tests with patched urlopen
+            body = exc.read().decode("utf-8", errors="replace")
+            raise SessionError(f"Failed to refresh session: {body}") from exc
+        except URLError as exc:  # pragma: no cover - depends on runtime/network setup
+            raise SessionError(f"Failed to refresh session: {exc.reason}") from exc
+        except ssl.SSLError as exc:  # pragma: no cover - depends on runtime/network setup
+            raise SessionError(f"Failed to refresh session: {exc}") from exc
+
+        new_auth = AuthState(
+            source=auth.source,
+            base_url=self.base_url,
+            anon_key=self.anon_key,
+            session=replace(
+                auth.session,
+                access_token=data["access_token"],
+                refresh_token=data.get("refresh_token", auth.session.refresh_token),
+                token_type=data.get("token_type", auth.session.token_type),
+                expires_at=data.get("expires_at"),
+            ),
+            user=data.get("user") or auth.user,
+            updated_at=datetime.now(timezone.utc).isoformat(),
+        )
+        if self.is_file_backed(auth):
+            with self.file_lock():
+                self.store.save_auth(new_auth)
+        return new_auth
+
+    @contextmanager
+    def file_lock(self) -> Iterator[None]:
+        self.store.ensure_base_dir()
+        lock_path = Path(self.store.base_dir) / ".auth.lock"
+        with lock_path.open("w", encoding="utf-8") as lock_file:
+            if fcntl is not None:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                if fcntl is not None:
+                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)

powerbase_cli/transport.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import json
+import ssl
+from dataclasses import dataclass
+from typing import Any
+from urllib import request
+from urllib.error import HTTPError, URLError
+
+from .config import BUNDLED_CA_CERT_SENTINEL, AppConfig, load_bundled_ca_cert
+from .session import SessionError, SessionManager
+
+
+class ApiError(RuntimeError):
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+@dataclass
+class RequestContext:
+    instance_id: str | None = None
+
+
+class PowerbaseTransport:
+    def __init__(self, config: AppConfig, session_manager: SessionManager) -> None:
+        self.config = config
+        self.session_manager = session_manager
+
+    def _urlopen(self, req: request.Request):
+        if self.config.tls_insecure:
+            context = ssl.create_default_context()
+            context.check_hostname = False
+            context.verify_mode = ssl.CERT_NONE
+            return request.urlopen(req, context=context)
+        if self.config.ca_cert_file:
+            if self.config.ca_cert_file == BUNDLED_CA_CERT_SENTINEL:
+                bundled_ca_cert = load_bundled_ca_cert()
+                if not bundled_ca_cert:
+                    raise ApiError("Bundled test CA certificate is unavailable.")
+                context = ssl.create_default_context(cadata=bundled_ca_cert)
+            else:
+                context = ssl.create_default_context(cafile=self.config.ca_cert_file)
+            return request.urlopen(req, context=context)
+        return request.urlopen(req)
+
+    def _build_headers(
+        self,
+        *,
+        auth_token: str | None,
+        headers: dict[str, str] | None,
+        instance_id: str | None,
+    ) -> dict[str, str]:
+        request_headers = {
+            "apikey": self.config.anon_key,
+            "Content-Type": "application/json",
+        }
+        if auth_token:
+            request_headers["Authorization"] = f"Bearer {auth_token}"
+        if instance_id:
+            request_headers["X-Instance-ID"] = instance_id
+        if headers:
+            request_headers.update(headers)
+        return request_headers
+
+    def _send(self, req: request.Request, *, stream: bool) -> Any:
+        resp = self._urlopen(req)
+        if stream:
+            return resp
+        raw = resp.read().decode("utf-8")
+        return json.loads(raw) if raw else {}
+
+    def _parse_http_error(self, exc: HTTPError) -> ApiError:
+        body_text = exc.read().decode("utf-8", errors="replace")
+        try:
+            data = json.loads(body_text)
+        except json.JSONDecodeError:
+            data = {"error": body_text}
+        return ApiError(data.get("error") or body_text or exc.reason, exc.code)
+
+    def invoke(
+        self,
+        function_path: str,
+        *,
+        method: str = "GET",
+        body: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        instance_id: str | None = None,
+        requires_auth: bool = True,
+        stream: bool = False,
+    ) -> Any:
+        if not self.config.base_url:
+            raise ApiError("Powerbase base URL is not configured.")
+        if not self.config.anon_key:
+            raise ApiError("Powerbase anon key is not configured.")
+
+        auth = self.session_manager.ensure_valid() if requires_auth else None
+        url = f"{self.config.base_url.rstrip('/')}/functions/v1/{function_path}"
+        payload = None if body is None else json.dumps(body).encode("utf-8")
+        request_headers = self._build_headers(
+            auth_token=auth.session.access_token if auth else None,
+            headers=headers,
+            instance_id=instance_id,
+        )
+        req = request.Request(url, data=payload, headers=request_headers, method=method.upper())
+
+        try:
+            return self._send(req, stream=stream)
+        except HTTPError as exc:
+            if exc.code == 401 and auth and auth.session.refresh_token:
+                try:
+                    refreshed_auth = self.session_manager.refresh(auth)
+                except SessionError as refresh_error:
+                    raise ApiError(str(refresh_error), 401) from refresh_error
+                retry_headers = self._build_headers(
+                    auth_token=refreshed_auth.session.access_token,
+                    headers=headers,
+                    instance_id=instance_id,
+                )
+                retry_req = request.Request(url, data=payload, headers=retry_headers, method=method.upper())
+                try:
+                    return self._send(retry_req, stream=stream)
+                except HTTPError as retry_exc:
+                    raise self._parse_http_error(retry_exc) from retry_exc
+            raise self._parse_http_error(exc) from exc
+        except URLError as exc:
+            raise ApiError(f"Request failed: {exc.reason}") from exc
+        except ssl.SSLError as exc:
+            raise ApiError(f"Request failed: {exc}") from exc
+

powerbase_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: powerbase-cli
+Version: 0.1.0
+Summary: CLI for operating Powerbase console workflows
+Author: Powerbase
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# powerbase-cli
+
+Python CLI for automating Powerbase console operations, with a command shape designed for Openclaw and other LLM agents.
+
+## What It Covers
+
+`powerbase-cli` mirrors the main console workflows with a user-mode auth model:
+
+- browser login bridge for CLI use
+- local session persistence and refresh
+- config and context management
+- organizations, databases, instances, branches
+- SQL execution
+- publish diff and publish run
+- sandbox file operations
+- sandbox agent provider config, chat, and login workflows
+
+The CLI is optimized for agent use:
+
+- stable command groups
+- `--help` explains parameter source and format
+- `--json` is available for machine-readable output
+- context can be saved so later commands need fewer flags
+
+Database model:
+
+- default path: `powerbase instance create` uses the managed Powerbase database flow
+- advanced path: `powerbase database create --dsn ...` registers an existing external database connection for later use with `--database-id`
+- `powerbase database create` does not provision a new physical database
+
+## Install And Run
+
+Install from PyPI:
+
+```bash
+python -m pip install powerbase-cli
+powerbase --help
+```
+
+From the repository root during development:
+
+```bash
+pip install -e .
+```
+
+Or run directly during development:
+
+```bash
+PYTHONPATH=src python3 -m powerbase_cli --help
+```
+
+## Configuration Model
+
+Values are resolved in this order:
+
+1. command flags
+2. environment variables
+3. `~/.config/powerbase/`
+4. built-in defaults
+
+Default local files:
+
+```text
+~/.config/powerbase/
+  config.toml
+  auth.json
+  context.json
+```
+
+Most users do not need environment variables.
+
+Optional advanced overrides:
+- `POWERBASE_ACCESS_TOKEN` and `POWERBASE_REFRESH_TOKEN` for non-browser or pre-issued login flows
+- `POWERBASE_INSTANCE_ID`, `POWERBASE_ORG_ID`, and `POWERBASE_BRANCH` to prefill local context
+- `POWERBASE_CONFIG_DIR` to isolate local state, for example in tests or E2E runs
+- `POWERBASE_OUTPUT` to default to `json`
+
+## Authentication
+
+### Browser Login
+
+The preferred flow is:
+
+```bash
+powerbase auth login
+```
+
+The CLI now includes a built-in `base_url` and `anon_key` default for this deployment. The test package also bundles this environment's self-signed CA certificate, so most users can start with browser login directly and only use flags or environment variables when overriding that default.
+
+The bundled CA is a test-only convenience for the current self-signed deployment. After the console moves to a publicly trusted TLS certificate, remove the bundled CA fallback and package resource, then keep only the built-in `base_url` and `anon_key` defaults.
+
+This will:
+
+1. request a CLI login session from Powerbase
+2. print a browser URL
+3. poll until browser approval or until `--timeout` elapses (default **300** seconds, five minutes)
+4. save the resulting session to `~/.config/powerbase/auth.json`
+
+Use `--timeout 0` to wait without a time limit. Use a larger value if users need more than five minutes to complete login.
+If an agent or wrapper script is coordinating the workflow, it is still helpful
+to tell the user: after browser approval, return to the current session so the
+remaining steps can continue.
+
+### Manual Token Import
+
+Use this when browser login is not available in the current agent environment:
+
+```bash
+powerbase auth token-set \
+  --access-token ACCESS_TOKEN \
+  --refresh-token REFRESH_TOKEN \
+  --expires-at 1760000000
+```
+
+Use `--base-url` or `--anon-key` here only when you intentionally want to override the built-in deployment defaults.
+
+### Check Auth State
+
+```bash
+powerbase auth status --json
+```
+
+### Refresh A Saved Session
+
+```bash
+powerbase auth refresh --json
+```
+
+## Context Workflow
+
+For repeated agent workflows, save the current org, instance, and branch:
+
+```bash
+powerbase context use-org ORG_ID
+powerbase context use-instance INSTANCE_ID
+powerbase context use-branch main
+powerbase context show --json
+```
+
+After that, many commands can omit `--instance-id`.
+
+## Common Workflows
+
+### Discover Resources
+
+```bash
+powerbase org list --json
+powerbase database list --json
+powerbase instance list --json
+powerbase branch list --instance-id INSTANCE_ID --json
+```
+
+### Create An Instance With The Managed Database Flow
+
+This is the default and recommended path:
+
+```bash
+powerbase org list --json
+powerbase instance create --name todo-app --org-id ORG_ID --json
+```
+
+`instance create` returns when provisioning starts, not necessarily when every
+dependent resource is immediately readable. If `instance get`, `branch list`, or
+sandbox commands briefly say the instance is missing or partial, retry after a
+short wait.
+
+### Register And Reuse An External Database Connection
+
+Use this only when you intentionally want the advanced bring-your-own-database flow:
+
+```bash
+powerbase database create --name todo-db --dsn "mysql://user:pass@host:3306/db" --db-type mysql --json
+powerbase instance create --name todo-app --database-id DATABASE_ID --org-id ORG_ID --json
+```
+
+Notes for the advanced path:
+
+- `powerbase database create` registers a DSN in Powerbase; it does not create a physical database server
+- DSN credentials are sensitive and are stored by the platform
+- branch and preview workflows may require SeekDB-compatible database behavior, not just generic MySQL wire compatibility
+- deleting a Powerbase database record does not delete the external database itself
+
+### Switch To An Instance And Branch
+
+```bash
+powerbase context use-instance INSTANCE_ID
+powerbase branch switch feature/demo --instance-id INSTANCE_ID --json
+powerbase context use-branch feature/demo
+```
+
+When you create a branch with a name like `feature/demo`, later delete or SQL
+commands should prefer the normalized slug returned by the API, such as
+`feature-demo`, instead of assuming the original input string is still valid.
+
+### Run SQL
+
+Inline SQL:
+
+```bash
+powerbase sql run --instance-id INSTANCE_ID --branch main --sql "SELECT 1" --json
+```
+
+From a file:
+
+```bash
+powerbase sql run --instance-id INSTANCE_ID --sql-file ./query.sql --json
+```
+
+### Publish
+
+```bash
+powerbase publish diff --instance-id INSTANCE_ID --json
+powerbase publish run --instance-id INSTANCE_ID --json
+```
+
+### Sandbox Files
+
+```bash
+powerbase sandbox files tree --instance-id INSTANCE_ID --root / --json
+powerbase sandbox files read --instance-id INSTANCE_ID /src/app.tsx --json
+powerbase sandbox files upload --instance-id INSTANCE_ID ./local.txt --target-path /tmp --json
+```
+
+### Sandbox Agent Providers
+
+```bash
+powerbase agent providers --instance-id INSTANCE_ID --json
+powerbase agent status --instance-id INSTANCE_ID --provider cursor --json
+powerbase agent login-url --instance-id INSTANCE_ID --provider cursor --json
+```
+
+### Sandbox Agent Chat And Config
+
+Send one prompt to the sandbox agent and stream events as JSONL:
+
+```bash
+powerbase branch switch feature/demo --instance-id INSTANCE_ID --json
+
+powerbase agent chat \
+  --instance-id INSTANCE_ID \
+  --provider cursor \
+  --message "Build a todo app with create, complete, and delete actions." \
+  --stream-jsonl
+```
+
+`agent chat` follows the sandbox's current branch for the automatic preview build. Use
+`powerbase branch switch ...` first when you want the generated preview to land on a
+feature branch. `powerbase context use-branch ...` only changes the local default value;
+it does not switch the remote sandbox by itself.
+
+Read and update opencode provider config:
+
+```bash
+powerbase agent opencode-config get --instance-id INSTANCE_ID --json
+powerbase agent opencode-config set --instance-id INSTANCE_ID --provider anthropic --api-key API_KEY --json
+powerbase agent opencode-config delete --instance-id INSTANCE_ID --provider anthropic --json
+```
+
+Replace the sandbox `opencode.json` file:
+
+```bash
+powerbase agent opencode-json set --instance-id INSTANCE_ID --file ./opencode.json --json
+```
+
+## Openclaw Usage Notes
+
+When Openclaw or another LLM agent uses `powerbase`:
+
+- prefer `--json` on all commands
+- run discovery commands before write operations
+- set context for long multi-step tasks
+- use `auth status` before workflows that assume login
+- use `auth token-set` if browser login is not practical in the current environment
+- remember that `--json` overrides a saved `config output text` setting for that command
+
+Recommended agent sequence:
+
+1. `powerbase auth status --json`
+2. If unauthenticated, run `powerbase auth login` or `powerbase auth token-set`
+3. `powerbase context show --json`
+4. If no instance is selected, run `powerbase instance list --json`
+5. If no suitable instance exists, prefer `powerbase instance create --name ... --org-id ... --json`
+6. Use `powerbase database ...` only for the advanced bring-your-own-database path
+7. Set context with `powerbase context use-instance ...`
+8. If you want the sandbox agent preview on a non-main branch, run `powerbase branch switch ...`
+9. Continue with `branch`, `sql`, `publish`, `sandbox files`, or `agent` commands
+
+## Testing
+
+Run the full CLI test suite:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+Compile the modules:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m py_compile src/powerbase_cli/*.py
+```
+
+## Project Skill
+
+A project skill for Cursor/Openclaw-style agent usage lives in:
+
+`./.cursor/skills/powerbase-cli-openclaw/SKILL.md`
+
+Design and auth review notes live in:
+
+`./docs/console-cli-plan.md`

powerbase_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+powerbase_cli/__init__.py,sha256=EynUg4YKF7Qh1Hr8P1CbV8QyzMTU2jfqVE-Tfm8_ETw,79
+powerbase_cli/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+powerbase_cli/api.py,sha256=F7TZzX7A2rl2j9Ecf1GG9kPowgdjADcKnefkuMz4WUw,12547
+powerbase_cli/cli.py,sha256=Gc_tWlLI5CC3Nl3DhgomiHreqX7Im2jZ9T02-ZDZ08k,304
+powerbase_cli/config.py,sha256=lqMUPQHaHlsr4hsYLVncMAOEM-z8WIhfdaJ9U491220,8588
+powerbase_cli/session.py,sha256=1C5WbGN8ZAtx5miluJOn7Ll3nKw-EX-vKRCipd_yIx0,5492
+powerbase_cli/transport.py,sha256=ObTjXn1DLZcysecIODqPiMBUg9yR_nxMIrR1I0PwQOo,4969
+powerbase_cli/certs/powerbase-test-ca.pem,sha256=Pxtx-qkzTFign1vq7fPF_IrCTcue1Oqy2OQuVqeGk8o,1281
+powerbase_cli/commands/__init__.py,sha256=OMk2nZXMUizPR1Ss7kCSRSEIiRnQYlOErYERGTe9Bqw,75
+powerbase_cli/commands/agent.py,sha256=u6SvqwHA_rn_8NUAZZWxVxJSBHMjKtgqm7ySHpq-u4Q,8813
+powerbase_cli/commands/auth.py,sha256=DTPnGEqE_NSmZO-3eVwP7757IvycDJgxu4Z1N2wvYZQ,6611
+powerbase_cli/commands/branch.py,sha256=9PA2Dq510MUiPT2Zysa6OkfUH3D5VEfbdddUMzJn38E,3892
+powerbase_cli/commands/config_cmd.py,sha256=LHGm3U9VwMquqyLqEjqqXUj57zte2v2qUTieFCbITCE,2613
+powerbase_cli/commands/context.py,sha256=BbrdCcE_LcRP_skFJCW-NgflIoG3sBVHRUjpERS_S4s,3453
+powerbase_cli/commands/database.py,sha256=JZPM7Gw3DECuyK93_oDwUIH7S8C6weS5PY_KnCqiUMQ,5011
+powerbase_cli/commands/instance.py,sha256=o6E3UUSClfKqH2g-ijar9gbqlQyYB1U481yW4caXAuw,3424
+powerbase_cli/commands/org.py,sha256=_VA9uyCCiK3UwkfXRhLJIUubj-hAyxGTIp1HZsjqPUQ,688
+powerbase_cli/commands/parser.py,sha256=CGIEn2fwf-nO8P_gHm6mBSystl98NP2Zng0Se_-_JHM,3889
+powerbase_cli/commands/publish.py,sha256=QTo2wmBTsTsXKu4vIur-IoJphbzRxi0ouFIcJYyVHbw,1985
+powerbase_cli/commands/sandbox.py,sha256=fmGl4QpBr5bxVfjkmRoG0KtTWoWfEunek7EGb8ErcCI,4756
+powerbase_cli/commands/shared.py,sha256=O8eVwnYIoWNpHD4doW_1a9FhGAL1PLuNkR-x7h9Z_w0,4833
+powerbase_cli/commands/sql.py,sha256=T97TccsCylRRQ92bZEif_yHLDo5-qp6Xy161gkn-YYY,1417
+powerbase_cli-0.1.0.dist-info/METADATA,sha256=tHC8wvMqsxP5TfpBQ4xtoyR0F_iynR2sQiRO6_7doNg,9607
+powerbase_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+powerbase_cli-0.1.0.dist-info/entry_points.txt,sha256=DPiHWLoDquxxsBfhtCbMTkjINlDZp06IO_nG5JMgUaY,53
+powerbase_cli-0.1.0.dist-info/top_level.txt,sha256=mKtJfQ2PmKUb-g8K_D9JxAMEUwJA7poXura72Hh76nA,14
+powerbase_cli-0.1.0.dist-info/RECORD,,

powerbase_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

powerbase_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+powerbase = powerbase_cli.cli:main

powerbase_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+powerbase_cli