Initialize Nix overlay repository with blueprint, goose-cli, and docs

Add the complete overlay structure using numtide/blueprint with:
- Two overlay strategies (default and shared-nixpkgs)
- goose-cli package with custom librusty_v8 fetcher
- Interactive package launcher via fzf
- Flake input caching utility
- Comprehensive README and AGENTS.md documentation

packages/default/default.nix

@@ -0,0 +1,19 @@
+{
+  pkgs,
+  perSystem,
+  ...
+}:
+let
+  allPackages = perSystem.self;
+
+  # Filter to visible, runnable packages
+  visibleNames = builtins.filter (
+    name: name != "default" && !(allPackages.${name}.passthru.hideFromDocs or false)
+  ) (builtins.attrNames allPackages);
+
+  # Build "name\tdescription" lines
+  packageLines = map (name: "${name}\t${allPackages.${name}.meta.description or ""}") visibleNames;
+
+  packageList = builtins.concatStringsSep "\n" packageLines;
+in
+pkgs.callPackage ./package.nix { inherit packageList; }

packages/default/package.nix

@@ -0,0 +1,60 @@
+{
+  lib,
+  writeShellApplication,
+  fzf,
+  nix,
+  util-linux,
+  packageList,
+}:
+
+let
+  packageListFile = builtins.toFile "millerson-overlay-packages.tsv" packageList;
+in
+writeShellApplication {
+  name = "millerson-overlay-launcher";
+
+  runtimeInputs = [
+    fzf
+    nix
+    util-linux # column
+  ];
+
+  text = ''
+    # Format for fzf: "name  description" (tab-aligned)
+    entries=$(column -t -s $'\t' < "${packageListFile}")
+
+    if [[ -z $entries ]]; then
+      echo "No packages found" >&2
+      exit 1
+    fi
+
+    # Let user pick with fzf
+    selected=$(echo "$entries" | fzf \
+      --header="Select an pkg to run (ESC to cancel)" \
+      --preview-window=hidden \
+      --no-multi \
+      --height=~40% \
+      --layout=reverse) || exit 0
+
+    # Extract package name (first word)
+    pkg_name=$(echo "$selected" | awk '{print $1}')
+
+    if [[ -z $pkg_name ]]; then
+      exit 0
+    fi
+
+    echo "→ Running: nix run git.millerson.name/alex/nix-overlay.git#$pkg_name"
+    exec nix run "git.millerson.name/alex/nix-overlay.git#$pkg_name"
+  '';
+
+  meta = with lib; {
+    description = "Interactive fzf launcher for millerson-overlay.nix packages";
+    license = licenses.mit;
+    mainProgram = "millerson-overlay-launcher";
+    platforms = platforms.all;
+  };
+
+  passthru = {
+    hideFromDocs = true;
+  };
+}

packages/flake-inputs/default.nix

@@ -0,0 +1,12 @@
+{
+  inputs,
+  pkgs,
+  ...
+}:
+# A derivation that references all flake inputs to ensure they get cached
+pkgs.runCommand "flake-inputs" { } ''
+  echo ${pkgs.lib.concatMapStringsSep " " (name: inputs.${name}) (builtins.attrNames inputs)} > $out
+''
+// {
+  passthru.hideFromDocs = true;
+}

packages/goose-cli/default.nix

@@ -0,0 +1,9 @@
+{
+  pkgs,
+  ...
+}:
+pkgs.callPackage ./package.nix {
+  librusty_v8 = pkgs.callPackage ./librusty_v8.nix {
+    inherit (pkgs.callPackage ./fetchers.nix { }) fetchLibrustyV8;
+  };
+}

packages/goose-cli/fetchers.nix

@@ -0,0 +1,21 @@
+# Fetchers for goose-cli pre-built dependencies
+# Based on deno's approach for handling rusty_v8
+{
+  lib,
+  stdenv,
+  fetchurl,
+}:
+
+{
+  fetchLibrustyV8 =
+    args:
+    fetchurl {
+      name = "librusty_v8-${args.version}";
+      url = "https://github.com/denoland/rusty_v8/releases/download/v${args.version}/librusty_v8_release_${stdenv.hostPlatform.rust.rustcTarget}.a.gz";
+      sha256 = args.shas.${stdenv.hostPlatform.system};
+      meta = {
+        inherit (args) version;
+        sourceProvenance = with lib.sourceTypes; [ binaryNativeCode ];
+      };
+    };
+}

packages/goose-cli/librusty_v8.nix

@@ -0,0 +1,13 @@
+# Pre-built librusty_v8 library for goose-cli
+# This file specifies the rusty_v8 version and hashes for all supported platforms
+{ fetchLibrustyV8 }:
+
+fetchLibrustyV8 {
+  version = "145.0.0";
+  shas = {
+    x86_64-linux = "sha256-chV1PAx40UH3Ute5k3lLrgfhih39Rm3KqE+mTna6ysE=";
+    aarch64-linux = "sha256-4IivYskhUSsMLZY97+g23UtUYh4p5jk7CzhMbMyqXyY=";
+    x86_64-darwin = "sha256-1jUuC+z7saQfPYILNyRJanD4+zOOhXU2ac/LFoytwho=";
+    aarch64-darwin = "sha256-yHa1eydVCrfYGgrZANbzgmmf25p7ui1VMas2A7BhG6k=";
+  };
+}

packages/goose-cli/package.nix

@@ -0,0 +1,71 @@
+{
+  lib,
+  fetchFromGitHub,
+  rustPlatform,
+  pkg-config,
+  openssl,
+  libxcb,
+  dbus,
+  versionCheckHook,
+  librusty_v8,
+}:
+
+rustPlatform.buildRustPackage rec {
+  pname = "goose-cli";
+  version = "1.33.1";
+
+  src = fetchFromGitHub {
+    owner = "block";
+    repo = "goose";
+    rev = "v${version}";
+    hash = "sha256-FBICGOfVs2jbOdLWSInqfTYBdnCcbcGWHwqY/b6v8eg=";
+  };
+
+  cargoHash = "sha256-fN0FKDYFkZrQQPWdUlemOaGzIAZhqFyskz9TEmG+X4o=";
+
+  nativeBuildInputs = [ pkg-config ];
+
+  buildInputs = [
+    openssl
+    libxcb
+    dbus
+  ];
+
+  # The v8 package will try to download a `librusty_v8.a` release at build time to our read-only filesystem
+  # To avoid this we pre-download the file and export it via RUSTY_V8_ARCHIVE
+  env.RUSTY_V8_ARCHIVE = librusty_v8;
+
+  # Build only the CLI package
+  cargoBuildFlags = [
+    "--package"
+    "goose-cli"
+  ];
+
+  # Enable tests with proper environment
+  doCheck = true;
+  checkPhase = ''
+    export HOME=$(mktemp -d)
+    export XDG_CONFIG_HOME=$HOME/.config
+    export XDG_DATA_HOME=$HOME/.local/share
+    export XDG_STATE_HOME=$HOME/.local/state
+    export XDG_CACHE_HOME=$HOME/.cache
+    mkdir -p $XDG_CONFIG_HOME $XDG_DATA_HOME $XDG_STATE_HOME $XDG_CACHE_HOME
+
+    # Run tests for goose-cli package only
+    cargo test --package goose-cli --release
+  '';
+
+  doInstallCheck = true;
+  nativeInstallCheckInputs = [ versionCheckHook ];
+
+  passthru.category = "AI Coding Agents";
+
+  meta = with lib; {
+    description = "CLI for Goose - a local, extensible, open source AI agent that automates engineering tasks";
+    homepage = "https://github.com/block/goose";
+    changelog = "https://github.com/block/goose/releases/tag/v${version}";
+    license = licenses.asl20;
+    sourceProvenance = with sourceTypes; [ fromSource ];
+    mainProgram = "goose";
+  };
+}

packages/goose-cli/update.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env nix
+#! nix shell --inputs-from .# nixpkgs#python3 --command python3
+
+"""Update script for goose-cli package.
+
+This script updates both the goose-cli version and the librusty_v8 hashes.
+The v8 version is extracted from the Cargo.lock file of the goose repository.
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "scripts"))
+
+from updater import (
+    calculate_platform_hashes,
+    fetch_text,
+    load_hashes,
+    save_hashes,
+)
+
+HASHES_FILE = Path(__file__).parent / "librusty_v8_hashes.json"
+
+PLATFORMS = {
+    "x86_64-linux": "x86_64-unknown-linux-gnu",
+    "aarch64-linux": "aarch64-unknown-linux-gnu",
+    "x86_64-darwin": "x86_64-apple-darwin",
+    "aarch64-darwin": "aarch64-apple-darwin",
+}
+
+
+def fetch_v8_version_from_cargo_lock(goose_version: str) -> str:
+    """Extract the v8 version from goose's Cargo.lock file."""
+    url = f"https://raw.githubusercontent.com/block/goose/v{goose_version}/Cargo.lock"
+    cargo_lock = fetch_text(url)
+
+    # Parse the Cargo.lock to find v8 version
+    lines = cargo_lock.split("\n")
+    for i, line in enumerate(lines):
+        if line.strip() == 'name = "v8"':
+            # Look for version in the next few lines
+            for j in range(i + 1, min(i + 10, len(lines))):
+                if "version = " in lines[j]:
+                    return lines[j].split('"')[1]
+
+    msg = "Could not find v8 version in Cargo.lock"
+    raise ValueError(msg)
+
+
+def main() -> None:
+    """Update the librusty_v8 hashes for goose-cli."""
+    # Read the current goose-cli version from package.nix
+    package_nix = (Path(__file__).parent / "package.nix").read_text()
+    for line in package_nix.split("\n"):
+        if "version = " in line and '"' in line:
+            goose_version = line.split('"')[1]
+            break
+    else:
+        msg = "Could not find version in package.nix"
+        raise ValueError(msg)
+
+    print(f"Goose version: {goose_version}")
+
+    # Get the v8 version from Cargo.lock
+    v8_version = fetch_v8_version_from_cargo_lock(goose_version)
+    print(f"V8 version: {v8_version}")
+
+    # Check if we need to update
+    try:
+        data = load_hashes(HASHES_FILE)
+        current_v8 = data.get("version", "")
+        if current_v8 == v8_version:
+            print(f"V8 hashes already up to date ({v8_version})")
+            return
+    except FileNotFoundError:
+        print("No existing hashes file, creating new one")
+
+    # Calculate hashes for all platforms
+    url_template = f"https://github.com/denoland/rusty_v8/releases/download/v{v8_version}/librusty_v8_release_{{platform}}.a.gz"
+    hashes = calculate_platform_hashes(url_template, PLATFORMS)
+
+    # Save the hashes
+    save_hashes(HASHES_FILE, {"version": v8_version, "hashes": hashes})
+
+    # Update librusty_v8.nix
+    librusty_v8_nix = Path(__file__).parent / "librusty_v8.nix"
+    content = f"""# Pre-built librusty_v8 library for goose-cli
+# This file specifies the rusty_v8 version and hashes for all supported platforms
+{{ fetchLibrustyV8 }}:
+
+fetchLibrustyV8 {{
+  version = "{v8_version}";
+  shas = {{
+    x86_64-linux = "{hashes["x86_64-linux"]}";
+    aarch64-linux = "{hashes["aarch64-linux"]}";
+    x86_64-darwin = "{hashes["x86_64-darwin"]}";
+    aarch64-darwin = "{hashes["aarch64-darwin"]}";
+  }};
+}}
+"""
+    librusty_v8_nix.write_text(content)
+
+    print(f"Updated librusty_v8 to {v8_version}")
+
+
+if __name__ == "__main__":
+    main()