zuraffa 6.2.2

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

🦒 Zuraffa

The AI-first Clean Architecture framework for Flutter.

Zuraffa v5 standardizes code generation around one canonical workflow:

1. zfa entity create
2. zfa make
3. zfa build

zfa make is the primary generation surface. zfa feature still exists, but only as a wrapper over the normalized feature preset.

---

Sponsor

Thanks to ZikZak AI for sponsoring this project!

ZikZak AI is an AI-Powered Price Comparison app that you scan barcodes, and discover amazing savings instantly. Your personal shopping assistant that never sleeps.

Why Zuraffa?

• AI-native: predictable structure for humans and coding agents.
• Clean Architecture by default: domain, data, presentation, and DI stay consistent.
• Zorphy-first entities: immutable, typed entities generated under a fixed domain root.
• Deterministic generation: presets, aliases, --with, and --without resolve through the same plan system.
• Result-based failures: generated code uses Result<T, AppFailure> patterns throughout.
• Hermetic-friendly workflows: docs and tests are aligned around the current v5 surface.

---

Scope

zfa is scoped to Zuraffa apps — packages that depend on zuraffa/zorphy_annotation and carry a .zfa.json. The CLI generates clean-architecture code inside that contract and nothing else: it does not rewrite existing non-Zuraffa Flutter packages or plugins, and zfa doctor reporting missing Zuraffa dependencies inside such a package is expected behavior. Rewriting a non-Zuraffa plugin stays hand-written work unless you file a feature request for that support. See the CLI guide for details.

---

Installation

Add Zuraffa to your project:

dependencies:
  zuraffa: ^5.0.0

dev_dependencies:
  zuraffa: ^5.0.0
  zorphy_annotation: ^1.7.0
  build_runner: ^2.4.0

Install the CLI globally if you want zfa on your PATH:

dart pub global activate zuraffa

---

Quick Start: the canonical v5 flow

1. Create an entity

Entities are always generated under lib/src/domain/entities in v5.

zfa entity create -n Product \
  --field id:String \
  --field name:String \
  --field price:double \
  --field description:String?

2. Generate architecture with make

Use zfa make as the default way to build the architecture around that entity.

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

That expands to a normalized plan that generates the domain, data, presentation, and test layers for Product.

3. Run the build step

zfa build

Use zfa build instead of calling build_runner directly in docs and agent workflows.

---

Core v5 commands

Command	Role in v5
zfa entity create	Define or update Zorphy entities
zfa make	Canonical architecture generator
zfa build	Run the codegen/build step
zfa feature scaffold	Wrapper over the normalized feature preset
zfa config	Manage .zfa.json project defaults
zfa manifest	Inspect available plugins and capabilities
zfa doctor	Inspect local tooling and project health

---

Fixed project layout

Zuraffa v5 assumes a fixed architecture root:

lib/src/
├── data/
├── di/
├── domain/
│   ├── entities/
│   ├── repositories/
│   └── usecases/
└── presentation/

Entity files must live at:

lib/src/domain/entities/{entity_snake}/{entity_snake}.dart

Example:

lib/src/domain/entities/product/product.dart

---

.zfa.json defaults and .zfa/ project memory

Zuraffa v5 separates project defaults from project memory:

• .zfa.json: active project configuration such as plugin defaults and entity-first rules.
• .zfa/: the canonical v5 project-memory model for plans, runs, decisions, blueprints, manifests, and future agent context.

A useful mental model for humans and AI agents is:

.zfa.json      -> what this project prefers by default
.zfa/          -> what has been planned, generated, and decided over time

Canonical .zfa/ layout

.zfa/
├── plans/
├── runs/
├── blueprints/
├── decisions/
├── manifests/
├── receipts/
└── context.json

During the v5 migration, some internal surfaces may still reference older storage paths. Treat the structure above as the public documentation contract going forward.

---

Proof-carrying generation (v0)

Every artifact zfa entity create, zfa entity add-field and zfa make writes ships with a generation receipt in .zfa/receipts/ — a JSON record (schema proof.v1) binding it to the command that produced it, the generator version, the input context, the entity spec it was generated from, and the SHA-256 digest of the exact bytes that landed on disk.

zfa proof check re-derives every digest and fails on any artifact that cannot prove where it came from:

• Editing or deleting a generated file flips the check red with a precise line diff (small files keep a snapshot in the receipt).
• A stale-spec artifact (the entity drifted after generation) is flagged and the receipt names the exact spec delta.
• Pass coverage roots to fail on unprovenanced generated-code paths:

zfa proof check lib/src                  # text verdict, exit 1 on drift
zfa proof check lib/src --format=json    # proof.v1 envelope for CI (#778)

CI recipe (fail on unprovenanced or tampered generated code) — a runnable version lives in tools/proof_smoke.sh:

- run: dart run bin/zfa.dart proof check lib/src --format=json

---

make first, feature second

If you see both commands in the codebase, prefer this rule:

• Use zfa make when you want explicit control.
• Use zfa feature scaffold only when you intentionally want the feature preset wrapper.

Equivalent example:

zfa make Product --preset=feature --plan

zfa feature scaffold Product --plan

---

AI-agent contract

For Zuraffa v5 projects:

• Generate architecture code with zfa, not by hand.
• Create entities with zfa entity create.
• Generate layers with zfa make.
• Run zfa build after generation.
• Handcraft only manual UI composition/layout zones and normal business implementation details that generation does not own.

The pipeline rule

If an AI agent is asked to build a feature, it should always start by asking:

1. Does a new entity need to exist? → use zfa entity create
2. Does the architecture skeleton need to exist or change? → use zfa make
3. Do generated annotations/build outputs need to be finalized? → use zfa build

Zuraffa owns the architecture skeleton. Human or agent implementation work should narrow to the remaining business logic, datasource implementation, styling, and manual UI composition after that pipeline runs.

---

The exit-code protocol + machine verdicts (SPEC 917)

zfa exits are a protocol, not a grab-bag of codes — the golden table is asserted against the live CLI by test/commands/exit_protocol_golden_test.dart and enforced in CI by .github/workflows/conformance.yml:

code	name	meaning
0	success	GREEN / complete — the operation ran and passed
1	failure	RED (honest, in-loop) / stopped / audit failure (see the verdict's exit_class)
2	usage	the operation could not run as invoked (legacy 64 maps here)
3	drift	contract/spec drift — manifest ↔ CLI flag drift, corrupt state evidence
4	conflict	state conflict — concurrent run ownership, evidence lock inconsistency

Every non-zero exit ends with a machine-actionable --> fix: line: errors are an API, not an apology. 255/-9/137 are external-kill signals zfa never emits.

The treaty gate: zfa manifest --verify [pluginIds...] certifies manifest inputSchemas ↔ CLI flags ↔ help text for every CLI-aware plugin (schema→flags, help text, dead-flag, and resolution legs). Drift exits 3; a clean pass exits 0 and drops into CI. --format json emits one machine-verifiable manifest-verify.v1 document.

Machine verdicts: every zfa tdd verb and every zfa corpus subcommand accepts --json and closes with a versioned verdict.v1 envelope as the final stdout line (errors included — the envelope carries the same --> fix: remediation). The driving verbs (tdd run, run-engine, run-skin) also accept --stream: one NDJSON step-verdict.v1 event per completed loop step as it happens, terminated by the final verdict.v1 envelope. The table itself is printed by zfa --help and embedded in zfa schema (x-zfa-exit-protocol).

---

Migration notes

If you are coming from pre-v5 guidance:

• the old one-shot generator command is gone,
• zfa make is now the canonical generator,
• zfa feature is a wrapper, not the primary public workflow,
• the domain root is fixed to lib/src/domain, and
• v5 public docs assume Zorphy-based entities.

See doc/MIGRATION_GUIDE.md for a focused migration walkthrough.

---

Mock data & prototyping (v5.1.0)

# Generate Dart mock data
zfa mock Product

# Generate JSON mock data with fromJson-based helpers
zfa mock json Product

# Tier-1 certified mock: auto-generated contract test proven in a
# throwaway sandbox (dart analyze + dart test) + per-method receipt
zfa mock create Login --certify

# Deterministic, replayable generation (same seed → byte-identical mocks)
zfa mock create Login --seed=42

# Re-certify live and register the mock in the #832 fixture registry
zfa mock certify Login

# Re-run the certification gate against the mocks on disk — read-only,
# exit 0 conforming / 1 with --> fix: lines on entity drift (--json emits
# the canonical zuraffa.verdict.v1 envelope)
zfa mock verify Login

# Explain a mock: method coverage, skipped members, per-method
certification status, MockData.forMethod fixture-selector bindings
zfa mock explain Login

--certify (spec 1001, VISION §9 "mocks the framework certifies, not the agent") writes test/mock/<snake>/<snake>_mock_contract_test.dart — every interface method pinned through the interface type, so interface drift turns the certification red — plus a mock-cert.<Entity>.json receipt with per-method satisfied flags and the contract digest. zfa mock certify <Entity> re-proves the contract live and registers the receipt in the feature's tdd/fixtures/ #832 manifest (mocks: provenance, hash-chained kind: mock-cert cycle evidence). zfa tdd run-engine <feature> (and the zfa tdd run preflight) refuse to proceed when any CORE (declared Key Entity) mock is present but uncertified.

zfa mock verify <Entity> (spec 1121) re-runs the SAME conformance gate --certify uses against the mock files already on disk and the current entity source — read-only, so re-proving after an entity edit never generates. Drift exits 1 with --> fix: lines naming the missing/incorrect members; zfa mock verify <Entity> --json emits one canonical zuraffa.verdict.v1 envelope (findings, drifts, certification record). zfa mock explain <Entity> (also spec 1121) reports the mock's surface: covered and skipped methods, per-method certification status from the committed receipt (certified, certified-red, uncertified, missing), and the MockData.forMethod fixture-selector bindings (issue #1034); --json carries the full report under the envelope's details.explain.

JSON mocks produce standalone JSON files under data/mock_json/{domain}/ and Dart helpers that load them via fromJson. Swap JSON content for instant prototyping without code changes or regeneration.

final products = await ProductMockJson.loadProducts();
final sample = await ProductMockJson.loadSampleProduct();

See website/docs/features/mock-data.md for details.

---

Learn more

• CLI_GUIDE.md
• AGENTS.md
• SKILL.md
• website/docs/intro.md
• doc/MIGRATION_GUIDE.md

Made with 🦒 and ⚡ by the Zuraffa project.