This page documents the structure and configuration of the flake.nix file, which defines the reproducible development environment for the StackOne AI SDK. It covers the flake's inputs, outputs, formatting tools, pre-commit hooks, and development shell configuration. For information about dependency pinning and version locking, see Nix Dependencies. For details on the agent skills system, see Agent Skills Integration.
The flake.nix file is structured as a standard Nix flake with inputs, outputs, and a flake-parts-based modular configuration. The flake provides a development shell (devShells.default) with all necessary tools, pre-commit hooks, and automatic dependency installation.
Flake Structure Diagram
Sources: flake.nix1-153
The flake declares seven inputs in the inputs attribute set, each serving a specific purpose in the development environment.
| Input Name | Source | Type | Purpose |
|---|---|---|---|
nixpkgs | github:NixOS/nixpkgs/nixpkgs-unstable | Flake | Base package repository |
flake-parts | github:hercules-ci/flake-parts | Flake | Modular flake structure |
git-hooks | github:cachix/git-hooks.nix | Flake | Pre-commit hook management |
treefmt-nix | github:numtide/treefmt-nix | Flake | Multi-language formatting |
agent-skills | github:Kyure-A/agent-skills-nix | Flake | Skill discovery system |
stackone-skills | github:StackOneHQ/skills | Non-flake | StackOne skill repository |
The agent-skills input follows nixpkgs to ensure version consistency:
The stackone-skills input is marked as flake = false because it's a non-flake repository used as a data source for skill discovery.
Sources: flake.nix4-17
The outputs function receives all inputs and uses the flake-parts.lib.mkFlake function to generate a modular flake structure. The flake supports three system architectures:
x86_64-linux (Intel/AMD Linux)aarch64-linux (ARM64 Linux)aarch64-darwin (Apple Silicon macOS)Agent Skills Initialization
Before the flake-parts configuration, agent skills are initialized outside the perSystem scope to allow access to inputs:
This initialization chain discovers skills from the stackone-skills repository, filters them through an allowlist (enabling just-commands and release-please), and produces a selection used later in the development shell.
Agent Skills Initialization Flow
Sources: flake.nix28-48 flake.nix50-55
The perSystem function generates system-specific outputs (formatter and devShell) for each supported architecture. It configures three main components: treefmt formatting, pre-commit hooks, and the development shell.
The treefmtEval variable holds the result of evaluating a treefmt-nix configuration, which defines formatting rules for multiple languages:
| Formatter | Purpose | File Patterns |
|---|---|---|
nixfmt | Format Nix files | *.nix |
ruff-check | Lint Python files | *.py |
ruff-format | Format Python files | *.py |
oxfmt | Format markdown/misc | All files except CHANGELOG.md |
The oxfmt formatter is configured with custom options to skip unmatched patterns and exclude the changelog:
The treefmtEval.config.build.wrapper is exposed as both the flake's formatter output and within the treefmt pre-commit hook.
Sources: flake.nix60-75 flake.nix110
The pre-commit-check variable configures three pre-commit hooks using git-hooks.lib.${system}.run:
| Hook | Tool | Purpose | Configuration |
|---|---|---|---|
gitleaks | gitleaks | Secret scanning | Runs gitleaks protect --staged --config .gitleaks.toml |
treefmt | treefmt | Multi-language formatting | Uses treefmtEval.config.build.wrapper |
ty | ty | Python type checking | Runs ty check on stackone_ai/ files only |
The gitleaks hook uses pass_filenames = false to scan all staged files, while the ty hook filters for Python files in the stackone_ai/ directory using files = "^stackone_ai/".
Pre-Commit Hook Execution Flow
Sources: flake.nix77-100
The bundle variable creates an agent skills bundle using agentLib.mkBundle, passing the previously computed selection:
The localTargets variable transforms the default local targets to use symlinks instead of copies:
This optimization avoids duplicating skill files on disk, using symlinks to point to the Nix store.
Sources: flake.nix103-107
The devShells.default attribute defines the development shell using pkgs.mkShellNoCC (no C compiler needed). It consists of two main parts: buildInputs and shellHook.
The buildInputs list declares all tools available in the development shell:
| Tool | Purpose | Category |
|---|---|---|
uv | Python package manager | Python tooling |
ty | Python type checker | Python tooling |
just | Task runner | Development automation |
nixfmt | Nix formatter | Code quality |
gitleaks | Secret scanner | Security |
bun | JavaScript runtime | Node.js tooling |
pnpm_10 | Node package manager | Node.js tooling |
typescript-go | TypeScript compiler | Node.js tooling |
The Node.js tools (bun, pnpm_10, typescript-go) are included to support the MCP mock server in vendor/stackone-ai-node/.
Sources: flake.nix113-126
The shellHook attribute defines shell initialization logic executed when entering the development environment. It performs four tasks:
1. Welcome Message
2. Git Submodule Initialization
Checks if .gitmodules exists and the MCP mock server isn't initialized, then runs git submodule update --init --recursive:
3. Python Dependency Installation
Installs Python dependencies with uv sync --all-extras --locked only if .venv is missing or uv.lock is newer than .venv:
This optimization avoids redundant uv sync calls when dependencies haven't changed.
4. Git Hook and Agent Skills Installation
Appends two shell hook fragments:
pre-commit-check.shellHook: Installs pre-commit hooksagentLib.mkShellHook: Installs agent skills to local targetsThe agent skills hook uses the bundle and localTargets variables to install skills as symlinks.
shellHook Execution Sequence
Sources: flake.nix128-149
The flake configuration is consumed by the setup-nix composite action in GitHub Actions workflows. The action uses nix profile install --inputs-from . to install specific packages from the flake's nixpkgs input:
This command installs packages (e.g., nixpkgs#uv, nixpkgs#ty, nixpkgs#just) using the same nixpkgs version as the flake, ensuring CI and local environments use identical tool versions.
The action then replicates the shellHook logic manually:
uv sync --all-extras --lockedpnpm install --frozen-lockfileThe skip-uv-sync input allows skipping steps 2-3 for jobs that don't need Python or Node.js dependencies.
CI/CD Environment Setup Flow
Sources: .github/actions/setup-nix/action.yaml15-50
The .envrc file enables automatic environment activation using direnv:
The watch_file uv.lock directive tells direnv to re-evaluate the environment when uv.lock changes, ensuring the development shell is updated after dependency changes. The use flake directive activates the devShells.default output from flake.nix.
When entering the project directory with direnv enabled, the shell automatically:
buildInputsshellHook (submodules, uv sync, pre-commit hooks, agent skills)Sources: .envrc1-3
The flake.nix file provides a declarative, reproducible development environment through:
This architecture ensures local development, CI, and collaboration all use identical tool versions, with automatic dependency installation and pre-commit hooks enforcing code quality standards.
Refresh this wiki