Release 0.0.4: fix MCP empty tools/list (issue #7) + fsa staleness + missing artisan_command stub

[anilcancakir]

Closes #7.

Summary

Substrate-side fix for the empty `tools/list` symptom from GitHub issue #7 (`./bin/fsa mcp:serve` returned 0 tools even when plugin providers were correctly registered), plus two pre-existing bugs surfaced during A-Z end-to-end testing in a fresh consumer.

What landed

Issue #7 root cause (verified end-to-end)

• Bug A `assets/stubs/dispatcher.dart.stub`: missing `collectMcpTools` arg on the generated dispatcher's `runArtisan(...)` call.
• Bug B `lib/src/commands/mcp_install_command.dart`: hardcoded `.mcp.json` entry pointed at the substrate standalone (`dart run fluttersdk_artisan:mcp`), which never loads consumer plugin providers.
• Latent regression `lib/src/console/run_artisan.dart`: `_defaultDelegate` emitted `dart run :artisan`, which only resolves to `bin/artisan.dart`. Post-0.0.2 the canonical wrapper is `bin/dispatcher.dart`.

Issue body correction

The issue's proposed fallback `dart run :artisan mcp:serve` does not resolve (per dart docs, `dart run :name` is a pure `bin/.dart` filename lookup; `executables:` is honored only by `dart pub global activate`). The correct fallback shape is `dart run :dispatcher mcp:serve`.

A-Z testing bonus fixes

• `./bin/fsa` rebuilt AOT bundle on every invocation: staleness condition 4 compared `pubspec.yaml -nt pubspec.lock`. `dart pub add` updates `pubspec.yaml` after pub get writes the lock, leaving `pubspec.yaml` mtime newer than `pubspec.lock` for every freshly installed consumer. Compare against the build stamp file instead.
• `make:command` crashed with "Stub file not found: artisan_command.stub": `MakeCommandCommand.getStub()` declared the asset name but the file never shipped. Added the canonical stub.

`doctor` migration aid

`doctor` now advisory-warns when `.mcp.json` still contains the pre-fix `fluttersdk_artisan:mcp` args shape, pointing the user at `./bin/fsa mcp:install` to upgrade.

Migration

• Substrate-installed consumers: `dart run fluttersdk_artisan install --force` then `./bin/fsa mcp:install`.
• Magic-installed consumers: paired magic-side stub update needed (tracked separately) before `magic:artisan install --force` propagates the fix.

Verification

• `dart format --output=none --set-exit-if-changed lib/ test/ bin/` 0 changed
• `dart analyze lib/ test/ bin/` 0 issues
• `dart test` 1129/1129 pass (+9 new tests covering 4 fix surfaces)
• `dart pub publish --dry-run` 0 warnings, 398 KB archive
• Coverage 83.78% scoped to lib/
• A-Z e2e in fresh Flutter consumer at /tmp: install -> bin/fsa cached startup ~120ms (was ~5s) -> make:command Greet succeeds -> mcp:install writes branched shape -> mcp:serve tools/list returns 10 substrate `artisan_*` descriptors -> doctor advisory fires on legacy + pre-fix shapes

See CHANGELOG.md [0.0.4] for the full bullet list.

Process

Plan + execute autonomous run: `.ac/plans/mcp-empty-tools-list/` (planning artifacts gitignored). Deep code review + oracle both APPROVED first pass.

[Copilot]

Pull request overview

This PR prepares the 0.0.4 release by fixing the “empty tools/list” MCP symptom (issue #7) by routing MCP server startup through the consumer wrapper and ensuring MCP tools are collected, plus additional reliability fixes discovered during end-to-end validation (fast CLI staleness detection and a missing make:command stub asset).

Changes:

• Fix consumer dispatcher stub and mcp:install so MCP server invocation loads consumer plugin providers and collects MCP tool descriptors.
• Update auto-delegation to target the post-0.0.2 wrapper name (bin/dispatcher.dart) and add doctor advisory for pre-fix .mcp.json shapes.
• Improve bin/fsa staleness detection and ship the missing artisan_command.stub, with tests and docs updated accordingly.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
test/stubs/stub_loader_test.dart	Adds regression test ensuring dispatcher stub forwards collectMcpTools.
test/stubs/bin_fsa_stub_test.dart	Adds regression test for corrected bin/fsa staleness check condition.
test/console/run_artisan_test.dart	Updates/extends tests to assert delegation prefixes :dispatcher.
test/commands/mcp_uninstall_command_test.dart	Adds tests covering uninstall of new .mcp.json shapes.
test/commands/mcp_install_command_test.dart	Updates tests for branched .mcp.json install shape (fsa vs dart fallback).
test/commands/make_command_command_test.dart	Adds regression test asserting artisan_command stub asset exists.
test/commands/install_command_test.dart	Asserts rendered dispatcher includes collectMcpTools forwarding.
test/commands/doctor_command_test.dart	Adds coverage for new advisory warning on pre-fix .mcp.json shape.
skills/fluttersdk-artisan/SKILL.md	Updates skill guidance for new MCP invocation and installation flow.
skills/fluttersdk-artisan/references/mcp-server.md	Updates canonical .mcp.json shapes and client config guidance.
skills/fluttersdk-artisan/references/commands.md	Updates MCP command docs to reflect new invocation shapes.
README.md	Updates Quick Start MCP wiring snippet and documents new .mcp.json shape.
pubspec.yaml	Bumps version to 0.0.4.
lib/src/console/run_artisan.dart	Changes auto-delegation to prepend :dispatcher and simplifies delegate invocation.
lib/src/commands/mcp_install_command.dart	Branches .mcp.json entry shape based on fsa availability and platform; injects test seams.
lib/src/commands/doctor_command.dart	Adds advisory warning for pre-fix fluttersdk_artisan:mcp entry shape.
doc/mcp/tool-reference.md	Updates MCP restart/invocation guidance for new server entry points.
doc/mcp/setup.md	Updates per-client setup matrix for new MCP server spawn shapes.
doc/mcp/overview.md	Updates overview to describe the post-install MCP invocation path and legacy entrypoint behavior.
doc/getting-started/installation.md	Updates command list to describe how to run mcp:serve post-install.
doc/commands/mcp-serve.md	Updates examples/synopsis to prefer ./bin/fsa mcp:serve with dart fallback.
doc/commands/install.md	Documents collectMcpTools forwarding behavior in the generated dispatcher.
CHANGELOG.md	Adds 0.0.4 release notes covering the fixes and migrations.
assets/stubs/dispatcher.dart.stub	Updates generated dispatcher to forward collectMcpTools for mcp:serve.
assets/stubs/bin_fsa.sh.stub	Fixes staleness check to compare pubspec.yaml against the build stamp file.
assets/stubs/artisan_command.stub	Adds the missing command stub used by make:command.

Comments suppressed due to low confidence (1)

lib/src/commands/mcp_install_command.dart:123

• This code writes .mcp.json via File.writeAsString, which is not atomic and can leave a truncated/partial file if the process is interrupted mid-write. The comment calls this atomic; if the repo convention is .tmp + rename for persistent writes, consider switching to that pattern here too (write to $path.tmp, then rename over the original).

    // 3. Write atomically (single write; no partial-read window on success).
    await file.writeAsString(
      '${const JsonEncoder.withIndent('  ').convert(config)}\n',
    );