maintain-packaging

# Maintain Release And Packaging Surfaces ## Companion Guidance Use `karpathy-guidelines` alongside this skill for implementation or review work. Keep changes scoped, surface assumptions, and define focused validation before editing. Use this skill when a change affects how NeMo Fabric is built, packaged, named, or consumed outside the source tree. ## Audit Areas - Rust `Cargo.toml` package names and workspace metadata - Root development coordination in `pyproject.toml` - Published Python package metadata under `sdk/python/` and `adapter-contract/python/` - Native extension naming and placement under `sdk/python/nemo-fabric-runtime/src/nemo_fabric` - Dependency resolution in `Cargo.lock` and `uv.lock` - TypeScript adapter-contract metadata and dependency resolution in `adapter-contract/typescript/package.json` and `package-lock.json` - Documentation tooling metadata in `docs/package.json` and `docs/package-lock.json` - CI workflows, install commands, and example commands - npm trusted publishing through `.github/workflows/publish_typescript.yml` and the protected `npmjs` environment - `justfile` build, test, clean, and documentation recipes - Release tags, registry publication, and release-facing documentation in `RELEASING.md` - Metadata-only adapter catalog under `sdk/python/nemo-fabric-adapter-catalog`: regenerate its single resource bundle with `just adapter-catalog` and check freshness with `just check-adapter-catalog`. Keep source metadata outside descriptor objects and catalog resources outside automatic execution discovery. `just set-version` refreshes the bundle after stamping both ecosystems; `just wheels` checks freshness and builds the package. ## Dependency Selection ### Catalog Bundle Maintenance `scripts/ci/generate_adapter_catalog.py` collects canonical descriptors and registered targets from leaf packages under `adapters/python/` and `adapters/typescript/`, without an adapter-ID allowlist. Support packages, presets, fixtures, and source-only external integrations are excluded. The bundle keeps source package names, versions, paths, ecosystems, and fingerprints outside descriptor objects. Fingerprints use UTF-8 JSON with sorted keys, compact separators, and unescaped Unicode. These fields describe a release snapshot, not an observed execution environment. Run `just adapter-catalog`, `just check-adapter-catalog`, and `uv build --wheel --sdist --out-dir dist sdk/python/nemo-fabric-adapter-catalog` when maintaining the bundle. `just set-version` refreshes it after stamping Python and TypeScript versions. Python tests and wheel builds reject stale bundles; wheels and source distributions must build independently of the adapter source tree. Keep these maintainer details out of the PyPI-facing package README. ### Select Dependencies Treat every direct dependency as a long-lived API, supply-chain, and licensing commitment. - Keep `nemo-fabric` as a metapackage that unconditionally installs the exact-version `nemo-fabric-runtime` distribution. Its harness extras delegate to version-matched leaf adapter `harness` extras. Hermes Agent is the sole exception: its root extra delegates to the bare adapter because Hermes Agent 0.20 and later is not installable from PyPI. Do not add other adapter-only aliases. - Keep the runtime `streaming` extra pinned to the version-matched `nemo-fabric-collector` distribution. The metapackage `streaming` extra must delegate to the version-matched runtime extra. Do not expose a separate metapackage `collector` extra. - Keep leaf adapters adapter-only by default. Every leaf provides `full`, and every package-installable harness provides `harness`. The Hermes adapter omits `harness` because users install Hermes Agent separately from source. Provide `relay` only when the adapter imports the NeMo Relay Python package. For adapters that launch the Relay CLI, both `harness` and `full` install the version-matched `nemo-relay-cli-bin` package and remain equivalent. - First prefer the standard library, an existing dependency, or a small local implementation when it keeps the behavior clear and maintainable. - When multiple dependencies satisfy the technical requirement, prefer the maintained OSS option with clear SPDX metadata, a smaller transitive graph, and permissive terms such as Apache-2.0, MIT, BSD, or ISC. - Inspect the resolved transitive graph, not only the direct package license. - Treat `UNKNOWN`, non-SPDX/custom, proprietary or source-available terms, and copyleft or network-copyleft terms as explicit review points. Do not silently accept or reject them; route them to the dependency approvers with the distribution and linkage context. - Record the functional need, viable alternatives considered, why the selected dependency is the narrowest fit, and any unresolved licensing question. - Run `uv run --no-project python scripts/licensing/license_diff.py --base-ref origin/main` after updating manifests and lockfiles, then review added packages and license changes. - For `adapter-contract/typescript/package-lock.json`, inspect the resolved package entries and their `license` fields. The adapter-contract package must keep an empty production dependency graph; build-only dependencies still require permissive, recorded license evidence. - Regenerate the attribution files with the named pre-commit hooks instead of editing generated output: ```bash uv run pre-commit run --all-files attributions-rust uv run pre-commit run --all-files attributions-python uv run pre-commit run --all-files attributions-node ``` The license diff is evidence for reviewers. Dependency approvers make compatibility decisions using the distribution and linkage context. ## Checklist - [ ] Package names, import paths, and module names are internally consistent - [ ] Generated artifacts still land where downstream consumers expect - [ ] Docs and examples use the current install/import/build commands - [ ] CI references the same package names as local workflows - [ ] Public packaging changes are reflected in release-facing docs - [ ] Workspace, Python, and lockfile versions remain aligned where required - [ ] The TypeScript adapter-contract package version follows the workspace release version without changing its independent wire contract version - [ ] The editable maturin build still produces `nemo_fabric._native` - [ ] New dependencies are necessary, maintained, and narrower than the viable alternatives - [ ] Direct and transitive license changes were reviewed from the resolved lockfiles - [ ] Licensing uncertainties are called out for dependency approver review - [ ] Changed attribution files are regenerated and included ## References - `pyproject.toml` - `RELEASING.md` - `sdk/python/nemo-fabric/pyproject.toml` - `sdk/python/nemo-fabric-runtime/pyproject.toml` - `adapter-contract/python/pyproject.toml` - `Cargo.toml` - `Cargo.lock` - `uv.lock` - `docs/package.json` - `docs/package-lock.json` - `adapter-contract/typescript/package.json` - `adapter-contract/typescript/package-lock.json` - `.github/workflows/ci_typescript.yml` - `.github/workflows/publish_typescript.yml` - `scripts/ci/publish_typescript_package.py` - `.github/workflows/ci_python.yml` - `.github/workflows/ci_rust.yml` - `.pre-commit-config.yaml` - `scripts/licensing/license_diff.py` - `justfile`