Productize/production readiness

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: gomod
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

.github/workflows/ci.yml

@@ -9,35 +9,23 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ui-ci-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     name: build and check
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - name: Check out
         uses: actions/checkout@v4
 
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.24'
-          check-latest: true
-
-      - name: Verify gofmt
-        run: |
-          unformatted=$(gofmt -l .)
-          if [ -n "$unformatted" ]; then
-            echo "These files are not gofmt-clean:"
-            echo "$unformatted"
-            echo "Run 'make fmt' and commit the result."
-            exit 1
-          fi
-
-      - name: go vet
-        run: go vet ./...
-
-      - name: Build
-        run: go build ./...
+          go-version: '1.24.2'
 
-      - name: Test
-        run: go test ./...
+      - name: Run the local gate
+        run: make check

.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: release binaries
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: ${{ matrix.goos }}-${{ matrix.goarch }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+          - goos: linux
+            goarch: arm64
+          - goos: darwin
+            goarch: amd64
+          - goos: darwin
+            goarch: arm64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.24.2"
+          cache: true
+      - name: Verify tag has changelog entry
+        run: |
+          python3 - <<'PY'
+          import os
+          from pathlib import Path
+
+          version = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          heading = f"## [{version}]"
+          if heading not in Path("CHANGELOG.md").read_text(encoding="utf-8"):
+              raise SystemExit(f"CHANGELOG.md has no release heading for {version}")
+          declared = Path("VERSION").read_text(encoding="utf-8").strip()
+          if declared != version:
+              raise SystemExit(f"VERSION declares {declared}, but tag is {version}")
+          print(f"changelog entry: {heading}")
+          print(f"UI version: {declared}")
+          PY
+      - name: Build and package
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: "0"
+        run: |
+          set -euo pipefail
+          export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
+          version="${GITHUB_REF_NAME#v}"
+          name="lachesis-ui-${GITHUB_REF_NAME}-${GOOS}-${GOARCH}"
+          mkdir -p dist
+          go build -trimpath -ldflags="-s -w -X github.com/UnboundCompute/lachesis-ui/internal/mcp.Version=$version" -o "dist/$name/lachesis-ui" .
+          cp README.md LICENSE "dist/$name/"
+          # Normalize tar metadata and the gzip header so the same tag rebuilds
+          # to byte-identical artifacts.
+          tar -C dist --sort=name --mtime="@${SOURCE_DATE_EPOCH}" \
+            --owner=0 --group=0 --numeric-owner -cf - "$name" \
+            | gzip -n > "dist/$name.tar.gz"
+          sha256sum "dist/$name.tar.gz" > "/tmp/${name}.first.sha256"
+          tar -C dist --sort=name --mtime="@${SOURCE_DATE_EPOCH}" \
+            --owner=0 --group=0 --numeric-owner -cf - "$name" \
+            | gzip -n > "dist/$name.tar.gz"
+          sha256sum -c "/tmp/${name}.first.sha256"
+          (cd dist && sha256sum "$name.tar.gz") >> dist/SHA256SUMS
+      - name: Smoke-test native binary
+        if: matrix.goos == 'linux' && matrix.goarch == 'amd64'
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME#v}"
+          name="lachesis-ui-${GITHUB_REF_NAME}-${{ matrix.goos }}-${{ matrix.goarch }}"
+          expected="lachesis-ui ${version}"
+          verify_dir="$(mktemp -d)"
+          trap 'rm -rf "$verify_dir"' EXIT
+          tar -xzf "dist/$name.tar.gz" -C "$verify_dir"
+          test -f "$verify_dir/$name/lachesis-ui"
+          actual="$("$verify_dir/$name/lachesis-ui" --version)"
+          test "$actual" = "$expected" || {
+            echo "version mismatch: got '$actual', want '$expected'" >&2
+            exit 1
+          }
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: lachesis-ui-${{ github.ref_name }}-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: dist/

CHANGELOG.md

@@ -7,8 +7,12 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+- Added a machine-readable `VERSION` source used by the installer’s source-build
+  default; release CI now rejects tags that do not match it.
+
 ### Added
 
+- Tagged releases now build checksummed Linux and macOS binaries for amd64 and arm64.
 - Nested, collapsible source tree on the Tree screen. Folders expand in place
   and load their children lazily, with child-count badges, so a large repo
   opens as a handful of top-level folders rather than a flat wall of files.
@@ -18,9 +22,65 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ### Changed
 
+- Release verification now executes the native Linux binary and checks its stamped
+  version from the extracted archive before uploading cross-platform archives.
+
+- The stack installer now disables Git terminal prompts so unattended setup fails
+  clearly when a checkout cannot authenticate or reach its repository.
+
+- The stack installer now applies Git low-speed and pip network bounds, so stalled
+  repository or dependency transfers fail clearly instead of hanging unattended.
+
+- UI MCP tool requests now have a two-minute default bound, configurable with
+  `LACHESIS_UI_REQUEST_TIMEOUT`, and report recent engine diagnostics when a request
+  times out instead of leaving the terminal waiting indefinitely.
+
+- The install documentation now uses `python -m pip` so engine dependencies
+  stay in the interpreter the UI discovers.
+
+- Engine startup recovery now points to the supported source-checkout install and
+  labels the PyPI command as conditional until a release is published.
+
+- The binary-only install section now distinguishes the working source build from
+  the `go install` command reserved for a published UI tag.
+
+- The stack installer now warns when engine or catalog refs remain on mutable `main`,
+  while preserving those defaults for development use.
+
+- UI engine shutdown now uses a dedicated POSIX process group, so startup or request
+  timeouts terminate compiler/helper children along with the MCP parent.
+- The stack installer now exposes the generated graph helper's frontend timeout as
+  `LACHESIS_BUILD_TIMEOUT` instead of requiring edits to generated shell code.
+- Documented the engine's Python 3.10–3.12 release-tested window in the UI setup guide.
+- The Makefile now derives its default binary version from `VERSION`, matching the
+  installer and release workflow while retaining explicit `VERSION=...` overrides.
+
+- UI startup diagnostics now use `python -m pip` in their engine-install hint,
+  avoiding interpreter mismatches during recovery.
+
+- The installer rejects empty, option-like, or whitespace-containing engine,
+  catalog, and UI refs before invoking Git.
+
+- MCP startup and request failures now include the bounded recent engine stderr
+  tail, making wrong-interpreter, missing-graph, and import failures visible in
+  the UI instead of looking like a silent server exit.
+
+- Added a single `make check` developer/CI gate covering formatting, vet, build,
+  and tests.
+
+- The generated `build-graph.sh` helper rejects path-like graph names so output
+  cannot escape the configured graph directory.
+
+- The generated graph helper now reports a clear error for a missing source
+  directory before attempting to resolve it.
+
 - The Tree keys now match a nested tree: right expands a folder, left collapses
   it or jumps to its parent, and enter opens a folder or a symbol's
   neighborhood.
+- Custom `LACHESIS_HOME` installs now work end-to-end, including UI engine and graph
+  discovery.
+- Engine startup is bounded by a configurable timeout, and invalid graph artifacts
+  are rejected with actionable diagnostics.
 
 ## [0.1.0]
 

CONTRIBUTING.md

@@ -19,7 +19,7 @@ about how that information is shown or navigated, it belongs here.
 
 ## Getting set up
 
-You need Go 1.24+ and, to run the UI against a real graph, the engine.
+You need Go 1.24.2+ and, to run the UI against a real graph, the engine.
 
 ```sh
 git clone https://github.com/UnboundCompute/lachesis-ui
@@ -64,15 +64,14 @@ in the screen's own file.
 
 ## Before you open a pull request
 
-Run the local checks. CI runs the same ones and will block a merge if any fail.
+Run the local gate. CI runs the same command and will block a merge if any check fails.
 
 ```sh
-make fmt      # gofmt: formatting must be clean
-make vet      # go vet: no reported problems
-make build    # the binary must build
-go test ./... # tests must pass
+make check    # gofmt check, vet, build, and tests
 ```
 
+Use `make fmt` when the formatting check reports files that need rewriting.
+
 Guidelines:
 
 - Keep formatting gofmt-clean. CI fails on any file gofmt would rewrite.

Makefile

@@ -1,11 +1,13 @@
 BIN     ?= lachesis-ui
 PREFIX  ?= $(HOME)/.lachesis/bin
+VERSION ?= $(shell tr -d '[:space:]' < VERSION 2>/dev/null || printf '0.1.0')
+LDFLAGS ?= -X github.com/UnboundCompute/lachesis-ui/internal/mcp.Version=$(VERSION)
 
-.PHONY: build install run tidy fmt vet clean stack
+.PHONY: build install run tidy fmt vet check clean stack
 
 ## build the binary into the working directory
 build:
-	go build -o $(BIN) .
+	go build -ldflags "$(LDFLAGS)" -o $(BIN) .
 
 ## build and drop the binary into ~/.lachesis/bin
 install: build
@@ -29,5 +31,18 @@ fmt:
 vet:
 	go vet ./...
 
+## run the complete local gate used by CI
+check:
+	@unformatted="$$(gofmt -l .)"; \
+	if [ -n "$$unformatted" ]; then \
+		echo "These files are not gofmt-clean:"; \
+		echo "$$unformatted"; \
+		echo "Run 'make fmt' and commit the result."; \
+		exit 1; \
+	fi
+	go vet ./...
+	go build ./...
+	go test ./...
+
 clean:
 	rm -f $(BIN)