Prepare development environment for Amp orbs

.agents/resume

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# The repository currently has no persistent local services to repair after an
+# orb wake. If services are added, declare them in .amp/services.yaml and run
+# `amp orb services ensure` here rather than starting unmanaged processes.
+:

.agents/setup

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "Installing orb prerequisites..."
+if ! command -v direnv >/dev/null 2>&1; then
+  sudo apt-get update
+  sudo DEBIAN_FRONTEND=noninteractive apt-get install -y direnv
+fi
+
+# Make the repository's existing .envrc activate in interactive orb terminals.
+direnv_hook='eval "$(direnv hook bash)"'
+if ! grep -Fqx "$direnv_hook" "$HOME/.bashrc"; then
+  printf '\n%s\n' "$direnv_hook" >> "$HOME/.bashrc"
+fi
+
+if ! command -v nix >/dev/null 2>&1 \
+  && [ ! -x /nix/var/nix/profiles/default/bin/nix ]; then
+  curl --proto '=https' --tlsv1.2 -fsSL https://install.determinate.systems/nix \
+    | sh -s -- install --no-confirm
+fi
+
+# The installer updates future login shells, but this setup process also needs Nix.
+if [ -f /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
+  # shellcheck disable=SC1091
+  source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
+fi
+
+# Amp commands use non-login shells, so expose Nix on their existing PATH too.
+mkdir -p "$HOME/.local/bin"
+ln -sfn /nix/var/nix/profiles/default/bin/nix "$HOME/.local/bin/nix"
+
+echo "Preparing the pinned Nix development environment..."
+direnv allow .
+eval "$(direnv export bash)"
+npm ci
+spago build
+
+echo "Orb setup complete."

AGENTS.md

@@ -13,6 +13,13 @@ We use Nix with direnv. Expect to be in a Nix shell automatically, but if you ar
 nix develop
 ```
 
+Orb setup configures interactive terminals to load `.envrc` automatically, so bare commands such as `spago build` work there. Amp's non-login command shells do not load `.envrc`; in those shells, prefix commands that need the development environment with `direnv exec .`, for example:
+
+```sh
+direnv exec . spago build
+direnv exec . spago test
+```
+
 ### Nix Quirks
 
 - If Nix tries to fetch from git during a build and fails, then most likely `spago.yaml` files have been changed but the lockfiles were not updated. Update them with `spago build`.