flowstash-cli 0.11.0__tar.gz → 0.13.0__tar.gz

{flowstash_cli-0.11.0 → flowstash_cli-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flowstash-cli
-Version: 0.11.0
+Version: 0.13.0
 Summary: CLI for the flowstash Managed Platform
 License: MIT
 Author: juraj.bezdek@gmail.com
@@ -11,7 +11,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: flowstash-runtime (>=0.11.0,<0.12.0)
+Requires-Dist: flowstash-runtime (>=0.13.0,<0.14.0)
 Requires-Dist: httpx (>=0.27.0)
 Requires-Dist: keyring (>=25.0.0)
 Requires-Dist: libcst (>=1.1.0)

{flowstash_cli-0.11.0 → flowstash_cli-0.13.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "flowstash-cli"
-version = "0.11.0"
+version = "0.13.0"
 description = "CLI for the flowstash Managed Platform"
 authors = [{name = "juraj.bezdek@gmail.com", email = "juraj.bezdek@gmail.com"}]
 license = "MIT"
 requires-python = ">=3.11"
 dependencies = [
-    "flowstash-runtime>=0.11.0,<0.12.0",
+    "flowstash-runtime>=0.13.0,<0.14.0",
     "typer[all]>=0.12.0",
     "httpx>=0.27.0",
     "pyyaml>=6.0.1",

{flowstash_cli-0.11.0 → flowstash_cli-0.13.0}/src/flowstash/cli/commands/apikey.py

@@ -24,7 +24,7 @@ from rich.prompt import Prompt
 from rich.table import Table
 
 from ..core.api_client import APIClient
-from ..core.config import get_access_token, resolve_credentials
+from ..core.config import get_access_token, resolve_credentials, find_project_root, load_project_config
 
 app = typer.Typer(
     name="api-keys",
@@ -33,9 +33,10 @@ app = typer.Typer(
 )
 console = Console()
 
-_VALID_SCOPES = {"observability:ingest", "admin"}
+_VALID_SCOPES = {"observability:ingest", "observability:read", "admin"}
 _SCOPE_DESCRIPTIONS = {
     "observability:ingest": "Write-only ingestion (SDK / workers)",
+    "observability:read": "Read-only managed diagnostics (agents)",
     "admin": "Full management access (CI / automation)",
 }
 
@@ -49,7 +50,8 @@ def _format_ts(ts) -> str:
         return str(ts)
 
 
-def _find_project_root(start_path: Path = Path.cwd()) -> Optional[Path]:
+def _find_project_root(start_path: Optional[Path] = None) -> Optional[Path]:
+    start_path = start_path or Path.cwd()
     for parent in [start_path] + list(start_path.parents):
         if (parent / ".flowstash").exists() or (parent / "pyproject.toml").exists():
             return parent
@@ -104,6 +106,8 @@ def _create_key(
     scope: Optional[str],
     env: Optional[str],
     user: Optional[str] = None,
+    project: Optional[str] = None,
+    write_env: Optional[str] = None,
 ):
     """Shared implementation for 'new' and 'create'."""
     token = resolve_credentials(user=user)
@@ -119,7 +123,7 @@ def _create_key(
             "Key scope:",
             choices=[
                 questionary.Choice(f"{s}  —  {_SCOPE_DESCRIPTIONS[s]}", s)
-                for s in _VALID_SCOPES
+                for s in sorted(_VALID_SCOPES - {"observability:read"})
             ],
             default="observability:ingest",
         ).ask()
@@ -132,6 +136,21 @@ def _create_key(
         )
         raise typer.Exit(code=1)
 
+    # Preserve legacy ingest/admin --env file setup without --project.
+    # Read keys require explicit scope and never write to a file implicitly.
+    restricted_env = env if project or scope == "observability:read" else None
+    if restricted_env and not project:
+        root = find_project_root()
+        try:
+            config = load_project_config(root, strict=True) if root else None
+        except ValueError:
+            console.print("[red]Malformed .flowstash configuration.[/red]")
+            raise typer.Exit(code=2)
+        project = config.project_id if config else None
+        if not project:
+            console.print("[red]An environment restriction requires --project or a linked project.[/red]")
+            raise typer.Exit(code=2)
+
     if scope == "admin" and env:
         console.print(
             "[yellow]Warning: writing an 'admin' key to .env is not recommended. "
@@ -140,7 +159,12 @@ def _create_key(
 
     async def _create():
         api = APIClient(token=token)
-        return await api.post("/v1/api-keys", json={"label": label, "scopes": [scope]})
+        body = {"label": label, "scopes": [scope]}
+        if project:
+            body["project_id"] = project
+        if restricted_env:
+            body["environment"] = restricted_env
+        return await api.post("/v1/api-keys", json=body)
 
     try:
         result = asyncio.run(_create())
@@ -155,14 +179,19 @@ def _create_key(
     console.print(f"   Key ID  : [bold]{result['key_id']}[/bold]")
     console.print(f"   Label   : {label}")
     console.print(f"   Scope   : {scope}")
+    if project:
+        console.print(f"   Project : {project}")
+    if restricted_env:
+        console.print(f"   Env     : {restricted_env}")
     console.print()
     console.print(
         "[bold yellow]⚠  Save this key — it will NOT be shown again:[/bold yellow]"
     )
     console.print(f"\n   [bold cyan]{raw_key}[/bold cyan]\n")
 
-    if env:
-        _write_key_to_env(env, raw_key)
+    target_env = write_env or (env if scope != "observability:read" else None)
+    if target_env:
+        _write_key_to_env(target_env, raw_key)
 
 
 @app.command("new")
@@ -171,17 +200,19 @@ def apikey_new(
         None, "--label", "-l", help="Human-readable label for the key"
     ),
     scope: Optional[str] = typer.Option(
-        None, "--scope", "-s", help="Scope: observability:ingest | admin"
+        None, "--scope", "-s", help="Scope: observability:ingest | observability:read | admin"
     ),
     env: Optional[str] = typer.Option(
-        None, "--env", "-e", help="Write key to this environment's .env file"
+        None, "--env", "-e", help="Restrict read keys to an environment; legacy ingest/admin .env setup"
     ),
     user: Optional[str] = typer.Option(
         None, "--user", "-u", help="Account to use (default: project-linked or current)"
     ),
+    project: Optional[str] = typer.Option(None, "--project", help="Restrict key to a managed project"),
+    write_env: Optional[str] = typer.Option(None, "--write-env", help="Explicitly write key to an environment .env file"),
 ):
     """Create a new API key and optionally write it to an environment .env file."""
-    _create_key(label=label, scope=scope, env=env, user=user)
+    _create_key(label=label, scope=scope, env=env, user=user, project=project, write_env=write_env)
 
 
 @app.command("create")
@@ -190,17 +221,19 @@ def apikey_create(
         None, "--label", "-l", help="Human-readable label for the key"
     ),
     scope: Optional[str] = typer.Option(
-        None, "--scope", "-s", help="Scope: observability:ingest | admin"
+        None, "--scope", "-s", help="Scope: observability:ingest | observability:read | admin"
     ),
     env: Optional[str] = typer.Option(
-        None, "--env", "-e", help="Write key to this environment's .env file"
+        None, "--env", "-e", help="Restrict read keys to an environment; legacy ingest/admin .env setup"
     ),
     user: Optional[str] = typer.Option(
         None, "--user", "-u", help="Account to use (default: project-linked or current)"
     ),
+    project: Optional[str] = typer.Option(None, "--project", help="Restrict key to a managed project"),
+    write_env: Optional[str] = typer.Option(None, "--write-env", help="Explicitly write key to an environment .env file"),
 ):
     """Create a new API key (alias for 'new')."""
-    _create_key(label=label, scope=scope, env=env, user=user)
+    _create_key(label=label, scope=scope, env=env, user=user, project=project, write_env=write_env)
 
 
 @app.command("list")
@@ -235,6 +268,8 @@ def apikey_list(
     table.add_column("Label")
     table.add_column("Prefix")
     table.add_column("Scopes", style="cyan")
+    table.add_column("Project")
+    table.add_column("Environment")
     table.add_column("Created")
     table.add_column("Last Used")
 
@@ -244,6 +279,8 @@ def apikey_list(
             k["label"],
             k["key_prefix"],
             ", ".join(k.get("scopes", [])),
+            k.get("project_id") or "—",
+            k.get("environment") or "—",
             _format_ts(k.get("created_at")),
             _format_ts(k.get("last_used_at")),
         )

flowstash_cli-0.13.0/src/flowstash/cli/commands/diagnostics.py

@@ -0,0 +1,336 @@
+"""Resource-specific read-only diagnostics. No payload hydration or page draining."""
+from enum import Enum
+from typing import Optional
+import typer
+from ..core.diagnostics import DiagnosticCommand, DiagnosticGroup, execute, resolve_context, query_options
+
+class Order(str, Enum):
+    asc = "asc"
+    desc = "desc"
+
+class EventType(str, Enum):
+    STARTED = "STARTED"
+    PROGRESS = "PROGRESS"
+    ENDED = "ENDED"
+    SCHEDULED = "SCHEDULED"
+
+class BuildSeverity(str, Enum):
+    DEFAULT = "DEFAULT"
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    NOTICE = "NOTICE"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+    ALERT = "ALERT"
+    EMERGENCY = "EMERGENCY"
+
+obs_app = typer.Typer(help="Read managed execution evidence", cls=DiagnosticGroup, no_args_is_help=True)
+builds_app = typer.Typer(help="Read managed builds and paginated build logs", cls=DiagnosticGroup, no_args_is_help=True)
+
+
+def observation(resource, options):
+    options = dict(options)
+    json_mode = options.pop("json_mode")
+    project, env, user = (options.pop(k) for k in ("project", "env", "user"))
+    run_id = options.get("run_id")
+    async def work():
+        params, window = query_options(options, scoped=bool(run_id), logs=resource == "logs", default_window=not run_id)
+        context = await resolve_context(project, env, user)
+        result = await context.api.diagnostic_query(resource, {**context.location, **params}, run_id if resource != "runs" else None)
+        return result, window
+    execute(work, json_mode)
+
+
+@obs_app.command("run", cls=DiagnosticCommand)
+def run_summary(
+    run_id: str = typer.Argument(...),
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+):
+    """Read one run summary in the selected workspace."""
+    async def work():
+        context = await resolve_context(project, env, user)
+        result = await context.api.diagnostic_run(run_id, context.location)
+        context.check_item(result)
+        return result, {}
+    execute(work, json_mode)
+
+
+@obs_app.command("runs", cls=DiagnosticCommand)
+def runs(
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+    limit: Optional[int] = typer.Option(None, "--limit", help='Page size: 50; run logs: 100 (maximum 500)', min=1, max=500),
+    page_token: Optional[str] = typer.Option(None, "--page-token", help='Opaque continuation token; reuse fixed times and filters'),
+    order: Optional[Order] = typer.Option(None, "--order", help='Project queries: desc; run/build logs: asc'),
+    from_time: Optional[str] = typer.Option(None, "--from", help='Inclusive timezone-aware RFC3339 start'),
+    to_time: Optional[str] = typer.Option(None, "--to", help='Timezone-aware RFC3339 end'),
+    since: Optional[str] = typer.Option(None, "--since", help='Positive duration: 30m, 2h, 7d'),
+    integration: Optional[str] = typer.Option(None, "--integration", help='Exact integration'),
+    pipeline: Optional[str] = typer.Option(None, "--pipeline", help='Exact pipeline'),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help='Exact run id'),
+    span_id: Optional[str] = typer.Option(None, "--span-id", help='Exact span id'),
+    trace_id: Optional[str] = typer.Option(None, "--trace-id", help='Exact trace id'),
+    parent_run_id: Optional[str] = typer.Option(None, "--parent-run-id", help='Exact parent run id'),
+    operation_id: Optional[str] = typer.Option(None, "--operation-id", help='Exact operation id'),
+    record_key: Optional[str] = typer.Option(None, "--record-key", help='Exact record key'),
+    status: Optional[str] = typer.Option(None, "--status", help='status'),
+):
+    """Read one page of runs; fetch additional pages explicitly."""
+    observation("runs", locals())
+
+
+@obs_app.command("logs", cls=DiagnosticCommand)
+def logs(
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+    limit: Optional[int] = typer.Option(None, "--limit", help='Page size: 50; run logs: 100 (maximum 500)', min=1, max=500),
+    page_token: Optional[str] = typer.Option(None, "--page-token", help='Opaque continuation token; reuse fixed times and filters'),
+    order: Optional[Order] = typer.Option(None, "--order", help='Project queries: desc; run/build logs: asc'),
+    from_time: Optional[str] = typer.Option(None, "--from", help='Inclusive timezone-aware RFC3339 start'),
+    to_time: Optional[str] = typer.Option(None, "--to", help='Timezone-aware RFC3339 end'),
+    since: Optional[str] = typer.Option(None, "--since", help='Positive duration: 30m, 2h, 7d'),
+    integration: Optional[str] = typer.Option(None, "--integration", help='Exact integration'),
+    pipeline: Optional[str] = typer.Option(None, "--pipeline", help='Exact pipeline'),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help='Exact run id'),
+    span_id: Optional[str] = typer.Option(None, "--span-id", help='Exact span id'),
+    trace_id: Optional[str] = typer.Option(None, "--trace-id", help='Exact trace id'),
+    parent_run_id: Optional[str] = typer.Option(None, "--parent-run-id", help='Exact parent run id'),
+    operation_id: Optional[str] = typer.Option(None, "--operation-id", help='Exact operation id'),
+    record_key: Optional[str] = typer.Option(None, "--record-key", help='Exact record key'),
+    severity: Optional[str] = typer.Option(None, "--severity", help='severity'),
+    search: Optional[str] = typer.Option(None, "--search", help='search'),
+):
+    """Read one page of logs; fetch additional pages explicitly."""
+    observation("logs", locals())
+
+
+@obs_app.command("spans", cls=DiagnosticCommand)
+def spans(
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+    limit: Optional[int] = typer.Option(None, "--limit", help='Page size: 50; run logs: 100 (maximum 500)', min=1, max=500),
+    page_token: Optional[str] = typer.Option(None, "--page-token", help='Opaque continuation token; reuse fixed times and filters'),
+    order: Optional[Order] = typer.Option(None, "--order", help='Project queries: desc; run/build logs: asc'),
+    from_time: Optional[str] = typer.Option(None, "--from", help='Inclusive timezone-aware RFC3339 start'),
+    to_time: Optional[str] = typer.Option(None, "--to", help='Timezone-aware RFC3339 end'),
+    since: Optional[str] = typer.Option(None, "--since", help='Positive duration: 30m, 2h, 7d'),
+    integration: Optional[str] = typer.Option(None, "--integration", help='Exact integration'),
+    pipeline: Optional[str] = typer.Option(None, "--pipeline", help='Exact pipeline'),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help='Exact run id'),
+    span_id: Optional[str] = typer.Option(None, "--span-id", help='Exact span id'),
+    trace_id: Optional[str] = typer.Option(None, "--trace-id", help='Exact trace id'),
+    parent_run_id: Optional[str] = typer.Option(None, "--parent-run-id", help='Exact parent run id'),
+    operation_id: Optional[str] = typer.Option(None, "--operation-id", help='Exact operation id'),
+    record_key: Optional[str] = typer.Option(None, "--record-key", help='Exact record key'),
+    status: Optional[str] = typer.Option(None, "--status", help='status'),
+    search: Optional[str] = typer.Option(None, "--search", help='search'),
+):
+    """Read one page of spans; fetch additional pages explicitly."""
+    observation("spans", locals())
+
+
+@obs_app.command("io", cls=DiagnosticCommand)
+def io(
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+    limit: Optional[int] = typer.Option(None, "--limit", help='Page size: 50; run logs: 100 (maximum 500)', min=1, max=500),
+    page_token: Optional[str] = typer.Option(None, "--page-token", help='Opaque continuation token; reuse fixed times and filters'),
+    order: Optional[Order] = typer.Option(None, "--order", help='Project queries: desc; run/build logs: asc'),
+    from_time: Optional[str] = typer.Option(None, "--from", help='Inclusive timezone-aware RFC3339 start'),
+    to_time: Optional[str] = typer.Option(None, "--to", help='Timezone-aware RFC3339 end'),
+    since: Optional[str] = typer.Option(None, "--since", help='Positive duration: 30m, 2h, 7d'),
+    integration: Optional[str] = typer.Option(None, "--integration", help='Exact integration'),
+    pipeline: Optional[str] = typer.Option(None, "--pipeline", help='Exact pipeline'),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help='Exact run id'),
+    span_id: Optional[str] = typer.Option(None, "--span-id", help='Exact span id'),
+    trace_id: Optional[str] = typer.Option(None, "--trace-id", help='Exact trace id'),
+    parent_run_id: Optional[str] = typer.Option(None, "--parent-run-id", help='Exact parent run id'),
+    operation_id: Optional[str] = typer.Option(None, "--operation-id", help='Exact operation id'),
+    record_key: Optional[str] = typer.Option(None, "--record-key", help='Exact record key'),
+    state: Optional[str] = typer.Option(None, "--state", help='state'),
+    remote_system: Optional[str] = typer.Option(None, "--remote-system", help='remote system'),
+    channel: Optional[str] = typer.Option(None, "--channel", help='channel'),
+    operation: Optional[str] = typer.Option(None, "--operation", help='operation'),
+    status_code: Optional[int] = typer.Option(None, "--status-code", help='status code'),
+    query: Optional[str] = typer.Option(None, "--query", help='query'),
+):
+    """Read one page of io; fetch additional pages explicitly."""
+    observation("data-exchanges", locals())
+
+
+@obs_app.command("records", cls=DiagnosticCommand)
+def records(
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+    limit: Optional[int] = typer.Option(None, "--limit", help='Page size: 50; run logs: 100 (maximum 500)', min=1, max=500),
+    page_token: Optional[str] = typer.Option(None, "--page-token", help='Opaque continuation token; reuse fixed times and filters'),
+    order: Optional[Order] = typer.Option(None, "--order", help='Project queries: desc; run/build logs: asc'),
+    from_time: Optional[str] = typer.Option(None, "--from", help='Inclusive timezone-aware RFC3339 start'),
+    to_time: Optional[str] = typer.Option(None, "--to", help='Timezone-aware RFC3339 end'),
+    since: Optional[str] = typer.Option(None, "--since", help='Positive duration: 30m, 2h, 7d'),
+    integration: Optional[str] = typer.Option(None, "--integration", help='Exact integration'),
+    pipeline: Optional[str] = typer.Option(None, "--pipeline", help='Exact pipeline'),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help='Exact run id'),
+    span_id: Optional[str] = typer.Option(None, "--span-id", help='Exact span id'),
+    trace_id: Optional[str] = typer.Option(None, "--trace-id", help='Exact trace id'),
+    parent_run_id: Optional[str] = typer.Option(None, "--parent-run-id", help='Exact parent run id'),
+    operation_id: Optional[str] = typer.Option(None, "--operation-id", help='Exact operation id'),
+    record_key: Optional[str] = typer.Option(None, "--record-key", help='Exact record key'),
+    kind: Optional[str] = typer.Option(None, "--kind", help='kind'),
+    source: Optional[str] = typer.Option(None, "--source", help='source'),
+):
+    """Read one page of records; fetch additional pages explicitly."""
+    observation("records", locals())
+
+
+@obs_app.command("events", cls=DiagnosticCommand)
+def events(
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+    limit: Optional[int] = typer.Option(None, "--limit", help='Page size: 50; run logs: 100 (maximum 500)', min=1, max=500),
+    page_token: Optional[str] = typer.Option(None, "--page-token", help='Opaque continuation token; reuse fixed times and filters'),
+    order: Optional[Order] = typer.Option(None, "--order", help='Project queries: desc; run/build logs: asc'),
+    from_time: Optional[str] = typer.Option(None, "--from", help='Inclusive timezone-aware RFC3339 start'),
+    to_time: Optional[str] = typer.Option(None, "--to", help='Timezone-aware RFC3339 end'),
+    since: Optional[str] = typer.Option(None, "--since", help='Positive duration: 30m, 2h, 7d'),
+    integration: Optional[str] = typer.Option(None, "--integration", help='Exact integration'),
+    pipeline: Optional[str] = typer.Option(None, "--pipeline", help='Exact pipeline'),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help='Exact run id'),
+    span_id: Optional[str] = typer.Option(None, "--span-id", help='Exact span id'),
+    trace_id: Optional[str] = typer.Option(None, "--trace-id", help='Exact trace id'),
+    parent_run_id: Optional[str] = typer.Option(None, "--parent-run-id", help='Exact parent run id'),
+    operation_id: Optional[str] = typer.Option(None, "--operation-id", help='Exact operation id'),
+    record_key: Optional[str] = typer.Option(None, "--record-key", help='Exact record key'),
+    status: Optional[str] = typer.Option(None, "--status", help='status'),
+    event_type: Optional[EventType] = typer.Option(None, "--event-type", help='event type'),
+):
+    """Read one page of events; fetch additional pages explicitly."""
+    observation("run-events", locals())
+
+
+@obs_app.command("payload", cls=DiagnosticCommand)
+def payload(
+    payload_ref: str = typer.Argument(...),
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+    run_id: Optional[str] = typer.Option(None, "--run-id", help='Captured owning run'),
+):
+    """Fetch one stored payload; binary data remains base64 in JSON."""
+    async def work():
+        context = await resolve_context(project, env, user)
+        params = {**context.location}
+        if run_id is not None:
+            params["run_id"] = run_id
+        return await context.api.diagnostic_payload(payload_ref, params), {}
+    execute(work, json_mode)
+
+
+@builds_app.command("get", cls=DiagnosticCommand)
+def build_get(
+    build_id: str = typer.Argument(...),
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+):
+    """Read status using a managed build ID; does not trigger a build."""
+    async def work():
+        context = await resolve_context(project, env, user)
+        result = await context.api.build_status(build_id)
+        context.check_item(result, environment=False)
+        return result, {}
+    execute(work, json_mode)
+
+
+@builds_app.command("list", cls=DiagnosticCommand)
+def build_list(
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+    limit: Optional[int] = typer.Option(None, "--limit", help='Page size: 50; run logs: 100 (maximum 500)', min=1, max=500),
+    page_token: Optional[str] = typer.Option(None, "--page-token", help='Opaque continuation token; reuse fixed times and filters'),
+    order: Optional[Order] = typer.Option(None, "--order", help='Project queries: desc; run/build logs: asc'),
+    from_time: Optional[str] = typer.Option(None, "--from", help='Inclusive timezone-aware RFC3339 start'),
+    to_time: Optional[str] = typer.Option(None, "--to", help='Timezone-aware RFC3339 end'),
+    since: Optional[str] = typer.Option(None, "--since", help='Positive duration: 30m, 2h, 7d'),
+):
+    """Read one page of environment-neutral builds (server time/order semantics)."""
+    options = locals().copy()
+    async def work():
+        filters = {k: options[k] for k in ("limit", "page_token", "order", "from_time", "to_time", "since")}
+        params, window = query_options(filters, scoped=True)
+        # The native build-list API has fixed ordering, no environment filter,
+        # and optional epoch bounds rather than observability's 24-hour default.
+        if order is not None and order != Order.desc:
+            from ..core.diagnostics import DiagnosticError
+            raise DiagnosticError("INVALID_ORDER", "Build list uses server descending order; use --order desc")
+        params.pop("order")
+        params["page_size"] = params.pop("limit")
+        from ..core.diagnostics import timestamp
+        for old, new in (("from_time", "start_ts"), ("to_time", "end_ts")):
+            if old in params:
+                params[new] = timestamp(params.pop(old)).timestamp()
+        context = await resolve_context(project, env, user)
+        params["project_id"] = context.info["project_id"]
+        return await context.api.get("/v1/builds", params=params), window
+    execute(work, json_mode)
+
+
+@builds_app.command("logs", cls=DiagnosticCommand)
+def build_logs(
+    build_id: str = typer.Argument(...),
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+    limit: Optional[int] = typer.Option(None, "--limit", help='Page size: 50; run logs: 100 (maximum 500)', min=1, max=500),
+    page_token: Optional[str] = typer.Option(None, "--page-token", help='Opaque continuation token; reuse fixed times and filters'),
+    order: Optional[Order] = typer.Option(None, "--order", help='Project queries: desc; run/build logs: asc'),
+    from_time: Optional[str] = typer.Option(None, "--from", help='Inclusive timezone-aware RFC3339 start'),
+    to_time: Optional[str] = typer.Option(None, "--to", help='Timezone-aware RFC3339 end'),
+    since: Optional[str] = typer.Option(None, "--since", help='Positive duration: 30m, 2h, 7d'),
+    severity: Optional[BuildSeverity] = typer.Option(None, "--severity", help='Cloud Logging severity'),
+    search: Optional[str] = typer.Option(None, "--search", help='Cloud Logging quoted text search'),
+):
+    """Read one page of all build log entries, including preamble."""
+    options = locals().copy()
+    async def work():
+        filters = {k: options[k] for k in ("limit", "page_token", "order", "from_time", "to_time", "since", "severity", "search")}
+        params, window = query_options(filters, scoped=True)
+        context = await resolve_context(project, env, user)
+        status = await context.api.build_status(build_id)
+        context.check_item(status, environment=False)
+        return await context.api.build_log_entries(build_id, params), window
+    execute(work, json_mode)
+
+
+def context_command(
+    json_mode: bool = typer.Option(False, "--json", help='Emit the unchanged server JSON'),
+    project: Optional[str] = typer.Option(None, "--project", help='Managed project ID'),
+    env: Optional[str] = typer.Option(None, "--env", help='Environment (default: prod)'),
+    user: Optional[str] = typer.Option(None, "--user", help='Login account; cannot combine with FLOWSTASH_API_KEY'),
+):
+    """Resolve and validate the current managed project and authentication."""
+    async def work():
+        context = await resolve_context(project, env, user, require_managed=False)
+        return context.info, {}
+    execute(work, json_mode)

{flowstash_cli-0.11.0 → flowstash_cli-0.13.0}/src/flowstash/cli/core/api_client.py

@@ -1,4 +1,6 @@
 import httpx
+import os
+from urllib.parse import quote
 from typing import Optional, Dict, Any
 from .config import load_global_config, get_access_token
 
@@ -6,7 +8,7 @@ from .config import load_global_config, get_access_token
 class APIClient:
     def __init__(self, token: Optional[str] = None):
         self.config = load_global_config()
-        self.base_url = self.config.api_url.rstrip("/")
+        self.base_url = os.getenv("FLOWSTASH_API_URL", self.config.api_url).rstrip("/")
         self._token = token  # explicit token takes priority over resolved one
 
     def _get_headers(self) -> Dict[str, str]:
@@ -24,6 +26,25 @@ class APIClient:
             response.raise_for_status()
             return response.json()
 
+    async def diagnostic_query(self, resource: str, params: Dict[str, Any], run_id: Optional[str] = None):
+        path = f"/observability/{resource}"
+        if run_id is not None:
+            suffix = "events" if resource == "run-events" else resource
+            path = f"/observability/runs/{quote(run_id, safe='')}/{suffix}"
+        return await self.get(path, params=params)
+
+    async def diagnostic_run(self, run_id: str, params: Dict[str, Any]):
+        return await self.get(f"/observability/runs/{quote(run_id, safe='')}", params=params)
+
+    async def diagnostic_payload(self, ref: str, params: Dict[str, Any]):
+        return await self.get("/observability/blobs", params={**params, "ref": ref})
+
+    async def build_status(self, build_id: str):
+        return await self.get(f"/v1/builds/{quote(build_id, safe='')}/status")
+
+    async def build_log_entries(self, build_id: str, params: Dict[str, Any]):
+        return await self.get(f"/v1/builds/{quote(build_id, safe='')}/log-entries", params=params)
+
     async def post(
         self, path: str, json: Optional[Dict[str, Any]] = None, timeout: float = 30.0
     ):

{flowstash_cli-0.11.0 → flowstash_cli-0.13.0}/src/flowstash/cli/core/config.py

@@ -107,7 +107,7 @@ def register_user(
     save_global_config(config)
 
 
-def resolve_credentials(user: Optional[str] = None) -> Optional[str]:
+def resolve_credentials(user: Optional[str] = None, project_root: Optional[Path] = None) -> Optional[str]:
     """
     Resolve an access token using the priority chain:
       1. Explicit user (--user flag)
@@ -121,7 +121,8 @@ def resolve_credentials(user: Optional[str] = None) -> Optional[str]:
     if effective_user:
         return get_token_for_user(effective_user)
 
-    project_config = load_project_config()
+    root = project_root if project_root is not None else find_project_root()
+    project_config = load_project_config(root) if root is not None else None
     if project_config and project_config.linked_user:
         token = get_token_for_user(project_config.linked_user)
         if token:
@@ -173,9 +174,20 @@ def delete_access_token(email: Optional[str] = None) -> None:
             pass
 
 
-def load_project_config() -> Optional[ProjectConfig]:
-    path = Path(PROJECT_CONFIG_FILE)
-    if not path.exists():
+def find_project_root(start_path: Optional[Path] = None) -> Optional[Path]:
+    """Find the nearest actual .flowstash file, evaluating cwd at invocation."""
+    start = (start_path if start_path is not None else Path.cwd()).resolve()
+    for parent in (start, *start.parents):
+        if (parent / PROJECT_CONFIG_FILE).is_file():
+            return parent
+    return None
+
+
+def load_project_config(root: Optional[Path] = None, *, strict: bool = False) -> Optional[ProjectConfig]:
+    path = Path(root) if root is not None else Path(PROJECT_CONFIG_FILE)
+    if path.is_dir():
+        path = path / PROJECT_CONFIG_FILE
+    if not path.is_file():
         return None
 
     try:
@@ -183,6 +195,8 @@ def load_project_config() -> Optional[ProjectConfig]:
             data = yaml.safe_load(f) or {}
             return ProjectConfig(**data)
     except Exception:
+        if strict:
+            raise ValueError(f"Malformed project configuration: {path}") from None
         return None
 
 

flowstash_cli-0.13.0/src/flowstash/cli/core/diagnostics.py

@@ -0,0 +1,193 @@
+"""Read-only managed context, fixed query windows, and machine-safe output."""
+import asyncio
+import json
+import os
+import re
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+from urllib.parse import quote
+
+import click
+import httpx
+import typer
+from typer.core import TyperCommand, TyperGroup
+
+from .api_client import APIClient
+from .config import find_project_root, load_project_config, resolve_credentials
+
+
+class DiagnosticError(Exception):
+    def __init__(self, code, message, exit_code=2, http_status=None):
+        self.code, self.message = code, message
+        self.exit_code, self.http_status = exit_code, http_status
+
+
+def fail(error, json_mode):
+    detail = {"code": error.code, "message": error.message}
+    if error.http_status is not None:
+        detail["http_status"] = error.http_status
+    typer.echo(json.dumps({"error": detail}) if json_mode else error.message, err=True)
+    raise typer.Exit(error.exit_code)
+
+
+class MachineParsing:
+    """Keep Click's own parameter/unknown-option errors machine readable too."""
+    def parse_args(self, ctx, args):
+        json_mode = "--json" in args
+        try:
+            return super().parse_args(ctx, args)
+        except click.ClickException as exc:
+            fail(DiagnosticError("INVALID_PARAMETERS", exc.format_message()), json_mode)
+
+
+class DiagnosticCommand(MachineParsing, TyperCommand):
+    pass
+
+
+class DiagnosticGroup(MachineParsing, TyperGroup):
+    def resolve_command(self, ctx, args):
+        try:
+            return super().resolve_command(ctx, args)
+        except click.ClickException as exc:
+            fail(DiagnosticError("INVALID_PARAMETERS", exc.format_message()), "--json" in args)
+
+
+@dataclass
+class ManagedContext:
+    api: APIClient
+    info: dict
+
+    @property
+    def location(self):
+        return {"project_id": self.info["project_id"], "environment": self.info["environment"]}
+
+    def check_item(self, item, *, environment=True):
+        # Single-item backend routes may not accept workspace query filters.
+        if item.get("project_id") != self.info["project_id"] or (
+            environment and item.get("environment") != self.info["environment"]
+        ):
+            raise DiagnosticError("NOT_FOUND", "Item is outside the selected project/environment", 4, 404)
+
+
+async def resolve_context(project=None, env=None, user=None, *, require_managed=True):
+    root = find_project_root()
+    try:
+        local = load_project_config(root, strict=True) if root else None
+    except ValueError as exc:
+        raise DiagnosticError("INVALID_CONTEXT", str(exc)) from None
+    project_id = project or (local.project_id if local else None)
+    if not project_id:
+        raise DiagnosticError("PROJECT_REQUIRED", "Link a .flowstash project or supply --project PROJECT_ID")
+    environment = env or "prod"
+    managed = True
+    if local and local.environments:
+        mode = next((e for e in local.environments if e.name == environment), None)
+        if mode is None:
+            raise DiagnosticError("UNKNOWN_ENVIRONMENT", f"Unknown environment '{environment}'; configured: {', '.join(e.name for e in local.environments)}")
+        managed = mode.managed
+        if require_managed and not managed:
+            raise DiagnosticError("LOCAL_ENVIRONMENT", f"Environment '{environment}' is local; diagnostics require a managed --env")
+    key = os.getenv("FLOWSTASH_API_KEY")
+    if key and user:
+        raise DiagnosticError("AMBIGUOUS_IDENTITY", "Do not combine --user with FLOWSTASH_API_KEY")
+    token = key or resolve_credentials(user=user, project_root=root)
+    if not token:
+        message = f"No token for requested user '{user}'" if user else "Run flowstash login or configure FLOWSTASH_API_KEY"
+        raise DiagnosticError("AUTH_REQUIRED", message, 3, 401)
+    api = APIClient(token=token)
+    identity = await api.get("/v1/auth/me")
+    requested_user = user or (os.getenv("FLOWSTASH_USER") if not key else None)
+    if requested_user and identity.get("email") != requested_user:
+        raise DiagnosticError("IDENTITY_MISMATCH", "Authenticated identity differs from the requested user; log in again for that user", 3, 401)
+    tenant = identity.get("tenant_id")
+    if local and local.tenant_id and local.tenant_id != tenant:
+        raise DiagnosticError("TENANT_MISMATCH", "Local tenant differs from authenticated tenant; supply the correct --user or FLOWSTASH_API_KEY")
+    if identity.get("project_id") and identity["project_id"] != project_id:
+        raise DiagnosticError("PROJECT_RESTRICTION", "API key is restricted to another project; select its --project", 3, 403)
+    if identity.get("environment") and identity["environment"] != environment:
+        raise DiagnosticError("ENVIRONMENT_RESTRICTION", f"API key requires --env {identity['environment']}", 3, 403)
+    remote = await api.get(f"/v1/projects/{quote(project_id, safe='')}")
+    if remote.get("tenant_id") != tenant or remote.get("project_id") != project_id:
+        raise DiagnosticError("TENANT_MISMATCH", "Remote project does not match authenticated tenant/project", 3, 403)
+    return ManagedContext(api, {
+        "project_root": str(root) if root else None,
+        "project_id": project_id, "project_name": remote.get("name"),
+        "tenant_id": tenant, "environment": environment, "managed": managed,
+        "api_url": api.base_url, "auth_method": "api_key" if key else "login",
+        "user_email": identity.get("email"),
+        "project_source": "explicit" if project else "local_config",
+    })
+
+
+def timestamp(value):
+    if value is None:
+        return None
+    if not re.fullmatch(r"\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})", value):
+        raise DiagnosticError("INVALID_TIME", "Timestamps must be timezone-aware RFC3339 values")
+    try:
+        return datetime.fromisoformat(value.upper().replace("Z", "+00:00")).astimezone(timezone.utc)
+    except ValueError:
+        raise DiagnosticError("INVALID_TIME", "Invalid RFC3339 timestamp") from None
+
+
+def time_window(from_time=None, to_time=None, since=None, *, default_window=False, page_token=None):
+    start, end = timestamp(from_time), timestamp(to_time)
+    duration = None
+    if since is not None:
+        if from_time is not None:
+            raise DiagnosticError("INVALID_TIME", "--since cannot be combined with --from")
+        match = re.fullmatch(r"([1-9][0-9]*)([smhd])", since)
+        if not match:
+            raise DiagnosticError("INVALID_TIME", "--since requires a positive integer duration, e.g. 30m, 2h, 7d")
+        try:
+            duration = timedelta(seconds=int(match[1]) * {"s": 1, "m": 60, "h": 3600, "d": 86400}[match[2]])
+        except (OverflowError, ValueError):
+            raise DiagnosticError("INVALID_TIME", "--since duration is too large") from None
+    # Never manufacture different timestamps for a continuation. An opaque cursor
+    # cannot tell us the exact timestamps sent by an earlier CLI process.
+    if page_token and (since or (default_window and (start is None or end is None))):
+        raise DiagnosticError("FIXED_WINDOW_REQUIRED", "For pagination reuse the exact --from and --to from the first page; do not use --since")
+    try:
+        if default_window or duration:
+            end = end or datetime.now(timezone.utc)
+            start = start or end - (duration or timedelta(hours=24))
+    except OverflowError:
+        raise DiagnosticError("INVALID_TIME", "Time range is outside supported dates") from None
+    if start and end and start >= end:
+        raise DiagnosticError("INVALID_TIME", "--from must be before --to")
+    return {key: value.isoformat().replace("+00:00", "Z") for key, value in (("from_time", start), ("to_time", end)) if value is not None}
+
+
+def query_options(options, *, scoped=False, logs=False, default_window=False):
+    options = dict(options)
+    window = time_window(options.pop("from_time", None), options.pop("to_time", None), options.pop("since", None), default_window=default_window, page_token=options.get("page_token"))
+    limit = options.get("limit")
+    options["limit"] = limit if limit is not None else (100 if logs and scoped else 50)
+    options["order"] = options.get("order") or ("asc" if scoped else "desc")
+    return {k: v for k, v in {**options, **window}.items() if v is not None}, window
+
+
+def execute(work, json_mode=False):
+    try:
+        result, window = asyncio.run(work())
+    except DiagnosticError as exc:
+        fail(exc, json_mode)
+    except httpx.HTTPStatusError as exc:
+        status = exc.response.status_code
+        codes = {400: ("INVALID_QUERY", 2), 401: ("AUTH_REQUIRED", 3), 403: ("FORBIDDEN", 3), 404: ("NOT_FOUND", 4), 422: ("INVALID_PARAMETERS", 2)}
+        code, exit_code = codes.get(status, ("PROVIDER_FAILURE", 5))
+        # Do not print request URLs/headers or arbitrary provider response bodies:
+        # they can contain credentials, cursor values, and untrusted content.
+        messages = {400: "Invalid filter or cursor; start a fresh search if filters changed", 401: "Run flowstash login or configure FLOWSTASH_API_KEY", 403: "Access denied; check observability:read scope and project/environment restrictions", 404: "Item missing or inaccessible; recent evidence may still be ingesting", 422: "Invalid request parameters", 502: "Provider or storage unavailable"}
+        fail(DiagnosticError(code, messages.get(status, "Managed API request failed"), exit_code, status), json_mode)
+    except httpx.RequestError:
+        fail(DiagnosticError("NETWORK_FAILURE", "Unable to reach the managed API", 5), json_mode)
+    except Exception:
+        fail(DiagnosticError("CLIENT_FAILURE", "Unable to read diagnostics; check configuration and credential storage", 5), json_mode)
+    if not json_mode:
+        if window:
+            typer.echo("Time range: " + " ".join(f"--{k.replace('_time', '')} {v}" for k, v in window.items()))
+        if isinstance(result, dict) and result.get("next_page_token"):
+            typer.echo(f"Next page: --page-token {result['next_page_token']} (reuse the exact time range and filters)")
+    typer.echo(json.dumps(result, ensure_ascii=False, indent=None if json_mode else 2))

{flowstash_cli-0.11.0 → flowstash_cli-0.13.0}/src/flowstash/cli/main.py

@@ -9,6 +9,8 @@ from .commands import run as run_cmds
 from .commands import webhook as webhook_cmds
 from .commands import apikey as apikey_cmds
 from .commands import client as client_cmds
+from .commands import diagnostics as diagnostic_cmds
+from .core.diagnostics import DiagnosticCommand
 
 from rich.console import Console
 import importlib.metadata
@@ -34,6 +36,10 @@ Run commands below to initialize, build, and deploy your integrations.
     rich_markup_mode="rich",
 )
 
+app.add_typer(diagnostic_cmds.obs_app, name="obs")
+app.add_typer(diagnostic_cmds.builds_app, name="builds")
+app.command("context", cls=DiagnosticCommand)(diagnostic_cmds.context_command)
+
 env_app = typer.Typer(
     name="env",
     help="Manage environments",