blobhub-cli 0.1.0__tar.gz

blobhub_cli-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Worktrees (workspace convention: one worktree per feature, under .worktrees/)
+.worktrees/
+
+# Temporary files (workspace convention: never store them outside the repo)
+.tmp/
+
+# Agent scratch (subagent-driven-development ledger, briefs, review packages)
+.superpowers/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

blobhub_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BlobHub. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blobhub_cli-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: blobhub-cli
+Version: 0.1.0
+Summary: BlobHub command line interface — work with blobs, revisions, and their contents from the terminal
+Project-URL: Homepage, https://blobhub.io/
+Project-URL: Documentation, https://docs.blobhub.io/
+Project-URL: Source, https://github.com/blobhubio/blobhub-cli
+Project-URL: Issues, https://github.com/blobhubio/blobhub-cli/issues
+Author-email: BlobHub <developers@blobhub.io>
+License: MIT License
+        
+        Copyright (c) 2026 BlobHub. All rights reserved.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: automation,blobhub,blobs,cli,command-line,versioning,workflows
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# blobhub-cli
+
+The command line interface for [BlobHub](https://blobhub.io/) — the serverless platform for versioned blob
+storage. `blobhub` authenticates against the platform, addresses your orgs, blobs and revisions, and works with
+what those revisions contain, from a terminal or from CI.
+
+## How the CLI is organized
+
+Everything that is not tied to a particular kind of blob — authentication and profiles, JSON output, error
+reporting — is shared:
+
+```sh
+blobhub login | logout | whoami | profile ls | profile use
+```
+
+Everything else is grouped by **blob domain**, which is the axis the platform itself extends along. Each domain
+adds its own command group and its own manifest types over one shared base:
+
+```sh
+blobhub workflow …      # workflow blobs — the domain implemented today
+```
+
+**`workflow` is the first domain and currently the most developed one.** Its flagship capability — deploying a
+revision's code from a real Python package rather than hand-editing it in the visual editor — is described below.
+Further domains slot in as additional command groups without changing anything above this line.
+
+## Install
+
+```sh
+pipx install blobhub-cli
+```
+
+(or `pip install blobhub-cli` inside a virtualenv). Requires Python 3.12+; installs a `blobhub` binary.
+
+## Authenticate
+
+```sh
+blobhub login
+```
+
+Prompts for the API URL (defaults to `https://api.blobhub.io/v1`) and your API key, verifies it against the
+platform, and stores it as a named profile under `~/.blobhub/credentials.yaml` (`0600`, refused on load if
+looser). Multiple profiles are supported:
+
+```sh
+blobhub profile ls                  # list stored profiles, marking the default
+blobhub profile use staging         # switch the default
+blobhub login --profile staging --api-url https://api.staging.blobhub.io/v1
+blobhub whoami                      # resolved identity, profile, URL, and key scope
+```
+
+For CI, skip the credentials file entirely — set `BLOBHUB_API_KEY` (and optionally `BLOBHUB_API_URL`,
+`BLOBHUB_PROFILE`); the environment always wins over a stored profile, and a key from the environment alone
+works with no credentials file present at all.
+
+A manifest may name its blob bare (`blob: checkout`) instead of org-qualified. The org then comes from the global
+`--org` option (`blobhub --org acme-corp workflow deploy …`) or from `BLOBHUB_ORG`; with neither, the bare name is
+a manifest error naming all three ways to supply one.
+
+## The `workflow` domain
+
+A workflow blob's revision holds definitions whose `logic.code` components normally have their code typed into
+the browser, where it cannot be imported, unit-tested, linted, reviewed or version-controlled. The `workflow`
+command group closes that gap: you keep the code as an ordinary Python package, and the CLI compiles it into the
+flat, import-less namespace the platform's sandbox actually executes.
+
+### A worked example: deploying a workflow
+
+Say your revision has one workflow definition, alias `checkout_flow`, with a `logic.code` component (`id: c1`)
+whose code should come from a real Python package rather than being typed into the editor:
+
+```
+my-project/
+├── manifest.yaml
+├── definitions/
+│   └── checkout_flow.json      # the definition document — pulled from, or pushed to, the platform
+└── pkg/
+    ├── entry.py                 # entry_point
+    └── lib/
+        └── pricing.py           # a local module entry.py imports
+```
+
+`manifest.yaml`:
+
+```yaml
+type: workflow_blob_deployment
+version: "1.0"
+blob: acme-corp/checkout                # <org>/<blob>, or a bare <blob> plus --org/BLOBHUB_ORG
+revision: latest                        # or a pinned revision UUID
+definitions:
+  - alias: checkout_flow
+    source: definitions/checkout_flow.json
+    category: workflow
+    components:
+      - id: c1
+        code:
+          base_path: pkg
+          entry_point: entry.py
+```
+
+First pull the current definition (skip this if you're starting a definition from scratch):
+
+```sh
+blobhub workflow pull -f manifest.yaml
+```
+
+Compile and deploy:
+
+```sh
+blobhub workflow deploy -f manifest.yaml
+```
+
+`deploy` builds every bound component locally (inlining local imports from `pkg/`, stripping sandbox-pre-bound
+and allowlisted imports, rejecting anything else), uploads only the definitions whose serialized document
+actually changed, and runs the platform's `check_definition` against each workflow definition it uploaded.
+Re-running `deploy` with nothing changed uploads nothing and says so. `--dry-run` on every mutating command
+prints the exact intended calls without performing them; `--json` emits a single machine-readable object instead
+of the rendered output.
+
+Other commands in the `workflow` group:
+
+```sh
+blobhub workflow diff -f manifest.yaml     # report local/remote differences without writing or uploading
+blobhub workflow build -f manifest.yaml    # compile locally only, no network
+blobhub workflow check -f manifest.yaml    # re-run check_definition against what's already deployed
+blobhub workflow push -f manifest.yaml     # upload verbatim, without the compiler (rarely what you want)
+```
+
+If a code port was edited in the visual editor since the CLI last built it, `build`/`deploy` refuse to overwrite
+it with `REMOTE_EDIT` (or `UNMANAGED_CODE` for hand-typed code the CLI never built) — pass `--force` to overwrite,
+or reconcile by hand first. See `docs/reference/error-codes.md` for the full catalog of error and advisory codes,
+what each one means, and how to resolve it.
+
+## License
+
+MIT. See `LICENSE`.

blobhub_cli-0.1.0/README.md

@@ -0,0 +1,136 @@
+# blobhub-cli
+
+The command line interface for [BlobHub](https://blobhub.io/) — the serverless platform for versioned blob
+storage. `blobhub` authenticates against the platform, addresses your orgs, blobs and revisions, and works with
+what those revisions contain, from a terminal or from CI.
+
+## How the CLI is organized
+
+Everything that is not tied to a particular kind of blob — authentication and profiles, JSON output, error
+reporting — is shared:
+
+```sh
+blobhub login | logout | whoami | profile ls | profile use
+```
+
+Everything else is grouped by **blob domain**, which is the axis the platform itself extends along. Each domain
+adds its own command group and its own manifest types over one shared base:
+
+```sh
+blobhub workflow …      # workflow blobs — the domain implemented today
+```
+
+**`workflow` is the first domain and currently the most developed one.** Its flagship capability — deploying a
+revision's code from a real Python package rather than hand-editing it in the visual editor — is described below.
+Further domains slot in as additional command groups without changing anything above this line.
+
+## Install
+
+```sh
+pipx install blobhub-cli
+```
+
+(or `pip install blobhub-cli` inside a virtualenv). Requires Python 3.12+; installs a `blobhub` binary.
+
+## Authenticate
+
+```sh
+blobhub login
+```
+
+Prompts for the API URL (defaults to `https://api.blobhub.io/v1`) and your API key, verifies it against the
+platform, and stores it as a named profile under `~/.blobhub/credentials.yaml` (`0600`, refused on load if
+looser). Multiple profiles are supported:
+
+```sh
+blobhub profile ls                  # list stored profiles, marking the default
+blobhub profile use staging         # switch the default
+blobhub login --profile staging --api-url https://api.staging.blobhub.io/v1
+blobhub whoami                      # resolved identity, profile, URL, and key scope
+```
+
+For CI, skip the credentials file entirely — set `BLOBHUB_API_KEY` (and optionally `BLOBHUB_API_URL`,
+`BLOBHUB_PROFILE`); the environment always wins over a stored profile, and a key from the environment alone
+works with no credentials file present at all.
+
+A manifest may name its blob bare (`blob: checkout`) instead of org-qualified. The org then comes from the global
+`--org` option (`blobhub --org acme-corp workflow deploy …`) or from `BLOBHUB_ORG`; with neither, the bare name is
+a manifest error naming all three ways to supply one.
+
+## The `workflow` domain
+
+A workflow blob's revision holds definitions whose `logic.code` components normally have their code typed into
+the browser, where it cannot be imported, unit-tested, linted, reviewed or version-controlled. The `workflow`
+command group closes that gap: you keep the code as an ordinary Python package, and the CLI compiles it into the
+flat, import-less namespace the platform's sandbox actually executes.
+
+### A worked example: deploying a workflow
+
+Say your revision has one workflow definition, alias `checkout_flow`, with a `logic.code` component (`id: c1`)
+whose code should come from a real Python package rather than being typed into the editor:
+
+```
+my-project/
+├── manifest.yaml
+├── definitions/
+│   └── checkout_flow.json      # the definition document — pulled from, or pushed to, the platform
+└── pkg/
+    ├── entry.py                 # entry_point
+    └── lib/
+        └── pricing.py           # a local module entry.py imports
+```
+
+`manifest.yaml`:
+
+```yaml
+type: workflow_blob_deployment
+version: "1.0"
+blob: acme-corp/checkout                # <org>/<blob>, or a bare <blob> plus --org/BLOBHUB_ORG
+revision: latest                        # or a pinned revision UUID
+definitions:
+  - alias: checkout_flow
+    source: definitions/checkout_flow.json
+    category: workflow
+    components:
+      - id: c1
+        code:
+          base_path: pkg
+          entry_point: entry.py
+```
+
+First pull the current definition (skip this if you're starting a definition from scratch):
+
+```sh
+blobhub workflow pull -f manifest.yaml
+```
+
+Compile and deploy:
+
+```sh
+blobhub workflow deploy -f manifest.yaml
+```
+
+`deploy` builds every bound component locally (inlining local imports from `pkg/`, stripping sandbox-pre-bound
+and allowlisted imports, rejecting anything else), uploads only the definitions whose serialized document
+actually changed, and runs the platform's `check_definition` against each workflow definition it uploaded.
+Re-running `deploy` with nothing changed uploads nothing and says so. `--dry-run` on every mutating command
+prints the exact intended calls without performing them; `--json` emits a single machine-readable object instead
+of the rendered output.
+
+Other commands in the `workflow` group:
+
+```sh
+blobhub workflow diff -f manifest.yaml     # report local/remote differences without writing or uploading
+blobhub workflow build -f manifest.yaml    # compile locally only, no network
+blobhub workflow check -f manifest.yaml    # re-run check_definition against what's already deployed
+blobhub workflow push -f manifest.yaml     # upload verbatim, without the compiler (rarely what you want)
+```
+
+If a code port was edited in the visual editor since the CLI last built it, `build`/`deploy` refuse to overwrite
+it with `REMOTE_EDIT` (or `UNMANAGED_CODE` for hand-typed code the CLI never built) — pass `--force` to overwrite,
+or reconcile by hand first. See `docs/reference/error-codes.md` for the full catalog of error and advisory codes,
+what each one means, and how to resolve it.
+
+## License
+
+MIT. See `LICENSE`.

blobhub_cli-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "blobhub-cli"
+dynamic = ["version"]
+description = "BlobHub command line interface — work with blobs, revisions, and their contents from the terminal"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.12"
+authors = [{ name = "BlobHub", email = "developers@blobhub.io" }]
+keywords = ["blobhub", "cli", "command-line", "blobs", "versioning", "workflows", "automation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = ["typer>=0.12", "rich>=13.7", "httpx>=0.27", "pyyaml>=6.0"]
+
+[project.urls]
+Homepage = "https://blobhub.io/"
+Documentation = "https://docs.blobhub.io/"
+Source = "https://github.com/blobhubio/blobhub-cli"
+Issues = "https://github.com/blobhubio/blobhub-cli/issues"
+
+[project.scripts]
+blobhub = "blobhub_cli.cli.app:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=4.1", "ruff>=0.6", "build>=1.2", "twine>=5.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/blobhub_cli/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/blobhub_cli"]
+
+[tool.hatch.build.targets.sdist]
+# Anchored with a leading slash. Hatchling matches gitignore-style, so a bare `README.md` also matched
+# `tests_online/README.md` and shipped the online tier's setup notes to everyone installing the sdist.
+include = ["/src/blobhub_cli", "/README.md", "/LICENSE", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "BLE", "ARG", "SIM", "RUF"]

blobhub_cli-0.1.0/src/blobhub_cli/__init__.py

@@ -0,0 +1,8 @@
+"""BlobHub CLI package root.
+
+Contract: this module is the sole source of the package version — hatchling reads
+`__version__` from here via `[tool.hatch.version] path` in pyproject.toml.
+Invariant: no other file in this package defines `__version__`.
+"""
+
+__version__ = "0.1.0"

blobhub_cli-0.1.0/src/blobhub_cli/__main__.py

@@ -0,0 +1,11 @@
+"""Process entry point for `python -m blobhub_cli`.
+
+Contract: invoking this module runs the CLI the same way the installed `blobhub`
+console script does.
+Invariant: holds no logic of its own — it only delegates to `cli.app.main`.
+"""
+
+from blobhub_cli.cli.app import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

blobhub_cli-0.1.0/src/blobhub_cli/api/__init__.py

@@ -0,0 +1,8 @@
+"""HTTP client and error hierarchy for talking to the BlobHub platform.
+
+Contract: `client.Client` is the only object in this package (and the only one in
+`blobhub_cli`) permitted to perform network I/O; every other module reaches the platform
+through it.
+Invariant: nothing in this package ever logs, echoes, or includes an API key in an
+exception message, output line, or `--json` payload.
+"""

blobhub_cli-0.1.0/src/blobhub_cli/api/client.py

@@ -0,0 +1,126 @@
+"""Synchronous HTTP client for the BlobHub API — the only module in this package that performs network I/O.
+
+Contract: `get`, `query`, `command`, and `raw_query` route every response through `_handle`,
+which maps HTTP status and the body's `status` field onto the `api.errors` hierarchy;
+`raw_query` alone skips the status gate, and `probe` skips both the gate and the retry loop.
+`query`/`command`/`raw_query` take a required keyword-only `engine` -- the engine a data request
+targets is the caller's to supply, never this class's to assume, because one command can
+legitimately span both: a scheduler `deploy` writes schedules against `scheduler_blobhub` and
+validates its targets with `workflow_blobhub` calls against the target revision, so a client
+fixed to one engine could not do that.
+Invariant: `Content-Type: application/json` is sent on every request, and the API key is
+never logged, echoed, or included in any exception message. This module is the only one that
+performs I/O against the BlobHub API -- the single sanctioned exception elsewhere is `doctor`'s
+PyPI version probe, which must NOT go through this class precisely because this class attaches
+`X-API-Key` to every request and the key must never reach a third-party host.
+"""
+
+import random
+import time
+
+import httpx
+
+from blobhub_cli.api.errors import (
+    ApiAuthError,
+    ApiCommandError,
+    ApiNetworkError,
+    ApiRateLimited,
+    ApiTransientError,
+)
+
+WORKFLOW_ENGINE = "workflow_blobhub"
+SCHEDULER_ENGINE = "scheduler_blobhub"
+
+_TRANSIENT = (ApiRateLimited, ApiTransientError, ApiNetworkError)
+_ATTEMPTS = 3
+_BASE_DELAY = 0.5
+_MAX_DELAY = 8.0
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 30.0,
+        sleep=time.sleep,
+    ) -> None:
+        self._sleep = sleep
+        self._http = httpx.Client(
+            base_url=base_url,
+            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
+            transport=transport,
+            timeout=timeout,
+        )
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self._http.close()
+
+    def get(self, path: str) -> dict:
+        return self._send("GET", path, gate_status=True)
+
+    def probe(self, path: str = "/users/me") -> tuple[int, float]:
+        """One unretried request, returning (status_code, elapsed_ms) without gating the body.
+
+        `doctor` uses this to prove reachability independently of credentials: every route needs
+        auth, so a 401 is a perfectly good proof that the host answered. Deliberately unretried --
+        a diagnostic wants a fast honest answer, not three backoffs.
+        """
+        start = time.monotonic()
+        try:
+            resp = self._http.request("GET", path)
+        except httpx.TransportError as exc:
+            raise ApiNetworkError(str(exc)) from exc
+        return resp.status_code, (time.monotonic() - start) * 1000
+
+    def query(self, revision_id: str, command: str, *, engine: str, **args: object) -> dict:
+        return self._data_request(revision_id, "query", command, engine=engine, gate_status=True, **args)
+
+    def command(self, revision_id: str, command: str, *, engine: str, **args: object) -> dict:
+        return self._data_request(revision_id, "command", command, engine=engine, gate_status=True, **args)
+
+    def raw_query(self, revision_id: str, command: str, *, engine: str, **args: object) -> dict:
+        return self._data_request(revision_id, "query", command, engine=engine, gate_status=False, **args)
+
+    def _data_request(
+        self, revision_id: str, channel: str, command: str, *, engine: str, gate_status: bool, **args: object
+    ) -> dict:
+        path = f"/revisions/{revision_id}/data/{channel}"
+        body = {"engine": engine, "command": command, **args}
+        return self._send("POST", path, gate_status=gate_status, json=body)
+
+    def _send(self, method: str, path: str, *, gate_status: bool, **kwargs: object) -> dict:
+        last_error: Exception
+        for attempt in range(_ATTEMPTS):
+            try:
+                resp = self._http.request(method, path, **kwargs)
+            except httpx.TransportError as exc:
+                last_error = ApiNetworkError(str(exc))
+            else:
+                try:
+                    return self._handle(resp, gate_status=gate_status)
+                except _TRANSIENT as exc:
+                    last_error = exc
+            if attempt < _ATTEMPTS - 1:
+                self._sleep(random.random() * min(_MAX_DELAY, _BASE_DELAY * 2**attempt))
+        raise last_error
+
+    def _handle(self, resp: httpx.Response, *, gate_status: bool) -> dict:
+        if resp.status_code in (401, 403):
+            raise ApiAuthError(f"auth failed: HTTP {resp.status_code}")
+        if resp.status_code == 429:
+            raise ApiRateLimited("HTTP 429")
+        if resp.status_code >= 500:
+            raise ApiTransientError(f"HTTP {resp.status_code}")
+        try:
+            data = resp.json()
+        except ValueError as exc:
+            raise ApiTransientError(f"non-JSON response: HTTP {resp.status_code}") from exc
+        if gate_status and data.get("status") != "success":
+            raise ApiCommandError(data.get("error", "unknown"), data.get("message", ""))
+        return data