artisan

<!-- Generated by ac:init-project on 2026-05-19. Rewritten for the v0.0.1 publish-ready state (post tinker absorption, post doc/ tree, post skills/ addition, post example_magic removal). -->

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Stack

Pure Dart 3.4+ CLI framework. NO Flutter runtime dependency: the package is consumed by Flutter apps via `dart run fluttersdk_artisan <cmd>` but the framework itself runs on the Dart VM. Vendor deps locked: `args ^2.7`, `vm_service ^15.2` (DDS-aware), `dart_mcp ^0.5.1` (labs.dart.dev official MCP SDK), `stream_channel ^2.1`, `xml`, `yaml`, `yaml_edit ^2.2.3` (in-place YAML mutation), `crypto`, `meta`, `path`. Published on pub.dev as `fluttersdk_artisan ^0.0.1`; never reference `path:` local-dev syntax in user-facing artifacts.

## Commands

| Command | When |
|---|---|
| `dart test` | Run all tests (1060 baseline). |
| `dart test --coverage=coverage && dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info` | Generate `coverage/lcov.info` for the 80% gate (Golden Rule 3). |
| `dart format lib/ test/ bin/` | Format. Must produce no diff. |
| `dart analyze` | Static analysis. Zero issues required across `lib/ test/ bin/`. |
| `dart run fluttersdk_artisan <cmd>` | Run a builtin command standalone (no consumer wrapper needed). |
| `dart run fluttersdk_artisan:mcp` | Stdio JSON-RPC MCP server entry. Reads `~/.artisan/state.json` for VM Service URI; soft-fails when no Flutter app is running. |
| `dart pub publish --dry-run` | Validate publish archive. Target under 500 KB compressed. |

## Golden Rules (apply on every change)

1. **Doc sync (`doc/`)**. If a code change touches behavior described in `doc/**/*.md`, update the relevant doc page in the same change. New feature without an existing page: add one matching the `doc/{getting-started,commands,mcp,plugins,reference}/<name>.md` structure. URL routing is `https://fluttersdk.com/artisan/X/Y` per file path.
2. **Skill sync (`skills/`)**. Same rule for `skills/fluttersdk-artisan/SKILL.md` and `skills/fluttersdk-artisan/references/*.md`. When a change shifts behavior the LLM-agent skill describes (commands surface, install.yaml schema, installer DSL, MCP tools, plugin authoring), edit the matching reference file and update the SKILL.md surface when the change affects the cached overview.
3. **Test coverage stays at or above 80%**. Current line coverage is 83.79% (`coverage/lcov.info`). Run the coverage command above after behavioral changes; verify via `awk -F: '/^LF:/{lf+=$2} /^LH:/{lh+=$2} END{printf "%.2f%%\n", (lh/lf)*100}' coverage/lcov.info`. Drops below 80% block the change.
4. **README sync**. When a change is significant enough for the package landing page (new command group, new MCP tool surface, new install flow, breaking change), update `README.md` and `llms.txt`. Use descriptive link labels pointing at `https://fluttersdk.com/artisan/...` paths.
5. **CHANGELOG always under `[Unreleased]`**. Every behavioral or interface change lands an entry under `## [Unreleased]` in `CHANGELOG.md`. Categories: `Added` / `Changed` / `Fixed` / `Removed`. Promote to a dated section on `dart pub publish`.
6. **Green gate plus TDD**. `dart format lib/ test/ bin/` produces zero diff, `dart analyze` returns zero issues, `dart test` returns all green. TDD red-green-refactor for behavioral changes: write the failing test first, then the implementation that turns it green. Reverting the implementation must turn the test red again.
7. **GitHub Flow**. One long-lived branch: `master` (the canonical line every release is cut from). Cut every task branch from `master`, push the work, open a PR back into `master`. Releases ship by bumping `pubspec.yaml`, promoting `## [Unreleased]` in `CHANGELOG.md`, merging the bump PR, then tagging the commit on `master`; the tag is what publishes to pub.dev. No `develop` accumulator. See the Branching section below for the full flow.

## Branching

- One long-lived branch: `master`. Direct pushes blocked; everything lands via PR. Matches the flutter, dart-lang/sdk, dart-lang/pub, and Anthropic-ecosystem convention. `master` is the only canonical line; the CI workflow lists `main` alongside `master` purely for GitHub-default-branch portability and is not a second working branch (do not create or target `main`).
- Task branches: cut from `master`, named with a `<type>/<kebab-case-topic>` prefix where `<type>` is one of `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, or `release` (examples: `feat/mcp-install-invocation-flag`, `fix/lock-staleness-pid-reclaim`, `docs/skills-tinker-eval-recipes`). One topic per branch, PR back into `master`. Squash for tightly scoped PRs whose review-fixup commits are noise; rebase or merge commit when the commits each carry standalone signal.
- Release: open a `release/X.Y.Z` PR from a topic branch that bumps `pubspec.yaml` `version:` and promotes `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD` with the footer link. Merge, then `git tag X.Y.Z && git push origin X.Y.Z`. The tag triggers `.github/workflows/publish.yml` to push to pub.dev and cut the GitHub Release.
- External contributors fork the repo and PR against `master` using the same shape.

## Architecture

Single barrel: `package:fluttersdk_artisan/artisan.dart` re-exports the full public API. `lib/fluttersdk_artisan.dart` is a convention sibling that re-exports the same. Two binaries under `bin/`: `fluttersdk_artisan.dart` (CLI) and `mcp.dart` (MCP server entry; prepends `mcp:serve`, forces `collectMcpTools: true`, forces `delegateToConsumer: false` so the substrate's complete builtin list owns dispatch). Subsystem-first layout under `lib/src/`:

| Path | Purpose |
|---|---|
| `console/` | `ArtisanApplication` + `ArtisanRegistry` + `CommandSignature` (signature DSL) + `ArtisanContext` / `Input` / `Output`. `runArtisan(args, collectMcpTools:, delegateToConsumer:)` is the shared entry. |
| `commands/` | 21 builtin commands. Naming: `<Verb>Command extends ArtisanCommand`. Six declare `String get signature`; five declare `configure(ArgParser)` with flags; ten have no flag surface. |
| `installer/` | `PluginInstaller` fluent DSL + `ManifestInstaller` + `InstallTransaction` + `PluginsRegistryFile` + sealed `InstallOperation` hierarchy (26 variants). See `.claude/rules/installer.md`. |
| `mcp/` | `McpServer extends MCPServer with ToolsSupport` (dart_mcp) + `McpToolDescriptor` + `McpFilterConfig` (3-layer Cargo-style: file + env + CLI). Substrate commands surface as `artisan_*` MCP tools via the 10-entry allowlist at `lib/src/mcp/mcp_server.dart:744-755`: `start` / `stop` / `status` / `logs` / `restart` / `reload` / `hot-restart` / `doctor` / `list` / `tinker`. |
| `helpers/` | `FileHelper`, `ConfigEditor` (idempotent injects), `MainDartEditor`, `EnvEditor`, `PlistWriter`, `GradleEditor`, `PodfileEditor`, `HtmlEditor`, `JsonEditor`, `XmlEditor`, `RouteRegistryEditor`. |
| `stubs/` | `StubLoader` (4-tier resolution: env, package_config, pubspec walk, fallback). Stub assets under `assets/stubs/`. |
| `state/` | `StateFile` (`~/.artisan/state.json` for the running app: pid, vmServiceUri, device, FIFO pipe). |
| `tinker/`, `vm/` | REPL + `VmServiceClient` (wraps `package:vm_service`, no isolate-id cache to handle device-target switches). |

User-facing assets:

| Path | Purpose |
|---|---|
| `README.md` | pub.dev + GitHub landing page. Wind-paralel structure (~383 lines). |
| `llms.txt` | LLM-agent index per llmstxt.org spec (under 2 KB; links use `.md` extensions for direct Markdown fetch). |
| `doc/` | 17-file URL-routable documentation tree (`getting-started/`, `commands/`, `mcp/`, `plugins/`, `reference/`). Maps to `https://fluttersdk.com/artisan/X/Y` per the path. |
| `skills/fluttersdk-artisan/` | LLM-agent skill (`SKILL.md` + 5 references) mirroring the magic-framework skill pattern. |
| `CHANGELOG.md` | Release notes; new entries land under `## [Unreleased]`. |

## Conventions

- **Signature DSL primary**: command declaration via `String get signature => 'cmd:name {arg} {--flag}'`. `configure(ArgParser)` is the explicit fallback for cases the DSL cannot express. The grammar is artisan's own; reference docs describe it as the "signature DSL" without comparison-language.
- **`final class` universal** on every new public type (`McpServer`, `McpToolDescriptor`, `McpFilterConfig`, etc.). Sealed dispatch via Dart 3 exhaustiveness; no `default:` branch on sealed switches.
- **Plugin MCP contract**: `ArtisanServiceProvider.mcpTools() => const <McpToolDescriptor>[]` default-empty. Plugins override to expose tools; the MCP server collects them when `runArtisan(collectMcpTools: true)`.
- **MCP tool descriptions** follow Claude Code canonical format: imperative opening sentence, brief context paragraph, `Usage:` bullet list, constraint-forward language. Per-property `inputSchema` descriptions include defaults plus concrete examples. Critical info first (CC truncates MCP descriptions at 2 KB chars).
- **Idempotent installers**: `ConfigEditor.insertCodeAfterPattern` early-returns when `content.contains(code.trim())`; `PluginInstaller` injects via lookahead-anchored regex (`(?=\s*\n\s*\])`) so re-running `plugin:install` is a safe no-op.
- **Atomic writes**: every persistent file write goes through `.tmp` + rename (`PluginsRegistryFile`, `InstallTransaction`, `PluginsRefreshCommand`, `StateFile`). Concurrent readers never see partial state.
- **Codegen barrels**: `lib/app/commands/_index.g.dart` (consumer commands) and `lib/app/_plugins.g.dart` (plugin providers). Both are GENERATED. Never hand-edit. Regenerated by `commands:refresh` / `plugins:refresh` / `make:command` / `plugin:install`.
- **Stub placeholders**: `{{ name }}`, `{{ pascalName }}`, `{{ commandPrefix }}` resolved at scaffold time via `StubLoader.replace`. Stub file keeps `.stub` suffix; rendered target gets the real extension.
- **Forbidden keywords in artifacts**: no "Laravel", "Symfony Console", "Artisan-style", "Artisan-inspired" anywhere in code, docs, comments, commit messages, or README. No em-dash (`—`) or en-dash (`–`); use comma, colon, semicolon, period, or parentheses instead.
- **Numbered step comments** (`// 1.`, `// 2.`) for methods with 3+ sequential phases. Docblocks per public class/method explaining WHY + invariants. Internal comments are plain `//`; only public API gets `///`.

## Off-limits

- `example/` is a dev playground for live e2e validation. Production code does not depend on it. Pub.dev archive ships only `lib/`, `bin/`, `pubspec.yaml`, `README.md`, `CHANGELOG.md`, `LICENSE`, `assets/`, `doc/`, `llms.txt`, `skills/`, `analysis_options.yaml`; the rest is excluded via `.pubignore`.
- `*.g.dart` files (`_index.g.dart`, `_plugins.g.dart`) are codegen output. Edit the source of truth (`.artisan/plugins.json` for plugins; `lib/app/commands/<name>_command.dart` for commands) and re-run the matching refresh command.
- `magic_tinker` sibling package's `tinker_eval` MCP descriptor is OBSOLETE since artisan absorbed `artisan_tinker` as the 10th substrate tool. Any new code path or doc page must point at `artisan_tinker`, not `tinker_eval`.
- `path:` deps in docs and the pub.dev archive are forbidden: README, install.yaml templates, doc pages, and `llms.txt` always use `^0.0.1` caret form (or `dart pub add` form). The `install` command itself picks the right dep shape at scaffold time: a `path:` entry when `.dart_tool/package_config.json` resolves `fluttersdk_artisan` to a relative `rootUri` (sibling-package monorepo workflow), otherwise `fluttersdk_artisan: any` so the next `pub get` pulls the published package. Never hand-write `path:` syntax in documentation, even when the codebase is monorepo-vendored.
- `~/.artisan/` is machine-local state. Never commit; `.gitignore` already excludes it.
- Platform: V1 lifecycle commands (`start` / `stop` / `reload` / `hot-restart`) use POSIX FIFO stdin via `mkfifo`. macOS and Linux only; Windows unsupported.

## Release

- Version: `0.0.1` (first public release). Bump per SemVer in `pubspec.yaml` and promote the `[Unreleased]` block of `CHANGELOG.md` to a dated section before publishing.
- Pub.dev topics (max 5, declared in `pubspec.yaml`): `cli`, `mcp-server`, `scaffolding`, `plugin-system`, `code-generation`.
- Homepage and documentation URL: `https://fluttersdk.com/artisan`. Repository: `https://github.com/fluttersdk/artisan`.
- `dart pub publish --dry-run` must end clean (0 errors). Dev-state warnings (uncommitted, gitignored-but-tracked) are acceptable in dev and cleared before publish via clean git checkout.
- No CI workflow; releases are manual. Run `dart test` + `dart analyze` + `dart format --output=none --set-exit-if-changed lib/ test/ bin/` + `dart pub publish --dry-run` before tagging.

## Path-scoped rules

- `.claude/rules/installer.md` (paths: `lib/src/installer/**`, `test/installer/**`, `lib/src/helpers/config_editor.dart`, `lib/src/commands/plugin_install_command.dart`, `lib/src/commands/plugin_uninstall_command.dart`, `lib/src/commands/plugins_refresh_command.dart`): installer subsystem internals (fluent DSL phases, atomic writes, three routing modes).
- `.claude/rules/tests.md` (paths: `test/**`): test discipline (layout mirror, file-private fake naming, InMemoryFs vs tempDir, idempotency assertions, TDD red-green-refactor specifics, 80% coverage gate).

Read those files when touching the matching paths; the loader injects them on demand.