feat: add Nix support

[srid]

Description

Package apm with uv2nix so it can be run via nix run github:microsoft/apm (what's Nix?) on Linux and macOS (and Windows, via WSL).

To test, run:

nix run github:srid/apm/add-nix-flake

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• All existing tests pass
• Added tests for new functionality (if applicable)

[srid]

@microsoft-github-policy-service agree

[Copilot]

Pull request overview

Adds Nix flake packaging for APM so it can be executed via nix run github:microsoft/apm, and documents the new install path.

Changes:

• Introduces flake.nix/flake.lock using uv2nix + pyproject-nix to build a Python 3.12 virtualenv that runs apm.
• Adds a GitHub Actions workflow to build and smoke-run the flake on CI.
• Documents Nix installation in the docs site (and also in README).

Reviewed changes

Copilot reviewed 4 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Adds Nix to the “Other install methods” snippet.
flake.nix	Defines the flake outputs for building/running APM via Nix using uv2nix.
flake.lock	Pins Nix flake inputs for reproducible builds.
docs/src/content/docs/getting-started/installation.md	Documents Nix install path for macOS/Linux.
.gitignore	Ignores Nix result output artifact.
.github/workflows/nix.yml	Adds CI job to nix build and run apm --version from the flake.

[Copilot]

Per the repo documentation rules, changes to README.md require explicit approval before merging. Please confirm that README should include Nix install instructions (or move this guidance to the docs page only and keep README unchanged).

Suggested change

	# Nix
	nix run github:microsoft/apm

[Copilot]

These third-party actions are referenced by branch ("@main"). For supply-chain safety and reproducibility, pin to an immutable tag or (preferably) a specific commit SHA.

Suggested change

	- uses: DeterminateSystems/nix-installer-action@main
	- uses: DeterminateSystems/magic-nix-cache-action@main
	- uses: DeterminateSystems/nix-installer-action@v16
	- uses: DeterminateSystems/magic-nix-cache-action@v7

[Copilot]

This workflow doesn't set top-level GITHUB_TOKEN permissions. To follow least-privilege (as used in other workflows), explicitly set permissions: { contents: read } (and add more only if needed).

Suggested change

	permissions:
	contents: read

[Copilot]

Running Nix builds on macos-latest for every PR can significantly increase CI time/cost and may be subject to long runner queues. Consider limiting PR runs to Linux only, or switching macOS to a more predictable runner (e.g., the same macOS intel runner used elsewhere) and/or gating macOS builds to push/release-only.

Suggested change

	strategy:
	matrix:
	os: [ubuntu-latest, macos-latest]
	if: ${{ github.event_name != 'pull_request' || matrix.run_on_pr }}
	strategy:
	matrix:
	include:
	- os: ubuntu-latest
	run_on_pr: true
	- os: macos-13
	run_on_pr: false

[danielmeppiel]

Thanks for the contribution! I'm not ready to support Nix packaging at this stage — I don't have Nix expertise to maintain it, and I haven't seen user demand yet. If this becomes a frequently requested feature, I'd love to revisit.

[danielmeppiel]

Hi @srid -- circling back on this with more concrete context now that #675 has landed.

#675 added a build-time update_policy module that lets package-manager distributions disable apm update and surface their own update guidance instead. The conda-forge package (apm-cli-feedstock, maintained by @melund) ships using that pattern: feedstock lives downstream, only the upstream enabler lives in this repo.

For Nix, I'd love to support users via the same model rather than carrying flake.nix / flake.lock in-tree. Concretely: APM packaged in nixpkgs (or a Nix overlay you maintain in a separate repo we link from our docs).

Reasons:

1. I don't have Nix expertise to maintain flake.nix / refresh flake.lock reliably, debug uv2nix regressions, or audit transitive Nix-side dependencies. An in-tree flake that breaks (advertised as nix run github:microsoft/apm from the README) is a worse first-run experience than no flake at all.
2. Membership in nixpkgs is the actual signal of "real Nix support" -- it reaches users via nix-shell -p apm / nix profile install nixpkgs#apm and shows up in the standard Nix discovery surfaces. An in-repo flake from one upstream contributor doesn't carry that signal.
3. It keeps audit responsibility with the Nix community, who are qualified to do it.

If you'd be up for shepherding APM into nixpkgs (or maintaining a separate flake repo), I'd happily coordinate any small upstream changes you need -- including using update_policy from #675 to disable self-update in the Nix build, the same way conda-forge does. Happy to link the resulting package prominently from the README and docs once it's available.

Leaving #540 closed for now, but very much open to revisiting via this route. Thanks again for the contribution and for caring enough to push on this.

[srid]

@danielmeppiel Makes full sense to me.

Somebody will eventually package apm in nixpkgs. Third-party packaging also exists, such as numtide/llm-agents.nix#3666.

All of those tend to be behind, so I've resolved to using nix shell nixpkgs#uv -c uvx git+... (uv works pretty well).