fix: refresh local serve and build workflow

CONTRIBUTING.md

@@ -24,6 +24,8 @@ Common commands:
 make help
 make test
 make lint
+make build
+make serve ecommerce
 make web
 make audit-public
 go run src/main.go --help
@@ -37,10 +39,13 @@ Useful fixture commands:
 ```bash
 make validate demo
 make scan ecommerce
-make graph migration
+make export-json-graph migration
+make export-json-visualisation migration
 make serve ecommerce
 ```
 
+`make build` auto-refreshes the embedded web bundle when the frontend sources are newer than `src/internal/webui/dist/`. `make serve <fixture>` always rebuilds the embedded web bundle first, then rebuilds the binary, so local explorer testing always uses the latest app state. Use `make web` when you want an explicit frontend-only rebuild without building a binary.
+
 ## Frontend changes
 
 The web explorer source lives under `src/internal/webui/frontend/`.

Makefile

@@ -3,7 +3,7 @@ FIXTURES := $(EXAMPLE_FIXTURES) playground
 FIXTURE ?= demo
 PRIMARY_GOAL := $(firstword $(MAKECMDGOALS))
 SECOND_GOAL := $(word 2,$(MAKECMDGOALS))
-POSITIONAL_FIXTURE_COMMANDS := validate scan graph serve
+POSITIONAL_FIXTURE_COMMANDS := validate scan export-json-graph export-json-visualisation serve
 
 ifneq ($(filter $(PRIMARY_GOAL),$(POSITIONAL_FIXTURE_COMMANDS)),)
 ifneq ($(filter $(SECOND_GOAL),$(FIXTURES)),)
@@ -17,18 +17,18 @@ endif
 .PHONY: help fixtures build web install-dev-tools install-git-hooks init-hooks \
 	test-go test lint vet fmt cli-help \
 	testing-help testing-build testing-init playground-init audit-public \
-	validate scan graph serve run
+	validate scan export-json-graph export-json-visualisation serve run
 
 help: ## Show grouped development, verification, and fixture commands
 	@./scripts/help.sh
 
 fixtures: ## List discovered fixtures
 	@for fixture in $(FIXTURES); do echo "$$fixture"; done
 
-build: ## Build the local mapture binary into build/
+build: ## Build the latest local binary into build/, refreshing embedded web if stale
 	@./scripts/build.sh
 
-web: ## Rebuild the frontend bundle under src/internal/webui/dist/
+web: ## Rebuild only the frontend bundle under src/internal/webui/dist/
 	@go run ./scripts/build-web
 
 install-dev-tools: ## Install local Go dev tools into testing/tools/bin
@@ -73,33 +73,39 @@ testing-init: ## Run init against testing/playground
 playground-init: ## Run init against the gitignored testing playground
 	@$(MAKE) --no-print-directory testing-init
 
-validate: ## Validate a fixture through testing/: make validate FIXTURE=<fixture|all>
+validate: ## Validate a fixture through testing/: make validate ecommerce or FIXTURE=ecommerce
 	@./scripts/go.sh validate "$(FIXTURE)"
 
 scan: ## Scan a fixture and write testing/outputs/<fixture>.scan.json; FIXTURE=all scans all examples
 	@./scripts/go.sh scan "$(FIXTURE)"
 
-graph: ## Export Mermaid for a fixture into testing/outputs/<fixture>.mmd; FIXTURE=all graphs all examples
-	@./scripts/go.sh graph "$(FIXTURE)"
+export-json-graph: ## Export JGF for a fixture into testing/outputs/<fixture>.graph.json; FIXTURE=all exports all examples
+	@./scripts/go.sh export-json-graph "$(FIXTURE)"
 
-serve: ## Rebuild testing/bin/mapture and run the local server against a fixture
+export-json-visualisation: ## Export explorer JSON into testing/outputs/<fixture>.visualisation.json; FIXTURE=all exports all examples
+	@./scripts/go.sh export-json-visualisation "$(FIXTURE)"
+
+serve: ## Always rebuild the embedded UI and binary, then run the local server against a fixture
 	@./scripts/go.sh serve "$(FIXTURE)"
 
 run: ## Run any CLI command for a fixture: make run FIXTURE=<fixture> CMD=<cli-command>
 	@if [ -z "$(CMD)" ]; then echo 'Usage: make run FIXTURE=<fixture> CMD="<cli-command>"'; exit 1; fi
 	@./scripts/go.sh fixture "$(FIXTURE)" $(CMD)
 
 define MAKE_FIXTURE_TARGETS
-.PHONY: validate.$(1) scan.$(1) graph.$(1) serve.$(1)
+.PHONY: validate.$(1) scan.$(1) export-json-graph.$(1) export-json-visualisation.$(1) serve.$(1)
 
 validate.$(1):
 	@$(MAKE) --no-print-directory validate FIXTURE=$(1)
 
 scan.$(1):
 	@$(MAKE) --no-print-directory scan FIXTURE=$(1)
 
-graph.$(1):
-	@$(MAKE) --no-print-directory graph FIXTURE=$(1)
+export-json-graph.$(1):
+	@$(MAKE) --no-print-directory export-json-graph FIXTURE=$(1)
+
+export-json-visualisation.$(1):
+	@$(MAKE) --no-print-directory export-json-visualisation FIXTURE=$(1)
 
 serve.$(1):
 	@$(MAKE) --no-print-directory serve FIXTURE=$(1)

README.md

@@ -30,6 +30,15 @@ Then open the local explorer and inspect the bundled example graph.
 For the repo’s day-to-day wrappers and testing helpers, run `make help`.
 Release packaging and distribution scripts live under `scripts/release/`.
 
+For local development:
+
+```bash
+make build
+make serve ecommerce
+```
+
+`make build` refreshes the embedded web bundle automatically when the frontend is stale. `make serve <fixture>` always rebuilds the embedded web bundle first, then rebuilds the binary, so the local explorer reflects the latest frontend and backend changes. Use `make web` only when you want a frontend-only rebuild.
+
 Once installed, `mapture --help` and `mapture --version` show the current version, detected release channel, install source, and whether a newer build is available for that channel.
 
 ## Install

scripts/build.sh

@@ -4,5 +4,10 @@ set -euo pipefail
 source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib.sh"
 
 ROOT_DIR="$(root_dir)"
+OUTPUT="$ROOT_DIR/build/mapture"
 
-build_binary "$ROOT_DIR/build/mapture"
+mapture_print_section "Local Build"
+ensure_embedded_web_bundle
+build_binary "$OUTPUT"
+print_binary_summary "local build" "$OUTPUT"
+printf '%s\n' "$(mapture_success "build complete")"

scripts/go.sh

@@ -66,6 +66,16 @@ fixture_output() {
   printf '%s/%s.%s\n' "$OUTPUTS_DIR" "$fixture" "$kind"
 }
 
+ensure_testing_binary() {
+  local command="${1:-}"
+  if [[ "$command" == "serve" ]]; then
+    rebuild_embedded_web_bundle
+  else
+    ensure_embedded_web_bundle
+  fi
+  build_binary "$BIN"
+}
+
 sync_example_fixtures() {
   local requested="${1:-all}"
   local fixture source target
@@ -90,27 +100,41 @@ run_for_all_examples() {
   shift || true
 
   case "$command" in
-    validate|scan|graph)
+    validate|scan|export-json-graph|export-json-visualisation)
       ;;
     *)
       printf '%s\n' "$(mapture_error "unsupported all-fixtures command: $command")" >&2
-      printf '%s\n' "$(mapture_muted "supported commands: validate scan graph")" >&2
+      printf '%s\n' "$(mapture_muted "supported commands: validate scan export-json-graph export-json-visualisation")" >&2
       exit 1
       ;;
   esac
 
-  local fixture
+  ensure_testing_binary "$command"
+
+  local fixture target output
   while IFS= read -r fixture; do
     printf '%s\n' "$(mapture_strong "== $fixture ($command) ==")"
     case "$command" in
       validate)
         "$BIN" validate "$(fixture_path "$fixture")" "$@"
         ;;
       scan)
-        run_scan "$fixture"
+        target="$(fixture_path "$fixture")"
+        output="$(fixture_output "$fixture" "scan.json")"
+        "$BIN" scan "$target" >"$output"
+        printf '%s\n' "$(mapture_success "wrote $(mapture_muted "$output")")"
         ;;
-      graph)
-        run_graph "$fixture"
+      export-json-graph)
+        target="$(fixture_path "$fixture")"
+        output="$(fixture_output "$fixture" "graph.json")"
+        "$BIN" export-json-graph "$target" -o "$output"
+        printf '%s\n' "$(mapture_success "wrote $(mapture_muted "$output")")"
+        ;;
+      export-json-visualisation)
+        target="$(fixture_path "$fixture")"
+        output="$(fixture_output "$fixture" "visualisation.json")"
+        "$BIN" export-json-visualisation "$target" -o "$output"
+        printf '%s\n' "$(mapture_success "wrote $(mapture_muted "$output")")"
         ;;
     esac
   done < <(example_fixture_names)
@@ -145,17 +169,18 @@ serve_port() {
 show_help() {
   local fixture
   mapture_print_section "Repo Development Commands"
-  mapture_print_kv "./scripts/go.sh build" "Build the testing binary under $(mapture_muted "$BIN")"
+  mapture_print_kv "./scripts/go.sh build" "Build the latest local app into $(mapture_muted "$BIN")"
   mapture_print_kv "./scripts/go.sh init" "Run init against the testing playground"
 
   mapture_print_section "Repo Verification Commands"
   mapture_print_kv "./scripts/go.sh validate <fixture|all>" "Validate one fixture or every example fixture"
   mapture_print_kv "./scripts/go.sh scan <fixture|all>" "Write normalized scan output into $(mapture_muted "$OUTPUTS_DIR")"
-  mapture_print_kv "./scripts/go.sh graph <fixture|all>" "Write Mermaid output into $(mapture_muted "$OUTPUTS_DIR")"
+  mapture_print_kv "./scripts/go.sh export-json-graph <fixture|all>" "Write JGF output into $(mapture_muted "$OUTPUTS_DIR")"
+  mapture_print_kv "./scripts/go.sh export-json-visualisation <fixture|all>" "Write explorer JSON into $(mapture_muted "$OUTPUTS_DIR")"
 
   mapture_print_section "Local Verification With Fixtures"
   mapture_print_kv "./scripts/go.sh fixtures" "List known fixtures"
-  mapture_print_kv "./scripts/go.sh serve <fixture>" "Run the local explorer for a fixture"
+  mapture_print_kv "./scripts/go.sh serve <fixture>" "Run the latest local explorer for a fixture"
   mapture_print_kv "./scripts/go.sh fixture <fixture> <command>" "Run any CLI command against a fixture path"
 
   mapture_print_section "Paths"
@@ -176,7 +201,7 @@ run_validate() {
   if run_across_examples_if_needed validate "$fixture"; then
     return
   fi
-  build_binary "$BIN"
+  ensure_testing_binary validate
   exec "$BIN" validate "$(fixture_path "$fixture")"
 }
 
@@ -185,24 +210,37 @@ run_scan() {
   if run_across_examples_if_needed scan "$fixture"; then
     return
   fi
-  build_binary "$BIN"
+  ensure_testing_binary scan
   local target output
   target="$(fixture_path "$fixture")"
   output="$(fixture_output "$fixture" "scan.json")"
   "$BIN" scan "$target" >"$output"
   printf '%s\n' "$(mapture_success "wrote $(mapture_muted "$output")")"
 }
 
-run_graph() {
+run_export_json_graph() {
   local fixture="$1"
-  if run_across_examples_if_needed graph "$fixture"; then
+  if run_across_examples_if_needed export-json-graph "$fixture"; then
     return
   fi
-  build_binary "$BIN"
+  ensure_testing_binary export-json-graph
   local target output
   target="$(fixture_path "$fixture")"
-  output="$(fixture_output "$fixture" "mmd")"
-  "$BIN" graph "$target" -o "$output"
+  output="$(fixture_output "$fixture" "graph.json")"
+  "$BIN" export-json-graph "$target" -o "$output"
+  printf '%s\n' "$(mapture_success "wrote $(mapture_muted "$output")")"
+}
+
+run_export_json_visualisation() {
+  local fixture="$1"
+  if run_across_examples_if_needed export-json-visualisation "$fixture"; then
+    return
+  fi
+  ensure_testing_binary export-json-visualisation
+  local target output
+  target="$(fixture_path "$fixture")"
+  output="$(fixture_output "$fixture" "visualisation.json")"
+  "$BIN" export-json-visualisation "$target" -o "$output"
   printf '%s\n' "$(mapture_success "wrote $(mapture_muted "$output")")"
 }
 
@@ -212,10 +250,13 @@ run_serve() {
     printf '%s\n' "$(mapture_error 'serve does not support fixture "all"; choose one fixture')" >&2
     exit 1
   fi
-  build_binary "$BIN"
+  ensure_testing_binary serve
   local target addr
   target="$(fixture_path "$fixture")"
   addr="$(serve_port "$fixture")"
+  print_binary_summary "local testing binary" "$BIN"
+  printf '  %s %s\n' "$(mapture_accent "fixture")" "$(mapture_muted "$target")"
+  printf '  %s %s\n' "$(mapture_accent "serve")" "$(mapture_muted "http://$addr")"
   exec "$BIN" serve "$target" --addr "$addr" --open
 }
 
@@ -236,11 +277,14 @@ case "$1" in
     fixture_path "${1:-demo}"
     ;;
   build)
-    build_binary "$BIN"
-    printf '%s\n' "$(mapture_success "built $(mapture_muted "$BIN")")"
+    mapture_print_section "Testing Build"
+    ensure_testing_binary serve
+    print_binary_summary "testing build" "$BIN"
+    printf '%s\n' "$(mapture_success "build complete")"
     ;;
   init)
     shift
+    ensure_testing_binary init
     exec "$BIN" init "${1:-$PLAYGROUND_DIR}"
     ;;
   validate)
@@ -251,9 +295,13 @@ case "$1" in
     shift
     run_scan "${1:-demo}"
     ;;
-  graph)
+  export-json-graph)
+    shift
+    run_export_json_graph "${1:-demo}"
+    ;;
+  export-json-visualisation)
     shift
-    run_graph "${1:-demo}"
+    run_export_json_visualisation "${1:-demo}"
     ;;
   serve)
     shift
@@ -269,10 +317,12 @@ case "$1" in
     fi
     shift
     shift || true
+    ensure_testing_binary "$command"
     exec "$BIN" "$command" "$(fixture_path "$fixture")" "$@"
     ;;
   run)
     shift
+    ensure_testing_binary "${1:-}"
     exec "$BIN" "$@"
     ;;
   demo|ecommerce|migration|playground)
@@ -281,6 +331,7 @@ case "$1" in
     if [[ $# -eq 0 ]]; then
       set -- validate
     fi
+    ensure_testing_binary "${1:-validate}"
     exec "$BIN" "$1" "$(fixture_path "$fixture")" "${@:2}"
     ;;
   *)

scripts/help.sh

@@ -14,8 +14,8 @@ print_help() {
   mapture_print_kv "install-dev-tools" "Install local Go dev tools into testing/tools/bin"
   mapture_print_kv "install-git-hooks" "Configure git to use the repo-managed hooks"
   mapture_print_kv "init-hooks" "Configure git to use the repo-managed hooks"
-  mapture_print_kv "build" "Build the local mapture binary into build/"
-  mapture_print_kv "web" "Rebuild the frontend bundle under src/internal/webui/dist/"
+  mapture_print_kv "build" "Build the latest local mapture binary into build/"
+  mapture_print_kv "web" "Rebuild only the frontend bundle under src/internal/webui/dist/"
 
   mapture_print_section "Repo Verification Commands"
   mapture_print_kv "test-go" "Run Go tests through gotestsum"
@@ -32,10 +32,11 @@ print_help() {
   mapture_print_kv "testing-build" "Build the current source into testing/bin/mapture"
   mapture_print_kv "testing-init" "Run init against testing/playground"
   mapture_print_kv "playground-init" "Run init against the gitignored testing playground"
-  mapture_print_kv "validate" "Validate a fixture: make validate FIXTURE=<fixture|all>"
+  mapture_print_kv "validate" "Validate a fixture: make validate ecommerce or FIXTURE=ecommerce"
   mapture_print_kv "scan" "Scan a fixture: make scan FIXTURE=<fixture|all>"
-  mapture_print_kv "graph" "Export Mermaid for a fixture: make graph FIXTURE=<fixture|all>"
-  mapture_print_kv "serve" "Run the local server against a fixture: make serve FIXTURE=<fixture>"
+  mapture_print_kv "export-json-graph" "Export JGF for a fixture: make export-json-graph FIXTURE=<fixture|all>"
+  mapture_print_kv "export-json-visualisation" "Export explorer JSON: make export-json-visualisation FIXTURE=<fixture|all>"
+  mapture_print_kv "serve" "Always rebuild UI+binary, then run: make serve ecommerce or FIXTURE=ecommerce"
   mapture_print_kv "run" "Run any CLI command for a fixture: make run FIXTURE=<fixture> CMD=<cli-command>"
 
   mapture_print_section "Fixtures"
@@ -46,9 +47,9 @@ print_help() {
 
   mapture_print_section "Fixture Aliases"
   while IFS= read -r fixture; do
-    printf '  validate.%s  scan.%s  graph.%s  serve.%s\n' "$fixture" "$fixture" "$fixture" "$fixture"
+    printf '  validate.%s  scan.%s  export-json-graph.%s  export-json-visualisation.%s  serve.%s\n' "$fixture" "$fixture" "$fixture" "$fixture" "$fixture"
   done < <(discover_example_fixtures)
-  printf '  validate.playground  scan.playground  graph.playground  serve.playground\n'
+  printf '  validate.playground  scan.playground  export-json-graph.playground  export-json-visualisation.playground  serve.playground\n'
 }
 
 print_help