nsbx: add one-command dev onboarding (branch + worktree + isolated engram)

Add 'nsbx dev <name>' / 'nsbx dev-down <name>' plus a Makefile so a newcomer goes from clone to coding on an isolated cloned engram in one command. The worktree is created on a real named branch at a persistent path (never /tmp, guarded), and the whole worktree is pinned to the clone via an emitted .nsbx-env so live :8742 / ~/.neuron/engram is unreachable by accident. Optimizes the El edit->build->run loop so provisional work is built in El against a throwaway clone instead of prototyped in Python and re-ported. Additive over the proven primitives; no live cutover.
2026-08-14 17:24:06 -05:00
parent 112bb2540f
commit 6660becfdb
3 changed files with 295 additions and 0 deletions
@@ -0,0 +1,64 @@
+# nsbx — Neuron dev-environment Makefile
+# ---------------------------------------------------------------------------
+# Thin, documented wrappers over the `nsbx` primitive so a newcomer never has to
+# memorise the elc/cc build incantation or the sandbox lifecycle. Every target is
+# a one-liner over `nsbx`; nothing here reimplements engram logic.
+#
+#   make dev NAME=tim        # new branch + worktree + isolated engram, one shot
+#   make status NAME=tim     # inspect it (omit NAME to list all sandboxes)
+#   make run NAME=tim        # poke its API (API=/api/stats by default)
+#   make test NAME=tim       # run the safety rails as checks (nsbx validate)
+#   make build NAME=tim      # compile the worktree's changes into the engram
+#   make destroy NAME=tim    # tear it all down (branch kept)
+#
+# The isolated engram is ALWAYS a clone of the live store on a NON-default port;
+# prod (:8742 / :7770) is untouchable from here.
+# ---------------------------------------------------------------------------
+
+# locate nsbx next to this Makefile, regardless of where make is run from
+NSBX := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))nsbx
+SBX  := dev-$(NAME)
+API  ?= /api/stats
+
+.DEFAULT_GOAL := help
+
+.PHONY: help dev build run test status list destroy bt
+
+help: ## Show this help
+	@echo "nsbx dev-environment — one-command isolated Neuron dev setup"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(firstword $(MAKEFILE_LIST)) \
+	  | awk 'BEGIN{FS=":.*?## "}{printf "  make %-22s %s\n", $$1, $$2}'
+	@echo ""
+	@echo "  Variables:  NAME=<dev name> (required for most)   API=<path> (run)"
+	@echo "              BASE=<git ref>  WT=<worktree dir>  PORT=<n>  ARGS=<extra nsbx flags>"
+
+dev: ## Create branch + worktree + isolated engram (NAME=x [BASE=ref PORT=n WT=dir ARGS=...])
+	@test -n "$(NAME)" || { echo "usage: make dev NAME=<name>"; exit 2; }
+	$(NSBX) dev $(NAME) $(if $(BASE),--base $(BASE)) $(if $(PORT),--port $(PORT)) $(if $(WT),--worktree $(WT)) $(ARGS)
+
+build: ## Rebuild the engram from the dev worktree's own source (NAME=x)
+	@test -n "$(NAME)" || { echo "usage: make build NAME=<name>"; exit 2; }
+	@wt=$$(python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/.neuron/sandboxes/$(SBX)/dev.json')))['worktree'])" 2>/dev/null); \
+	 test -n "$$wt" || { echo "no dev.json for $(SBX) — run 'make dev NAME=$(NAME)' first"; exit 2; }; \
+	 $(NSBX) build $(SBX) --source "$$wt"
+
+bt: build run ## Fast El loop: rebuild the engram from the worktree, then poke it (NAME=x)
+
+run: ## Poke the isolated engram's API (NAME=x [API=/api/stats])
+	@test -n "$(NAME)" || { echo "usage: make run NAME=<name> [API=/path]"; exit 2; }
+	$(NSBX) run $(SBX) api $(API)
+
+test: ## Run the safety rails as checks: zero-loss, reboot, RSS, parity, keystones (NAME=x)
+	@test -n "$(NAME)" || { echo "usage: make test NAME=<name>"; exit 2; }
+	$(NSBX) validate $(SBX)
+
+status: ## Show one sandbox's status (NAME=x), or list all if NAME is unset
+	@if [ -n "$(NAME)" ]; then $(NSBX) status $(SBX); else $(NSBX) list; fi
+
+list: ## List all sandboxes
+	$(NSBX) list
+
+destroy: ## Tear down engram + worktree (NAME=x [ARGS=--delete-branch])
+	@test -n "$(NAME)" || { echo "usage: make destroy NAME=<name>"; exit 2; }
+	$(NSBX) dev-down $(NAME) $(ARGS)