refactor: extract inline shell tasks to mise-tasks file-tasks; add shellcheck + shfmt (#299)

richardthe3rd · claude · web-flow · commit 6f3e2fba98da · 2026-05-20T08:29:55.000+01:00
* refactor: extract inline shell tasks to mise-tasks file-tasks; add shellcheck + shfmt

All multi-line inline shell scripts in mise.toml and mise.dev.toml are
moved to standalone executable files under mise-tasks/. Filenames ending
in .sh are used where a directory of the same base name already exists
(test.sh, dev.sh, build/web.sh, test/e2e.sh) so that both the parent
task and its colon-namespaced children can coexist on the filesystem.

New file-tasks added:
  mise-tasks/analyze            (was inline in mise.toml)
  mise-tasks/coverage           (was inline in mise.toml)
  mise-tasks/test.sh            (was inline in mise.toml)
  mise-tasks/dev.sh             (was inline in mise.dev.toml)
  mise-tasks/build/web.sh       (was inline in mise.dev.toml)
  mise-tasks/serve/release      (was inline in mise.dev.toml)
  mise-tasks/test/e2e.sh        (was inline in mise.dev.toml)
  mise-tasks/test/e2e/ui        (was inline in mise.dev.toml)
  mise-tasks/test/e2e/headed    (was inline in mise.dev.toml)
  mise-tasks/test/check-page    (was inline in mise.dev.toml)
  mise-tasks/screenshots/batch  (was inline in mise.dev.toml)

shellcheck and shfmt added as mise tools (mise.toml). Two new tasks:
  mise-tasks/shell/check   — shellcheck on all .sh files + mise-tasks/
  mise-tasks/shell/format  — shfmt -w on all .sh files + mise-tasks/

shell:check is wired into `check`; shell:format into `format`.
All 22 shell files pass shellcheck; shfmt normalises indentation to tabs.

* refactor: standardise all mise-tasks files with .sh extension

Consistent convention: every file-task in mise-tasks/ has a .sh
extension regardless of whether the name conflicts with a subdirectory.
Previously only conflict cases (test.sh, dev.sh, build/web.sh,
test/e2e.sh) had the extension.

Renamed:
  analyze          -&gt; analyze.sh
  coverage         -&gt; coverage.sh
  build/web/prod   -&gt; build/web/prod.sh
  dev/tunnel       -&gt; dev/tunnel.sh
  serve/release    -&gt; serve/release.sh
  setup/playwright -&gt; setup/playwright.sh
  setup/tunnel     -&gt; setup/tunnel.sh
  shell/check      -&gt; shell/check.sh
  shell/format     -&gt; shell/format.sh
  test/check-page  -&gt; test/check-page.sh
  test/e2e/headed  -&gt; test/e2e/headed.sh
  test/e2e/ui      -&gt; test/e2e/ui.sh

Also adds mise-tasks/screenshots/ gitignore exception (the screenshots/
rule was blocking mise-tasks/screenshots/batch.sh from being tracked),
and simplifies shell:check / shell:format to a single find *.sh pass
now that the grep-for-shebang fallback is no longer needed.

* fix: use #USAGE headers for task args; pin shellcheck/shfmt versions

Replace broken #MISE usage= multi-line strings with the correct #USAGE
per-line syntax (the format mise actually parses for argument docs).
Reverts positional-arg fallback back to $usage_* env vars now that
the header syntax is correct.

Also pins shellcheck = "0.9.0" and shfmt = "3.8.0" instead of "latest"
so mise tools resolve without hitting GitHub releases API.

* feat: pass args through test and analyze tasks; update descriptions

Both tasks now forward $@ so agents can run a subset without resorting
to mise exec:

  mise run test test/widgets/drink_card_test.dart
  mise run analyze lib/screens/

Descriptions rewritten to answer "when to run" rather than "what it does",
and to clarify that the log file is auto-created (not a required input).
AGENTS.md updated to show the task form instead of the mise exec workaround.

* fix: scope shellcheck/shfmt as task-level tools; drop from global [tools]

Declaring them in [tools] caused mise to attempt installation on every
task run, blocking all tasks when GitHub's API is rate-limited.
Moving them to #MISE tools={} in the tasks that actually need them means
they're only resolved for shell:check and shell:format.

* fix: suppress flutter root warning; fix set -e masking grep hints on failure

The "Woah! You appear to be running flutter as root" warning on stderr
was filtered out with grep -v in the test/analyze/coverage pipelines.

Also fixes a latent bug: set -euo pipefail caused the script to exit
immediately on flutter failure, so the "Grep with:" hint was never
printed on failure — exactly when it's most needed. Replaced with
set -uo pipefail and EXIT_CODE=${PIPESTATUS[0]} to capture flutter's
exit code while letting the hint always print.

* fix: add export mode to get_version_info.sh; fix comments and error message

- get_version_info.sh: add 'export' mode (eval-safe VAR=value lines)
  that prod.sh was already calling but was falling through to the
  human-readable default, causing eval to fail on the "Version: ..."
  output. Also switch == to = in [ ] comparisons (shellcheck SC2039).

- serve/release.sh: error hint now points to the correct
  MISE_ENV=dev ./bin/mise invocation instead of bare `mise`.

- mise.dev.toml: update task→file mapping comments to include .sh
  extension to match the actual committed filenames.

* fix: drop deprecated #MISE tools={system}; exclude .mise/ from shell scans

'system' version in #MISE tools={} is deprecated in mise. Removing the
declaration entirely — shellcheck and shfmt are expected on PATH (install
via apt/brew). Also adds -not -path "./.mise/*" to the find commands so
the Flutter SDK's own shell scripts in .mise/http-tarballs/ are not
included in shellcheck/shfmt runs.

* fix: restore shellcheck/shfmt to [tools] for mise-managed installation

'system' is not a valid mise version. The correct approach is to pin
versions in [tools] so mise installs and manages them. In environments
where they are already available (e.g. this sandbox, devcontainers),
set MISE_DISABLE_TOOLS=shellcheck,shfmt to skip installation and use
the PATH versions instead.

* fix: use printf %q for shell-safe eval output in export mode

---------

Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -144,4 +144,5 @@ app.*.symbols
 !test/*.mocks.dart
 !test/**/*.mocks.dart
 screenshots/
+!mise-tasks/screenshots/
 test/failures/
diff --git a/AGENTS.md b/AGENTS.md
@@ -122,8 +122,11 @@ MISE_ENV=dev ./bin/mise run build:web
 `test` and `analyze` automatically save output to a temp file, print the path before the run starts, and print a ready-to-use grep command at the end. Run once, grep the file as many times as needed — do not re-run to grep different things.
 
 ```bash
-# Run a specific test file
-./bin/mise exec flutter -- flutter test test/my_test.dart
+# Run a specific test file or directory
+./bin/mise run test test/widgets/drink_card_test.dart
+
+# Run a specific analysis path
+./bin/mise run analyze lib/screens/
 ```
 
 > `TEST_LOG` and `ANALYZE_LOG` env vars let you override the temp file path if you need a stable location across multiple runs.
diff --git a/mise-tasks/analyze.sh b/mise-tasks/analyze.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+#MISE description="Run after Dart changes — pass a path to limit scope; grep output with the path printed at start"
+#MISE depends=["generate"]
+
+set -uo pipefail
+ANALYZE_LOG="${ANALYZE_LOG:-$(mktemp /tmp/analyze-XXXXXX.log)}"
+echo "ANALYZE_LOG=$ANALYZE_LOG"
+flutter analyze --no-fatal-infos "$@" 2>&1 \
+	| grep -v -E "Woah! You appear|superuser privileges" \
+	| tee "$ANALYZE_LOG"
+EXIT_CODE=${PIPESTATUS[0]}
+echo "---"
+echo "Grep with: grep -n 'error\|warning' $ANALYZE_LOG"
+exit "$EXIT_CODE"
diff --git a/mise-tasks/build/web.sh b/mise-tasks/build/web.sh
@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+#MISE description="Build Flutter web app in release mode (for local testing/e2e)"
+
+set -euo pipefail
+echo "Building Flutter web app in release mode..."
+flutter build web --release --base-href "/"
+echo ""
+echo "Build complete! Output at: build/web/"
+echo ""
+echo "To serve locally for testing:"
+echo "  npx http-server build/web -p 8080"
diff --git a/mise-tasks/build/web/prod.sh b/mise-tasks/build/web/prod.sh
@@ -7,19 +7,19 @@ echo "Building Flutter web app for production..."
 
 # Get version information
 if [ -x "scripts/get_version_info.sh" ]; then
-  echo "Gathering version information..."
-  eval "$(scripts/get_version_info.sh export)"
+	echo "Gathering version information..."
+	eval "$(scripts/get_version_info.sh export)"
 else
-  echo "Warning: scripts/get_version_info.sh not found, building without version info"
+	echo "Warning: scripts/get_version_info.sh not found, building without version info"
 fi
 
 # Build with version information
 flutter build web --release --base-href "/" \
-  ${GIT_TAG:+--dart-define=GIT_TAG=$GIT_TAG} \
-  ${GIT_COMMIT:+--dart-define=GIT_COMMIT=$GIT_COMMIT} \
-  ${GIT_BRANCH:+--dart-define=GIT_BRANCH=$GIT_BRANCH} \
-  ${BUILD_VERSION:+--dart-define=BUILD_VERSION=$BUILD_VERSION} \
-  ${BUILD_TIME:+--dart-define=BUILD_TIME=$BUILD_TIME}
+	${GIT_TAG:+--dart-define=GIT_TAG=$GIT_TAG} \
+	${GIT_COMMIT:+--dart-define=GIT_COMMIT=$GIT_COMMIT} \
+	${GIT_BRANCH:+--dart-define=GIT_BRANCH=$GIT_BRANCH} \
+	${BUILD_VERSION:+--dart-define=BUILD_VERSION=$BUILD_VERSION} \
+	${BUILD_TIME:+--dart-define=BUILD_TIME=$BUILD_TIME}
 
 echo ""
 echo "✅ Production build complete! Output at: build/web/"
diff --git a/mise-tasks/coverage.sh b/mise-tasks/coverage.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+#MISE description="Run tests with coverage reporting (output: coverage/lcov.info)"
+#MISE depends=["generate"]
+
+set -uo pipefail
+flutter test --coverage 2>&1 | grep -v -E "Woah! You appear|superuser privileges"
+EXIT_CODE=${PIPESTATUS[0]}
+echo "Coverage report generated at coverage/lcov.info"
+echo "To view HTML report, install lcov and run: genhtml coverage/lcov.info -o coverage/html"
+exit "$EXIT_CODE"
diff --git a/mise-tasks/dev.sh b/mise-tasks/dev.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+#MISE description="Start Flutter dev server on localhost:8080"
+
+set -euo pipefail
+echo "Starting Flutter dev server on http://localhost:8080"
+flutter run -d web-server --web-port 8080 --pid-file flutter-dev.pid
diff --git a/mise-tasks/dev/tunnel.sh b/mise-tasks/dev/tunnel.sh
@@ -21,10 +21,10 @@ echo ""
 
 # Cleanup function
 cleanup() {
-  echo ""
-  echo "Stopping tunnel..."
-  kill $TUNNEL_PID 2>/dev/null
-  exit
+	echo ""
+	echo "Stopping tunnel..."
+	kill $TUNNEL_PID 2>/dev/null
+	exit
 }
 
 # Set up cleanup on exit
diff --git a/mise-tasks/screenshots/batch.sh b/mise-tasks/screenshots/batch.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+#MISE description="Capture screenshots of multiple pages from config file"
+#USAGE arg "[config]" help="Config file path" default="screenshots.config.json"
+#USAGE arg "[output]" help="Output directory" default="screenshots"
+
+set -euo pipefail
+CONFIG="${usage_config:-screenshots.config.json}"
+OUTPUT="${usage_output:-screenshots}"
+
+echo "Running batch screenshot capture..."
+echo "Config: $CONFIG"
+echo "Output: $OUTPUT"
+node scripts/screenshot-batch.mjs -c "$CONFIG" -o "$OUTPUT"
diff --git a/mise-tasks/serve/release.sh b/mise-tasks/serve/release.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+#MISE description="Serve release build with http-server (SPA mode for deep linking)"
+
+set -euo pipefail
+if [ ! -d "build/web" ]; then
+	echo "Error: build/web directory not found"
+	echo "Run: MISE_ENV=dev ./bin/mise run build:web first"
+	exit 1
+fi
+
+echo "Starting http-server with SPA routing..."
+echo "Available at: http://localhost:8080"
+echo "Press Ctrl+C to stop"
+npx http-server build/web -p 8080 --proxy http://localhost:8080?
diff --git a/mise-tasks/setup/playwright.sh b/mise-tasks/setup/playwright.sh
@@ -8,19 +8,19 @@ echo ""
 
 # Install npm dependencies if needed
 if [ ! -d node_modules ]; then
-  echo "Step 1: Installing npm dependencies..."
-  npm install
+	echo "Step 1: Installing npm dependencies..."
+	npm install
 else
-  echo "✓ npm dependencies already installed"
+	echo "✓ npm dependencies already installed"
 fi
 
 # Check if Playwright browsers are installed
 if [ ! -d ~/.cache/ms-playwright ] || [ -z "$(ls -A ~/.cache/ms-playwright 2>/dev/null)" ]; then
-  echo ""
-  echo "Step 2: Installing Playwright browsers..."
-  npx playwright install chromium
+	echo ""
+	echo "Step 2: Installing Playwright browsers..."
+	npx playwright install chromium
 else
-  echo "✓ Playwright browsers already installed"
+	echo "✓ Playwright browsers already installed"
 fi
 
 # Install system dependencies (requires sudo)
diff --git a/mise-tasks/setup/tunnel.sh b/mise-tasks/setup/tunnel.sh
@@ -8,19 +8,19 @@ echo ""
 
 # Check if already logged in
 if [ ! -f ~/.cloudflared/cert.pem ]; then
-  echo "Step 1: Login to Cloudflare (browser will open)..."
-  cloudflared tunnel login
+	echo "Step 1: Login to Cloudflare (browser will open)..."
+	cloudflared tunnel login
 else
-  echo "✓ Already logged in to Cloudflare"
+	echo "✓ Already logged in to Cloudflare"
 fi
 
 # Check if tunnel already exists
 if cloudflared tunnel list 2>/dev/null | grep -q "cbf-dev-tunnel"; then
-  echo "✓ Tunnel 'cbf-dev-tunnel' already exists"
+	echo "✓ Tunnel 'cbf-dev-tunnel' already exists"
 else
-  echo ""
-  echo "Step 2: Creating tunnel 'cbf-dev-tunnel'..."
-  cloudflared tunnel create cbf-dev-tunnel
+	echo ""
+	echo "Step 2: Creating tunnel 'cbf-dev-tunnel'..."
+	cloudflared tunnel create cbf-dev-tunnel
 fi
 
 # Route DNS
diff --git a/mise-tasks/shell/check.sh b/mise-tasks/shell/check.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+#MISE description="Run after editing any .sh or mise-tasks/ file"
+
+set -euo pipefail
+
+mapfile -t ALL_FILES < <(find . -name "*.sh" -not -path "./.git/*" -not -path "./.mise/*" -not -path "*/node_modules/*" | sort)
+
+if [ "${#ALL_FILES[@]}" -eq 0 ]; then
+	echo "No shell scripts found"
+	exit 0
+fi
+
+echo "Running shellcheck on ${#ALL_FILES[@]} files..."
+shellcheck "${ALL_FILES[@]}"
+echo "shellcheck passed"
diff --git a/mise-tasks/shell/format.sh b/mise-tasks/shell/format.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+#MISE description="Run after editing any .sh or mise-tasks/ file"
+
+set -euo pipefail
+
+mapfile -t ALL_FILES < <(find . -name "*.sh" -not -path "./.git/*" -not -path "./.mise/*" -not -path "*/node_modules/*" | sort)
+
+if [ "${#ALL_FILES[@]}" -eq 0 ]; then
+	echo "No shell scripts found"
+	exit 0
+fi
+
+echo "Formatting ${#ALL_FILES[@]} files with shfmt..."
+shfmt -w -i 0 -ci "${ALL_FILES[@]}"
+echo "shfmt complete"
diff --git a/mise-tasks/test.sh b/mise-tasks/test.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+#MISE description="Run before committing — pass a file arg to run a subset; grep output with the path printed at start"
+#MISE depends=["generate"]
+
+set -uo pipefail
+TEST_LOG="${TEST_LOG:-$(mktemp /tmp/test-XXXXXX.log)}"
+echo "TEST_LOG=$TEST_LOG"
+flutter test "$@" 2>&1 \
+	| grep -v -E "Woah! You appear|superuser privileges" \
+	| tee "$TEST_LOG"
+EXIT_CODE=${PIPESTATUS[0]}
+echo "---"
+echo "Grep with: grep -n 'FAILED\|ERROR' $TEST_LOG"
+exit "$EXIT_CODE"
diff --git a/mise-tasks/test/check-page.sh b/mise-tasks/test/check-page.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+#MISE description="Check page for console errors and take screenshot"
+#USAGE arg "[url]" help="URL to check" default="http://localhost:8080"
+#USAGE arg "[screenshot]" help="Screenshot output path" default="screenshot.png"
+
+set -euo pipefail
+URL="${usage_url:-http://localhost:8080}"
+SCREENSHOT="${usage_screenshot:-screenshot.png}"
+
+echo "Checking page: $URL"
+echo "Screenshot will be saved to: $SCREENSHOT"
+node scripts/check-page.mjs -u "$URL" -s "$SCREENSHOT"
diff --git a/mise-tasks/test/e2e.sh b/mise-tasks/test/e2e.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+#MISE description="Run e2e tests with Playwright (headless mode)"
+
+set -euo pipefail
+echo "Running e2e tests with Playwright..."
+npm run test:e2e
diff --git a/mise-tasks/test/e2e/headed.sh b/mise-tasks/test/e2e/headed.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+#MISE description="Run e2e tests in headed mode (visible browser)"
+
+set -euo pipefail
+echo "Running e2e tests in headed mode..."
+npm run test:e2e:headed
diff --git a/mise-tasks/test/e2e/ui.sh b/mise-tasks/test/e2e/ui.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+#MISE description="Run e2e tests in Playwright UI mode (interactive)"
+
+set -euo pipefail
+echo "Running e2e tests in UI mode..."
+npm run test:e2e:ui
diff --git a/mise.dev.toml b/mise.dev.toml
@@ -14,94 +14,16 @@
 #   Docs: https://mise.jdx.dev/tasks/task-arguments.html
 #         https://mise.jdx.dev/tasks/file-tasks.html
 
-[tasks.dev]
-description = "Start Flutter dev server on localhost:8080"
-run = '''
-echo "Starting Flutter dev server on http://localhost:8080"
-flutter run -d web-server --web-port 8080 --pid-file flutter-dev.pid
-'''
-
-# Complex tasks moved to mise-tasks/ for better maintainability:
-# - setup:tunnel -> mise-tasks/setup/tunnel
-# - setup:playwright -> mise-tasks/setup/playwright
-# - dev:tunnel -> mise-tasks/dev/tunnel
-# - build:web:prod -> mise-tasks/build/web/prod
-
-[tasks."test:e2e"]
-description = "Run e2e tests with Playwright (headless mode)"
-run = '''
-echo "Running e2e tests with Playwright..."
-npm run test:e2e
-'''
-
-[tasks."test:e2e:ui"]
-description = "Run e2e tests in Playwright UI mode (interactive)"
-run = '''
-echo "Running e2e tests in UI mode..."
-npm run test:e2e:ui
-'''
-
-[tasks."test:e2e:headed"]
-description = "Run e2e tests in headed mode (visible browser)"
-run = '''
-echo "Running e2e tests in headed mode..."
-npm run test:e2e:headed
-'''
-
-[tasks."build:web"]
-description = "Build Flutter web app in release mode (for local testing/e2e)"
-run = '''
-echo "Building Flutter web app in release mode..."
-flutter build web --release --base-href "/"
-echo ""
-echo "✅ Build complete! Output at: build/web/"
-echo ""
-echo "To serve locally for testing:"
-echo "  npx http-server build/web -p 8080"
-'''
-
-[tasks."serve:release"]
-description = "Serve release build with http-server (SPA mode for deep linking)"
-run = '''
-if [ ! -d "build/web" ]; then
-  echo "Error: build/web directory not found"
-  echo "Run: mise run build:web first"
-  exit 1
-fi
-
-echo "Starting http-server with SPA routing..."
-echo "Available at: http://localhost:8080"
-echo "Press Ctrl+C to stop"
-npx http-server build/web -p 8080 --proxy http://localhost:8080?
-'''
-
-[tasks."test:check-page"]
-description = "Check page for console errors and take screenshot"
-usage = '''
-arg "[url]" help="URL to check" default="http://localhost:8080"
-arg "[screenshot]" help="Screenshot output path" default="screenshot.png"
-'''
-run = '''
-URL="${usage_url:-http://localhost:8080}"
-SCREENSHOT="${usage_screenshot:-screenshot.png}"
-
-echo "Checking page: $URL"
-echo "Screenshot will be saved to: $SCREENSHOT"
-node scripts/check-page.mjs -u "$URL" -s "$SCREENSHOT"
-'''
-
-[tasks."screenshots:batch"]
-description = "Capture screenshots of multiple pages from config file"
-usage = '''
-arg "[config]" help="Config file path" default="screenshots.config.json"
-arg "[output]" help="Output directory" default="screenshots"
-'''
-run = '''
-CONFIG="${usage_config:-screenshots.config.json}"
-OUTPUT="${usage_output:-screenshots}"
-
-echo "Running batch screenshot capture..."
-echo "Config: $CONFIG"
-echo "Output: $OUTPUT"
-node scripts/screenshot-batch.mjs -c "$CONFIG" -o "$OUTPUT"
-'''
+# All tasks moved to mise-tasks/ for better maintainability and shellcheck/shfmt support:
+# - dev            -> mise-tasks/dev.sh
+# - test:e2e       -> mise-tasks/test/e2e.sh
+# - test:e2e:ui    -> mise-tasks/test/e2e/ui.sh
+# - test:e2e:headed -> mise-tasks/test/e2e/headed.sh
+# - build:web      -> mise-tasks/build/web.sh
+# - serve:release  -> mise-tasks/serve/release.sh
+# - test:check-page -> mise-tasks/test/check-page.sh
+# - screenshots:batch -> mise-tasks/screenshots/batch.sh
+# - setup:tunnel   -> mise-tasks/setup/tunnel.sh
+# - setup:playwright -> mise-tasks/setup/playwright.sh
+# - dev:tunnel     -> mise-tasks/dev/tunnel.sh
+# - build:web:prod -> mise-tasks/build/web/prod.sh
diff --git a/mise.toml b/mise.toml
diff --git a/scripts/get_version_info.sh b/scripts/get_version_info.sh
