keystone-cli 0.1.0__py3-none-any.whl

keystone_cli/commands/dev.py

@@ -0,0 +1,57 @@
+"""``keystone dev`` — the local iterate loop (in-process graph + reload on change).
+
+Thin adapter: resolve the manifest, validate it, then hand off to :func:`keystone_cli.devloop.dev_loop`.
+Deliberately a TOP-LEVEL command, not ``keystone agent dev``: it is the command a dev lives in while
+writing the graph, and burying the inner loop one level down makes the common case the long one.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from keystone.agent_sdk import validate as sdk_validate
+
+from keystone_cli.devloop import dev_loop
+
+
+def dev(
+    path: str = typer.Argument("agent.yaml", help="Path to agent.yaml, or the agent project directory."),
+    input_: str = typer.Option("", "--input", help="JSON input for the first run. Omitted → prompt for it."),
+    offline: bool = typer.Option(
+        False, "--offline", help="Mock rag/gateway calls — iterate with no live services or quota."
+    ),
+) -> None:
+    """Run the agent's graph in-process, reloading it whenever the source changes."""
+    manifest_path = _manifest_path(path)
+    result = sdk_validate(manifest_path)
+    if not result.ok or result.manifest is None:
+        for err in result.errors:
+            typer.secho(f"✗ {err}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    initial = None
+    if input_.strip():
+        try:
+            parsed = json.loads(input_)
+        except json.JSONDecodeError as exc:
+            typer.secho(f"✗ --input is not valid JSON: {exc}", fg=typer.colors.RED)
+            raise typer.Exit(1) from exc
+        if not isinstance(parsed, dict):
+            typer.secho("✗ --input must be a JSON object", fg=typer.colors.RED)
+            raise typer.Exit(1)
+        initial = parsed
+
+    dev_loop(
+        entrypoint=result.manifest.entrypoint,
+        project_dir=Path(manifest_path).resolve().parent,
+        initial_input=initial,
+        offline=offline,
+    )
+
+
+def _manifest_path(path: str) -> str:
+    """Accept either the manifest or its directory — same convention as the `agent` commands."""
+    p = Path(path)
+    return str(p / "agent.yaml") if p.is_dir() else str(p)

keystone_cli/commands/login.py

@@ -0,0 +1,207 @@
+"""``keystone login`` — OAuth2 device flow against Keycloak (FDP-3170).
+
+Thin command: run the device flow (``auth/device_flow``), print the verification URI + user code, poll
+until the dev approves in a browser, then cache the tokens (``auth/token_store``, mode 0600). No secret
+is typed on the CLI; only the refresh token is persisted.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import webbrowser
+
+import httpx
+import typer
+
+from keystone_cli import platform_client as pc
+from keystone_cli.auth import device_flow as df
+from keystone_cli.auth import token_store as ts
+
+
+def login(
+    issuer: str | None = typer.Option(
+        None, "--issuer", envvar="KEYSTONE_ISSUER", help="Keycloak realm URL, e.g. https://<kc>/realms/aip-dev"
+    ),
+    client_id: str | None = typer.Option(
+        None, "--client-id", envvar="KEYSTONE_CLIENT_ID", help="Device-flow client id"
+    ),
+    api_base: str | None = typer.Option(
+        None, "--api-base", envvar="KEYSTONE_API_BASE", help="Platform API base (through Kong) — used by `deploy`"
+    ),
+    no_browser: bool = typer.Option(
+        False, "--no-browser", envvar="KEYSTONE_NO_BROWSER", help="Don't auto-open the browser (SSH / headless)"
+    ),
+    no_select_workspace: bool = typer.Option(
+        False, "--no-select-workspace", help="Skip the post-login default-workspace picker (scripts/CI)."
+    ),
+    client_credentials: bool = typer.Option(
+        False,
+        "--client-credentials",
+        help=(
+            f"Non-interactive service-account login for CI. Reads the secret from ${df.ENV_CLIENT_SECRET} "
+            f"only — there is deliberately no --client-secret flag, because a secret on argv is visible in "
+            f"`ps`, shell history and CI build logs."
+        ),
+    ),
+) -> None:
+    """Log in via the Keycloak device flow and cache the refresh token (~/.keystone/config.json, 0600)."""
+    # Precedence: --flag / KEYSTONE_* env (typer) > cached config > baked platform default → `keystone
+    # login` works flagless once the baked issuer is set (Ops); flags are only for other envs / overrides.
+    cfg = ts.load()
+    cfg.issuer = issuer or cfg.issuer or ts.DEFAULT_ISSUER
+    cfg.client_id = client_id or cfg.client_id or ts.DEFAULT_CLIENT_ID
+    cfg.api_base = api_base or cfg.api_base or ts.DEFAULT_API_BASE
+    if not cfg.issuer or not cfg.client_id:
+        typer.secho(
+            "✗ no issuer configured — pass --issuer (or set KEYSTONE_ISSUER), or bake DEFAULT_ISSUER once Ops "
+            "provisions the Keycloak client",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+
+    # A terminal is what makes the device grant work — a human reads a code and approves in a browser.
+    # Without one, opening a browser is pointless (and on a runner it can hang), so it is suppressed.
+    interactive = sys.stdin.isatty() and sys.stdout.isatty()
+    if not interactive:
+        no_browser = True
+
+    if client_credentials:
+        _login_client_credentials(cfg, interactive=interactive, no_select_workspace=no_select_workspace)
+        return
+
+    if not interactive:
+        typer.secho(
+            "  (no TTY — not opening a browser; the device grant still needs a human to approve the URL below. "
+            f"For unattended runs use --client-credentials or set ${df.ENV_TOKEN}.)",
+            fg=typer.colors.YELLOW,
+        )
+
+    with httpx.Client(timeout=30) as client:
+        try:
+            start = df.start_device_flow(client, cfg.issuer, cfg.client_id)
+        except df.DeviceFlowError as exc:
+            typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+            raise typer.Exit(1) from exc
+
+        # verification_uri_complete has the code pre-embedded (AWS-CLI-style: click → Allow, no typing).
+        verify_uri = start.get("verification_uri_complete") or start.get("verification_uri", "")
+        user_code = start.get("user_code", "")
+        typer.secho("\nTo authorize this CLI, open:", fg=typer.colors.CYAN)
+        typer.echo(f"  {verify_uri}")
+        typer.secho(f"  (code: {user_code})", fg=typer.colors.YELLOW)
+        # Auto-open the browser to the code-embedded URL (best-effort; the URL above is the fallback).
+        # contextlib.suppress, not try/except/pass — headless/no-DISPLAY raises and is fine (bandit B110).
+        if not no_browser:
+            with contextlib.suppress(Exception):
+                webbrowser.open(verify_uri)
+        typer.echo("\nWaiting for approval…")
+
+        try:
+            token = df.poll_for_token(
+                client,
+                cfg.issuer,
+                cfg.client_id,
+                start["device_code"],
+                interval=int(start.get("interval", 5)),
+                expires_in=int(start.get("expires_in", 600)),
+            )
+        except df.DeviceFlowError as exc:
+            typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+            raise typer.Exit(1) from exc
+
+    df.apply_token_response(cfg, token)
+    ts.save(cfg)
+    typer.secho(f"✓ logged in — token cached at {ts.config_path()}", fg=typer.colors.GREEN)
+
+    if not no_select_workspace:
+        # No TTY gate here on purpose: the picker already degrades to "skipped" on EOF, and gating it
+        # would change behaviour for piped-but-answered input, which nobody asked for.
+        _pick_default_workspace(cfg)
+
+
+def _login_client_credentials(cfg: ts.AuthConfig, *, interactive: bool, no_select_workspace: bool) -> None:
+    """Service-account login: mint once, record the mode, done. No browser, no prompt, no refresh token.
+
+    ``auth_mode`` is persisted so the read path knows to re-run this grant when the token expires
+    rather than looking for a refresh token that will never exist.
+    """
+    secret = (os.environ.get(df.ENV_CLIENT_SECRET) or "").strip()
+    if not secret:
+        typer.secho(
+            f"✗ --client-credentials needs ${df.ENV_CLIENT_SECRET} in the environment "
+            f"(there is no --client-secret flag on purpose — argv leaks).",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+
+    with httpx.Client(timeout=30) as client:
+        try:
+            token = df.client_credentials_token(client, cfg.issuer, cfg.client_id, secret)
+        except df.DeviceFlowError as exc:
+            typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+            raise typer.Exit(1) from exc
+
+    cfg.auth_mode = df.MODE_CLIENT_CREDENTIALS
+    # The grant issues no refresh token; clear any stale one from an earlier human login on this
+    # machine. Bandit B105 fires on the empty literal alone — and it parses everything after
+    # `nosec` as test ids, so the reason has to live up here rather than trailing the pragma.
+    cfg.refresh_token = ""  # nosec B105
+    df.apply_token_response(cfg, token)
+    ts.save(cfg)
+    typer.secho(
+        f"✓ logged in as service account '{cfg.client_id}' — config at {ts.config_path()}",
+        fg=typer.colors.GREEN,
+    )
+
+    if not no_select_workspace and interactive:
+        _pick_default_workspace(cfg)
+
+
+def _pick_default_workspace(cfg: ts.AuthConfig) -> None:
+    """Best-effort post-login step: pick a default workspace so `deploy` needs no extra step.
+
+    A user belongs to an entity (from the JWT) but must choose a workspace per deploy. Fetch the
+    access tree (`GET /users/me`), then: 0 → nothing to pick; 1 → auto-select; many → prompt. Never
+    fails the login — a platform hiccup just prints a hint to run `keystone workspace use` later.
+    """
+    base = (cfg.api_base or ts.DEFAULT_API_BASE).rstrip("/")
+    try:
+        me = pc.get_me(cfg.access_token, base)
+    except pc.PlatformError as exc:
+        typer.secho(
+            f"  (couldn't list workspaces: {exc} — set one later with `keystone workspace use`)",
+            fg=typer.colors.YELLOW,
+        )
+        return
+
+    rows = pc.workspace_rows(me)
+    if not rows:
+        typer.echo("  (no workspaces available for your account yet)")
+        return
+    if len(rows) == 1:
+        _save_workspace(cfg, rows[0])
+        return
+
+    typer.echo("\nYour workspaces:")
+    for i, r in enumerate(rows, 1):
+        current = "  (current)" if r.workspace_id == cfg.workspace_id else ""
+        typer.echo(f"  {i}) {r.entity}/{r.workspace}{current}")
+    try:
+        choice = typer.prompt(
+            "Select a default workspace [number, Enter to skip]", default="", show_default=False
+        ).strip()
+    except typer.Abort:  # Ctrl-C / EOF (non-interactive) → treat as skip; login already succeeded.
+        choice = ""
+    if not choice.isdigit() or not (1 <= int(choice) <= len(rows)):
+        typer.echo("  (skipped — set later with `keystone workspace use <name|id>`)")
+        return
+    _save_workspace(cfg, rows[int(choice) - 1])
+
+
+def _save_workspace(cfg: ts.AuthConfig, row: pc.WorkspaceRow) -> None:
+    cfg.workspace_id = row.workspace_id
+    cfg.workspace_name = row.workspace
+    ts.save(cfg)
+    typer.secho(f"✓ default workspace: {row.entity}/{row.workspace}", fg=typer.colors.GREEN)

keystone_cli/commands/workspace.py

@@ -0,0 +1,87 @@
+"""``keystone workspace`` — discover + select the workspace that ``deploy`` targets (FDP-3170).
+
+A user belongs to an entity (from the JWT); the workspace is a per-session choice. `list` shows the
+entity→workspace tree from ``GET /users/me``; `use` saves the chosen workspace UUID into
+``~/.keystone/config.json`` (sent as X-Workspace-ID by `deploy`); `current` shows the selection.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from keystone_cli import platform_client as pc
+from keystone_cli.auth import device_flow as df
+from keystone_cli.auth import token_store as ts
+
+workspace_app = typer.Typer(
+    help="Discover + select the workspace that `agent deploy` targets.",
+    no_args_is_help=True,
+)
+
+
+def _fetch_rows() -> tuple[ts.AuthConfig, list[pc.WorkspaceRow]]:
+    """Load config, get a token (cached/refreshed), and return the caller's workspace rows."""
+    cfg = ts.load()
+    base = (cfg.api_base or ts.DEFAULT_API_BASE).rstrip("/")
+    try:
+        token = df.get_access_token(cfg, save=ts.save)
+    except df.DeviceFlowError as exc:
+        typer.secho(f"✗ {exc} — run `keystone login` first.", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    try:
+        me = pc.get_me(token, base)
+    except pc.PlatformError as exc:
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+        raise typer.Exit(1) from exc
+    return cfg, pc.workspace_rows(me)
+
+
+@workspace_app.command("list")
+def list_workspaces() -> None:
+    """List every workspace your account can reach (entity / workspace / id)."""
+    cfg, rows = _fetch_rows()
+    if not rows:
+        typer.echo("No workspaces available for your account.")
+        return
+    ew = max(len("ENTITY"), *(len(r.entity) for r in rows))
+    ww = max(len("WORKSPACE"), *(len(r.workspace) for r in rows))
+    typer.echo(f"  {'ENTITY':<{ew}}  {'WORKSPACE':<{ww}}  ID")
+    for r in rows:
+        mark = "*" if r.workspace_id and r.workspace_id == cfg.workspace_id else " "
+        typer.echo(f"{mark} {r.entity:<{ew}}  {r.workspace:<{ww}}  {r.workspace_id}")
+
+
+@workspace_app.command()
+def use(ref: str = typer.Argument(..., help="Workspace name or UUID.")) -> None:
+    """Select a workspace by name or UUID — saved for subsequent `agent deploy`."""
+    cfg, rows = _fetch_rows()
+    matches = [r for r in rows if r.workspace_id == ref] or [r for r in rows if r.workspace.lower() == ref.lower()]
+    if not matches:
+        typer.secho(
+            f"✗ no workspace '{ref}' in your access tree — run `keystone workspace list`.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1)
+    if len(matches) > 1:
+        typer.secho(f"✗ '{ref}' matches multiple workspaces — pick by ID:", fg=typer.colors.RED)
+        for r in matches:
+            typer.echo(f"    {r.entity}/{r.workspace}  {r.workspace_id}")
+        raise typer.Exit(1)
+    row = matches[0]
+    cfg.workspace_id = row.workspace_id
+    cfg.workspace_name = row.workspace
+    ts.save(cfg)
+    typer.secho(
+        f"✓ workspace set: {row.entity}/{row.workspace} ({row.workspace_id})",
+        fg=typer.colors.GREEN,
+    )
+
+
+@workspace_app.command()
+def current() -> None:
+    """Show the currently-selected workspace."""
+    cfg = ts.load()
+    if not cfg.workspace_id:
+        typer.echo("No workspace selected. Run `keystone workspace use <name|id>`.")
+        return
+    typer.echo(f"{cfg.workspace_name or '?'} ({cfg.workspace_id})")

keystone_cli/devloop.py

@@ -0,0 +1,183 @@
+"""The `keystone dev` loop: run the agent's graph IN-PROCESS, reloading it when the source changes.
+
+"Deploy local" here means in-process — no container, no Postgres/Redis, no Celery. The graph is
+imported from the project directory exactly the way ``keystone agent run`` imports it, so what you
+iterate on locally is the same object the runtime compiles.
+
+The whole reason this module exists rather than a shell loop around ``keystone agent run``:
+
+* **``sys.modules`` caches the agent's package.** A second ``load_graph`` in the same process
+  re-imports nothing — it hands back the module object built from the code as it was at first
+  import. A dev-loop that ignores this edits ``graph.py``, sees the OLD behaviour, and gets no
+  warning at all; the natural conclusion is "my change did nothing", which is the worst possible
+  feedback from a tool whose entire job is feedback. :func:`_purge_project_modules` is the fix, and
+  it is scoped by ``__file__`` living under the project root so third-party packages (langgraph,
+  httpx) are NOT reloaded — reloading those would be slow and, worse, would give the graph a second
+  copy of classes it compares against with ``isinstance``.
+* **Reload has to be cheap enough to be automatic.** Change detection is an mtime+size scan of the
+  project's ``*.py``, checked right before each run, so no thread and no watchdog dependency. The
+  cost is that a change made *while* a run is in flight is picked up on the next one, which is the
+  right trade for a REPL.
+
+One input per Enter; empty input re-uses the previous one, so the edit → Enter → read-trace loop
+needs no retyping. Errors never end the session: a graph that fails to import or raises mid-run
+prints and returns you to the prompt, because the next thing you do is fix it and press Enter.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import typer
+from keystone.agent_sdk.loader import GraphLoadError
+
+from keystone_cli.runner import run_agent
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# Watched for changes. `agent.yaml` is included because the entrypoint can move — but note the
+# manifest is re-read only to detect the change; a manifest edit reloads the graph, it does not
+# re-validate the whole file (run `keystone agent validate` for that).
+_WATCH_GLOBS = ("*.py", "agent.yaml")
+
+
+@dataclass
+class _Fingerprint:
+    """Cheap change signal: (path, mtime_ns, size) for every watched file."""
+
+    entries: frozenset[tuple[str, int, int]]
+
+    @classmethod
+    def of(cls, project_dir: Path) -> _Fingerprint:
+        out: set[tuple[str, int, int]] = set()
+        for pattern in _WATCH_GLOBS:
+            for path in project_dir.rglob(pattern):
+                # A venv inside the project would swamp the scan and never be the thing you edited.
+                if not path.is_file() or _is_noise(path.relative_to(project_dir)):
+                    continue
+                try:
+                    st = path.stat()
+                except OSError:  # deleted between glob and stat — treat as a change
+                    continue
+                out.add((str(path), st.st_mtime_ns, st.st_size))
+        return cls(entries=frozenset(out))
+
+
+_NOISE_DIRS = frozenset({".venv", "venv", "env", "__pycache__", ".git", "build", "dist", ".keystone"})
+
+
+def _is_noise(rel: Path) -> bool:
+    return bool(set(rel.parts) & _NOISE_DIRS)
+
+
+def _purge_project_modules(project_dir: Path) -> list[str]:
+    """Drop every already-imported module whose file lives under ``project_dir``.
+
+    Returns the purged names (for the "reloaded" line). Scoped by ``__file__`` rather than by name
+    prefix on purpose: the agent's package name is not knowable from the entrypoint alone once it
+    imports siblings, and a name-prefix rule would either miss those or over-match a third-party
+    package that happens to share the prefix.
+    """
+    root = str(project_dir.resolve())
+    purged = [
+        name
+        for name, module in list(sys.modules.items())
+        if (file := getattr(module, "__file__", None)) and str(Path(file).resolve()).startswith(root + "/")
+    ]
+    for name in purged:
+        del sys.modules[name]
+    return purged
+
+
+def _parse_input(raw: str) -> dict[str, Any]:
+    value = json.loads(raw)
+    if not isinstance(value, dict):
+        raise ValueError(f"input must be a JSON object, got {type(value).__name__}")
+    return value
+
+
+def dev_loop(
+    *,
+    entrypoint: str,
+    project_dir: Path,
+    initial_input: dict[str, Any] | None,
+    offline: bool,
+    read_line: Callable[[], str] | None = None,
+) -> None:
+    """Run the interactive loop until EOF/quit. ``read_line`` is injected so tests can drive it."""
+    prompt = read_line or (lambda: typer.prompt("input", default="", show_default=False))
+
+    def _next_line() -> str | None:
+        """The dev's next line, or ``None`` when the session is over.
+
+        Ctrl-D / a closed stdin is the DOCUMENTED way to quit, so it must exit 0 and print nothing.
+        ``typer.prompt`` raises ``typer.Abort`` there — not ``EOFError`` — and letting that escape
+        makes typer print "Aborted." and exit **1**, i.e. quitting as instructed looks like a
+        failure and would fail any script or CI step wrapping the command. Caught via ``typer.Abort``
+        and NOT ``click.Abort``: typer 0.27 vendors click as ``typer._click``, so ``import click``
+        raises ModuleNotFoundError here — and click is not a declared dependency of this package
+        either, so importing it directly would be relying on someone else's transitive dep.
+        """
+        try:
+            raw = prompt()
+        except (EOFError, KeyboardInterrupt, typer.Abort):
+            typer.echo("")
+            return None
+        return None if raw.strip() in {"quit", "exit"} else raw
+
+    fingerprint = _Fingerprint.of(project_dir)
+    last_input: dict[str, Any] | None = initial_input
+
+    typer.secho(
+        f"keystone dev — {entrypoint} (in-process{', offline' if offline else ''}). "
+        "Enter JSON input, blank to repeat the last one, Ctrl-D to quit.",
+        fg=typer.colors.GREEN,
+    )
+
+    while True:
+        current = _Fingerprint.of(project_dir)
+        if current != fingerprint:
+            purged = _purge_project_modules(project_dir)
+            fingerprint = current
+            typer.secho(f"↻ source changed — reloaded {len(purged)} module(s)", fg=typer.colors.MAGENTA)
+
+        if last_input is None:
+            raw = _next_line()
+            if raw is None:
+                return
+            if not raw.strip():
+                typer.secho("• nothing to run yet — paste a JSON object", fg=typer.colors.YELLOW)
+                continue
+            try:
+                last_input = _parse_input(raw)
+            except (ValueError, json.JSONDecodeError) as exc:
+                typer.secho(f"✗ bad input: {exc}", fg=typer.colors.RED)
+                continue
+
+        _run_once(entrypoint=entrypoint, project_dir=project_dir, inputs=last_input, offline=offline)
+
+        raw = _next_line()
+        if raw is None:
+            return
+        if raw.strip():
+            try:
+                last_input = _parse_input(raw)
+            except (ValueError, json.JSONDecodeError) as exc:
+                typer.secho(f"✗ bad input: {exc}", fg=typer.colors.RED)
+
+
+def _run_once(*, entrypoint: str, project_dir: Path, inputs: dict[str, Any], offline: bool) -> None:
+    """One run. Never raises — a broken graph must return you to the prompt, not end the session."""
+    try:
+        state = run_agent(entrypoint=entrypoint, project_dir=project_dir, inputs=inputs, offline=offline)
+    except GraphLoadError as exc:
+        typer.secho(f"✗ {exc}", fg=typer.colors.RED)
+    except Exception as exc:  # noqa: BLE001 — the agent's own code raised; show it and keep going
+        typer.secho(f"✗ run failed: {type(exc).__name__}: {exc}", fg=typer.colors.RED)
+    else:
+        typer.secho(f"✓ result: {state}", fg=typer.colors.GREEN)

keystone_cli/platform_client.py

@@ -0,0 +1,75 @@
+"""Thin platform API client for the CLI (FDP-3170).
+
+Currently just ``GET /api/platform/v1/users/me`` — the caller's entity→workspace access tree,
+used to discover + select the workspace that ``deploy`` targets. ``/users/me`` is on platform's
+tenancy bypass list and is keyed on the JWT subject, so it needs only the login bearer token (the
+edge injects X-User-ID / X-Entity-ID); no X-Workspace-ID (that's the thing we're trying to find).
+
+FDP-3482 — platform retired the Stage tier: ``/users/me`` now returns workspaces directly under
+each entity (``entities[].workspaces[]``), a two-level tree. We still read the legacy three-level
+shape (``entities[].stages[].workspaces[]``) as a fallback so the CLI keeps working against any
+env that hasn't deployed FDP-3482 yet (dev leads qc/staging).
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+import httpx
+
+ME_PATH = "/api/platform/v1/users/me"
+
+
+class PlatformError(Exception):
+    """Platform call failed (transport error or non-200)."""
+
+
+class WorkspaceRow(NamedTuple):
+    """One leaf of the /users/me access tree. ``entity``/``workspace`` are display names.
+
+    FDP-2071: the Stage tier is retired fleet-wide — rows no longer carry stage fields."""
+
+    entity: str
+    workspace: str
+    workspace_id: str
+
+
+def get_me(token: str, api_base: str, *, client: httpx.Client | None = None) -> dict:
+    """Return the ``data`` of ``GET /users/me`` — ``{user, entities:[{..,workspaces:[]}]}`` post-FDP-3482
+    (legacy envs may still nest ``workspaces`` under a ``stages`` level; ``workspace_rows`` reads both).
+
+    ``client`` is injectable for tests; otherwise a short-lived client is used.
+    """
+    url = f"{api_base.rstrip('/')}{ME_PATH}"
+    headers = {"Authorization": f"Bearer {token}", "Accept": "application/json"}
+    try:
+        if client is not None:
+            resp = client.get(url, headers=headers)
+        else:
+            with httpx.Client(timeout=30) as owned:
+                resp = owned.get(url, headers=headers)
+    except httpx.RequestError as exc:
+        raise PlatformError(f"could not reach platform at {api_base} ({exc})") from exc
+
+    if resp.status_code != 200:
+        raise PlatformError(f"platform {ME_PATH} returned {resp.status_code}: {resp.text[:200]}")
+    body = resp.json() if resp.content else {}
+    return body.get("data", {})
+
+
+def workspace_rows(me: dict) -> list[WorkspaceRow]:
+    """Flatten the ``/me`` tree to ``WorkspaceRow(entity, workspace, workspace_id)``.
+
+    FDP-2071 removed the Stage tier fleet-wide; the tree is two-level (``entity.workspaces``).
+    The legacy three-level nesting (``entity.stages[].workspaces``) is still READ so the CLI keeps
+    listing workspaces against any straggler environment — the stage values themselves are gone."""
+    rows: list[WorkspaceRow] = []
+    for entity in me.get("entities", []) or []:
+        ename = entity.get("name", "")
+        for ws in entity.get("workspaces", []) or []:
+            rows.append(WorkspaceRow(ename, ws.get("name", ""), ws.get("id", "")))
+        # Legacy nesting: read the workspaces, discard the retired stage tier.
+        for stage in entity.get("stages", []) or []:
+            for ws in stage.get("workspaces", []) or []:
+                rows.append(WorkspaceRow(ename, ws.get("name", ""), ws.get("id", "")))
+    return rows