artisan library

fluttersdk_artisan: Symfony-Console-grade CLI framework for Dart + Flutter.

Single barrel entry. Consumers import via package:fluttersdk_artisan/artisan.dart and gain access to the full public API surface (Application + Command + Input/Output

  • ServiceProvider + Context + VmServiceClient + StateFile + Stub system + Helpers).

16 make:* commands from magic_cli are NOT carried here — they live in the magic package as MagicArtisanProvider. fluttersdk_artisan is framework-agnostic.

Classes

AddDependency
Adds a package dependency to pubspec.yaml.
AddPathDependency
Adds a path dependency to pubspec.yaml.
AddPubspecAsset
Appends an asset path to the flutter.assets list in pubspec.yaml.
AddWebMetaTag
Adds a <meta> tag to web/index.html with the given attributes.
AndroidConfig
Android native configuration sub-section.
ArgParser
A class for taking a list of raw command line arguments and parsing out options and flags from them.
ArgResults
The results of parsing a series of command line arguments using ArgParser.parse.
ArgumentSpec
Positional argument specification parsed out of a signature.
ArgvInput
Parses List<String> argv typical of CLI invocation.
ArtisanApplication
Core console application + dispatcher.
ArtisanCommand
Base class for every artisan command (Laravel + Symfony Console parity).
ArtisanContext
Execution context handed to every ArtisanCommand.handle.
ArtisanGeneratorCommand
Base for code-gen commands (make:controller, make:model, etc.).
ArtisanInput
Abstract input layer for ArtisanCommand (Laravel-style).
ArtisanInstallCommand
Base class for every install command in the PluginInstaller DSL ecosystem.
ArtisanOutput
Abstract output layer for ArtisanCommand (Symfony Console parity).
ArtisanRegistry
Authoritative command registry for an ArtisanApplication.
ArtisanServiceProvider
Base for any package that contributes commands to an ArtisanApplication.
AskToRunSpec
One ask-to-run shell command spec.
BufferedOutput
Test-friendly output that captures everything into an in-memory buffer.
CommandSignature
Laravel-style command signature DSL parser.
CommandsRefreshCommand
artisan commands:refresh — scans lib/app/commands/ and rewrites _index.g.dart so every ArtisanCommand subclass in that directory is auto-registered on the next artisan invocation.
ConfigEditor
Configuration file editing utilities for CLI commands.
Conflict
Pre-flight conflict detector flagged one or more user-modified files and the caller did not pass force: true.
ConflictDetector
Pre-flight conflict detector for InstallTransaction.
ConsoleStyle
Console output styling utilities for Laravel Artisan-style CLI commands.
CopyFile
Copies a file from sourcePath to targetPath.
DeleteFile
Deletes the file at targetPath if it exists.
DiscoveredCommand
One discovered command entry from the filesystem scan.
DoctorCommand
Runs environment preflight checks (artisan toolchain).
DryRun
Dry-run completed: ops were rendered but nothing was written.
DryRunRenderer
Pure-function renderer that prints a structured dry-run preview of a staged InstallOperation list without touching the filesystem.
EnvEditor
Line-based .env file editor for CLI install commands.
EnvVarSpec
One env var spec: {default, comment?}.
Error
A write failed, an unimplemented op was encountered, or a post-rename step raised. rolledBack reflects whether the .tmp cleanup ran.
FileConflict
Represents a single file-level conflict detected before committing an InstallTransaction.
FileHelper
File system operation helpers for CLI commands.
GradleConfig
Gradle plugins + dependencies block (lives under native.android.gradle).
GradleDepSpec
One Gradle dependency entry: {scope, notation}.
GradleEditor
Android build.gradle / build.gradle.kts file manipulation helper.
GradlePluginSpec
One Gradle plugin entry: {id, version?}.
HelpCommand
artisan help <command> — prints full signature for a single command.
HotRestartCommand
artisan hot-restart — full state reset of the running flutter app.
HtmlEditor
HTML file injection helper for CLI commands.
InjectAfterPattern
Inserts code immediately after the first match of pattern in targetFile.
InjectAndroidMetaData
Adds a <meta-data> element inside <application> in AndroidManifest.xml.
InjectAndroidPermission
Adds a <uses-permission> element to AndroidManifest.xml.
InjectBeforePattern
Inserts code immediately before the first match of pattern in targetFile.
InjectEntitlement
Sets a key-value pair in the .entitlements file for platform.
InjectEnvVar
Writes a key-value pair to the project's .env file.
InjectGradleDependency
Adds a dependency declaration to android/app/build.gradle.
InjectGradlePlugin
Adds a plugin to the plugins block in android/settings.gradle.
InjectImport
Injects an import statement into targetFile if not already present.
InjectInfoPlistKey
Sets a key-value pair in ios/Runner/Info.plist.
InjectIntoMainDart
Injects code into lib/main.dart at the position specified by placement.
InjectIntoWebHead
Injects raw HTML content before the closing </head> tag in web/index.html.
InjectMainDartImport
Injects an import statement specifically into lib/main.dart.
InjectPodfileLine
Appends a line to the Podfile target block for platform.
InjectRouteRegistration
Registers a route function by appending a call to functionName in the project's route registry file.
InMemoryFs
In-memory VirtualFs backed by a Map (absPath -> UTF-8 content).
InstallArtisanCommand
install — scaffold the canonical native Flutter consumer (bin/dispatcher.dart + lib/app/_plugins.g.dart + initial lib/app/commands/_index.g.dart) into the current project AND auto-chain make:fast-cli so bin/fsa lands in the same invocation.
InstallContext
Dependency-injection container handed to every install operation in the PluginInstaller DSL.
InstallManifest
Root manifest carrying every section a plugin can declare.
InstallOperation
Base sealed class for all PluginInstaller DSL operations.
InstallTransaction
Orchestrator that stages a list of InstallOperations and either applies them atomically to disk, renders a dry-run preview, or refuses to write when ConflictDetector flags a target file the user has modified out-of-band.
IosConfig
iOS native configuration sub-section.
JsonEditor
JSON file manipulation helper for CLI commands.
JsonMergeSpec
JSON merge spec: where to read the source from + whether existing keys survive a collision.
ListCommand
artisan list — prints every registered command grouped by : namespace.
LogsCommand
Print or tail the captured flutter run stdout/stderr log.
MacosConfig
macOS native configuration sub-section. Shape mirrors IosConfig.
MagicIntegration
Magic-framework integration block. Every slot is optional.
MainDartEditor
Targeted mutations for a Flutter application's lib/main.dart file.
MakeCommandCommand
artisan make:command MyCommand — scaffolds a new ArtisanCommand subclass.
MakePluginCommand
artisan make:plugin <name>, scaffolds a new fluttersdk_artisan plugin skeleton under packages/<name>/ (or a --target / --path override).
ManifestInstaller
Bridges an InstallManifest onto a PluginInstaller chain + commits.
ManifestParser
Static parser: reads YAML text, returns a validated InstallManifest.
MapInput
In-memory map input for programmatic invocation (tests, command-from-command).
McpFilterConfig
Three-layer filter configuration for MCP tool discovery.
McpInstallCommand
artisan mcp:install — idempotently adds the fluttersdk MCP server entry to the project's .mcp.json (Claude Code / Cursor / Windsurf config).
McpServeCommand
artisan mcp:serve — starts the fluttersdk MCP server over stdio JSON-RPC.
McpServer
MCP server that exposes ArtisanRegistry.mcpTools to a connected MCP client (Claude Code, Cursor, etc.) over a StreamChannel of newline- delimited JSON-RPC.
McpToolDescriptor
A value type describing a single MCP tool contributed by an ArtisanServiceProvider via its mcpTools override.
McpUninstallCommand
artisan mcp:uninstall — remove the fluttersdk MCP server entry from .mcp.json. Handles both the legacy fluttersdk_mcp:server args shape and the new fluttersdk_artisan:mcp args shape; the key name is fluttersdk in both cases. Preserves all other entries. Idempotent.
MergeJson
Deep-merges sourceData into the JSON file at targetPath.
NativeConfig
Per-platform native configuration. Each slot is independently optional.
NullOutput
Discards every write. For tests that don't care about output.
Option
A command-line option.
OptionSpec
Option / flag specification parsed out of a signature.
OptionType
What kinds of values an option accepts.
PlatformHelper
Flutter platform detection and path resolution helper for CLI commands.
PlistWriter
Apple XML plist (v1.0) DOM writer for CLI plugin installers.
PluginEntry
Immutable value object representing a single registered plugin entry inside .artisan/plugins.json.
PluginInstallCommand
plugin:install <name>, register a third-party artisan plugin into the consumer project.
PluginInstaller
Fluent builder consumed by every plugin's <plugin>:install command.
PluginsRefreshCommand
artisan plugins:refresh: regenerates lib/app/_plugins.g.dart from the authoritative .artisan/plugins.json registry written by plugin install commands.
PluginsRegistry
Immutable value object representing the full contents of .artisan/plugins.json.
PluginsRegistryFile
Reads and writes the .artisan/plugins.json registry file through a VirtualFs abstraction so the class is fully testable without touching the host filesystem.
PluginUninstallCommand
plugin:uninstall <name>, reverse a manifest-driven plugin install.
PodfileConfig
Podfile sub-block (under native.ios.podfile or native.macos.podfile).
PodfileEditor
iOS and macOS Podfile manipulation helper for CLI install commands.
PostInstallSpec
Post-install shell + message block.
Prompt
Interactive stdin prompts for ArtisanCommands.
PromptDriver
Contract for interactive user-prompt I/O in the PluginInstaller DSL.
PromptSpec
One prompt spec: {key, type, default?, options?, question}.
PublishFile
Resolves a stub template, applies token replacements, and writes the result to targetPath.
PubspecDeps
Pubspec dependency section: dependencies / dev_dependencies / asset paths to append under flutter.assets.
RealFs
Production VirtualFs backed by dart:io. Every method delegates to the existing FileHelper utilities so the installer reuses the same atomic write + parent-directory semantics applied throughout the framework.
RealPromptDriver
Production PromptDriver that delegates every call to the static Prompt class.
RealStubDriver
Production StubDriver that delegates every call to the static StubLoader class.
ReloadCommand
artisan reload — hot reload the running flutter app.
RemoveDependency
Removes a dependency from pubspec.yaml (from either dependencies or dev_dependencies).
RestartCommand
Composes stop + start atomically.
RouteRegistryEditor
Route registration injection utilities for RouteServiceProvider.boot().
RunShell
Executes an arbitrary shell command after all file mutations have been committed.
ShellSpec
One unconditional shell command spec.
StartCommand
Spawns flutter run -d <device> detached, scrapes the VM Service URI from stdout, writes ~/.artisan/state.json for downstream consumers.
StateFile
Atomic JSON read/write for the artisan state file at ~/.artisan/state.json.
StatusCommand
Prints JSON status of the recorded flutter app + liveness check.
StdioOutput
Default output: stdout for normal/info/success/comment, stderr for error.
StopCommand
SIGTERMs the recorded flutter run PID + the FIFO stdin holder PID, deletes the FIFO + state.json. When chromePid is present in state, also delivers SIGTERM (with SIGKILL escalation) to that Chrome process and deletes the tmpProfileDir. Idempotent (silent if state.json absent).
StringHelper
StubDriver
Contract for stub template I/O in the PluginInstaller DSL.
StubLoader
Loads .stub template files from assets/stubs/ and replaces placeholders.
Success
All staged operations applied; the install record was persisted.
Tinker
Static hooks populated by host-side integration packages.
TinkerCommand
artisan tinker — connected REPL into the running Flutter app.
TransactionResult
Sealed outcome of InstallTransaction.commit.
VirtualFs
File-system abstraction consumed by every operation inside the installer/ subtree.
VmServiceClient
Wrapper around package:vm_service exposing the fluttersdk-house-style surface that artisan connected-mode commands consume.
WebConfig
Web native configuration sub-section.
WorkspaceEnroller
Detects a parent Flutter application in the directory hierarchy and enrolls a plugin package into its Dart pub workspace.
WriteFile
Writes raw content directly to targetPath, overwriting any existing file.
XmlEditor
XML and Plist file manipulation helper for CLI commands.

Enums

CommandBoot
Lifecycle boot mode an ArtisanCommand needs from the dispatcher.
MainDartPlacement
Placement anchor for code injected into lib/main.dart.

Functions

defaultConsumerWrapperExists({String? cwd}) → bool
Default wrapper presence check.
defaultConsumerWrapperName({String? cwd}) → String?
Default wrapper-name resolver.
discoverCommandsInDir(Directory commandsDir) → List<DiscoveredCommand>
Scans commandsDir for *.dart files (excluding _index.g.dart and anything else starting with _), extracts ArtisanCommand subclass names, returns one DiscoveredCommand per match.
formatInstanceRef(Object? value) → String
Best-effort pretty-print for a raw VM Service evaluate result.
formatTinkerResult(Object? value, {List<TinkerCaster>? casters}) → String
Formats a VM Service evaluate result for REPL output.
parsePidLines(Iterable<String> lines) → Map<String, int>
Parses <TAG>=<int> lines emitted by the start wrapper script into a map keyed by tag. Unknown lines are skipped; malformed entries (tag matches but value is not an integer) are also skipped silently — the caller decides whether missing entries are fatal.
processAlive(int pid) → bool
Returns true when a process with the supplied PID is currently alive.
registerExtensionIdempotent(String method, ServiceExtensionHandler handler) → void
Calls developer.registerExtension swallowing the duplicate-registration ArgumentError that fires when the same extension name is registered twice within a single isolate.
renderCommandsIndex(List<DiscoveredCommand> commands) → String
Renders the auto-generated index file content for commands.
runArtisan(List<String> args, {List<ArtisanServiceProvider> baseProviders = const <ArtisanServiceProvider>[], List<ArtisanServiceProvider> autoProviders()?, bool delegateToConsumer = true, bool collectMcpTools = false, WrapperExistsCheck? wrapperExists, WrapperNameResolver? wrapperName, DelegateStrategy? delegate}) → Future<int>
Shared artisan bootstrap.
shellQuoteTokens(List<String> tokens) → String
POSIX shell-quoting for arguments passed to sh -c '...'.
writeCommandsIndex(Directory commandsDir) → List<DiscoveredCommand>
End-to-end: scan + write. Returns the discovered command list so the caller can report what was registered.

Typedefs

CdpChromeBinaryResolver = String? Function(String? envOverride)
Resolves the on-disk Chrome binary path or returns null when unsupported.
CdpChromeNavigator = Future<void> Function(int port, String url)
Sends a Page.navigate CDP command to Chrome on port for url.
CdpChromeProber = Future<void> Function(int port, Duration timeout)
Probes a local Chrome instance on port within timeout. Returns when Chrome answers /json/version; throws otherwise.
CdpFifoMaker = Future<void> Function(String path)
Creates a POSIX FIFO at path. Real implementation calls mkfifo; tests stub to a regular file.
CdpProcessRunner = Future<ProcessResult> Function(String executable, List<String> arguments, {Map<String, String>? environment, bool includeParentEnvironment, bool runInShell, Encoding? stderrEncoding, Encoding? stdoutEncoding, String? workingDirectory})
Signature for Process.run test seam.
CdpProcessStarter = Future<Process> Function(String executable, List<String> arguments, {ProcessStartMode? mode, String? workingDirectory})
Signature for Process.start test seam. Mirrors the upstream subset StartCommand needs. The mode parameter is nullable so test fakes can omit it comfortably; _defaultProcessStart bridges to Process.start's non-nullable parameter with a default.
CdpVmServiceScraper = Future<String> Function(File logFile)
Scrapes the VM Service URI from a log file. Used to inject a fake in tests.
CdpWebServerReadyWaiter = Future<void> Function(File logFile)
Waits until the web-server log emits the "is being served at" line. Used to inject a fake (instant-return) in tests so the CDP branch can be exercised without a real flutter process writing to the log.
DelegateStrategy = Future<int> Function(List<String> args)
Signature for an injected delegation strategy.
ServeStrategy = Future<void> Function({required McpFilterConfig filter, required ArtisanRegistry registry})
Signature for the serve strategy injected into McpServeCommand.
StateReader = Future<Map<String, dynamic>?> Function()
Signature for the state-file reader.
TinkerCaster = String? Function(Object? value)
Returns a formatted string representation of value, or null to defer to the next caster in the chain.
VmServiceClientFactory = VmServiceClient Function(String wsUri)
Signature for the VM Service client factory.
WrapperExistsCheck = bool Function()
Signature for an injected "does CWD have a consumer wrapper?" check.
WrapperNameResolver = String? Function()
Signature for an injected wrapper-name resolver.

Exceptions / Errors

ArgParserException
An exception thrown by ArgParser.
ArtisanCommandCollisionException
Thrown by ArtisanRegistry.register when two providers register a command with the same name without explicit override: true.
ArtisanMcpToolCollisionException
Thrown by ArtisanRegistry.registerMcpToolsFor when two providers register an MCP tool with the same name.
InstallException
Base exception for all errors raised by the PluginInstaller DSL.
ManifestValidationException
Raised when an install.yaml manifest fails schema or semantic validation.