zuraffa 5.7.1

AI first Flutter Clean Architecture Framework and CLI with Result types, UseCase patterns, Dependency Injection and MCP server for building type-safe, scalable apps with AI agents.

5.7.1 - 2026-07-30

Change

• MCP tools now execute CLI commands (fixes #150, #160); zuraffa_setup tool; config_init dependency report; Process.start timeout fix

5.6.2 - 2026-07-21

Changed

• Zorphy upgrade: updated zorphy to ^1.9.0, zorphy_annotation to ^1.9.0
• Checked deserialization: all fromJson methods now use $checkedCreate with checked: true, providing field-level error messages that identify which field failed and the input data on deserialization failure — significantly easier debugging for malformed JSON
• Credentials: fromJson now delegates to the generated _$CredentialsFromJson instead of manual casting; toJson no longer includes the spurious hashCode field

Fixed

• Publish script: hardened submodule handling — git pull --rebase replaced with git fetch origin master + reset --hard for deterministic zuraffa-zed sync; submodule is now updated in step 2 (before the main repo commit) so the submodule pointer is correct in the release commit

Chores

• Zed extension submodule updated for v5.6.2

5.6.0 - 2026-07-16

Added

• Strategy plugin: new zfa strategy create command generates FetchStrategy abstract base, concrete pipeline variants, and a StrategySelector for pluggable data-fetching — ideal for A/B testing scraper vs AI pipelines at runtime
• Strategy builder: auto-resolves entity imports for paramsType/returnsType generics via CommonPatterns.entityImports(), using the same resolution logic as all other generators
• FetchStrategy<Input, Output>: core abstraction with fetchOne, fetch (stream), and canHandle — analogous to SyncStrategy for the fetch side
• StrategySelector: wires candidates in priority order, returns the first applicable strategy via select(), or all via selectAll()
• GeneratorConfig: enableStrategy and strategyNames fields for strategy-aware code generation

Fixed

• Strategy builder: unnecessary braces in string interpolation (${variantPascal} → $variantPascal)
• Strategy plugin: eliminated late final StrategyBuilder by moving initialization to the initializer list
• Hook registry: replaced bool get isEnabled / set isEnabled wrapper with a direct public field (unnecessary_getters_setters lint)

Tests

• 23 new tests covering the strategy plugin and builder: plugin metadata & capability lifecycle, builder content verification (abstract base, concrete variants, selector), entity import resolution, dry-run behavior, file path correctness, and dynamic type fallback

5.5.0 - 2026-07-13

Changed

• API bridge codegen: generated bridge files now use getIt<Type>() pattern instead of GetIt.I<Type>(), aligning with Zuraffa project conventions
• Example app: added registerTodoApiBridge() to main.dart, demonstrating full bridge initialization lifecycle on app startup

Documentation

• Updated VM Service API Bridge design docs with v5.4.2 codegen details

5.4.2 - 2026-07-09

Fixed

• API bridge codegen: _paramsTypeHasFromJson() now strips generic type parameters (e.g. QueryParams<Product> → QueryParams) before checking for entity directories
• API bridge codegen: known Zuraffa core types (QueryParams, QueryParamsPatch) now correctly identified as having fromJson
• API bridge codegen: stream handlers with primitive params (String, int, etc.) now generate proper extraction instead of broken .fromJson(json) calls
• API bridge codegen: usecases whose params type lacks fromJson are now skipped with a warning instead of generating uncompilable code
• Test: added skip test for unknown param types, all 8 tests passing

5.4.1 - 2026-07-09

Fixed

• API bridge codegen: usecase import filenames now use _usecase.dart convention (strip "UseCase" suffix before camelToSnake)
• API bridge codegen: missing param type imports (e.g. BarcodeSpark) now auto-detected from entity directory
• API bridge codegen: bogus entity-path imports for non-entity param types (e.g. SearchMissingCoreChannelsParams) no longer generated
• API bridge codegen: removed unused uuid import from generated bridge files
• Test: added import correctness test covering _usecase.dart convention and entity param imports

5.4.0 - 2026-07-09

Added

• VM Service API Plugin (--with=vmapi): auto-registers every UseCase as a Dart VM Service extension
  • ZuraffaApiBridge core: init, registration, result serialization, stream subscription management
  • ApiEndpoint metadata model with _list discovery endpoint
  • zfa api <Entity> CLI command generating usecase bridge code
  • call_api.sh convenience script with auto-isolate discovery
  • Complete example: Todo entity with 2 exposed usecases (create, getList)
  • Release mode safety gate (kReleaseMode no-op), profile mode opt-in
  • Tested and validated on iOS Simulator and macOS Desktop

Fixed

• Build: removed broken json_serializable git override (ref: analyzer-13) — uses pub.dev ^6.13.1 instead
• Build: flutter pub get now resolves cleanly with analyzer 13.0.0 override for hive_ce_generator + dart_style coexistence
• Example app: setupDependencies() catchError now logs the full error and stack trace instead of silently swallowing
• Example app: Todo UseCases now properly registered in DI (all 7: create, delete, get, getList, update, watch, watchList)
• Bridge handler: createTodo auto-fills id and createdAt defaults for Zorphy fromJson compatibility

Docs

• Architecture, sequence, and class diagrams for the VM Service API bridge
• Platform testing guide with Python, curl, and shell script examples
• 6 key insights captured in INSIGHTS.md (isolateId requirement, DI registration, Zorphy defaults, Hive initialization, analyzer compatibility)

5.3.0 - 2026-06-30

Added

• UseCase Hook System: implement UseCaseHook protocol with pre-execute, post-execute, and error handlers. Supports stream and future usecases.
  • EngagementHook with smart timeout + fallback orchestration
  • Declarative hook registration via UseCase<T, P> constructor
• Offline-first sync plugin: local-first architecture with pending change queue and conflict resolution
• Sync retry strategy: syncFailed + autoSync for smart retry on failure

Fixed

• Zed extension WASM binary now uses correct wasm32-wasip1 target in publish script
• Various repository fixes

5.2.1 - 2026-06-12

[5.2.1] - 2026-06-12

Added

• Declarative UseCase Registration (zfa register <UseCaseName>): batch command to register a use case across Presenter, Controller, State, and DI layers without regenerating files.
  • zfa presenter register <UseCaseName> — register in an existing Presenter
  • zfa controller register <UseCaseName> — register in an existing Controller
  • zfa state register <FieldName> — register a field in an existing State class
  • zfa register <UseCaseName> --all — batch register across all layers in one command
  • Individual plugin capabilities auto-discovered by the MCP server
• MCP zuraffa_register tool — batch registration tool exposed via the MCP server, calls RegisterCommand in-process
• Zed extension arch fix — corrected arm64 asset matching (no longer incorrectly falls back to x64 binaries)
• Zed extension API fallback — try_direct_download constructs GitHub release download URL directly when the API is rate-limited or unavailable
• publish.sh now tags zuraffa-zed — creates and pushes a v<VERSION> tag on the zuraffa-zed repo to trigger CI releases

Changed

• MCP server runs fully in-process: all CLI commands (make, entity create, build, config, graphql, register, etc.) now execute via CliRunner.runCapturing() instead of spawning subprocesses. The zuraffa_mcp_server binary no longer requires a separate zfa CLI download or dart run zuraffa:zuraffa.
• Removed _resolveExecutable(), _cachedExecutable, and subprocess-based _runZuraffaProcess — dead code from the old subprocess approach
• Zed extension version updated from 4.1.2 to 5.1.1, matching the zuraffa package version
• MCP server source refactored for better readability and maintainability

Fixed

• Zed extension timeout on setup: fixed asset matching logic and added a direct URL download fallback that works when the GitHub API is rate-limited
• MCP server _runQuickDoctor restored (was accidentally removed during refactoring)

5.1.1 - 2026-06-12

Change

• Release 5.1.1

5.0.2 - 2026-06-12

Change

• Release 5.0.2

5.1.0 - 2026-06-06

Added

• JSON mock data generation (zfa mock json): generates standalone JSON files with mock entity data using fromJson-based Dart helpers for fast prototyping without code changes
• Clean folder convention for mock JSON data: data/mock_json/{domain}/{entity}.mock.json
• JsonMockCapability plugin capability with plan/execute interface
• MockJsonBuilder with path resolution, domain auto-detection, and recursive nested entity generation
• MockJsonHelperBuilder generating typed async accessors (loadProducts(), loadSampleProduct(), etc.)
• MockValueBuilder.generateMockValuesForJson() heuristic value generation for JSON output
• Polymorphic entity _type discriminator support in JSON output with switch-based deserialization
• Enum value extraction via EntityAnalyzer.getEnumValues() for correct JSON serialization
• Generation metadata tracking (.mock.json.meta) with hash comparison for non-overwrite safety
• Field mismatch detection warning when entity fields change between generations
• --json flag on zfa mock command and zfa mock json <Entity> subcommand
• generateMockJson and mockJsonDomain fields to GeneratorConfig
• mockJsonByDefault config key to ZfaConfig

Changed

• MockBuilder.generate() delegates to MockJsonBuilder when generateMockJson is true
• MockPlugin registers JsonMockCapability and exposes mock-json config schema option
• MockEntityGraphBuilder supports recursive nested entity name collection for JSON generation
• Version bumped to 5.1.0

5.0.1 - 2026-06-01

Change

• Release 5.0.1

5.0.0 - 2026-06-01

🎉 Zuraffa v5 - Canonical Pipeline Release

Zuraffa v5 establishes a unified, AI-first generation contract that replaces the legacy one-shot generator with a three-step canonical workflow.

Breaking Changes

Removed Legacy Generator

• Removed: zfa generate command and all legacy one-shot generation patterns
• Removed: Custom domain/output directory overrides (--domain-root, --entity-output, --output)
• Removed: Legacy flag combinations and implicit generation modes
• Migration: Use the v5 canonical workflow: entity create → make → build

Fixed Architecture Contract

• Fixed domain root: lib/src/domain (no longer configurable)
• Fixed entity location: lib/src/domain/entities/{entity_snake}/{entity_snake}.dart
• Fixed output root: lib/src for all generated architecture

New Canonical Workflow

The v5 contract enforces a three-step pipeline for all generation:

# Step 1: Create entity
zfa entity create -n Product --field id:String --field name:String --field price:double

# Step 2: Generate architecture
zfa make Product --preset=crud --methods=get,getList,create,update,delete --with=vpc --state --di --test

# Step 3: Run code generation
zfa build

What zfa make Generates

• Repository interfaces and implementations
• DataSource interfaces and implementations
• UseCases for business logic
• Presenters/Controllers/State (with --with=vpc --state)
• DI registration (with --di)
• Tests (with --test)
• Cache support (with --cache)
• Mock datasources (with --mock)
• Route generation (with --route)
• GraphQL support (with --gql)

Configuration Changes

New .zfa.json Structure

Migrated from flat configuration to nested v5 shape:

{
  "plugins": {
    "defaults": {
      "di": true,
      "test": true,
      "method_append": true,
      "route": false,
      "mock": false,
      "gql": false,
      "cache": false
    },
    "disabled": []
  },
  "planning": {
    "presets": {},
    "aliases": {}
  },
  "ui": {
    "adaptiveLayouts": true,
    "platformShells": true,
    "layoutTargets": ["mobile", "tablet", "desktop"],
    "adaptivePreset": "adaptive-feature"
  },
  "entity": {
    "entityFirst": true,
    "jsonByDefault": true,
    "compareByDefault": true,
    "filterByDefault": true
  },
  "buildByDefault": false,
  "formatByDefault": false
}

Project Memory: .zfa/ Directory

Introduced .zfa/ as the canonical project memory surface for AI agents and developers:

.zfa/
├── plans/          # Generation plans from `zfa make --plan`
├── runs/           # Execution logs and results
├── blueprints/     # Architectural blueprints and patterns
├── decisions/      # Architectural decision records (ADRs)
├── manifests/      # Feature manifests
└── context.json    # Project context and state

See doc/ZFA_MEMORY_GUIDE.md for complete usage documentation.

MCP Server Updates

• Updated: MCP now advertises zuraffa_make instead of zuraffa_generate
• Updated: MCP tool execution invokes zfa make with the v5 contract
• Updated: Tool schema includes preset parameter for generation patterns
• Updated: Documentation reflects the canonical v5 pipeline

Documentation Updates

New Documentation

• doc/V5_ACTION_PLAN.md - Concrete v5 execution plan
• doc/ROADMAP.md - v5-specific roadmap
• doc/ZFA_MEMORY_GUIDE.md - Complete .zfa/ usage guide
• doc/ZIK_ZAK_V5_MIGRATION_PLAN.md - Downstream migration guide

Updated Documentation

• README.md - v5 workflow and examples
• website/docs/intro.md - v5 getting started
• website/docs/features/mcp-server.md - v5 MCP integration
• doc/MCP_SERVER.md - v5 MCP documentation
• AGENTS.md - v5 AI agent guidelines

Removed Documentation

• doc/cli_command_list.md - Obsolete command reference
• doc/combinations.md - Legacy flag combinations

Example Project Updates

• Updated example/.zfa.json to v5 shape
• Updated all example code to use v5 workflow
• Cleaned legacy command references from comments
• Updated test fixtures to v5 patterns

Testing & Validation

New Tests

• test/regression/v5_pipeline_contract_test.dart - Enforces v5 contract across all surfaces
• Enhanced test/regression/docs_command_consistency_test.dart - Validates documentation consistency

Test Coverage

• ✅ Default .zfa context uses entity create → make → build
• ✅ Core docs teach the full canonical pipeline
• ✅ MCP advertises zuraffa_make and invokes make
• ✅ example/.zfa.json uses v5 config shape
• ✅ No active/public surfaces contain legacy commands

Migration Guide

For Existing Projects

Step 1: Update .zfa.json

# Backup your current config
cp .zfa.json .zfa.json.backup

# Update to v5 shape (see doc/ZFA_MEMORY_GUIDE.md for examples)

Step 2: Update project guidance

• Replace zfa generate with zfa make in docs
• Remove custom --domain-root or --output flags
• Update to fixed domain structure: lib/src/domain/entities/{entity}/{entity}.dart

Step 3: Seed .zfa/ directory

mkdir -p .zfa/{plans,runs,blueprints,decisions,manifests}
# Create initial context.json (see doc/ZFA_MEMORY_GUIDE.md)

Step 4: Regenerate features incrementally

# Start with a small pilot feature
zfa make YourEntity --preset=crud --methods=get,getList --with=vpc --state --di --test
zfa build

For New Projects

Start with the v5 workflow from day one:

# 1. Create entity
zfa entity create -n User --field id:String --field email:String --field name:String

# 2. Generate architecture
zfa make User --preset=crud --methods=get,getList,create,update,delete --with=vpc --state --di --test

# 3. Build
zfa build

Presets and Patterns

Available Presets

• crud - Complete CRUD stack (repository, datasource, usecases)
• feature - Full feature with presentation layer
• adaptive-feature - Feature with adaptive layouts for multiple platforms

Common Patterns

Basic CRUD:

zfa make Product --preset=crud --methods=get,getList,create,update,delete

Full stack with presentation:

zfa make Product --preset=crud --with=vpc --state --di --test --methods=get,getList,create,update,delete

Custom use case:

zfa make SearchProducts usecase --domain=search --params=SearchQuery --returns=List<Product>

With caching:

zfa make Product --preset=crud --cache --methods=get,getList

With mocks:

zfa make Product --preset=crud --mock --use-mock --methods=get,getList

Adaptive Layouts

v5 introduces adaptive layout support for multi-platform applications:

zfa make Product --preset=adaptive-feature --with=vpc --state --methods=get,getList

Generates layouts for:

• Mobile
• Tablet
• Desktop
• Platform-specific shells (e.g., macOS)

AI Agent Integration

v5 is designed for AI-first workflows:

• MCP Server: Native integration with Claude and other AI assistants
• Project Memory: .zfa/ provides context for multi-session agent work
• Canonical Contract: Single workflow reduces agent confusion
• Documentation: All docs teach the same v5 pattern

Downstream Validation

The v5 pipeline has been validated with:

• Complete example project regeneration
• ZikZak app migration (Phase 1 complete)
• v4 vs v5 comparison testing
• Comprehensive regression test suite

Known Limitations

Manual Integration for .zfa/

Currently, .zfa/ artifacts are manually managed. Future versions will:

• Auto-write plans when using --plan
• Auto-write run logs after execution
• Auto-update context.json after generation

GraphQL Support

GraphQL plugin is currently disabled by default. Full GraphQL support is planned for v5.1.x.

Upgrade Path

From v4.x to v5.0.0:

1. Update pubspec.yaml: zuraffa: ^5.0.0
2. Run flutter pub get
3. Update .zfa.json to v5 shape
4. Update project docs to remove legacy commands
5. Seed .zfa/ directory structure
6. Regenerate features incrementally with zfa make

Estimated migration time:

• Small projects (1-5 features): 1-2 hours
• Medium projects (5-15 features): 4-8 hours
• Large projects (15+ features): Plan incremental migration over multiple sessions

Future Roadmap

v5.1.x (SHOULD)

• zfa migrate - Automated migration from v4 to v5
• zfa doctor - Project health diagnostics
• zfa diff - Preview regeneration changes
• GraphQL decision and integration
• Adaptive layout refinements
• Unified root resolution

v5.2.x (NICE TO HAVE)

• Enhanced docs and recipes
• Faster incremental regeneration
• Better progress reporting
• Routing helpers
• Realtime scaffolds

Contributors

Special thanks to all contributors who helped shape v5.

Resources

• Documentation: https://zuraffa.com
• Repository: https://github.com/arrrrny/zuraffa
• Issues: https://github.com/arrrrny/zuraffa/issues
• Migration Guide: doc/ZIK_ZAK_V5_MIGRATION_PLAN.md
• Memory Guide: doc/ZFA_MEMORY_GUIDE.md
• Action Plan: doc/V5_ACTION_PLAN.md

---

4.1.2 - 2026-05-03

Change

• Release 4.1.2

4.1.1 - 2026-05-02

Fixed

• OpenTelemetry Context Management: Fixed "unexpected (mismatched) token given to detach" errors in concurrent scrape operations.
  • trace() and traceSync() now wrap their entire body in runZoned() to fork isolated zones with independent context stacks.
  • Parent context is explicitly captured and passed to startSpan() to maintain correct span lineage across asynchronous boundaries.

Change

• Release 4.1.1

4.1.0 - 2026-04-30

Added

• Analyzer 13 Support: Full compatibility with analyzer package version 13.0.0.
• Robust AST Migration: Implemented reflection-based helper methods in InjectBuilder and MethodExtractor to support both legacy and new analyzer AST structures (RegularFormalParameter, NamedArgument, Label.name, etc.).
• Improved DI Generation: Enhanced constructor merging and registration logic to handle breaking changes in formal parameter representation.

Changed

• Upgraded dart_style to ^3.1.9 for improved code formatting and compatibility with new Dart features.
• Pin analyzer to 13.0.0 in dependency overrides to ensure stable code generation.
• Upgraded zorphy_annotation to ^1.7.0 and zorphy to ^1.6.9.

4.0.10 - 2026-04-26

Change

• Release 4.0.10

4.0.9 - 2026-04-26

Change

• Release 4.0.9

4.0.8 - 2026-04-26