Binary Prerequisites & Offline Layout

Layout (authoritative)

  • local-nugets/ — single source for NuGet: holds curated .nupkg and the restored packages cache in local-nugets/packages/; see local-nugets/manifest.json for hashes of the .nupkg inputs.
  • vendor/ — pinned binaries/CLIs tracked via vendor/manifest.json.
  • offline/feeds/ — air-gap bundles (tarballs, OCI layers, SBOM packs) registered in offline/feeds/manifest.json.
  • Module-owned binaries (currently plugins/, tools/, deploy/, ops/) are tracked for integrity in vendor/manifest.json until relocated.

Adding or updating NuGet packages

  1. Place .nupkg into local-nugets/ and update local-nugets/manifest.json (use the manifest script in scripts/ if available or recompute hashes manually).
  2. Run dotnet restore --source local-nugets (or set OFFLINE=1) to populate .nuget/packages/.
  3. Never add new feeds to NuGet.config without review; the default feed order is local-nugets first, then nuget.org for online builds.

Adding other binaries

  1. Prefer building from source; if you must pin a binary, drop it under vendor/ (or offline/feeds/ for air-gap bundles) and append an entry with SHA-256, origin URL, version, and intended consumer.
  2. For module-owned binaries (e.g., plugins), record the artefact in vendor/manifest.json until it can be rebuilt deterministically as part of CI.

Automation & Integrity

  • Run scripts/update-binary-manifests.py to refresh local-nugets/manifest.json, vendor/manifest.json, and offline/feeds/manifest.json after adding binaries.
  • Run scripts/verify-binaries.sh locally; CI executes it on every PR/branch to block binaries outside approved roots.
  • CI also re-runs the manifest generator and fails if the manifests would change—commit regenerated manifests as part of the change.
  • Restore uses the single location: dotnet restore --source local-nugets with globalPackagesFolder=local-nugets/packages (configured in NuGet.config). Clean by removing local-nugets/packages/ if needed.
  • For offline enforcement, set OFFLINE=1 (CI should fail if it reaches nuget.org without ALLOW_REMOTE=1).

Housekeeping

  • Do not resurrect local-nuget/; the single source of truth is local-nugets/.
  • Refresh manifests when binaries change and record the update in the current sprint’s Execution Log.