Merge pull request #1 from compoundingtech/add-nix-flake-and-ci

Add Nix flake + `nix flake check` CI

Author: schickling

.github/workflows/nix.yml

@@ -0,0 +1,17 @@
+name: Nix
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/determinate-nix-action@v3
+      # `nix flake check` rather than `nix build`: it builds the package *and*
+      # evaluates every `checks.*`, so fmt, clippy, the hermetic test suite, and
+      # the `--help` smoke test all gate the PR from one entrypoint.
+      - run: nix flake check --print-build-logs

.gitignore

@@ -1,5 +1,8 @@
 /target
 
+# Nix build symlink.
+/result
+
 # Per-agent runtime overlay (materialized per clone; machine-specific, never product).
 .st2/
 .claude/

Cargo.lock

@@ -18,6 +18,7 @@ path = "src/lib.rs"
 # folder watch + a sleep), so no tokio. Deps grow per milestone; M0 needs only parse + CLI.
 anyhow = "1"
 clap = { version = "4", features = ["derive"] }
+clap_complete = "4"
 kdl = "6"
 libc = "0.2"
 notify = "8"

Cargo.toml

@@ -1,16 +1,33 @@
-//! Capture the git short-sha at build time for `st2 --version` (semver + sha, per convention).
+//! Bake a LocalStamp for `st2 --version` on a plain `cargo build`, per the shared
+//! build-versioning contract. Emitted as `ST2_BUILD_STAMP_LOCAL` — a private var
+//! distinct from the fleet's `CLI_BUILD_STAMP`, so the flake's authoritative
+//! NixStamp can never be overridden by this (see src/version.rs). A hermetic Nix
+//! build has no `.git`, so this yields nothing there and the NixStamp is used.
 use std::process::Command;
 
+fn git(args: &[&str]) -> Option<String> {
+    let out = Command::new("git").args(args).output().ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let s = String::from_utf8_lossy(&out.stdout).trim().to_string();
+    (!s.is_empty()).then_some(s)
+}
+
 fn main() {
-    let sha = Command::new("git")
-        .args(["rev-parse", "--short", "HEAD"])
-        .output()
-        .ok()
-        .filter(|o| o.status.success())
-        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
-        .filter(|s| !s.is_empty())
-        .unwrap_or_else(|| "unknown".to_string());
-    println!("cargo:rustc-env=ST2_GIT_SHA={sha}");
+    if let Some(rev) = git(&["rev-parse", "--short", "HEAD"]) {
+        let dirty = git(&["status", "--porcelain"]).is_some_and(|s| !s.is_empty());
+        let commit_ts = git(&["log", "-1", "--format=%ct"])
+            .and_then(|s| s.parse::<i64>().ok())
+            .unwrap_or(0);
+        // Hand-assembled JSON: the short-sha is hex so no escaping is needed, and
+        // this avoids a build-dependency just to serialize three fields.
+        let stamp =
+            format!(r#"{{"type":"local","rev":"{rev}","commitTs":{commit_ts},"dirty":{dirty}}}"#);
+        println!("cargo:rustc-env=ST2_BUILD_STAMP_LOCAL={stamp}");
+    }
+    // Rebuild the stamp when HEAD moves or the working tree changes (dirty flag).
     println!("cargo:rerun-if-changed=.git/HEAD");
     println!("cargo:rerun-if-changed=.git/refs");
+    println!("cargo:rerun-if-changed=.git/index");
 }

build.rs

@@ -0,0 +1,162 @@
+{
+  description = "st2 - harness-agnostic runner: reconcile a catalog+inbox folder of agent specs, keep their ptys running, deliver messages by moving files";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs =
+    {
+      self,
+      nixpkgs,
+      flake-utils,
+    }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
+      let
+        pkgs = import nixpkgs { inherit system; };
+
+        # Cargo.toml is the single source of truth for the version, so a release
+        # bump needs no matching edit here.
+        version = (builtins.fromTOML (builtins.readFile ./Cargo.toml)).package.version;
+
+        # NixStamp for the shared build-versioning contract: the flake rev is a
+        # pure input, so baking it lets a hermetic build know its own identity
+        # without an impure `.git` read. Same env var + JSON shape as the rest of
+        # the fleet (TS `@overeng/utils/node/cli-version`; the otel-scrape Rust
+        # reader) — `src/version.rs` reads it via `option_env!("CLI_BUILD_STAMP")`.
+        # `self.shortRev`/`lastModified` are absent only for a dirty tree, where
+        # `dirtyShortRev` and the working-tree mtime stand in and `dirty` is true.
+        buildStamp = builtins.toJSON {
+          type = "nix";
+          inherit version;
+          rev = self.shortRev or self.dirtyShortRev or "unknown";
+          commitTs = self.lastModified or 0;
+          dirty = !(self ? rev);
+        };
+
+        completionShells = [
+          "bash"
+          "zsh"
+          "fish"
+        ];
+
+        st2 = pkgs.rustPlatform.buildRustPackage {
+          pname = "st2";
+          inherit version;
+          src = self;
+
+          # No git or crates.io-yanked deps in the lockfile, so the lockfile
+          # alone pins every input reproducibly — no per-dep outputHashes, and
+          # nothing here to hand-patch when a dep bumps.
+          cargoLock.lockFile = ./Cargo.lock;
+
+          # This NixStamp is the binary's authoritative build identity; it wins
+          # over the LocalStamp `build.rs` bakes from git (which is empty here
+          # anyway — a flake source carries no `.git`). Reaches rustc as a plain
+          # env var, captured at compile time by `option_env!` (see
+          # src/version.rs). A derivation env var change rebuilds the crate.
+          CLI_BUILD_STAMP = buildStamp;
+
+          # `git` is present for the tests below (they init throwaway repos);
+          # `installShellFiles` provides `installShellCompletion`.
+          nativeBuildInputs = [
+            pkgs.git
+            pkgs.installShellFiles
+          ];
+
+          # Completions are generated by the binary we just built (never
+          # committed), so they cannot drift from the actual command tree —
+          # `checks.completions` gates that.
+          postInstall = ''
+            ${pkgs.lib.concatMapStringsSep "\n" (shell: ''
+              $out/bin/st2 completions ${shell} > completions-${shell}
+            '') completionShells}
+
+            installShellCompletion --cmd st2 \
+              --bash completions-bash \
+              --zsh completions-zsh \
+              --fish completions-fish
+          '';
+
+          # Run only the hermetic **unit** tests (`--lib --bins`). The integration
+          # tests in `tests/*.rs` each assume a real environment the Nix build
+          # sandbox deliberately lacks — `/bin/bash` + `jq` (the shipped Codex
+          # hooks), `/usr/bin/git` on a hardcoded `PATH` (materialize's
+          # git-worktree safety check), and a live `pty` / `convoy` / systemd
+          # `--user` manager (the survival + render-neutrality gates). Chasing
+          # those with per-test skips is unbounded as the suite grows, so they run
+          # on native CI (real runner) while the flake proves the package here:
+          # it builds, its ~150 pure unit tests pass, and `--help`/completions
+          # smoke-test the wired binary below.
+          cargoTestFlags = [
+            "--lib"
+            "--bins"
+          ];
+
+          # A few unit tests write under $HOME; the sandbox HOME is not writable.
+          preCheck = "export HOME=$(mktemp -d)";
+
+          meta = {
+            description = "Harness-agnostic runner over a unified catalog+inbox folder of agent specs";
+            homepage = "https://github.com/compoundingtech/st2";
+            license = pkgs.lib.licenses.mit;
+            mainProgram = "st2";
+          };
+        };
+      in
+      {
+        packages.st2 = st2;
+        packages.default = st2;
+
+        # `nix flake check` is the whole CI: it builds the package — which runs
+        # the hermetic portion of the in-tree `cargo test` suite via doCheck —
+        # and evaluates the `--help` + completions smoke tests below.
+        #
+        # `cargo fmt --check` / `clippy -D warnings` are intentionally NOT gated:
+        # this is a packaging PR on an actively-developed, hand-crafted tree, and a
+        # repo-wide formatting/lint gate here would fight the maintainer's own
+        # commits on every rebase. The devShell ships rustfmt + clippy for whoever
+        # wants them.
+        checks.st2 = st2;
+
+        # Smoke test that the built binary actually runs and its command tree is
+        # wired, independent of the in-tree `cargo test`.
+        checks.help = pkgs.runCommand "st2-help-${version}" { } ''
+          export HOME=$(mktemp -d)
+          ${st2}/bin/st2 --help > /dev/null
+          ${st2}/bin/st2 ls --help > /dev/null
+          touch $out
+        '';
+
+        # Guards the completions contract: every shell we install still generates
+        # a non-empty script, and fish in particular still binds to `st2` (the
+        # name the installed st2.fish file claims). Written to files first —
+        # clap_complete streams to stdout and panics on a `grep -q` early
+        # pipe-close (BrokenPipe), which the real `> file` usage never hits.
+        checks.completions = pkgs.runCommand "st2-completions-${version}" { } ''
+          ${pkgs.lib.concatMapStringsSep "\n" (shell: ''
+            ${st2}/bin/st2 completions ${shell} > ${shell}.out
+            test -s ${shell}.out || { echo "empty ${shell} completions" >&2; exit 1; }
+          '') completionShells}
+
+          grep -q 'complete -c st2' fish.out \
+            || { echo "fish completions do not bind to \`st2\`" >&2; exit 1; }
+
+          touch $out
+        '';
+
+        devShells.default = pkgs.mkShell {
+          packages = [
+            pkgs.cargo
+            pkgs.rustc
+            pkgs.clippy
+            pkgs.rustfmt
+            pkgs.rust-analyzer
+            pkgs.git
+          ];
+        };
+      }
+    );
+}

flake.lock

@@ -29,6 +29,7 @@ pub(crate) mod shepherd;
 pub mod spec;
 pub mod status;
 pub mod validate;
+pub mod version;
 
 pub use discovery::{Discovered, SpecError, discover};
 pub use exec_backend::ExecBackend;

flake.nix

@@ -6,7 +6,7 @@ use std::path::{Path, PathBuf};
 use std::time::Duration;
 
 use anyhow::{Context, Result};
-use clap::{Args, Parser, Subcommand};
+use clap::{Args, CommandFactory, Parser, Subcommand};
 
 use st2::{
     HostLock, Runner, SystemRunner, UpReport, detect_host, ding, discover, exec_state_dir, message,
@@ -16,7 +16,7 @@ use st2::{
 #[derive(Parser)]
 #[command(
     name = "st2",
-    version = concat!(env!("CARGO_PKG_VERSION"), " (", env!("ST2_GIT_SHA"), ")"),
+    version = st2::version::display_version(),
     about = "Harness-agnostic runner over a unified catalog+inbox folder"
 )]
 struct Cli {
@@ -248,6 +248,12 @@ enum Command {
         #[command(flatten)]
         ctx: MsgCtx,
     },
+    /// Print a shell completion script for `st2` to stdout (`st2 completions <bash|zsh|fish|…>`).
+    /// Generated from the live command tree, so it never drifts from the actual flags.
+    Completions {
+        /// The shell to generate completions for.
+        shell: clap_complete::Shell,
+    },
 }
 
 /// Shared context for message subcommands: where the catalog is, who "I" am, and the local host.
@@ -550,6 +556,13 @@ fn main() -> Result<()> {
             let root = catalog_arg(root)?;
             doctor_cmd(&root, host)
         }
+        Command::Completions { shell } => {
+            // Generate from the live command tree so the script can never drift
+            // from the actual flags (the flake gates this at build time).
+            let mut cmd = Cli::command();
+            clap_complete::generate(shell, &mut cmd, "st2", &mut std::io::stdout());
+            Ok(())
+        }
     }
 }