feat(cli): add plugin catalog core

[johnnygreco]

Summary

This PR adds the client-side plugin package workflow for Data Designer. The new data-designer plugin command discovers package-first catalogs, shows compatibility-aware package metadata, installs and uninstalls plugin packages, and verifies the runtime plugin entry points exposed by those packages.

The implementation follows the current NVIDIA-NeMo/DataDesignerPlugins catalog contract and uses the stable NVIDIA catalog at https://nvidia-nemo.github.io/DataDesignerPlugins/catalog/plugins.json as the built-in default catalog.

Related Issue

Closes #617

Changes

Public CLI

• Adds the singular data-designer plugin command group with list, search, info, install, uninstall, and installed.
• Adds singular catalog management under data-designer plugin catalog list/add/remove.
• Keeps package distributions as the only install/uninstall unit. Commands that target a package accept either the full package name, such as data-designer-calculator, or its package alias, such as calculator.
• Supports versioned plugin package installs with PACKAGE==VERSION or --version VERSION, while keeping the installed Data Designer package family fixed as the source of truth.
• Shows package descriptions, current package versions, runtime plugin names/types, Data Designer compatibility conditions, and installed markers in catalog output.
• Keeps plugin info and plugin install on the same streamlined metadata renderer: catalog, version, runtime plugins, compatibility, requirement, index URL, and install strategy.
• Makes plugin installed package-first by grouping installed runtime entry points under their owning distribution and version.
• Guides users who try to install a runtime plugin name toward the package that exposes it.

Catalog Contract And Discovery

• Adds schema v2 catalog models and strict validation for package-first catalog payloads: package metadata, docs URLs, install requirements, compatibility constraints, and nested runtime plugin entry points.
• Adds the built-in nvidia catalog, user-managed catalog names in plugin_catalogs.yaml, and DATA_DESIGNER_DEFAULT_PLUGIN_CATALOG_URL for QA/staging overrides.
• Supports remote catalog URLs, GitHub repository/tree/blob URLs, local catalog files, and local catalog directories, normalizing each to the catalog/plugins.json layout used by the plugin repo.
• Caches catalog payloads by catalog name and URL hash, writes cache files atomically, and only falls back to stale cache data when the catalog source cannot be fetched.
• Keeps cache TTL and trust metadata internal; neither is exposed in user-facing catalog output.

Compatibility And Package Management

• Evaluates catalog-declared Python and Data Designer compatibility before install, hides incompatible packages by default, and still supports dry-run inspection of incompatible install plans.
• Builds manager-specific install/uninstall plans for uv project installs, uv pip environment installs, and pip-only environments.
• Uses uv add --active when the user is in an active virtual environment with a user pyproject.toml, so plugin packages are recorded in the project.
• Requires a supported uv version for uv-managed plugin plans and falls back to pip in auto mode when uv is unavailable or too old, provided pip is available.
• Keeps pip support for constrained or sandboxed environments where uv is unavailable.
• Protects the active Data Designer package family (data-designer, data-designer-config, and data-designer-engine) from being reinstalled or upgraded as plugin package dependencies.
• Verifies every declared runtime entry point after install and verifies removal after uninstall without importing unrelated runtime plugins.

Docs And Tests

• Updates the CLI architecture docs and CLI README for package-first catalogs, package aliases, install/uninstall behavior, cache behavior, versioned installs, and catalog commands.
• Adds unit coverage across command dispatch, controller UX, catalog schema validation, repository loading/caching, package alias resolution, compatibility filtering, install/uninstall planning, entry-point verification, and lazy CLI loading.
• Adds upstream DataDesignerPlugins catalog fixtures as consumer contract tests plus a network-gated production catalog smoke test.
• Hardens tests for Python 3.10 pyproject parsing fallback, controller failure paths, package-manager errors, and additional schema validation edge cases.
• Refreshes the existing packaging lockfile entry used by the new catalog/compatibility code.

Review Focus

• plugin_catalog.py: schema v2 validation and the package-first compatibility boundary with DataDesignerPlugins.
• plugin_install_service.py: uv/pip command construction, active-project detection, Data Designer package-family protection, versioned installs, and post-mutation verification.
• plugin_catalog_repository.py: catalog persistence, source normalization, cache keying, and stale-cache behavior.
• plugin_catalog_controller.py and commands/plugin.py: user-facing package/runtime distinction, prompts, dry runs, and table output.

Testing

Local verification:

• uv run --package data-designer pytest packages/data-designer/tests/cli -q (762 passed, 1 skipped, 86 warnings)
• Focused plugin CLI coverage run (193 passed, 1 skipped; targeted plugin CLI module coverage 88%)
• uv run ruff check on changed plugin CLI test files
• uv run ruff format --check on changed plugin CLI test files
• git diff --check
• Temporary-directory integration gauntlet covering stable/local catalogs, aliases/full names, runtime-name rejection, compatibility blocking, uv project installs/uninstalls, uv environment installs/uninstalls, pip-only installs/uninstalls, Data Designer version preservation, and temporary constraint cleanup (145 checks)

Checklist

• Unit tests added/updated
• Architecture and CLI docs updated
• Consistent with the current DataDesignerPlugins package catalog and package-index publishing flow
• Keeps install, uninstall, info, and installed package-first while still displaying runtime plugin metadata

---

Description updated with AI

[github-actions]

Code Review: PR #618 — feat(cli): add plugin catalog core

Summary

Adds a data-designer plugins command group that lets users browse, search, inspect, and install plugins from "tap" catalogs (built-in NVIDIA tap plus user-added aliases), plus a strict schema-v2 validator that matches the DataDesignerPlugins PR #36 contract. The implementation follows the repo's existing command → controller → service → repository CLI layering, adds packaging>=24,<27 as a runtime dep, and ships ~850 lines of test coverage across the four new layers.

Overall the PR is well-structured, strictly validated, and thoughtfully tested. Comments below are mostly minor; one high-value item (entry point group constant usage) and a few smaller polish items.

Findings

Correctness

• plugin_catalog.py:900 and plugin_catalog_service.py:1796 hard-code "data_designer.plugins" instead of using the PLUGIN_ENTRY_POINT_GROUP constant defined in plugin_catalog.py:839. Three call-sites with the same literal invite drift — swap the string for the constant (including the PluginEntryPointInfo.group default and importlib.metadata.entry_points(group=...) call).
• PluginTapRepository.load() (repositories/plugin_tap_repository.py:1359) swallows every exception and returns None. A corrupted plugin_taps.yaml silently disappears from the user's config — they get the built-in tap back and no error. Consider narrowing the catch (at least to OSError | yaml.YAMLError | ValidationError) and surfacing a warning so the user knows their file didn't parse.
• _load_cached_catalog (repositories/plugin_tap_repository.py:1473) also catches bare Exception, which hides JSON corruption / partial writes. A print_warning on fall-through would help debuggability without changing behavior.
• PluginCatalogController exception handling is broad. run_search, _list_entries_or_exit, _get_entry_or_exit, run_taps_remove, etc. catch bare Exception → print_error(str(e)). Prefer catching the known types (PluginCatalogError, ValueError, URLError, OSError) so genuine bugs (e.g. AttributeError during refactors) don't turn into vague user-facing messages.
• run_taps_add double-catches ValidationError and then Exception. Since the repository only raises ValueError (duplicate) and Pydantic only raises ValidationError, the bare Exception branch is dead — remove it or narrow it.
• plugins_callback's dummy _ = tap is load-bearing but unobvious. A one-line comment ("# read via ctx.parent.params in subcommands") would save the next reader a trip to Click's internals. (Feedback instruction says "no comments unless WHY is non-obvious" — this qualifies.)
• _resolve_path_source (services/plugin_install_service.py:2029) assumes the tap URL points to <root>/catalog/plugins.json for path sources. This matches normalize_tap_location, but a user who passes a local catalog JSON named something else gets Path.parent which may or may not be what they want. Catalog-level _validate_package_path already blocks .. traversal, so this is a UX rather than a security issue — worth a test for the non-canonical tap location case.

Schema validation

• Strict key sets (CATALOG_PLUGIN_KEYS etc.) require exact equality. Good for the v2 freeze, but note: the Pydantic models carry ConfigDict(extra="allow") which becomes unreachable once the strict validator runs first. Either drop extra="allow" (defensive; strict is already enforced) or keep the asymmetry deliberately and document why in the module docstring. Current code works but the intent is ambiguous.
• _catalog_data_designer_compatibility enforces specifier == str(requirement.specifier) exactly. Catalog authors who write data-designer (>=0.5.7) in requirement and >=0.5.7 in specifier will hit spurious mismatches if Requirement's canonical form differs from what they wrote. Likely fine in practice (tap schema v2 controls the format), but worth noting to the tap-producer side.
• Catalog size limit is exactly 1 * 1024 * 1024. A 1 MB cap for a JSON catalog is reasonable but quite tight if the NVIDIA tap grows. Consider 4–8 MB, or document the cap in the tap schema so producers know.

Security

• urlopen(request, timeout=10) with 1 MB read cap is solid: no shell exec, size-capped read, http/https scheme guard, explicit timeout. ✓
• Subprocess install uses list-form subprocess.run(command, check=False) — no shell, no injection. ✓
• PEP 508 direct references (git install target) are built from validated fields (url scheme-checked, subdirectory passed through _validate_package_path). ✓
• Untrusted-tap install warning is printed but does not block. That matches the design (force confirmation via confirm_action(default=False)), but reviewers should note that --yes on an untrusted tap skips the prompt with only a yellow warning. Consider requiring an explicit --allow-untrusted flag when combining --yes with a non-trusted tap.
• Remote fetch follows redirects implicitly via urlopen's default HTTPRedirectHandler, which restricts to http/https/ftp — no file:// escape. ✓

Tests

• Coverage is broad: command delegation, controller branching (dry-run, incompatible, force, trusted/untrusted), repository (cache keying, zero-TTL refresh, schema rejection, case-insensitive aliases, duplicate runtime names), service (compatibility evaluation, grouping, installed entry points), install service (pypi/git/path, uv vs pip, verification flow).
• Missing: no test exercises _fetch_remote_catalog error paths (HTTP 4xx/5xx, oversized body, decode failure). A single patch("urllib.request.urlopen") test per branch would round this out.
• Missing: no test for the "cache fallback when fresh fetch fails" branch in load_catalog. That's the main reason to have a cache — worth one direct test.

Style / minor

• Several raise typer.Exit(code=1) blocks follow except ... as e: but don't chain (from e). The project convention appears to be bare raise typer.Exit(...) for CLI errors, so this is consistent, but the lost traceback makes debug logs less useful. Consider a debug-mode env var that re-raises.
• plugin_catalog.py is 490 lines with 20+ module-level constants and helper _-prefixed validators. Consider splitting the validator helpers into plugin_catalog/_validation.py in a follow-up — not blocking.
• InstalledPluginInfo, InstallPlan, CompatibilityResult are @dataclass(frozen=True) while the catalog models are Pydantic. Fine, but an out-of-band explanation ("internal DTOs vs serialized catalog schema") in the module docstring would help.
• _fetch_catalog_payload return type is dict; under the project's modern-typing rule it should be dict[str, object] (already done elsewhere in this PR).

Verdict

Approve with minor requests. The architecture is sound, the schema validation is appropriately strict for a v2 contract freeze, and the test coverage is solid. Action items in priority order:

1. Replace three "data_designer.plugins" string literals with PLUGIN_ENTRY_POINT_GROUP.
2. Narrow the bare except Exception catches in the controller and repository; drop the dead Exception branch in run_taps_add.
3. Surface (don't swallow) load errors for plugin_taps.yaml and cache files.
4. Add a couple of tests for remote-fetch error paths and cache fallback.
5. Consider --allow-untrusted as a stronger guard when --yes + untrusted tap combine.

[greptile-apps]

Greptile Summary

This PR adds the data-designer plugin command group with catalog browsing, install/uninstall, and catalog-alias management. It introduces schema v2 catalog models, a package-first catalog contract, a cache-and-fallback repository, uv/pip install-plan builder with Data Designer family protection, and post-install/uninstall entry-point verification.

• Catalog core (plugin_catalog.py, plugin_catalog_repository.py): strict schema v2 validation, GitHub URL normalization (including tree-path preservation from the previous thread fix), atomic cache writes, and stale-cache fallback on network failure.
• Install service (plugin_install_service.py): resolved uv 0.10.0 minimum, --constraint - via stdin for uv-environment mode, --no-install-package for uv-project mode, and entry-point verification using importlib.metadata directly rather than the plugin registry.
• Controller (plugin_catalog_controller.py): compatibility gate that now correctly fetches incompatible entries and applies the versioned-install bypass before building the plan, fixing the previously-noted unreachable guard.

Confidence Score: 5/5

This PR adds a self-contained plugin catalog subsystem with no changes to existing runtime paths; all four previously-flagged issues are addressed in the current HEAD.

The catalog validation, install-plan builder, cache layer, and controller all follow the invariants described in the PR. Entry-point verification now queries importlib.metadata directly rather than the plugin registry. The uv environment path uses --constraint - via stdin with a 0.10.0 minimum, and the uv-project path uses --no-install-package. The compatibility gate in run_install is now reachable for incompatible-only matches. Test coverage is broad (762 total, 193 focused on the plugin CLI with 88% module coverage). No new correctness issues were found.

No files require special attention.

Important Files Changed

Filename	Overview
packages/data-designer/src/data_designer/cli/plugin_catalog.py	New file: schema v2 catalog models with strict validation; duplicate package names checked by canonical form and duplicate runtime plugin names by enum-key normalization; install requirement consistency with declared specifier and marker is enforced.
packages/data-designer/src/data_designer/cli/services/plugin_install_service.py	New file: resolves uv/pip install targets, builds protection constraints via --constraint - stdin for uv-environment and temp-file for pip, --no-install-package for uv-project; entry-point verification uses importlib.metadata directly; uv minimum version pinned at 0.10.0.
packages/data-designer/src/data_designer/cli/repositories/plugin_catalog_repository.py	New file: catalog persistence with atomic cache writes (PID-scoped temp + replace), stale-cache fallback when source unavailable, GitHub repo/tree/blob URL normalization including subdirectory preservation, and case-insensitive alias management.
packages/data-designer/src/data_designer/cli/controllers/plugin_catalog_controller.py	New file: orchestrates catalog commands; run_install fetches with include_incompatible=True and applies the compatibility/versioned-install gate before plan building, making the guard reachable; dry-run exits 1 for blocked-compatibility installs.
packages/data-designer/src/data_designer/cli/services/plugin_catalog_service.py	New file: compatibility evaluation with marker and specifier checks, package alias resolution, version discovery via simple index (3-second timeout, per-call cache), and installed plugin enumeration via entry_points metadata without importing plugin code.
packages/data-designer/src/data_designer/cli/commands/plugin.py	New file: Typer command functions for list/search/info/install/uninstall/installed and catalog add/remove/list; propagates parent --catalog option through context traversal.
packages/data-designer/src/data_designer/cli/main.py	Adds plugin_app and plugin_catalog_app lazy Typer groups wired into the main app under the Setup panel; plugin_callback stores the parent --catalog option for subcommand propagation.
packages/data-designer/tests/cli/services/test_plugin_install_service.py	New file: comprehensive coverage of uv-project, uv-environment, pip-environment install/uninstall plan generation, old-uv fallback, Data Designer constraint generation, versioned requirements, and entry-point verification including catalog-name vs entry-point-name mismatch.

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as plugin.py (CLI)
    participant Ctrl as PluginCatalogController
    participant Svc as PluginCatalogService
    participant Repo as PluginCatalogRepository
    participant IS as PluginInstallService

    User->>CLI: data-designer plugin install PACKAGE
    CLI->>Ctrl: run_install(package_name, catalog_alias, ...)
    Ctrl->>Svc: get_catalog(alias)
    Svc->>Repo: get_catalog(alias)
    Repo-->>Ctrl: PluginCatalogConfig
    Ctrl->>Svc: "get_package_entries(package, include_incompatible=True)"
    Svc->>Repo: load_catalog(alias, refresh)
    alt Cache fresh
        Repo-->>Svc: PluginCatalog (from cache)
    else Cache stale / missing
        Repo->>Repo: _fetch_catalog_payload(url)
        Repo->>Repo: _validate_catalog(payload)
        Repo->>Repo: _save_catalog_cache (atomic)
        Repo-->>Svc: PluginCatalog
    end
    Svc-->>Ctrl: list[PluginCatalogEntry]
    Ctrl->>Svc: evaluate_compatibility(entry)
    Svc-->>Ctrl: CompatibilityResult
    alt Incompatible and not versioned install and not dry_run
        Ctrl-->>User: error + exit(1)
    end
    Ctrl->>IS: build_install_plan(entry, catalog, manager, version_specifier)
    IS->>IS: _resolve_install_target()
    IS->>IS: _installed_data_designer_distribution_versions()
    IS->>IS: _data_designer_protection_args()
    IS-->>Ctrl: InstallPlan
    Ctrl-->>User: display metadata + confirm prompt
    Ctrl->>IS: install(plan)
    IS->>IS: _materialized_install_command
    IS->>IS: _run_subprocess(command, stdin)
    IS-->>Ctrl: return code
    Ctrl->>IS: verify_entry_points(package_entries)
    IS->>IS: importlib.metadata.entry_points(group)
    IS->>IS: _matching_entry_point_loads_plugin()
    IS-->>Ctrl: bool
    Ctrl-->>User: success or warning message

Loading

_{Reviews (32): Last reviewed commit: "Merge branch 'main' into johnny/feat/617..." | Re-trigger Greptile}

[johnnygreco]

Greptile follow-up addressed in 955a675.

What changed:

• Aligned the plugin CLI UX/docs around catalog packages and runtime plugins, matching the current DataDesignerPlugins contract.
• Synced validation and repository behavior with the merged plugin repo updates: package-first schema, optional install.index_url handling, duplicate canonical package rejection, catalog-directory URL/path normalization, and untrusted env-overridden default catalogs.
• Strengthened install verification to match entry-point name, target value, and owning distribution for all declared runtime plugins in a package.
• Replaced broad controller/repository error handling with known catalog/config error paths and added coverage for invalid registries, remote fetch failures, stale-cache fallback, package-first display, compatibility filtering, and lazy CLI wiring.
• Confirmed tracked source/docs no longer contain the old vocabulary.

Verified with:

• uv run --package data-designer pytest packages/data-designer/tests/cli -q
• make format-check
• make lint
• Live validation of https://nvidia-nemo.github.io/DataDesignerPlugins/catalog/plugins.json against the local catalog validator

[eric-tramel]

While testing the plugin install flow, I hit one more install-safety issue.

The plugin package installs successfully, but the resolver can also replace the Data Designer packages in the current environment. In my test, installing data-designer-github changed the local/editable data-designer, data-designer-config, and data-designer-engine packages to the published 0.5.9 wheels, so the plugin command disappeared immediately afterward.

A simple approach for the uv path would be to treat the Data Designer host packages as protected during plugin installs, e.g. generate/pass an excludes file containing:

data-designer
data-designer-config
data-designer-engine

and include it in the install plan:

uv pip install \
  --python <current-python> \
  --excludes <protected-packages.txt> \
  --default-index https://pypi.org/simple/ \
  --index <catalog-index> \
  <plugin-requirement>

I tried that shape locally with --dry-run; it installs only the plugin package/deps and no longer plans to uninstall/reinstall the Data Designer packages. It would also be worth adding a regression test around the generated install plan and, ideally, a pre/post guard that errors or warns if those protected packages would change.

For pip, I do not think there is an equally clean equivalent to uv --excludes, so the safest near-term policy may be to require uv for catalog installs or make the pip path do an explicit dry-run/report guard before mutating the environment.

[johnnygreco]

@eric-tramel thanks, this install-safety issue is now addressed in the latest pushed commits.

What changed:

• uv pip install environment mode now protects the full Data Designer package family with --excludes - and stdin entries for:
  • data-designer
  • data-designer-config
  • data-designer-engine
• uv add project mode protects the same package family with --no-install-package for each distribution, and also uses --no-install-project so installing a plugin does not build/install the user's current project as a side effect.
• The pip path is still supported for pip-only/sandboxed environments, but now uses a process-scoped temporary constraints file pinning all three installed Data Designer distributions to their current versions.
• uv >= 0.6.0 is now required for uv plugin installs; auto mode falls back to pip with a warning when uv is unavailable or too old, while explicit --manager uv errors clearly.

Coverage added/verified:

• Unit tests assert the generated uv and pip install plans include the protected package family.
• Unit tests assert the pip constraint file is temporary and cleaned up after install.
• The temporary-directory integration gauntlet verified uv project, uv environment, and pip-only installs/uninstalls while confirming the installed Data Designer versions do not change.

I did not add a separate pre/post mutation guard in code because the resolver commands now carry the protection directly, and pip has the equivalent constraints protection for the pip-only case. Happy to add an extra post-install belt-and-suspenders version check later if we decide the extra noise is worth it, but I don't think it should block this PR now.

[andreatgretel]

Requesting changes for two catalog edge cases that still reproduce on the current head.

[andreatgretel]

I reran the review against the validated GitHub PR diff and added real smoke coverage: local pip install/uninstall, local uv env install/uninstall, uv project install/uninstall, production catalog fetch, and a live install/uninstall of data-designer-github from the NVIDIA catalog. The happy paths look good, but I found three warning-level issues worth fixing before approval.

[johnnygreco]

Plugin CLI e2e battle-test report

I ran a fresh end-to-end simulation suite against this branch using a temporary mock plugin catalog repo served over local HTTP. The mock repo included a catalog JSON file, a PEP 503-style simple package index, and real wheel files for multiple plugin packages and versions.

Result: 57 workflows passed, 0 failed.

Data Designer version under test: 0.5.10.dev82+332920f6

Covered:

• Catalog add/list/remove, default catalog override, invalid catalogs, and invalid aliases
• Package list/search/info UX, including narrow terminal layout and runtime-plugin-name recovery hints
• Compatibility filtering and blocked dry-run behavior for incompatible Python/Data Designer requirements
• uv pip install, pip install, and uv add project installs
• Versioned installs through both --version 0.1.0 and package==0.2.0
• Direct wheel-reference installs
• Transitive plugin dependencies while keeping the installed Data Designer version unchanged
• Package-first plugin installed output and uninstall verification
• Old-uv auto fallback to pip, plus the missing-pip failure path
• Entry-point verification warning when catalog metadata and installed entry points disagree

The HTML report was generated locally at .scratch/plugin-cli-e2e-report-20260512-215725.html, but I am not attaching it directly here because GitHub PR comments do not host/render local HTML files as openable pages for reviewers. This summary captures the pass/fail results and the tested behavior directly in the PR thread.

[eric-tramel]

[github-actions]

MkDocs preview: https://81e56767.dd-docs-preview.pages.dev

Fern preview: https://nvidia-preview-pr-618.docs.buildwithfern.com/nemo/datadesigner​

Notebook tutorials are rendered without execution outputs in previews.