sidepage 0.1.0__py3-none-any.whl

sidepage/__init__.py

@@ -0,0 +1,9 @@
+"""sidepage — local-first hosting, tunneling, and directory CLI for small apps and MCP servers.
+
+See README.md for the full command reference and docs/OPEN_QUESTIONS.md for
+decisions the spec left open. This package is currently CLI scaffolding only:
+command wiring, help text, and options are real; the underlying behavior
+lives in `sidepage.core` as commented placeholders until the SDK is built.
+"""
+
+__version__ = "0.1.0"

sidepage/cli.py

@@ -0,0 +1,143 @@
+"""Root Typer app — assembles every `sidepage.commands` module into the
+`sidepage` command tree described in the spec (v3). This module owns wiring
+only; see each `sidepage.commands.*` module for the spec section it
+implements.
+
+Command tree:
+  sidepage setup                                           (not in spec — see note below)
+  sidepage new <name>                                     §1
+  sidepage serve <target>                                  §2
+  sidepage stop <app-name>                                 §2
+  sidepage promote <app-name>                              §5
+  sidepage login                                           §13
+  sidepage account status                                  §13
+  sidepage account domain set <domain>                     §13 (v4: + --api-token-name)
+  sidepage usage <app-name>                                §7
+  sidepage secrets set|list|remove                         v4 §9
+  sidepage inspect [<app-name-or-url>]                     §10
+  sidepage ls                                              (no v3 section — see note below)
+  sidepage status <app-name>                               (no v3 section — see note below)
+  sidepage app register|list|show|unregister               (registry spec v2, no v3 section)
+  sidepage serve <app-name>                                (registry spec v2 — serve's <target>
+                                                             also accepts a registered app name)
+
+Note: `sidepage setup` isn't a v1/v3/v4 spec command at all — it's a
+`pip install sidepage` packaging concern (installing the `cloudflared`
+binary tunnel functionality needs without making it a Python dependency
+or vendoring it into the wheel). See `sidepage.core.cloudflared_installer`
+and `sidepage.commands.setup`.
+
+Note: v3 has no "Directory queries" section (v1's §10) — it doesn't
+mention `ls`/`status` at all, jumping from §9 (local reverse proxy) to §10
+(inspection) to §11 (static). Kept here on the same reasoning as
+guardrails: the directory model itself is still very much alive in v3
+(§3, §5), so this reads as "not re-stated" rather than "cut" — but flagged
+since it wasn't a locked-in decision the way the identity/keys/tunnel drops
+were.
+
+Dropped from v1's tree, not carried forward: `whoami` / `name check`
+(folded into `account status`, see sidepage.core.account), `keys
+create|revoke|list` (replaced by per-serve `--token`, see
+sidepage.core.token_runtime), `tunnel login|token set|status|revoke`
+(replaced by `login` / `account domain set`, tunnel mechanics moved into
+sidepage.core.tunnel_manager without a dedicated command group).
+
+(§8, token handling, has no standalone command — it's `serve --token` /
+`SIDEPAGE_TOKEN`. Guardrails, still parked though absent from v3, remain
+`serve --guardrail`; see sidepage.commands.serve and sidepage.core.guardrail.)
+
+v4 adds `sidepage secrets set|list|remove` — the secrets vault, cited by
+the user's own summary as "v4 §9." v3 §9 was "local reverse proxy"; the
+migration to v4 was done from a 4-point delta summary, not the full v4
+document, so whether v4 actually renumbered the reverse proxy section is
+unconfirmed — see `docs/OPEN_QUESTIONS.md` for the flagged collision.
+`sidepage.core.secrets_vault` is genuinely new, not a replacement for
+`sidepage.core.reverse_proxy`, regardless of how the numbering shakes out.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from sidepage import __version__
+from sidepage.commands import (
+    account,
+    app_registry,
+    directory,
+    inspect,
+    new,
+    scope,
+    secrets,
+    serve,
+    setup,
+    usage,
+)
+
+app = typer.Typer(
+    name="sidepage",
+    help=(
+        "Local-first hosting, tunneling, and directory for small apps and MCP servers.\n\n"
+        "Scaffold with `sidepage new`, serve it with `sidepage serve`, and share it — "
+        "ephemeral by default, torn down when you Ctrl+C."
+    ),
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"sidepage {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show the sidepage CLI version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """sidepage — local-first hosting, tunneling, and directory."""
+
+
+# Not a numbered spec section — `pip install sidepage` packaging concern,
+# not a v1/v3/v4 feature. Installs `cloudflared` (see
+# sidepage.core.cloudflared_installer) without making it a Python
+# dependency or vendoring it into the wheel.
+app.command("setup")(setup.setup)
+
+# §1 — targets / scaffolding
+app.command("new")(new.new)
+
+# §2 — serving
+app.command("serve")(serve.serve)
+app.command("stop")(serve.stop)
+
+# §5 — discovery & scope
+app.command("promote")(scope.promote)
+
+# §7 — metering
+app.command("usage")(usage.usage)
+
+# v4 §9 — secrets vault
+app.add_typer(secrets.secrets_app)
+
+# §10 — inspection & directory queries
+app.command("inspect")(inspect.inspect)
+app.command("ls")(directory.ls)
+app.command("status")(directory.status)
+
+# §13 — account & login
+app.command("login")(account.login)
+app.add_typer(account.account_app)
+
+# Local app registry (registry spec v2) — sidepage app register|list|show|unregister
+app.add_typer(app_registry.app_app)
+
+
+if __name__ == "__main__":
+    app()

sidepage/commands/__init__.py

@@ -0,0 +1,7 @@
+"""CLI command modules — argument parsing and help text only.
+
+Each module here maps 1:1 to a section of the spec and owns the Typer
+wiring for it. None of them implement real behavior; they validate/parse
+input, then call into `sidepage.core` (unimplemented) or print a
+`sidepage.output.not_implemented` notice naming the future implementation.
+"""

sidepage/commands/account.py

@@ -0,0 +1,98 @@
+"""`sidepage login` / `sidepage account status` / `sidepage account domain
+set` — spec v3 §13, account & login.
+
+Deliberately separate from per-app `--auth` (`sidepage serve --auth`) —
+signing in to Sidepage and gating one app's visitors are different
+concerns, and sharing a name would collide confusingly.
+
+`account status` absorbs v1's `sidepage whoami` — see
+`sidepage.core.account` for why that command was folded in rather than kept
+standalone. Still unimplemented: there's no Sidepage account backend to
+authenticate against.
+
+`domain set` is real. v4 delta: a **single** required flag,
+`--api-token-name` — a vault secret name (v4 §9,
+`sidepage.core.secrets_vault`), not a raw credential value. The earlier
+two-token design (`--zone-token-name` / `--tunnel-token-name`, requiring a
+tunnel already created out-of-band) is gone — this command now creates the
+tunnel itself via `sidepage.core.account.configure_domain`, and stores its
+run-token in the vault automatically. That storage always happens, but is
+never silent: success logs the internal vault name it landed under, and
+failure names it too (see `configure_domain`'s
+`TunnelProvisioningError` — the run-token is a one-time Cloudflare API
+response, so a failure to persist it leaves an orphaned tunnel behind that
+the user needs to know the ID of).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from sidepage.core import account as account_core
+from sidepage.core.exceptions import SecretNotFoundError, TunnelProvisioningError
+from sidepage.output import error, info, not_implemented, success
+
+account_app = typer.Typer(
+    name="account",
+    help="Account status and BYO-domain configuration.",
+    no_args_is_help=True,
+)
+
+domain_app = typer.Typer(
+    name="domain",
+    help="Manage the persistent default BYO domain (premium).",
+    no_args_is_help=True,
+)
+account_app.add_typer(domain_app)
+
+
+def login() -> None:
+    """Interactive login flow."""
+    not_implemented("sidepage login", implemented_by="sidepage.core.account.login")
+
+
+@account_app.command("status")
+def status() -> None:
+    """Show the identity/session/plan currently active on this machine."""
+    not_implemented(
+        "sidepage account status", implemented_by="sidepage.core.account.current_account"
+    )
+
+
+@domain_app.command("set")
+def domain_set(
+    domain: Annotated[str, typer.Argument(help="Zone apex to use as the persistent default.")],
+    api_token_name: Annotated[
+        str,
+        typer.Option(
+            "--api-token-name",
+            help="Vault secret name (see `sidepage secrets set`) holding a Cloudflare API "
+            "token scoped to Account -> Cloudflare Tunnel:Edit, Zone -> DNS:Edit, "
+            "Zone -> Zone:Read.",
+        ),
+    ],
+) -> None:
+    """Provision (or reuse) the persistent default BYO domain (premium):
+    creates one Cloudflare Tunnel meant to serve every app later run under
+    `domain` via `serve --domain`, and stores that tunnel's run-token in
+    the vault automatically — never typed by the user, but always
+    reported below by its vault name. `domain` should be the zone apex
+    (e.g. `example.com`), not a pre-built subdomain — served apps get
+    `<app-name>-<id>.<domain>`. Re-running for an already-configured
+    domain is a no-op, not a re-provision."""
+    try:
+        config = account_core.configure_domain(domain, api_token_name=api_token_name)
+    except SecretNotFoundError as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+    except TunnelProvisioningError as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+
+    success(f"default BYO domain set: {domain} (tunnel {config.tunnel_id})")
+    info(
+        f"tunnel run-token stored in vault as {config.tunnel_token_name!r} "
+        "(see `sidepage secrets list`)"
+    )

sidepage/commands/app_registry.py

@@ -0,0 +1,344 @@
+"""`sidepage app register|list|show|unregister` plus `sidepage serve
+<app-name>` — registry spec v2 (`sidepage-registry-spec.md`).
+
+**The parser-reuse mechanism, and why it's implemented here rather than
+in `sidepage.core.app_registry`:** the spec's core design goal is that a
+new `serve` flag automatically becomes registerable with zero changes on
+this side — achieved by parsing a registration invocation string with
+`serve`'s own real Click command object (`serve_cmd.make_context(...)`),
+not a hand-maintained second parser. That needs a runtime import of
+`sidepage.cli` (to fetch the fully-assembled Click command tree) — which
+would be circular at module-load time, since `cli.py` imports this module
+to wire up `sidepage app ...` in the first place. Deferred (function-body,
+not module-top) imports below exist specifically to break that cycle;
+`sidepage.core.app_registry` itself stays free of any `typer`/`click`
+import, consistent with every other `core` module never importing from
+`commands` or `cli`.
+
+**A wrinkle worth recording:** this installed Typer version (0.27.1) fully
+vendors its own fork of Click (`typer._click`) rather than depending on
+the real `click` package for its command/context machinery — confirmed by
+observing that errors raised from `Command.make_context(...)` here are
+`typer._click.exceptions.*` instances, not `click.exceptions.*` (the two
+are unrelated classes, even though a real `click` distribution is also
+separately installed and importable). That's why parsing failures below
+are caught as a broad `Exception` rather than the specific/expected
+`click.ClickException` a normal Click integration would use — there's no
+public Typer symbol for that private base class to catch instead, and
+reaching into the private `typer._click` module by name would be more
+fragile than a broad catch scoped tightly around one parse call.
+
+**`sidepage serve <app-name>` merge semantics** (`merge_with_registered`
+below) are the same for a real invocation and for `sidepage app show
+--with`'s preview — both ultimately answer "for each mergeable field, did
+*this* invocation pass it explicitly (`ctx.get_parameter_source(...) is
+COMMANDLINE`), or should the registered value apply?" `sidepage.commands.serve`
+calls this directly with its own already-Typer-typed parameters; `show
+--with` calls it with values coerced from a `make_context()`-parsed
+string, since raw `ctx.params` values are always plain strings/primitives
+regardless of the declared parameter type (confirmed live — Typer's
+type-conversion happens when it calls the real command function, not
+when populating `ctx.params`) — see `_coerce_raw_params`.
+"""
+
+from __future__ import annotations
+
+import shlex
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from sidepage.core import app_registry
+from sidepage.core.app_registry import AppRegistration
+from sidepage.core.auth import AuthTier
+from sidepage.core.directory_client import Scope
+from sidepage.core.exceptions import (
+    AppNotRegisteredError,
+    AppRegistrationError,
+    TargetDetectionError,
+)
+from sidepage.core.target import TargetKind, detect_target_kind
+from sidepage.output import error, info, stdout, success
+
+app_app = typer.Typer(
+    name="app",
+    help="Save a `serve` invocation under a short name and re-run it later.",
+    no_args_is_help=True,
+)
+
+
+def _serve_click_command():
+    """The real, live `serve` Click command object — fetched at call time,
+    not import time, to avoid the `cli.py` <-> this module import cycle
+    described in this module's docstring."""
+    import typer as typer_module
+
+    from sidepage.cli import app as cli_app
+
+    click_group = typer_module.main.get_command(cli_app)
+    return click_group.commands["serve"]
+
+
+def _make_serve_context(invocation: str, *, placeholder_target: bool = False):
+    """Parse `invocation` (shell-quoted `serve` flags, e.g. `"abc.py
+    --auth token"`) using `serve`'s own Click command — the single source
+    of truth this whole module exists to reuse rather than duplicate. Set
+    `placeholder_target=True` for a preview string that omits the target
+    entirely (`sidepage app show --with`, where the target is implied by
+    the already-registered app, not part of what's being previewed) —
+    `serve`'s positional `target` argument is required, so a harmless
+    placeholder is prepended and never read back out.
+    """
+    args = shlex.split(invocation)
+    if placeholder_target:
+        args = ["__sidepage_placeholder_target__", *args]
+    try:
+        return _serve_click_command().make_context("serve", args)
+    except Exception as exc:
+        raise AppRegistrationError(f"could not parse {invocation!r} as serve flags: {exc}") from exc
+
+
+def _coerce_raw_params(raw: dict) -> dict:
+    """`ctx.params` from `make_context()` holds plain strings/primitives
+    regardless of the real parameter type (confirmed live, not assumed —
+    see module docstring) — this turns them into the same typed values a
+    real `serve` invocation's function parameters would already have."""
+    from sidepage.commands.serve import ServeTargetType
+
+    return {
+        "target": Path(raw["target"]),
+        "target_type": ServeTargetType(raw["target_type"]),
+        "name": raw["name"],
+        "domain": raw["domain"],
+        "auth": AuthTier(raw["auth"]),
+        "scope": Scope(raw["scope"]),
+        "anon": raw["anon"],
+        "token": raw["token"],
+        "env": list(raw["env"] or ()),
+        "guardrail": Path(raw["guardrail"]) if raw["guardrail"] else None,
+    }
+
+
+def _is_explicit(ctx, field: str) -> bool:
+    source = ctx.get_parameter_source(field)
+    return source is not None and source.name == "COMMANDLINE"
+
+
+def merge_with_registered(
+    ctx,
+    registered: AppRegistration,
+    *,
+    target_type,
+    name: str | None,
+    domain: str | None,
+    auth: AuthTier,
+    scope: Scope,
+    anon: bool,
+    env: list[str],
+    guardrail: Path | None,
+) -> dict[str, Any]:
+    """For each mergeable field, an explicit command-line value (source
+    `COMMANDLINE` on `ctx`, per `ctx.get_parameter_source`) overrides the
+    registered one; otherwise the registered value applies — the spec's
+    resolved merge semantics (override-wins, base config never mutated by
+    a one-off override). `target`/`token` are deliberately excluded:
+    `target` is implied by which registered app you're serving, not a
+    mergeable flag, and `token` is never stored at all (process-scoped,
+    always whatever this invocation supplies, registered or not).
+
+    `env`'s merge is **replace, not append**: an explicit `--env` on this
+    invocation replaces the registered env list entirely rather than
+    accumulating with it — the spec's example only exercises a scalar
+    override (`--scope`), so this is a judgment call, made for consistency
+    with every other field's replace semantics rather than inventing a
+    different rule for the one list-valued flag.
+
+    Returns a dict shaped as `ServeConfig`'s own keyword arguments
+    (`target_kind`, `name`, `domain`, `auth`, `scope`, `anon`,
+    `env_secrets`, `guardrail`) — ready to splice into
+    `ServeConfig(target=..., token=..., **merged)`.
+    """
+    from sidepage.commands.serve import ServeTargetType
+
+    if _is_explicit(ctx, "target_type"):
+        target_kind = None if target_type is ServeTargetType.AUTO else TargetKind(target_type.value)
+    else:
+        target_kind = registered.target_kind
+
+    def use(field: str, live_value, registered_value):
+        return live_value if _is_explicit(ctx, field) else registered_value
+
+    return {
+        "target_kind": target_kind,
+        "name": use("name", name, registered.name),
+        "domain": use("domain", domain, registered.domain),
+        "auth": use("auth", auth, registered.auth),
+        "scope": use("scope", scope, registered.scope),
+        "anon": use("anon", anon, registered.anon),
+        "env_secrets": tuple(env) if _is_explicit(ctx, "env") else registered.env_secrets,
+        "guardrail": use("guardrail", guardrail, registered.guardrail),
+    }
+
+
+def _or_none(value: object, label: str = "(none)") -> str:
+    return str(value) if value is not None else f"[dim]{label}[/dim]"
+
+
+def _print_registration(app_name: str, r: AppRegistration) -> None:
+    stdout.print(f"[bold]{app_name}[/bold]")
+    stdout.print(f"  target:         {r.target}")
+    stdout.print(f"  type:           {r.target_kind.value}")
+    stdout.print(f"  name:           {_or_none(r.name, '(defaults to app-name)')}")
+    stdout.print(f"  domain:         {_or_none(r.domain)}")
+    stdout.print(f"  auth:           {r.auth.value}")
+    stdout.print(f"  scope:          {r.scope.value}")
+    stdout.print(f"  anon:           {r.anon}")
+    stdout.print(f"  env:            {', '.join(r.env_secrets) or '[dim](none)[/dim]'}")
+    stdout.print(f"  guardrail:      {_or_none(r.guardrail)}")
+    stdout.print(f"  registered_at:  {r.registered_at}")
+
+
+@app_app.command("register")
+def register(
+    invocation: Annotated[
+        str,
+        typer.Argument(
+            help="The target plus any serve flags, as one shell-quoted string, "
+            'e.g. "abc.py --auth token".'
+        ),
+    ],
+    app_name: Annotated[str, typer.Argument(help="Short name to register this invocation under.")],
+) -> None:
+    """Save a `serve` invocation under `app_name` for later `sidepage
+    serve <app-name>`. Parsed with `serve`'s own flags — a `--type` isn't
+    stored as given, it's resolved (auto-detection runs now, at
+    registration time, not deferred to every future `serve` call).
+
+    Rejects a literal `--token <value>` outright: auth tokens are
+    process-scoped and regenerate on each `serve` call, so persisting one
+    here would quietly reintroduce a plaintext, indefinitely-stored secret
+    — the exact separation the vault (`sidepage secrets`) and the runtime
+    token file already establish. `--env <NAME>` is fine to store: it's a
+    vault reference, not a value.
+    """
+    ctx = _make_serve_context(invocation)
+    raw = ctx.params
+
+    if raw["token"] is not None:
+        error(
+            "cannot register an app with a literal --token value.\n"
+            "Auth tokens are process-scoped and regenerate on each serve — omit --token "
+            "and one will be issued fresh each time this app is served."
+        )
+        raise typer.Exit(1)
+
+    values = _coerce_raw_params(raw)
+
+    try:
+        target_kind = detect_target_kind(
+            values["target"],
+            override=None
+            if values["target_type"].value == "auto"
+            else TargetKind(values["target_type"].value),
+        )
+        registration = app_registry.register(
+            app_name,
+            target=values["target"].resolve(),
+            target_kind=target_kind,
+            name=values["name"],
+            domain=values["domain"],
+            auth=values["auth"],
+            scope=values["scope"],
+            anon=values["anon"],
+            env_secrets=tuple(values["env"]),
+            guardrail=values["guardrail"],
+        )
+    except (AppRegistrationError, TargetDetectionError) as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+
+    success(f"registered {app_name!r} -> {registration.target} ({registration.target_kind.value})")
+
+
+@app_app.command("list")
+def list_() -> None:
+    """List registered app names."""
+    names = app_registry.list_registered()
+    if not names:
+        stdout.print("[dim]no apps registered[/dim]")
+        return
+    for name in names:
+        stdout.print(name)
+
+
+@app_app.command("show")
+def show(
+    app_name: Annotated[str, typer.Argument(help="Registered app name.")],
+    with_: Annotated[
+        str | None,
+        typer.Option(
+            "--with",
+            help="Preview the effective config if these serve flags were also passed, "
+            'e.g. --with "--scope web" — the same merge `serve <app-name>` would do, '
+            "without actually running it.",
+        ),
+    ] = None,
+) -> None:
+    """Show a registered app's saved config — or, with `--with`, the
+    effective merged config it would run with if those extra flags were
+    passed to `sidepage serve <app-name>` too. Inspectable before it
+    runs, so a one-off override is never a surprise."""
+    registered = app_registry.get(app_name)
+    if registered is None:
+        error(f"no app named {app_name!r} is registered")
+        raise typer.Exit(1)
+
+    if with_ is None:
+        _print_registration(app_name, registered)
+        return
+
+    ctx = _make_serve_context(with_, placeholder_target=True)
+    values = _coerce_raw_params(ctx.params)
+    merged = merge_with_registered(
+        ctx,
+        registered,
+        target_type=values["target_type"],
+        name=values["name"],
+        domain=values["domain"],
+        auth=values["auth"],
+        scope=values["scope"],
+        anon=values["anon"],
+        env=values["env"],
+        guardrail=values["guardrail"],
+    )
+    if merged["name"] is None:
+        merged["name"] = app_name
+
+    info(f"effective config for {app_name!r} with --with {with_!r}:")
+    preview = AppRegistration(
+        target=registered.target,
+        target_kind=merged["target_kind"],
+        name=merged["name"],
+        domain=merged["domain"],
+        auth=merged["auth"],
+        scope=merged["scope"],
+        anon=merged["anon"],
+        env_secrets=merged["env_secrets"],
+        guardrail=merged["guardrail"],
+        registered_at=registered.registered_at,
+    )
+    _print_registration(app_name, preview)
+
+
+@app_app.command("unregister")
+def unregister(
+    app_name: Annotated[str, typer.Argument(help="Registered app name to remove.")],
+) -> None:
+    """Delete a registered app's saved config."""
+    try:
+        app_registry.unregister(app_name)
+    except AppNotRegisteredError as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+    success(f"unregistered {app_name!r}")

sidepage/commands/directory.py

@@ -0,0 +1,73 @@
+"""`sidepage ls` / `sidepage status` — directory queries.
+
+Not a numbered section in the v3 spec (v1 had a "Directory queries" §10;
+v3 goes straight from §9 local reverse proxy to §10 inspection with no
+`ls`/`status` mention). Kept as-is since the directory model itself is
+still central to v3 (§3, §5) — treated as not re-stated, not cut.
+
+Real, but against `sidepage.core.registry` (this machine's running apps),
+not a cloud directory — there isn't one to talk to (see
+`sidepage.core.directory_client`, still unimplemented). `--scope`/`--mine`
+have no real meaning against a single-machine registry; `ls` notes that
+rather than pretending to filter. `status` does a live reachability check
+against the registered local URL — the "reconciliation" the spec describes,
+just against this machine's own record instead of a cloud directory's.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import httpx
+import typer
+
+from sidepage.core import registry
+from sidepage.core.directory_client import Scope
+from sidepage.output import error, info, stdout
+
+
+def ls(
+    scope: Annotated[
+        Scope | None, typer.Option("--scope", help="Filter to one scope.")
+    ] = None,
+    mine: Annotated[
+        bool, typer.Option("--mine", help="Limit to the current identity's own apps.")
+    ] = False,
+) -> None:
+    """List apps running on this machine."""
+    if scope is not None:
+        info("--scope filtering isn't implemented — no cloud directory to filter against yet")
+    apps = registry.list_running()
+    if not apps:
+        stdout.print("[dim]no apps running[/dim]")
+        return
+    for app in apps:
+        line = f"{app.name}  [dim]{app.target_kind}[/dim]  {app.url}"
+        if app.tunnel_url:
+            line += f"  [cyan]{app.tunnel_url}[/cyan]"
+        stdout.print(line)
+
+
+def status(
+    app_name: Annotated[str, typer.Argument(help="App to check.")],
+) -> None:
+    """Show reachability and connection info for a running app, reconciling
+    the local registry's record against a live check."""
+    app = registry.get(app_name)
+    if app is None:
+        error(f"no running app named {app_name!r}")
+        raise typer.Exit(1)
+
+    try:
+        httpx.get(app.url, timeout=2.0)
+        reachable = True
+    except httpx.TransportError:
+        reachable = False
+
+    stdout.print(f"name:      {app.name}")
+    stdout.print(f"target:    {app.target} ({app.target_kind})")
+    stdout.print(f"pid:       {app.pid}")
+    stdout.print(f"url:       {app.url}")
+    if app.tunnel_url:
+        stdout.print(f"public:    {app.tunnel_url}")
+    stdout.print(f"reachable: {'[green]yes[/green]' if reachable else '[red]no[/red]'}")