dataplat 0.2.3__tar.gz → 0.3.0__tar.gz

{dataplat-0.2.3 → dataplat-0.3.0}/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## 0.3.0
+
+### Changed
+
+- **Exit codes now say what went wrong.** Every failure used to be `1`, so a
+  wrapper script could not tell "your config is wrong" from "the warehouse is
+  down" — and only one of those is worth retrying. Typed failures now carry
+  their own code: `2` invalid input, `3` configuration, `4` authentication,
+  `5` external service. `0`, `1` and `2` keep their conventional meanings, and
+  `2` is deliberately shared with Click's own usage error, because
+  `--format nope` and `-t nosuchtarget` are one condition to the caller.
+
+  An unreachable warehouse exits `5`, since that is the retryable case. A bad
+  statement against a reachable server stays `1`: retrying a syntax error would
+  fail identically forever. Untyped failures and a declined confirmation also
+  stay `1`. The full table is in the README.
+
+  **Scripts that branch on a non-zero exit will see new numbers.** Anything
+  testing `== 1` for a config or auth problem needs updating.
+
+- **`dp db dbt-orphans` is more aggressive.** Its "which models are live" query
+  interpolated the dbt project name into a `LIKE` pattern without escaping it,
+  and dbt project names are snake_case — so the `_` in `my_project` matched any
+  character and a *sibling* project's models (`my2project`) sharing the
+  `dbt_artifacts` schema were counted as live. The same applied to
+  `DP_DBT_INVOCATION_COMMAND`, where `_` is ordinary in a dbt selector.
+
+  The direction is the point: an over-large live set makes **fewer** objects look
+  orphaned. Escaping it shrinks the live set, so dbt-orphans will now rename —
+  and after the grace period drop — objects it previously left alone. Run
+  `dp db dbt-orphans` (dry-run is the default) and read the plan before you
+  `--no-dry-run` the first time after upgrading.
+
+- **`dp status` runs its checks concurrently**: 40.7s to 10.4s with five
+  targets, one unreachable. Sections run in parallel and each database target is
+  probed in parallel within them, which is where the time actually went — a 10s
+  connect timeout per target was paid serially. Key order and section order are
+  unchanged, because both pools iterate the declared mapping rather than
+  completion order. The AWS section stays serial and last: it may hand the
+  terminal to an interactive `aws sso login`.
+
+### Added
+
+- **`--verbose` (or `DP_VERBOSE=1`) shows what dataplat actually sent** — SQL
+  statements, HTTP requests with status and duration, and AWS service calls.
+  It writes to stderr only, so `--json` and `--format csv` stay pipeable, and
+  everything passes through a redactor: passwords, secret values, bearer tokens
+  and API keys are never traced. Parameter values and response bodies are not
+  traced either — those are the data, not the request.
+
+- **Third-party command areas.** `dp` discovers areas declared in the
+  `dataplat.areas` entry-point group, so a package can add a command area
+  without a change here. Discovery reads only the entry-point metadata, never
+  imports the plugin, so `dp --version` and `dp --help` stay import-free and
+  fast. A plugin that fails to import warns on stderr and leaves the built-in
+  areas working; it cannot shadow a built-in area.
+
+- `dp config doctor` warns when a loaded `.envrc` value still contains an
+  unexpanded `$VAR`. dataplat does not run a shell, so
+  `export PGHOST=$DB_HOST` loads the literal text — which then surfaces as a
+  baffling connection failure rather than as the configuration mistake it is.
+
+- Shell completion is documented (`dp --install-completion`). It always worked;
+  the README never said so.
+
+### Fixed
+
+- `dp db query --format json|csv` could emit output that would not parse. The
+  progress spinner painted to stdout, which was invisible while Rich only did
+  that for a real terminal — the frames are erased — but `FORCE_COLOR` makes
+  Rich treat a pipe as a terminal too, and then the escape sequences ended up in
+  the redirected file. The spinner now follows the same sink as the notices.
+
+- `dp db describe` reported the owner's grant option two different ways
+  depending on whether you asked about a schema or a relation. PostgreSQL grants
+  an owner every grant option implicitly and never records it in the ACL, so
+  reading the ACL reported "cannot delegate" about a role that demonstrably can.
+  Schema privileges now agree with relation privileges.
+
+- The `Operating System :: OS Independent` classifier was an overclaim and has
+  been narrowed. Four things break on Windows: `dp config init` creates a
+  symlink, the dependency auto-install re-execs through `os.execvp`, the runner
+  commands shell out to `docker` with a POSIX default workdir, and the
+  credentials file is written with a `0o600` mode Windows ignores — after which
+  dataplat reports its own file as insecurely permissioned. CI tests Linux only.
+
 ## 0.2.3
 
 Redshift-only fixes. Nothing changes for PostgreSQL targets.

{dataplat-0.2.3 → dataplat-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataplat
-Version: 0.2.3
+Version: 0.3.0
 Summary: One command to manage any shape of data platform: databases, ingestion, BI, cloud, and CI.
 Project-URL: Homepage, https://github.com/hanslemm/dataplat
 Project-URL: Repository, https://github.com/hanslemm/dataplat
@@ -14,7 +14,8 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
-Classifier: Operating System :: OS Independent
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Database
@@ -94,7 +95,9 @@ dp
 
 ## Installation
 
-Requires Python 3.12 or newer.
+Requires Python 3.12 or newer, on Linux or macOS. Windows is untested and parts
+of it will not work: `dp config init` creates a symlink, the dependency
+self-install re-execs the process, and `dp ci github runner` drives `docker`.
 
 ```bash
 uv tool install "dataplat[all]"     # recommended: everything
@@ -141,6 +144,23 @@ Either path only ever *adds* to your install: the command is pinned to the
 tool underneath you, and it carries your existing extras along, so adding
 `db` cannot drop an `ingest` you already had.
 
+## Shell completion
+
+```bash
+dp --install-completion    # detect the shell, write the script, hook it up
+dp --show-completion       # print it instead, and install it yourself
+```
+
+Completion takes effect in the next shell. bash, zsh and fish are supported;
+`--show-completion` is the escape hatch when your rc file is managed by
+something else (Nix, chezmoi, a dotfiles repo) or when shell detection fails.
+
+`dp <TAB>` is answered from the area names alone and imports nothing.
+Completing *inside* an area has to import it, because the subcommands it owes
+the shell are that area's own — so the first `dp db <TAB>` pays for psycopg, and
+an area whose extra is not installed completes to nothing rather than offering
+to install it mid-keystroke.
+
 ## Quick start
 
 1. Declare your database targets — any names you like:
@@ -203,6 +223,7 @@ rely only on the global link you chose.
 | --- | --- |
 | `DP_ENVRC_PATH` | Explicit `.envrc` to load, ahead of every other candidate. |
 | `DP_ENVRC_ALLOW_CWD` | Set to `0` to stop picking up `.envrc` from the current directory. |
+| `DP_VERBOSE` | Set to `1` to trace every statement and request to stderr, for a whole session — same switch as `--verbose`. |
 | `DP_TARGETS` | Comma-separated DB target names (e.g. `warehouse,lake`). |
 | `DP_DEFAULT_TARGET` | Target used when `--target` is omitted (default: first of `DP_TARGETS`). |
 | `<NAME>_ENGINE` | `postgresql` (default) or `redshift`, per target. |
@@ -231,6 +252,89 @@ rely only on the global link you chose.
 - **`--limit/-n`** — row caps share one spelling everywhere.
 - **Secrets stay off argv** — prefer `--value-stdin` / hidden prompts; values
   are never echoed back.
+- **`--verbose`** — a root flag: show what the tool actually sent, on stderr.
+
+### Exit codes
+
+Exit codes are a contract, not an implementation detail — a wrapper script
+branches on them long after it has stopped reading our output:
+
+| Code | Meaning | Retry? |
+| --- | --- | --- |
+| `0` | Success. | — |
+| `1` | Unexpected or not-yet-classified failure. Also a declined confirmation: "no" is not an error, but it is not "done" either. | No — you don't know what happened. |
+| `2` | Invalid input: an unknown flag or target, a value that cannot be parsed, a combination of arguments that cannot work. | No — the command itself is wrong. |
+| `3` | Configuration problem: missing connection settings, an unknown engine, an unset `AIRBYTE_BASE_URL` or `DP_DBT_PROJECT`. | No — a human has to fix the config. |
+| `4` | Authentication failure: credentials rejected, a login endpoint that would not authenticate, `aws sso login` failed. | No — a new credential is needed. |
+| `5` | External service failure: a call to Airbyte, Superset or AWS failed, timed out or returned something unusable; a warehouse that refused the operation. | **Yes** — the only class where a retry can help. |
+
+`0`, `1` and `2` keep their conventional meanings. `2` is Click's own code for a
+usage error, which is why invalid input shares it: `dp db query --format nope`
+(Click's complaint) and `-t nosuchtarget` (ours) are one condition to the
+caller — "you passed something I cannot use" — and splitting them by who noticed
+would be a distinction with no use.
+
+The point of the codes above `2` is that `5` is the one worth retrying, and `3`
+and `4` are the ones you must never retry: no amount of sleeping and trying
+again creates a missing config file or repairs a rejected password. Cap the
+retries anyway — `5` means "the other end failed", which covers a warehouse
+that was restarting *and* a `DROP` the server refused because something still
+depends on it, and only the first of those gets better on its own.
+
+```bash
+dp db long-queries -t warehouse --json > queries.json
+case $? in
+  0) ;;
+  5) echo "service unavailable; will retry" >&2; exit 75 ;;   # EX_TEMPFAIL
+  *) echo "not retryable; fix and re-run" >&2; exit 1 ;;
+esac
+```
+
+Treat `1` as "unknown", never as "retryable": it is the code for a failure
+dataplat has not classified, so retrying it is a guess.
+
+### Verbose tracing
+
+`--verbose` (or `DP_VERBOSE=1`) answers the one question logs cannot: what did
+`dp` actually send?
+
+```bash
+dp --verbose db query 'SELECT 1'              # root flag, before the subcommand
+DP_VERBOSE=1 dp db long-queries 2> trace.log  # or for a whole session
+dp --verbose db describe public 2>&1 >/dev/null | grep '\[dp:sql\]'
+```
+
+Every line is prefixed with its category — `[dp:sql]` or `[dp:http]` — and
+collapsed onto one line, so the output greps cleanly:
+
+```text
+[dp:sql] connect me@db.example.com:5432/analytics engine=postgresql
+[dp:sql] SELECT 1 FROM pg_namespace WHERE nspname = %s | 1 params bound
+[dp:http] GET https://api.airbyte.com/v1/jobs?limit=20
+[dp:http] GET https://api.airbyte.com/v1/jobs?limit=20 -> 200 143.8ms
+```
+
+SQL is traced *before* the statement runs, which is the point: the trace you
+need is the one for the query that never came back, and a line written afterwards
+would never be written at all. That is also why there is no duration on it — use
+`dp db long-queries` for how long. HTTP gets two lines for the same reason, one
+on the way out and one on the response; a line with no `-> status` partner *is*
+the signal that a request hung, was refused, or never connected.
+
+**It writes to stderr and never to stdout**, so `--json` and `--format csv` stay
+machine-readable with tracing on. Piping into `jq` is still valid, and
+`2>/dev/null` drops the trace without touching the data:
+
+```bash
+dp --verbose db query --format json 'SELECT 1' 2>/dev/null | jq
+```
+
+**Secrets are never traced.** Every message is redacted on the way out —
+passwords (including the SQL `PASSWORD '…'` literal that role creation sends),
+tokens, API keys, `Authorization` headers and credentials embedded in a URL all
+become `***`. Parameter values, result rows and response bodies are not traced
+at all: they are your warehouse's data, and a trace that scrolls the answer past
+you has hidden the request it exists to show.
 
 ## Examples
 

{dataplat-0.2.3 → dataplat-0.3.0}/README.md

@@ -49,7 +49,9 @@ dp
 
 ## Installation
 
-Requires Python 3.12 or newer.
+Requires Python 3.12 or newer, on Linux or macOS. Windows is untested and parts
+of it will not work: `dp config init` creates a symlink, the dependency
+self-install re-execs the process, and `dp ci github runner` drives `docker`.
 
 ```bash
 uv tool install "dataplat[all]"     # recommended: everything
@@ -96,6 +98,23 @@ Either path only ever *adds* to your install: the command is pinned to the
 tool underneath you, and it carries your existing extras along, so adding
 `db` cannot drop an `ingest` you already had.
 
+## Shell completion
+
+```bash
+dp --install-completion    # detect the shell, write the script, hook it up
+dp --show-completion       # print it instead, and install it yourself
+```
+
+Completion takes effect in the next shell. bash, zsh and fish are supported;
+`--show-completion` is the escape hatch when your rc file is managed by
+something else (Nix, chezmoi, a dotfiles repo) or when shell detection fails.
+
+`dp <TAB>` is answered from the area names alone and imports nothing.
+Completing *inside* an area has to import it, because the subcommands it owes
+the shell are that area's own — so the first `dp db <TAB>` pays for psycopg, and
+an area whose extra is not installed completes to nothing rather than offering
+to install it mid-keystroke.
+
 ## Quick start
 
 1. Declare your database targets — any names you like:
@@ -158,6 +177,7 @@ rely only on the global link you chose.
 | --- | --- |
 | `DP_ENVRC_PATH` | Explicit `.envrc` to load, ahead of every other candidate. |
 | `DP_ENVRC_ALLOW_CWD` | Set to `0` to stop picking up `.envrc` from the current directory. |
+| `DP_VERBOSE` | Set to `1` to trace every statement and request to stderr, for a whole session — same switch as `--verbose`. |
 | `DP_TARGETS` | Comma-separated DB target names (e.g. `warehouse,lake`). |
 | `DP_DEFAULT_TARGET` | Target used when `--target` is omitted (default: first of `DP_TARGETS`). |
 | `<NAME>_ENGINE` | `postgresql` (default) or `redshift`, per target. |
@@ -186,6 +206,89 @@ rely only on the global link you chose.
 - **`--limit/-n`** — row caps share one spelling everywhere.
 - **Secrets stay off argv** — prefer `--value-stdin` / hidden prompts; values
   are never echoed back.
+- **`--verbose`** — a root flag: show what the tool actually sent, on stderr.
+
+### Exit codes
+
+Exit codes are a contract, not an implementation detail — a wrapper script
+branches on them long after it has stopped reading our output:
+
+| Code | Meaning | Retry? |
+| --- | --- | --- |
+| `0` | Success. | — |
+| `1` | Unexpected or not-yet-classified failure. Also a declined confirmation: "no" is not an error, but it is not "done" either. | No — you don't know what happened. |
+| `2` | Invalid input: an unknown flag or target, a value that cannot be parsed, a combination of arguments that cannot work. | No — the command itself is wrong. |
+| `3` | Configuration problem: missing connection settings, an unknown engine, an unset `AIRBYTE_BASE_URL` or `DP_DBT_PROJECT`. | No — a human has to fix the config. |
+| `4` | Authentication failure: credentials rejected, a login endpoint that would not authenticate, `aws sso login` failed. | No — a new credential is needed. |
+| `5` | External service failure: a call to Airbyte, Superset or AWS failed, timed out or returned something unusable; a warehouse that refused the operation. | **Yes** — the only class where a retry can help. |
+
+`0`, `1` and `2` keep their conventional meanings. `2` is Click's own code for a
+usage error, which is why invalid input shares it: `dp db query --format nope`
+(Click's complaint) and `-t nosuchtarget` (ours) are one condition to the
+caller — "you passed something I cannot use" — and splitting them by who noticed
+would be a distinction with no use.
+
+The point of the codes above `2` is that `5` is the one worth retrying, and `3`
+and `4` are the ones you must never retry: no amount of sleeping and trying
+again creates a missing config file or repairs a rejected password. Cap the
+retries anyway — `5` means "the other end failed", which covers a warehouse
+that was restarting *and* a `DROP` the server refused because something still
+depends on it, and only the first of those gets better on its own.
+
+```bash
+dp db long-queries -t warehouse --json > queries.json
+case $? in
+  0) ;;
+  5) echo "service unavailable; will retry" >&2; exit 75 ;;   # EX_TEMPFAIL
+  *) echo "not retryable; fix and re-run" >&2; exit 1 ;;
+esac
+```
+
+Treat `1` as "unknown", never as "retryable": it is the code for a failure
+dataplat has not classified, so retrying it is a guess.
+
+### Verbose tracing
+
+`--verbose` (or `DP_VERBOSE=1`) answers the one question logs cannot: what did
+`dp` actually send?
+
+```bash
+dp --verbose db query 'SELECT 1'              # root flag, before the subcommand
+DP_VERBOSE=1 dp db long-queries 2> trace.log  # or for a whole session
+dp --verbose db describe public 2>&1 >/dev/null | grep '\[dp:sql\]'
+```
+
+Every line is prefixed with its category — `[dp:sql]` or `[dp:http]` — and
+collapsed onto one line, so the output greps cleanly:
+
+```text
+[dp:sql] connect me@db.example.com:5432/analytics engine=postgresql
+[dp:sql] SELECT 1 FROM pg_namespace WHERE nspname = %s | 1 params bound
+[dp:http] GET https://api.airbyte.com/v1/jobs?limit=20
+[dp:http] GET https://api.airbyte.com/v1/jobs?limit=20 -> 200 143.8ms
+```
+
+SQL is traced *before* the statement runs, which is the point: the trace you
+need is the one for the query that never came back, and a line written afterwards
+would never be written at all. That is also why there is no duration on it — use
+`dp db long-queries` for how long. HTTP gets two lines for the same reason, one
+on the way out and one on the response; a line with no `-> status` partner *is*
+the signal that a request hung, was refused, or never connected.
+
+**It writes to stderr and never to stdout**, so `--json` and `--format csv` stay
+machine-readable with tracing on. Piping into `jq` is still valid, and
+`2>/dev/null` drops the trace without touching the data:
+
+```bash
+dp --verbose db query --format json 'SELECT 1' 2>/dev/null | jq
+```
+
+**Secrets are never traced.** Every message is redacted on the way out —
+passwords (including the SQL `PASSWORD '…'` literal that role creation sends),
+tokens, API keys, `Authorization` headers and credentials embedded in a URL all
+become `***`. Parameter values, result rows and response bodies are not traced
+at all: they are your warehouse's data, and a trace that scrolls the answer past
+you has hidden the request it exists to show.
 
 ## Examples
 

dataplat-0.3.0/dataplat/cli/_exit.py

@@ -0,0 +1,68 @@
+"""The one way a command reports a typed error and stops.
+
+Every catch site in the tree had grown the same two lines — print red with an
+``Error: `` prefix, then ``raise typer.Exit(code=1)`` — and the code was the
+part that was wrong: a missing config file, a rejected password and an
+unreachable warehouse all exited 1, so a script could tell that something broke
+and nothing else. :func:`fail` keeps the printing byte-for-byte and takes the
+number from the exception, which is the only thing that knows what happened.
+
+It does not branch on the error type, deliberately. A ``type -> code`` chain
+here would be a second source of truth that a new error class could be added
+without, and the first symptom would be a wrong exit code in someone's CI. The
+class attribute in :mod:`dataplat.core.errors` is the whole mechanism; this
+function is the plumbing.
+
+Two details that are load-bearing:
+
+- the message goes through :func:`dataplat.cli._render.esc`, because exception
+  text quotes warehouse rows and API response bodies verbatim, and a stray
+  ``[/x]`` in either one raises ``MarkupError`` mid-render — turning a handled
+  error into a traceback;
+- output goes to *stdout*, where this codebase's errors have always gone. That
+  is parity, not a claim that it is right: moving diagnostics to stderr is what
+  :mod:`dataplat.core.trace` does for tracing, and doing the same for errors
+  would change what every existing CliRunner assertion sees. If it happens, it
+  happens here, once, on purpose.
+"""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+import typer
+from rich.console import Console
+
+from dataplat.cli._render import esc
+from dataplat.core.errors import DataplatError, ExitCode
+
+__all__ = ["exit_code_for", "fail"]
+
+_console = Console()
+
+
+def exit_code_for(exc: BaseException) -> ExitCode:
+    """Return the exit code ``exc`` should produce, without exiting.
+
+    A :class:`~dataplat.core.errors.DataplatError` answers for itself; anything
+    else is unclassified and therefore :attr:`~dataplat.core.errors.ExitCode.
+    FAILURE`. Split out from :func:`fail` for the callers that need the number
+    but not the exit — logging it, recording it in a summary table, or exiting
+    through their own path (a TUI cannot raise ``typer.Exit`` at an arbitrary
+    point and expect it to mean anything).
+    """
+    if isinstance(exc, DataplatError):
+        return exc.exit_code
+    return ExitCode.FAILURE
+
+
+def fail(exc: DataplatError, *, console: Console | None = None) -> NoReturn:
+    """Print ``exc`` as an error and exit with the code it declares.
+
+    Pass ``console`` where the command already owns one, so the error lands in
+    the same stream the rest of its output did.
+    """
+    (console or _console).print(f"[red]Error: {esc(exc)}[/red]")
+    # exit_code_for rather than exc.exit_code: identical for every typed error,
+    # and total for the untyped one a caller slips past the annotation.
+    raise typer.Exit(code=exit_code_for(exc))

{dataplat-0.2.3 → dataplat-0.3.0}/dataplat/cli/_lazy.py

@@ -16,6 +16,12 @@ leave psycopg unimported). Completing *inside* an area — ``dp db <TAB>`` — d
 import it, because the subcommand list it has to offer is the area's own; that
 is the one non-dispatch path that pays, and there is no way around it.
 
+Plugin areas are mounted lazily too, one level up: ``main`` mounts only the
+built-ins (their names and help text are constants), and :class:`LazyRootGroup`
+adds a placeholder per plugin area the first time click asks for the command
+surface. That keeps the entry-point scan off ``dp --version``, which never looks
+at the command list, and off ``dp db …``, whose name a plugin cannot claim.
+
 No direct click import here either — typer vendors click, so only the
 ``TyperGroup`` surface is safe to rely on (see :mod:`dataplat.cli._missing`).
 """
@@ -29,7 +35,17 @@ from typer.core import TyperGroup
 from typer.main import get_group
 
 from dataplat.core.deps import ready
-from dataplat.core.registry import AreaMount, area_by_name, load_app, mount_help
+from dataplat.core.errors import ExitCode
+from dataplat.core.registry import (
+    AreaMount,
+    area_by_name,
+    is_builtin,
+    load_app,
+    mount_help,
+    plugin_areas,
+    warn_plugin,
+    warn_plugin_failed,
+)
 
 __all__ = [
     "AreaPlaceholderGroup",
@@ -57,6 +73,31 @@ def area_placeholder(mount: AreaMount) -> typer.Typer:
     )
 
 
+def _load_or_diagnose(mount: AreaMount) -> Any:
+    """:func:`load_app`, but a third-party area's import failure is news.
+
+    A built-in that will not import is a bug in dp, and the traceback is the bug
+    report — swallowing it would hide it behind a sentence. A plugin that raises
+    on import is a fact about the user's environment, and the useful output is
+    which area, from which target, failed how. Either way the blast radius is one
+    area: laziness means nothing else in the CLI has imported it, so ``dp
+    --help`` and every other area keep working.
+
+    ``Exception``, not ``BaseException``: a plugin that calls ``sys.exit()`` or is
+    interrupted mid-import is asking to stop the process, not to be diagnosed.
+    """
+    if is_builtin(mount):
+        # Unguarded on purpose — see above.
+        return load_app(mount)
+    try:
+        return load_app(mount)
+    except Exception as exc:
+        warn_plugin_failed(mount, exc)
+        # Unclassified failure: a broken third-party package is not invalid
+        # input, not our configuration, and not a service that answered badly.
+        raise typer.Exit(code=ExitCode.FAILURE)
+
+
 def area_command(mount: AreaMount) -> typer.Typer:
     """``mount``'s real Typer app, or the stub that offers to install its extra.
 
@@ -65,7 +106,7 @@ def area_command(mount: AreaMount) -> typer.Typer:
     ``mount.deps``, so an area that is not one of the built-ins still works.
     """
     if mount.deps is None or ready(mount.deps):
-        return load_app(mount)
+        return _load_or_diagnose(mount)
     # Imported on this branch only: the stub pulls in subprocess, which costs
     # more to import (~5 ms) than every readiness check in the CLI together.
     from dataplat.cli._missing import build_missing_deps_app
@@ -74,7 +115,67 @@ def area_command(mount: AreaMount) -> typer.Typer:
 
 
 class LazyRootGroup(TyperGroup):
-    """Root group that resolves an area's real app the first time it is used."""
+    """Root group that resolves an area's real app the first time it is used.
+
+    It also owns *when* plugin areas appear: ``main`` mounts the built-ins, and
+    the two overrides below add the plugin placeholders the moment click needs a
+    command surface that could contain one.
+    """
+
+    # Class-level default, set per instance on first use: an instance attribute
+    # avoids overriding TyperGroup.__init__ just to hold one bool.
+    _plugins_mounted: bool = False
+
+    def _mount_plugins(self) -> None:
+        """Mount a placeholder for every plugin area, once per group.
+
+        The flag is set *before* discovery, not after: a scan that warned about a
+        broken plugin must not repeat itself on the next lookup, and several
+        lookups happen in one invocation.
+        """
+        if self._plugins_mounted:
+            return
+        self._plugins_mounted = True
+        for mount in plugin_areas():
+            if mount.name in self.commands:
+                # The registry already refuses a built-in *area*'s name; what is
+                # left is the rest of the root surface (config, status, open),
+                # which only the group knows about. Refused for the same reason:
+                # `dp status` must keep meaning `dp status`.
+                warn_plugin(
+                    f"ignoring plugin area {mount.name!r}: "
+                    f"dp {mount.name} is already a command"
+                )
+                continue
+            # Same construction as a built-in placeholder, so plugin areas are
+            # indistinguishable downstream — including in --help, "did you mean"
+            # and completion, which read the group's commands and nothing else.
+            self.commands[mount.name] = get_group(area_placeholder(mount))
+
+    def list_commands(self, ctx: Any) -> list[str]:
+        """Every command name, plugin areas included.
+
+        --help, "did you mean" and top-level completion all come through here, so
+        this is where the scan is genuinely owed: the answer is a list of names,
+        and a plugin area's name belongs in it.
+        """
+        self._mount_plugins()
+        return super().list_commands(ctx)
+
+    def get_command(self, ctx: Any, name: str) -> Any:
+        """Look up one command, discovering plugins only if nothing claims it.
+
+        A name the built-ins already answer is returned without a scan, and that
+        is sound rather than a shortcut: a plugin cannot claim a built-in area's
+        name (the registry refuses it) nor an existing root command's (above), so
+        discovery could not change this answer. It is what keeps ``dp db query``
+        as cheap as it was before plugins existed.
+        """
+        command = super().get_command(ctx, name)
+        if command is not None:
+            return command
+        self._mount_plugins()
+        return super().get_command(ctx, name)
 
     def resolve_command(self, ctx: Any, args: Any) -> Any:
         """Import the area behind a placeholder, now that it is needed.