feat: add Nix flake for declarative builds and development

[smantzavinos]

Summary

• Add Nix flake support enabling nix run github:Fission-AI/OpenSpec and nix develop for reproducible builds and development environments
• Target nixos-25.11 stable channel for broad compatibility

Changes

• flake.nix: Declarative package definition with:

  • packages.default - Builds OpenSpec using pnpm
  • devShells.default - Dev environment with Node.js 22 + pnpm
  • apps.default - Enables nix run
  • Uses modern finalAttrs pattern and reads version from package.json

• flake.lock: Pinned dependencies (nixos-25.11, flake-utils)

• README.md: Added Nix installation section and contributing note

• .gitignore: Added result and .direnv/ entries

Testing

nix build        # ✓ Builds successfully
nix run . -- --version  # ✓ Returns 0.17.2
nix flake check  # ✓ Passes all checks

Summary by CodeRabbit

• New Features

  • Added Nix package support to install and run OpenSpec directly from source.
  • Added a Nix-based developer environment with Node.js and pnpm pre-configured.

• Documentation

  • Added an "Install with Nix" guide and contributor notes on entering the Nix development shell.

• Chores

  • Updated .gitignore to ignore Nix build artifacts.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds Nix support: a new flake.nix providing packages, devShells, and apps; README additions with Nix installation/dev instructions; and two Nix-related entries in .gitignore.

Changes

Cohort / File(s)	Summary
Nix Flake flake.nix	New flake defining packages.default (openspec derivation reading version from package.json, using nodejs/pnpm, custom build/install phases, wrapper via makeWrapper), devShells.default (nodejs + pnpm shell), and apps.default.
Documentation README.md	Added "Alternative: Install with Nix" section with commands to run OpenSpec from the repo and enter a nix dev shell; added cross-reference note in Contributing/Install guidance.
Ignore rules .gitignore	Added Nix header and two ignore lines: result and .direnv/.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Poem

🐇 A flake arrived with tidy cheer,
I hopped in devShells, pnpm near,
Wrappers set and build files neat,
README shows the Nixside street,
Hooray — OpenSpec's new Nix beat!

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding Nix flake support for declarative builds and development environments, which is the primary objective of this pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7703caf and 211ad26.

📒 Files selected for processing (1)

• flake.nix

🚧 Files skipped from review as they are similar to previous changes (1)

• flake.nix

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

flake.nix (1)

17-66: Well-structured derivation using modern patterns.

The use of finalAttrs pattern, reading version from package.json, and the pnpmConfigHook integration are all idiomatic. A few observations:

1. Hardcoded hash (line 32): The pnpmDeps hash will need updating whenever pnpm-lock.yaml changes. Consider documenting this in a comment or the README.

2. Empty maintainers list (line 62): Consider adding maintainer(s) for better discoverability if this gets upstreamed.

🔎 Optional: Add a comment about hash updates

          pnpmDeps = pkgs.fetchPnpmDeps {
            inherit (finalAttrs) pname version src;
+           # Update this hash when pnpm-lock.yaml changes:
+           # nix build 2>&1 | grep 'got:' | awk '{print $2}'
            hash = "sha256-vAlqVFaBN7KMlyP4HKbsMkaYrA5Yf2l5a+PLCZ6KOzs=";
            fetcherVersion = 3;
          };

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8dcd170 and 7703caf.

⛔ Files ignored due to path filters (1)

• flake.lock is excluded by !**/*.lock

📒 Files selected for processing (3)

• .gitignore
• README.md
• flake.nix

🧰 Additional context used

🧠 Learnings (3)

📚 Learning: 2025-11-25T01:08:19.004Z

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs

Applied to files:

• README.md

📚 Learning: 2025-11-25T01:08:19.004Z

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes

Applied to files:

• README.md

📚 Learning: 2025-11-25T01:08:19.004Z

Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Search existing work using `openspec spec list --long`, `openspec list` for enumerating changes; use `rg` only for full-text search

Applied to files:

• README.md

🔇 Additional comments (5)

.gitignore (1)

151-154: LGTM!

The Nix-related ignore entries are appropriate: result is the default symlink from nix build, and .direnv/ caches the nix develop environment when using direnv integration. The section header follows the existing file conventions.

README.md (2)

147-160: LGTM!

The collapsible Nix installation section is well-placed after the standard installation verification step. The commands are correct for flake-based usage, and using <details> keeps the primary installation path uncluttered for most users.

---

394-395: LGTM!

Clear and concise guidance for contributors using Nix.

flake.nix (2)

68-77: LGTM!

The development shell and app definitions are clean and functional. The dev shell correctly provides nodejs and pnpm matching the build environment.

---

4-7: nixos-25.11 is a valid, released channel.

The flake correctly pins to nixos-25.11, which was released on November 30, 2025. This is the current stable release and an appropriate target for the project.