From 29c3849034a55c132fb82ca2f735cf0dddca098d Mon Sep 17 00:00:00 2001 From: Ammar Date: Mon, 1 Dec 2025 21:31:10 -0600 Subject: [PATCH 1/4] fix: add mdbook linkcheck to static-check, rename docs targets - Rename docs -> docs-server (serves with browser) - Rename docs-build -> docs (just builds) - Add check-docs-links target (runs mdbook-linkcheck) - Include check-docs-links in static-check --- Makefile | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 3a5b8534f..de9e1ccdd 100644 --- a/Makefile +++ b/Makefile @@ -49,7 +49,7 @@ include fmt.mk .PHONY: test test-unit test-integration test-watch test-coverage test-e2e smoke-test .PHONY: dist dist-mac dist-win dist-linux .PHONY: vscode-ext vscode-ext-install -.PHONY: docs docs-build docs-watch +.PHONY: docs docs-server docs-watch check-docs-links .PHONY: storybook storybook-build test-storybook chromatic .PHONY: benchmark-terminal .PHONY: ensure-deps rebuild-native @@ -213,7 +213,7 @@ build/icon.png: docs/img/logo.webp scripts/generate-icons.ts @bun scripts/generate-icons.ts png ## Quality checks (can run in parallel) -static-check: lint typecheck fmt-check check-eager-imports check-bench-agent ## Run all static checks (includes startup performance checks) +static-check: lint typecheck fmt-check check-eager-imports check-bench-agent check-docs-links ## Run all static checks (includes startup performance checks) check-bench-agent: ## Verify terminal-bench agent configuration and imports @./scripts/check-bench-agent.sh @@ -337,15 +337,19 @@ vscode-ext-install: ## Build and install VS Code extension locally @$(MAKE) -C vscode install ## Documentation -docs: ## Serve documentation locally - @./scripts/docs.sh - -docs-build: ## Build documentation +docs: ## Build documentation @./scripts/docs_build.sh +docs-server: ## Serve documentation locally (opens browser) + @./scripts/docs.sh + docs-watch: ## Watch and rebuild documentation @cd docs && mdbook watch +check-docs-links: docs ## Check documentation for broken links + @echo "🔗 Checking documentation links..." + @cd docs && mdbook-linkcheck --standalone . + ## Storybook storybook: node_modules/.installed ## Start Storybook development server $(check_node_version) From 71f9d1e9cf72056dd618dde4eefb2317576945b3 Mon Sep 17 00:00:00 2001 From: Ammar Date: Mon, 1 Dec 2025 21:35:20 -0600 Subject: [PATCH 2/4] ci: use nix develop for static-check to get mdbook tools --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 86bcea98b..12f043710 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -65,7 +65,7 @@ jobs: run: echo "$HOME/.local/bin" >> $GITHUB_PATH - name: Run static checks - run: make -j3 static-check + run: nix develop --command make -j3 static-check test: name: Unit Tests From 7eac58db0b183893b0cc1349163918d3d167ec4f Mon Sep 17 00:00:00 2001 From: Ammar Date: Mon, 1 Dec 2025 21:35:50 -0600 Subject: [PATCH 3/4] fix: update package.json scripts and docs/README.md for renamed targets --- docs/README.md | 6 +++--- package.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index f2a107da0..08b53027f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,11 +5,11 @@ This directory contains the source for mux documentation built with [mdbook](htt ## Quick Start ```bash -# Serve docs with hot reload (opens in browser) +# Build docs bun docs -# Build docs -bun docs:build +# Serve docs with hot reload (opens in browser) +bun docs:serve # Watch for changes (no server) bun docs:watch diff --git a/package.json b/package.json index b702f0b58..7a62df63e 100644 --- a/package.json +++ b/package.json @@ -37,7 +37,7 @@ "dist:win": "make dist-win", "dist:linux": "make dist-linux", "docs": "make docs", - "docs:build": "make docs-build", + "docs:serve": "make docs-server", "docs:watch": "make docs-watch", "storybook": "make storybook", "storybook:build": "make storybook-build", From 1755cf6f2056f16ae6c548b9d34ec7e9bfdeb511 Mon Sep 17 00:00:00 2001 From: Ammar Date: Mon, 1 Dec 2025 21:38:04 -0600 Subject: [PATCH 4/4] fix: add mdbook linkcheck to static-check, rename docs targets - Rename docs -> docs-server (serves with browser) - Rename docs-build -> docs (just builds) - Add check-docs-links target (runs mdbook-linkcheck) - Include check-docs-links in static-check (skips gracefully if mdbook tools missing) - Add mdbook-pagetoc to flake.nix - Update package.json scripts and docs/README.md for renamed targets - Document mdbook tools requirement in AGENTS.md --- .github/workflows/ci.yml | 2 +- Makefile | 11 ++++++++--- docs/AGENTS.md | 1 + flake.nix | 1 + 4 files changed, 11 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 12f043710..86bcea98b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -65,7 +65,7 @@ jobs: run: echo "$HOME/.local/bin" >> $GITHUB_PATH - name: Run static checks - run: nix develop --command make -j3 static-check + run: make -j3 static-check test: name: Unit Tests diff --git a/Makefile b/Makefile index de9e1ccdd..4e5f0faf1 100644 --- a/Makefile +++ b/Makefile @@ -346,9 +346,14 @@ docs-server: ## Serve documentation locally (opens browser) docs-watch: ## Watch and rebuild documentation @cd docs && mdbook watch -check-docs-links: docs ## Check documentation for broken links - @echo "🔗 Checking documentation links..." - @cd docs && mdbook-linkcheck --standalone . +check-docs-links: ## Check documentation for broken links (requires mdbook tools via nix) + @if command -v mdbook >/dev/null 2>&1 && command -v mdbook-linkcheck >/dev/null 2>&1; then \ + $(MAKE) docs && \ + echo "🔗 Checking documentation links..." && \ + cd docs && mdbook-linkcheck --standalone .; \ + else \ + echo "⏭️ Skipping docs link check (mdbook tools not installed - use 'nix develop' for full checks)"; \ + fi ## Storybook storybook: node_modules/.installed ## Start Storybook development server diff --git a/docs/AGENTS.md b/docs/AGENTS.md index c40d49b60..76fc25e88 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -49,6 +49,7 @@ gh pr view --json mergeable,mergeStateStatus | jq '.' - Package manager: bun only. Use `bun install`, `bun add`, `bun run` (which proxies to Make when relevant). Run `bun install` if modules/types go missing. - Makefile is source of truth (new commands land there, not `package.json`). - Primary targets: `make dev|start|build|lint|lint-fix|fmt|fmt-check|typecheck|test|test-integration|clean|help`. +- Full `static-check` includes docs link checking which requires mdbook tools. Use `nix develop` to get them, or the check gracefully skips if unavailable. ## Refactoring & Runtime Etiquette diff --git a/flake.nix b/flake.nix index d6135c64d..def1a22dc 100644 --- a/flake.nix +++ b/flake.nix @@ -134,6 +134,7 @@ mdbook mdbook-mermaid mdbook-linkcheck + mdbook-pagetoc # Terminal bench uv