Nomos: GitHub Releases For Provider Installs

Hey folks, let's dive into an exciting upgrade for Nomos! We're talking about a significant shift in how we handle provider installations, moving away from local copies and embracing the power and safety of GitHub Releases. This change, marked by IMPLEMENT-2025-11-02-001, is all about making things smoother, more secure, and easier to manage for everyone. So, let's get into it, shall we?

The Big Picture: Why the Change?

Standardizing Provider Distribution is our primary aim. We're going to streamline the process by using GitHub Releases exclusively. This means providers are distributed in a consistent, reliable way, making it super simple for you to get the latest versions. We want to reduce any confusion and give you the best experience possible.

Boosting Security and Reproducibility. This means that we're going to verify the integrity of the downloaded files, ensuring you're getting exactly what you expect. This is all thanks to checksum verification and the use of a lockfile. It's all about making sure that every installation is predictable, and that your supply chain is safe.

Say Goodbye to Local Copy Headaches. The days of using --from to install from local files are numbered. This can be tricky and prone to errors. Instead, we'll drive installs from the project's .csl configuration. This will make installation cleaner and more reliable. We're also making sure that you can configure everything in a single place. This keeps things simple and easy to track.

Key Choices: How We're Doing It

Let's get into the details of the choices behind this shift. This is how we are building the future of provider installations.

.csl Configuration The .csl file is the heart of the configuration. Inside this, the type is going to have a simple owner/repo string. For example, autonomous-bits/nomos-provider-file. This will point directly to the provider's source on GitHub. Simple, right?

Smart Asset Naming. We'll smartly infer the asset name from the repository name and your system's OS/architecture. We're going to make sure the right version is installed for your environment. We'll also allow you to include provider-specific configurations. The goal is to make the process as seamless as possible.

The Downloader/Resolver Library. This will be built in libs/provider/downloader. We want to make this library reusable, with a straightforward API. This keeps the codebase clean and easy to maintain. We're going for something that is both robust and flexible.

Overwrite Semantics. We're going to make sure that matching provider assets are overwritten when installed. You will have full control over installations, with an option to force an overwrite. This ensures you always have the latest and greatest version.

GitHub-Only for v1. Initially, we are only focusing on public releases from GitHub. We will add support for private repositories via a GITHUB_TOKEN later. This allows us to maintain a stable release and add new features easily.

Making It Happen: The Acceptance Criteria

So, what does success look like? We have a clear set of goals.

• nomos init Will Discover provider sources from .csl and install binaries from GitHub Releases only.
• .nomos/providers.lock.json will contain GitHub metadata, checksums, and the path.
• The --from flag and installFromLocal will be removed. We want things to be cleaner and simpler.
• The CI will run hermetic tests and optional network tests.

Rolling Up Our Sleeves: The Tasks Ahead

Let's break down the tasks involved in this transition:

1. libs/provider/downloader. Here, we'll build the core functionality. We will add the public API, implement the GitHub Releases resolver using the REST API, and build a streaming downloader with retries and SHA256 verification. We'll also write tests to verify all aspects of the download process.
2. Wire CLI & initcmd. We need to integrate the new downloader into the command-line interface. That means removing the old --from parsing and updating the installation process to use the new downloader.
3. Lockfile. We'll update the lockfile to include GitHub metadata and checksums. This is critical for security and reproducibility.
4. Tests. We'll replace existing tests and add new ones, including hermetic tests and gated integration tests. The goal is to make sure everything works perfectly.
5. Docs. We'll update the CLI documentation, README, and examples to remove --from and explain the new .csl schema. We will also include a migration guide for users transitioning from the old way of doing things.
6. Release Notes & Changelog. This is where we'll document the changes, including any breaking changes and migration steps.

Developer Notes: What You Need to Know

Here's a quick look at the .csl source shape:

source:
  alias: 'configs'
  type: 'autonomous-bits/nomos-provider-file'  # owner/repo
  version: '1.0.0'
  directory: './data'  # provider-specific config (passed through)

Asset inference will try common patterns. Download and install must be atomic. Write to a temporary file, then rename it. This ensures the process is safe and reliable.

Testing & Rollout: How We'll Make Sure It Works

To ensure everything works perfectly, we'll go through a rigorous testing phase.

• Run unit tests: go test ./...
• Run downloader tests only: go test ./libs/provider/downloader -v
• Run hermetic init tests: go test ./apps/command-line/test -run TestInitCommand_Hermetic
• Run gated network test (manual):

  export NOMOS_RUN_NETWORK_INTEGRATION=1
  go test ./apps/command-line/test -tags=integration -run TestInitCommand_Integration_Network
  

We want to make sure everything runs smoothly before releasing this update to everyone. That's why we're focusing on thorough testing.

Let me know what you think. I can start an implementation PR that scaffolds libs/provider/downloader and wires a single hermetic test, or I can add more detail to any of the tasks above. If you'd like me to open follow-up issues for sub-tasks (e.g., tests, docs), I can do that as well. This is a step towards a better Nomos experience for everyone!