feat: add the stacflow SDK and move flow_ui into a pub workspace

[divyanshub024]

Summary

Turns the repo into a Dart pub workspace and adds the StacFlow SDK beside flow_ui.

• packages/flow_ui is the published package, moved as-is. Every file under lib/ is a pure rename; no widget changes.
• packages/stacflow is the SDK: StacFlowChat, the controller, and StacFlowChatView, the ready-made screen on flow_ui. Gemini, OpenAI and Claude adapters run natively with the developer's own key behind one TurnTransport seam, with streaming, stop, retry, regenerate, edit and resend, image attachments, copy, feedback and a model selector. The key is a private field set on exactly one header and never appears in URLs, logs or errors.
• Tools: Tool with read, write and destructive permissions, a confirmation card for gated calls, runToolLoop (dispatch, approval, timeouts, abort, continuation segments, a rounds cap), and the tool card in the thread with toolBodyBuilder for custom result bodies. Calls and results replay to the model in later turns on all three providers; Claude thinking blocks and Gemini signatures replay within a turn. Provider call ids ride inside the tc_ ids, so contracts/ is unchanged by tools.
• contracts/ holds the wire contract (SSE events, error codes) with tool/contracts_gen.dart generating packages/stacflow/lib/src/generated and CI failing on drift.
• Docs: package READMEs, the stacflow example app against Gemini with a set_theme tool, and CLAUDE.md/AGENTS.md for the workspace conventions.
• Root pubspec.yaml carries the melos scripts; playground and packages/stacflow depend on flow_ui: ^0.4.0.

Releases stay per package: flow_ui-v* and stacflow-v* tags. stacflow keeps publish_to: none until the 0.1.0 tag; the version bump is a follow-up.

Screenshots

Nothing in flow_ui renders differently; every lib/ file is a pure move. The SDK's view composes existing flow_ui components (thread, composer, tool and confirmation cards).

How this was verified

• dart run melos run analyze clean in all five members; dart format --set-exit-if-changed . clean.
• Smoke script (packages/stacflow/tool/smoke.dart) against Claude with TOOLS=true, including TOOL_PERMISSION=destructive and DECLINE=true.
• The stacflow example app against Gemini on web (chat, stop, retry, the set_theme tool).
• A banking demo app on Claude, on the iOS simulator: theme switch, a read tool rendering a custom card, a destructive transfer with confirm and decline, and a tool rendering model-generated Stac JSON.
• Gemini and OpenAI tool calling compile and share the runner but have not been exercised live since the tool work landed.

Checklist

• dart run melos run analyze is clean
• dart run melos run format applied
• Exercised in the playground (no new flow_ui component; the playground builds and runs from its new workspace position)
• Any new entry under dependencies: in packages/flow_ui/pubspec.yaml is flutter.dev-published, forces no configuration on hosts that never use the feature, and is argued in this PR (none added)
• Nothing model-facing in flow_ui; prompts, schemas and provider calls live only in packages/stacflow, enforced by the CI grep
• New public API is exported from packages/flow_ui/lib/flow_ui.dart and documented in docs/ and the README table (no new flow_ui API; stacflow's API is exported from lib/stacflow.dart and documented in its README; the docs site pages come later)
• packages/flow_ui/CHANGELOG.md updated for user-facing changes, with breaking changes called out (no flow_ui changes in this PR; the stacflow CHANGELOG carries 0.1.0)
• PR title follows conventional commits (feat:, fix:, refactor:, docs:, chore:)

---

Note

Medium Risk
Large repo and release-process change affects every contributor; the new stacflow package adds provider HTTP and API-key handling on the critical path even though flow_ui itself is only moved.

Overview
Restructures the repository into a Dart pub workspace (melos scripts at the root) and moves the published flow_ui package to packages/flow_ui/ at 0.4.0, with the root README trimmed to a workspace index. flow_ui’s lib/ is described as a pure relocation—no component API changes in this PR.

Adds packages/stacflow, the StacFlow SDK on top of flow_ui: StacFlowChat / StacFlowChatView, Gemini/OpenAI/Anthropic providers behind a shared transport, streaming chat UX, and a client tool loop (permissions, confirmations, replay). contracts/ plus tool/contracts_gen.dart define the SSE wire protocol and generate packages/stacflow/lib/src/generated; CI enforces flow_ui ↛ stacflow and generated-code drift.

CI and releases switch to dart run melos run analyze|test, build all three Flutter apps (including the new stacflow example), and per-package tags (flow_ui-v*, stacflow-v*) for pub publish. Examples now take API keys via --dart-define / gitignored env files instead of committed stubs.

^{Reviewed by Cursor Bugbot for commit 3550809. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d7baba2. Configure here.}