blobhub-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{blobhub_cli-0.6.0 → blobhub_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blobhub-cli
-Version: 0.6.0
+Version: 0.7.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/
@@ -106,6 +106,9 @@ For CI, skip the credentials file entirely — set `BLOBHUB_API_KEY` (and option
 `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.
 
+The root `--profile` selects a stored profile for any command (`blobhub --profile staging workflow events …`),
+as `BLOBHUB_PROFILE` does. An exported `BLOBHUB_API_KEY` or `BLOBHUB_API_URL` still wins over the profile it names.
+
 `login` itself can also run non-interactively and still store a profile, which the environment-only approach
 above does not:
 
@@ -178,9 +181,10 @@ 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.
+Re-running `deploy` with nothing changed uploads nothing and says so. `--dry-run` (on `workflow pull|push|build|deploy|
+prune` and `scheduler deploy`) prints the exact intended calls without performing them; `--json` emits a single
+machine-readable object instead of the rendered output. The exception is `workflow events --follow --json`, which
+writes JSON Lines, one `{"event", "schema_version"}` object per event and no final object.
 
 Other commands in the `workflow` group:
 
@@ -196,6 +200,43 @@ it with `REMOTE_EDIT` (or `UNMANAGED_CODE` for hand-typed code the CLI never bui
 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.
 
+### Listeners and session events
+
+A **listener** is a definition with `category: listener` that acts on a session's event stream: it filters events,
+batches them, and invokes a workflow, a thread item or an object write. It lives in the manifest beside the
+workflows and deploys, diffs, pulls and checks like any other definition. The source file holds the whole body
+(`type: listener_definition`, `filter`, `batch`, `concurrency`, `invocation_target_type`, `invocation_target`,
+`receipt`); a listener entry takes no `components`.
+
+```yaml
+definitions:
+  - alias: orchestrate
+    category: listener                  # or inferred from `type: listener_definition` in the file
+    source: listeners/orchestrate.yaml
+```
+
+A session is named as `<session>` (with `-f manifest.yaml` naming its blob and revision),
+`<blob-id>/<revision>/<session>` or `<org>/<blob>/<revision>/<session>`; a qualified reference takes no `-f`.
+
+```sh
+blobhub workflow events my-session -f manifest.yaml                      # newest 20 events
+blobhub workflow events my-session -f manifest.yaml --types object.written --aliases 'worker/**' --follow
+blobhub workflow events my-session -f manifest.yaml --listener orchestrate --after 2026-11-09T17:00:00Z
+blobhub workflow events my-session -f manifest.yaml --cursor <token>     # continue the page a listing printed
+blobhub workflow listeners my-session -f manifest.yaml [--listener orchestrate]
+blobhub workflow listener disable my-session orchestrate -f manifest.yaml   # enable | disable, for this session
+```
+
+`--types`, `--aliases` and `--executions` repeat, and take globs where the platform does. A listing ends with
+`more: --cursor <token>` when there is another page; the token carries its own filter and direction, so pass it alone.
+`--follow` prints new events until interrupted without missing a late commit. `workflow execute --watch` follows the
+run's log the same way and ends once the platform reports the execution finished.
+
+With `--json`, the new commands print these keys: `workflow events` `{session, events, cursor}`; `workflow listeners`
+`{session_id, listeners, connections}`, or with `--listener` `{session_id, listener, executions, last_execution_id}`;
+`workflow listener enable|disable` `{session_id, listener}`. `workflow diff` adds `body_changed` and `validation_error`
+to a listener's report, and `scheduler ls` adds `invocation_target_type` and `target_alias` to each schedule.
+
 ## License
 
 MIT. See `LICENSE`.

{blobhub_cli-0.6.0 → blobhub_cli-0.7.0}/README.md

@@ -53,6 +53,9 @@ For CI, skip the credentials file entirely — set `BLOBHUB_API_KEY` (and option
 `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.
 
+The root `--profile` selects a stored profile for any command (`blobhub --profile staging workflow events …`),
+as `BLOBHUB_PROFILE` does. An exported `BLOBHUB_API_KEY` or `BLOBHUB_API_URL` still wins over the profile it names.
+
 `login` itself can also run non-interactively and still store a profile, which the environment-only approach
 above does not:
 
@@ -125,9 +128,10 @@ 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.
+Re-running `deploy` with nothing changed uploads nothing and says so. `--dry-run` (on `workflow pull|push|build|deploy|
+prune` and `scheduler deploy`) prints the exact intended calls without performing them; `--json` emits a single
+machine-readable object instead of the rendered output. The exception is `workflow events --follow --json`, which
+writes JSON Lines, one `{"event", "schema_version"}` object per event and no final object.
 
 Other commands in the `workflow` group:
 
@@ -143,6 +147,43 @@ it with `REMOTE_EDIT` (or `UNMANAGED_CODE` for hand-typed code the CLI never bui
 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.
 
+### Listeners and session events
+
+A **listener** is a definition with `category: listener` that acts on a session's event stream: it filters events,
+batches them, and invokes a workflow, a thread item or an object write. It lives in the manifest beside the
+workflows and deploys, diffs, pulls and checks like any other definition. The source file holds the whole body
+(`type: listener_definition`, `filter`, `batch`, `concurrency`, `invocation_target_type`, `invocation_target`,
+`receipt`); a listener entry takes no `components`.
+
+```yaml
+definitions:
+  - alias: orchestrate
+    category: listener                  # or inferred from `type: listener_definition` in the file
+    source: listeners/orchestrate.yaml
+```
+
+A session is named as `<session>` (with `-f manifest.yaml` naming its blob and revision),
+`<blob-id>/<revision>/<session>` or `<org>/<blob>/<revision>/<session>`; a qualified reference takes no `-f`.
+
+```sh
+blobhub workflow events my-session -f manifest.yaml                      # newest 20 events
+blobhub workflow events my-session -f manifest.yaml --types object.written --aliases 'worker/**' --follow
+blobhub workflow events my-session -f manifest.yaml --listener orchestrate --after 2026-11-09T17:00:00Z
+blobhub workflow events my-session -f manifest.yaml --cursor <token>     # continue the page a listing printed
+blobhub workflow listeners my-session -f manifest.yaml [--listener orchestrate]
+blobhub workflow listener disable my-session orchestrate -f manifest.yaml   # enable | disable, for this session
+```
+
+`--types`, `--aliases` and `--executions` repeat, and take globs where the platform does. A listing ends with
+`more: --cursor <token>` when there is another page; the token carries its own filter and direction, so pass it alone.
+`--follow` prints new events until interrupted without missing a late commit. `workflow execute --watch` follows the
+run's log the same way and ends once the platform reports the execution finished.
+
+With `--json`, the new commands print these keys: `workflow events` `{session, events, cursor}`; `workflow listeners`
+`{session_id, listeners, connections}`, or with `--listener` `{session_id, listener, executions, last_execution_id}`;
+`workflow listener enable|disable` `{session_id, listener}`. `workflow diff` adds `body_changed` and `validation_error`
+to a listener's report, and `scheduler ls` adds `invocation_target_type` and `target_alias` to each schedule.
+
 ## License
 
 MIT. See `LICENSE`.

{blobhub_cli-0.6.0 → blobhub_cli-0.7.0}/src/blobhub_cli/__init__.py

@@ -5,4 +5,4 @@ Contract: this module is the sole source of the package version — hatchling re
 Invariant: no other file in this package defines `__version__`.
 """
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"

{blobhub_cli-0.6.0 → blobhub_cli-0.7.0}/src/blobhub_cli/api/commands.py

@@ -85,23 +85,68 @@ class Api:
     def get_execution(self, revision_id: str, execution_id: str) -> dict:
         return self._client.query(revision_id, "get_execution", execution_id=execution_id)["execution"]
 
+    def list_session_events(
+        self,
+        revision_id: str,
+        session: str,
+        *,
+        filter: dict | None = None,
+        after: str | None = None,
+        ascending: bool | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> tuple[list[dict], str | None]:
+        args = self._page_args(filter, after, ascending, limit, cursor)
+        body = self._client.query(revision_id, "list_session_events", session=session, **args)
+        return body["events"], body["cursor"]
+
     def list_execution_events(
         self,
         revision_id: str,
         execution_id: str,
         *,
-        created_since: str | None = None,
-        ascending: bool = True,
+        filter: dict | None = None,
+        after: str | None = None,
+        ascending: bool | None = None,
         limit: int | None = None,
-    ) -> list[dict]:
+        cursor: str | None = None,
+    ) -> tuple[list[dict], str | None]:
+        args = self._page_args(filter, after, ascending, limit, cursor)
+        body = self._client.query(revision_id, "list_execution_events", execution_id=execution_id, **args)
+        return body["events"], body["cursor"]
+
+    @staticmethod
+    def _page_args(
+        filter: dict | None, after: str | None, ascending: bool | None, limit: int | None, cursor: str | None
+    ) -> dict[str, object]:
         # Keys are omitted rather than sent as null: every command schema is
         # additionalProperties: false, so one stray key is a 400, not an ignored field.
-        args: dict[str, object] = {"execution_id": execution_id, "ascending": ascending}
-        if created_since is not None:
-            args["created_since"] = created_since
-        if limit is not None:
-            args["limit"] = limit
-        return self._client.query(revision_id, "list_execution_events", **args)["execution_events"]
+        given = {"filter": filter or None, "after": after, "ascending": ascending, "limit": limit, "cursor": cursor}
+        return {key: value for key, value in given.items() if value is not None}
+
+    def list_session_listeners(self, revision_id: str, session: str) -> list[dict]:
+        return self._client.query(revision_id, "list_session_listeners", session=session)["listeners"]
+
+    def set_session_listener(self, revision_id: str, session: str, listener: str, enabled: bool) -> dict:
+        return self._client.command(
+            revision_id, "set_session_listener", session=session, listener=listener, enabled=enabled
+        )["listener"]
+
+    def list_executions(
+        self,
+        revision_id: str,
+        session_id: str,
+        *,
+        listener: str | None = None,
+        start_execution_id: str | None = None,
+    ) -> tuple[list[dict], str | None]:
+        args: dict[str, object] = {"session_id": session_id}
+        if listener is not None:
+            args["listener"] = listener
+        if start_execution_id is not None:
+            args["start_execution_id"] = start_execution_id
+        body = self._client.query(revision_id, "list_executions", **args)
+        return body["executions"], body["last_execution_id"]
 
     def create_schedule(self, revision_id: str, **fields: object) -> dict:
         return self._client.command(revision_id, "create_schedule", **fields)["schedule"]

{blobhub_cli-0.6.0 → blobhub_cli-0.7.0}/src/blobhub_cli/blob/reference.py

@@ -40,12 +40,21 @@ def not_accessible(ref: BlobRef) -> CliExit:
     can add: an org-scoped key must address its org by UUID and gets exactly this 403 against an
     alias -- which is why it belongs to the message rather than to one of the two raise sites.
     """
-    message = f"blob {ref.label()} is absent or not accessible with this key"
+    message = _refused(ref.label())
     if not ids.looks_like_uuid(ref.org):
         message += f"; if this API key is org-scoped, it must address the org by UUID, not the alias {ref.org!r}"
     return CliExit(codes.BLOB_NOT_ACCESSIBLE, message, "blobhub whoami")
 
 
+def id_not_accessible(blob_id: str) -> CliExit:
+    """BLOB_NOT_ACCESSIBLE for a blob named by id alone, so no org clause applies."""
+    return CliExit(codes.BLOB_NOT_ACCESSIBLE, _refused(blob_id), "blobhub whoami")
+
+
+def _refused(label: str) -> str:
+    return f"blob {label} is absent or not accessible with this key"
+
+
 def parse(text: str, default_org: str | None, *, command: str = DEFAULT_COMMAND) -> BlobRef:
     # `command` is the sub-command the caller is running ("blob revisions", "blob limits", ...),
     # threaded in only so that every hint below is a command the user can actually paste. It is no

{blobhub_cli-0.6.0 → blobhub_cli-0.7.0}/src/blobhub_cli/cli/app.py

@@ -42,9 +42,10 @@ def build_app() -> typer.Typer:
         verbose: bool = typer.Option(False, "-v", "--verbose", help="Print extra diagnostic detail."),
         quiet: bool = typer.Option(False, "-q", "--quiet", help="Suppress advisory warnings."),
         org: str = typer.Option(None, "--org", help="Org a manifest's bare 'blob:' name belongs to."),
+        profile: str = typer.Option(None, "--profile", help="Profile to use for this command."),
     ) -> None:
         console.configure(json_output=json_output, verbose=verbose, quiet=quiet)
-        settings.configure(org=org)
+        settings.configure(org=org, profile=profile)
         if version:
             typer.echo(__version__)
             raise typer.Exit(0)
@@ -134,7 +135,10 @@ def build_app() -> typer.Typer:
 
         completion_cmd.emit(shell)
 
-    profile_app = typer.Typer(add_completion=False, help="Manage stored profiles.")
+    profile_app = typer.Typer(
+        add_completion=False,
+        help="Manage stored profiles. Takes names as arguments; ignores the root --profile.",
+    )
 
     @profile_app.command("ls")
     def profile_ls() -> None:
@@ -270,6 +274,73 @@ def build_app() -> typer.Typer:
 
         execute_cmd.execute(manifest, definition, session, watch, open_browser)
 
+    @workflow_app.command("events")
+    def workflow_events(
+        session: str = typer.Argument(
+            ..., help="A session, or <blob-id>/<revision>/<session> or <org>/<blob>/<revision>/<session>."
+        ),
+        manifest: Path = typer.Option(  # noqa: B008
+            None, "-f", "--file", help="Manifest naming the blob and revision of a bare session."
+        ),
+        types: list[str] = typer.Option([], "--types", help="Event types, globs allowed; repeatable."),  # noqa: B008
+        aliases: list[str] = typer.Option([], "--aliases", help="Object aliases; repeatable."),  # noqa: B008
+        executions: list[str] = typer.Option([], "--executions", help="Execution ids; repeatable."),  # noqa: B008
+        listener: str = typer.Option(None, "--listener", help="Only events a listener caused: its alias or id."),
+        after: str = typer.Option(None, "--after", help="List events after this id, boundary or ISO 8601 time."),
+        cursor: str = typer.Option(None, "--cursor", help="Continue a listing from the token it printed."),
+        limit: int = typer.Option(20, "--limit", min=1, max=1000, help="Events per page."),
+        follow: bool = typer.Option(False, "--follow", help="Print new events as they arrive until interrupted."),
+    ) -> None:
+        """List a session's events, newest first unless --after is given, or follow them."""
+        from blobhub_cli.commands import events as events_cmd
+
+        events_cmd.events(
+            session, manifest, types=types, aliases=aliases, executions=executions, listener=listener,
+            after=after, cursor=cursor, limit=limit, follow=follow,
+        )
+
+    @workflow_app.command("listeners")
+    def workflow_listeners(
+        session: str = typer.Argument(
+            ..., help="A session, or <blob-id>/<revision>/<session> or <org>/<blob>/<revision>/<session>."
+        ),
+        manifest: Path = typer.Option(  # noqa: B008
+            None, "-f", "--file", help="Manifest naming the blob and revision of a bare session."
+        ),
+        listener: str = typer.Option(None, "--listener", help="Show one declared listener: its alias or id."),
+    ) -> None:
+        """List a session's listeners with their switch, slots and outcomes, or show one in detail."""
+        from blobhub_cli.commands import events as events_cmd
+
+        events_cmd.listeners(session, manifest, listener=listener)
+
+    listener_app = typer.Typer(add_completion=False, help="Switch a declared listener for one session.")
+
+    def _listener_switch(session: str, listener: str, manifest: Path | None, enabled: bool) -> None:
+        from blobhub_cli.commands import events as events_cmd
+
+        events_cmd.switch(session, manifest, listener, enabled)
+
+    @listener_app.command("enable")
+    def listener_enable(
+        session: str = typer.Argument(..., help="A session reference, as for `workflow events`."),
+        listener: str = typer.Argument(..., help="A declared listener's alias or id."),
+        manifest: Path = typer.Option(None, "-f", "--file", help="Manifest naming a bare session's blob."),  # noqa: B008
+    ) -> None:
+        """Enable a listener for this session, overriding its definition when it is off there."""
+        _listener_switch(session, listener, manifest, True)
+
+    @listener_app.command("disable")
+    def listener_disable(
+        session: str = typer.Argument(..., help="A session reference, as for `workflow events`."),
+        listener: str = typer.Argument(..., help="A declared listener's alias or id."),
+        manifest: Path = typer.Option(None, "-f", "--file", help="Manifest naming a bare session's blob."),  # noqa: B008
+    ) -> None:
+        """Disable a listener for this session, overriding its definition when it is on there."""
+        _listener_switch(session, listener, manifest, False)
+
+    workflow_app.add_typer(listener_app, name="listener")
+
     @workflow_app.command("check")
     def workflow_check(
         manifest: Path = typer.Option(..., "-f", "--file", help="Path to the workflow manifest."),  # noqa: B008

{blobhub_cli-0.6.0 → blobhub_cli-0.7.0}/src/blobhub_cli/codes.py

@@ -39,11 +39,13 @@ DEFINITION_NOT_ACCESSIBLE = "DEFINITION_NOT_ACCESSIBLE"
 DEFINITION_ALIAS_INVALID = "DEFINITION_ALIAS_INVALID"
 DEFINITION_CATEGORY_UNKNOWN = "DEFINITION_CATEGORY_UNKNOWN"
 ALIAS_IN_USE = "ALIAS_IN_USE"
+LISTENER_INVALID = "LISTENER_INVALID"
 LIMIT_EXCEEDED = "LIMIT_EXCEEDED"
 PRUNE_NOT_CONFIRMED = "PRUNE_NOT_CONFIRMED"
 
 # Workflow references
 WORKFLOW_REFERENCE_INVALID = "WORKFLOW_REFERENCE_INVALID"
+SESSION_REFERENCE_INVALID = "SESSION_REFERENCE_INVALID"
 
 # Format
 FORMAT_UNSUPPORTED = "FORMAT_UNSUPPORTED"
@@ -82,6 +84,9 @@ SESSION_NOT_OPEN = "SESSION_NOT_OPEN"
 DEFINITION_NOT_EXECUTABLE = "DEFINITION_NOT_EXECUTABLE"
 EXECUTION_FAILED = "EXECUTION_FAILED"
 EXECUTION_OUTCOME_UNKNOWN = "EXECUTION_OUTCOME_UNKNOWN"
+EVENT_FILTER_INVALID = "EVENT_FILTER_INVALID"
+EVENT_CURSOR_INVALID = "EVENT_CURSOR_INVALID"
+LISTENER_NOT_FOUND = "LISTENER_NOT_FOUND"
 
 # Schedules
 SCHEDULE_ALIAS_REQUIRED = "SCHEDULE_ALIAS_REQUIRED"

{blobhub_cli-0.6.0 → blobhub_cli-0.7.0}/src/blobhub_cli/commands/auth.py

@@ -7,7 +7,6 @@ hint, or the returned payload — only the profile name, URL, and realtime URL a
 """
 
 import getpass
-import os
 import sys
 from collections.abc import Callable
 from typing import NamedTuple
@@ -86,7 +85,7 @@ def login(
     stdin_read: Callable[[], str] | None = None,
     api_factory: Callable[[Settings], Api] = _default_api_factory,
 ) -> dict:
-    name = profile or os.environ.get("BLOBHUB_PROFILE") or "default"
+    name = settings.profile_name(profile, None) or "default"
 
     requests = [
         sources.Request("api-key", supplied.api_key, supplied.api_key_stdin, supplied.api_key_env),
@@ -179,7 +178,7 @@ def logout(profile: str | None, all_profiles: bool) -> dict:
         removed = sorted(profiles)
         credentials.save({}, None)
     else:
-        name = profile or default
+        name = settings.profile_name(profile, default)
         if name is None or name not in profiles:
             raise CliExit(codes.PROFILE_NOT_FOUND, f"no profile named {name!r}", "blobhub profile ls")
         del profiles[name]

{blobhub_cli-0.6.0 → blobhub_cli-0.7.0}/src/blobhub_cli/commands/doctor.py

@@ -22,7 +22,7 @@ from blobhub_cli.api.commands import Api
 from blobhub_cli.api.errors import ApiAuthError, ApiError
 from blobhub_cli.compiler import allowlist
 from blobhub_cli.config import credentials
-from blobhub_cli.config.settings import DEFAULT_API_URL, DEFAULT_REALTIME_URL, Settings
+from blobhub_cli.config.settings import DEFAULT_API_URL, DEFAULT_REALTIME_URL, Settings, profile_name
 from blobhub_cli.exit import CliExit
 
 OK, FAIL, WARN, SKIP = "ok", "fail", "warn", "skip"
@@ -81,7 +81,7 @@ def _resolve_url(flag_url: str | None, flag_profile: str | None) -> str:
         profiles, default = credentials.load()
     except CliExit:
         return DEFAULT_API_URL
-    name = flag_profile or os.environ.get("BLOBHUB_PROFILE") or default
+    name = profile_name(flag_profile, default)
     profile = profiles.get(name) if name else None
     return profile.url if profile else DEFAULT_API_URL
 
@@ -97,7 +97,7 @@ def _resolve_key(flag_key: str | None, flag_profile: str | None) -> tuple[str |
     catch, in its most load-bearing row.
     """
     profiles, default = credentials.load()  # may raise CliExit; the caller converts it to a row
-    name = flag_profile or os.environ.get("BLOBHUB_PROFILE") or default
+    name = profile_name(flag_profile, default)
     if name and name not in profiles:
         return None, f"{codes.PROFILE_NOT_FOUND}: no profile named {name!r}"
     if flag_key:

{blobhub_cli-0.6.0 → blobhub_cli-0.7.0}/src/blobhub_cli/commands/eject.py

@@ -76,8 +76,12 @@ def eject(
     order: list[tuple[str, Path]] = []
     seen_keys: set[tuple[str, Path]] = set()
     suggestions: list[dict] = []
+    skipped: list[dict] = []
 
     for entry in set_.entries:
+        if entry.category == "listener":
+            skipped.append({"category": entry.category, "alias": entry.alias})
+            continue
         remote = set_.remote.get((entry.category, entry.alias))
         if remote is None:
             continue  # nothing on the revision yet for this alias -- nothing to eject
@@ -148,6 +152,6 @@ def eject(
             "alias": alias, "root": str(root), "files": [str(path) for path, _ in targets],
         })
 
-    payload = {"definitions": definitions_payload, "bound": not suggestions}
+    payload = {"definitions": definitions_payload, "bound": not suggestions, "skipped": skipped}
     console.result(payload, lambda p: _render_eject(p, suggestions))
     return payload