flutterflow_flash_beta 0.1.0

Dart SDK for programmatically reading and modifying FlutterFlow projects. Built for the beta environment.

0.1.0

Initial release.

Core SDK

• SDK client with session management (lock/unlock), project CRUD, and schema validation.
• 16+ helper modules: collections, pages, components, action blocks, app events, custom code, data schemas, enums, data structs, app state, queries, themes, APIs, library parameters, library values, widget class parameters, nav bar, routing, widget properties, tree mutation, pub dependencies, variable operations, state updates, graph analysis.
• 18 idempotent ensure* helpers (ensurePage, ensureCollection, etc.) for re-runnable pipelines — exact reruns return the existing identifier/key, while payload drift throws and should be handled with update* helpers or onUpdate:.
• 14 update* helpers for full CRUD coverage: updateCollection, updateCollectionField, updateDataStruct, updateDataStructField, updateEnum, updateEnumValue, updateAppStateField, updateAppConstant, updateActionBlock, updateApiEndpoint, updateApiGroup, updatePageParameter, updateComponentParameter, updateStateField.
• updatePageBody and updateComponentBody to replace widget trees in place.
• Enhanced "not found" error messages across helpers — lists available names for self-correction.
• FlashApiException.hint with recovery guidance for 409 (lock), 403 (auth), and 404 (not found) errors.
• listProjects() uses dedicated sdkListProjects endpoint with API token auth.
• Local validation via pre-compiled .dill kernel snapshots (no server round-trip).

DSL

• Declarative Dart DSL for building FlutterFlow apps: flash(builder) compiles and pushes in one call.
• Greenfield: define pages, components, enums, data structs, app state, API endpoints, and widget trees from scratch.
• Brownfield: editPage / editComponent for structural edits against existing projects — select widgets by key, name, type, or text, then insert, replace, remove, or rewire.
• DSL JSON snapshots (dsl_json/) — machine-readable project context written to disk on push, refresh-context, and workspace init. flash inspect reads from these for instant offline access.

Pipeline

• FlashPipeline + FlashTask for modular, dependency-aware task execution with automatic lifecycle management (lock → fetch → run tasks → validate → push → capture resulting commit → release).
• PipelineProject.findOrCreate(name) to reuse existing projects by name on re-run.
• PipelineSource for mandatory source code upload with pipeline runs.
• Per-task local validation — error-severity issues halt the pipeline immediately; subsequent tasks are not executed and push is blocked.
• Validation gates push — broken projects never reach FlutterFlow. Check result.validationBlocked and result.errors. result.diagnostics is the primary error surface.
• Dry-run mode (FlashPipeline(dryRun: true)) to preview changes without pushing.
• Greenfield runs auto-prune the untouched blank HomePage placeholder that brand-new FlutterFlow projects start with.
• Workspace state (.flash/workspace.json) — caches project ID, records per-task pass/fail/skip/validation_failed status.
• Local run journal and source archival — every run journaled to .flash/runs.jsonl with source files archived to .flash/history/<run-id>/.
• Canonical RunTrace artifacts in .flash/traces/<run-id>.json.
• Support bundle export and support replay workspace reconstruction.
• Local derived issue candidates built from repeated trace evidence.

UI Builder

• 50+ declarative widget builders for layout, text, input, buttons, lists, tabs, cards, forms, and more.
• Actions API for navigation, snack bars, Firestore CRUD, event triggers, and flow control (conditional, terminate, loop, parallel, nonBlocking).
• Design token system with theme-aware colors, spacing, radii, and shadows.
• Variable binding: 8 variable sources, operations, state updates.
• GenUI chat widget support: UI.genUiChat() builder and genui_helpers.dart module (24 functions) — expose action blocks as AI tools, manage catalog components, configure chat UI, subscribe to app events for context injection.

CLI

• flash init <name> — scaffold a new workspace with pubspec, CLAUDE.md, AGENTS.md, starter app and brownfield patch. Runs dart pub get automatically.
• flash run [file] — execute a pipeline or DSL script (loads .env, default: flash/app.dart).
• flash status <project-id> — show project summary.
• flash inspect <project-id> — DSL JSON snapshot for the project, a specific page (--page), or component (--component). Reads from on-disk dsl_json/ snapshots when available, falls back to API. Also supports --debug (consolidated report), --outline (ASCII tree), and --deep (PROJECT_CONTEXT.md-style).
• flash validate <file> — validate a DSL script without pushing (exits 1 on errors).
• flash refresh-context <project-id> — update PROJECT_CONTEXT.md, context/, and dsl_json/ snapshots.
• flash refresh-workspace — overwrite Flash-managed docs (CLAUDE.md, AGENTS.md, references/, patterns/, tooling/).
• flash context-check — check context freshness (local + optional server comparison).
• flash resources <project-id> — emit reusable project, library, and theme resources as machine-readable JSON.
• flash search <project-id> --query <text> — fuzzy entity search.
• flash docs [topic] — browse SDK documentation.
• flash history / flash history show <run-id> — view past runs and recover archived source.
• flash trace latest|show|export — inspect and export canonical run traces.
• flash support case|inspect|bundle|replay — support-oriented case assembly, inspection, bundle export, and replay workspace reconstruction.
• flash issue candidates|show — derive repeated local issue signals from traces.
• flash plan / flash plan save / flash plan clear — manage active plan.
• --api-key <key> flag on all commands as an alternative to FF_API_KEY env var.

MCP Server

• Exposes Flash CLI as structured tools for AI agents (Claude Code, Gemini CLI, etc.): init, status, search, inspect, validate, refreshContext, contextCheck, run, docs, history.

Testing

• 2,600+ unit tests across client, helpers, pipeline, DSL, and UI layers.
• Integration test helpers: addTestGroup, addTest, given/when/then steps, widget finders.