flutterflow: exact-once CLI, direct MCP launch

Make CLI invocations exact-once and launch MCP servers directly. Set FF_AI_AGENT_CLIENT default to codex, remove the exit-254 retry/re-run in flutterflow-cli.sh to avoid accidentally re-executing state-mutating commands, and add a test for that behavior. Change the MCP launcher to run the workspace's vendored server with `dart run` (and update mcp.example.json) to prevent pub/shim status text from contaminating JSON-RPC stdout; add a test for the helper. Update CI to run all helper-script tests and JSON validation. Bump plugin metadata and update README, SKILL.md, and CHANGELOG to document workspace-scoped MCP, exact-once execution, attribution, and revised onboarding/auth guidance.

Author: johnbhiggins7

.github/workflows/ci.yml

@@ -20,8 +20,12 @@ jobs:
             sh -n "$f"
           done
 
-      - name: Run clipboard hand-off tests
-        run: bash plugins/flutterflow/scripts/store-key-from-clipboard.test.sh
+      - name: Run helper-script tests
+        run: |
+          for f in plugins/flutterflow/scripts/*.test.sh; do
+            echo "test: $f"
+            bash "$f"
+          done
 
       - name: Validate JSON configs
         run: |

CHANGELOG.md

@@ -14,23 +14,21 @@ The base version follows [semantic versioning](https://semver.org). The
   fall-through path, so setting `FLUTTERFLOW_CLI_DIR` without a usable Dart
   toolchain correctly falls back to the globally installed `flutterflow` binary
   (and prints the intended diagnostics on total failure).
-- `flutterflow-cli.sh`: the exit-254 retry now fires only when the package config
-  pre-existed (a genuine stale-config case), so a command — including a
-  state-mutating one — is never silently re-run after an application-level error.
-- `flutterflow-mcp.sh`: the helper is now invoked via `sh`, so a distribution that
-  dropped the executable bit no longer fails with an opaque "Permission denied".
-- `SKILL.md`: aligned the create/edit flow with the FlutterFlow CLI's own
-  guidance — iterate on `run` (which validates internally and only pushes on
-  success) instead of always running `validate` first, and use the documented
-  `--project-name`/`--commit-message` create form with `--find-or-create` reserved
-  for recovery.
+- `flutterflow-cli.sh`: removed the post-execution exit-254 retry. Every CLI
+  command now runs exactly once, so an application or network failure cannot
+  silently repeat a state-mutating operation.
+- `flutterflow-mcp.sh` and `mcp.example.json`: launch the workspace's vendored
+  MCP server directly with Dart, preventing pub/shim output from corrupting
+  JSON-RPC stdout.
+- Auth guidance now distinguishes machine-level onboarding credentials from the
+  initialized workspace's private `.flutterflow/.env`.
+- `SKILL.md`: documents the real `run` failure boundary—validation failures do
+  not push, while later create, conflict, network, push, and post-push failures
+  can have remote side effects.
 - Credential guidance (`SKILL.md`, `README.md`): note that an inline
   `FF_API_KEY=<key> ...` prefix still lands in shell history and the process
   environment, and that `--api-key` persists the key to both
-  `~/.flutterflow/credentials.json` and the workspace `.env`.
-- `mcp.example.json`: use an absolute command path and an explicit
-  `FLUTTERFLOW_AI_WORKSPACE` instead of a relative command/cwd that resolved
-  against the host's working directory.
+  `~/.flutterflow/credentials.json` and `.flutterflow/.env`.
 - `plugin.json`: corrected the license identifier to the SPDX id `BUSL-1.1`.
 - `README.md`: documented GitHub marketplace installation as the primary path,
   with local `marketplace add .` reserved for repo-root development installs.
@@ -40,12 +38,20 @@ The base version follows [semantic versioning](https://semver.org). The
 
 ### Added
 
+- CLI 0.0.38 onboarding guidance: bare `flutterflow ai` for the interactive
+  project picker, and `init ... --yes` for deterministic agent automation.
+- Version-matched workflow guidance: read generated `AGENTS.md`, inspect the
+  typed project SDK, use generated Flutter code as read-only runtime truth,
+  confirm branch state, and run `flutterflow ai test` before pushes.
+- Codex attribution for direct CLI calls via `FF_AI_AGENT_CLIENT`, while
+  preserving explicit caller overrides.
+- Exact-once CLI and direct MCP-launch regression tests.
 - `store-key-from-clipboard.sh`: secure one-shot FlutterFlow API-key hand-off
   from the OS clipboard to `~/.config/flutterflow/codex-env.sh`, with validation,
   symlink protections, live clipboard clearing, and leak-freedom tests.
 - `SKILL.md` and `README.md`: documented the no-chat clipboard flow, fixed retry
   wording, unavailable fallback, and hard rules against bare clipboard reads.
-- `.github/workflows/ci.yml`: shellcheck, POSIX syntax check, clipboard hand-off
+- `.github/workflows/ci.yml`: shellcheck, POSIX syntax checks, all helper-script
   tests, and JSON validation.
 - `.gitignore` entries for `.env`, `.env.*`, and `credentials.json`.
 - This changelog.

README.md

@@ -2,18 +2,20 @@
 
 Build and edit [FlutterFlow](https://flutterflow.io) apps from
 [Codex](https://developers.openai.com/codex) — describe what you want in plain
-language and the agent drives the FlutterFlow CLI to scaffold workspaces, author
-changes as Dart DSL, validate them, and apply them.
+language and the agent drives the FlutterFlow CLI and project-scoped MCP to
+scaffold workspaces, understand typed project context, test changes, and apply
+them safely.
 
 This repo ships one plugin, `flutterflow`, which adds:
 
-- A **skill** that teaches Codex the FlutterFlow AI workflow — workspace setup,
-  inspection, validating and running Dart DSL edits, diagnostics, and code export.
+- A **skill** that handles secure onboarding, then follows each workspace's
+  version-matched `AGENTS.md` for typed SDK, branch-aware editing, testing,
+  diagnostics, and code export.
 - **Helper scripts** that resolve a globally installed `flutterflow` CLI (or a
   local `flutterflow_cli` source checkout), plus a secure clipboard hand-off
   script for FlutterFlow API keys.
-- An **optional MCP example** for workspace-bound setups. MCP is not registered
-  or started by default.
+- A **workspace-bound MCP example** that launches the vendored server directly.
+  Current CLI onboarding also writes project-scoped agent configuration.
 
 ## Prerequisites
 
@@ -53,7 +55,7 @@ codex plugin marketplace add .
 codex plugin add flutterflow@flutterflow
 ```
 
-Start a new Codex thread so the skill loads. (A public Plugin Directory listing
+Start a new Codex task so the skill loads. (A public Plugin Directory listing
 is coming soon; until then, install from GitHub or a local clone.)
 
 ## Use it
@@ -66,18 +68,22 @@ Once installed, just ask Codex in plain language:
 
 > Export my FlutterFlow project to Flutter code.
 
-The skill walks through auth, workspace setup, validation, and applying the
-change for you.
+The skill walks through auth and workspace setup, then follows the generated
+workspace contract for the installed FlutterFlow AI SDK.
 
 ### Use the CLI directly (optional)
 
 You can also run the FlutterFlow CLI yourself:
 
+For interactive human onboarding, bare `flutterflow ai` opens a searchable
+project picker with a create-new option. For deterministic automation:
+
 ```bash
-flutterflow ai init my-app                   # new workspace
-flutterflow ai init my-app --project <id>    # bind to an existing project
-flutterflow ai status <project-id>           # inspect
-flutterflow ai run <file.dart>               # apply a Dart DSL change
+flutterflow ai init my-app --yes                          # new workspace
+flutterflow ai init my-app --project <id> --yes           # existing project
+cd my-app && flutterflow ai branch current                # confirm push target
+flutterflow ai test                                       # workspace test gate
+flutterflow ai run <file.dart> --commit-message "<why>"   # apply a change
 ```
 
 If `flutterflow` isn't on your PATH, the plugin bundles a helper. Its own
@@ -88,10 +94,16 @@ give an absolute path:
 /absolute/path/to/plugins/flutterflow/scripts/flutterflow-cli.sh ai --help
 ```
 
+The helper preserves the caller's directory, invokes the CLI exactly once, and
+defaults direct-command attribution to Codex unless `FF_AI_AGENT_CLIENT` is
+already set.
+
 ## Authentication
 
-- `flutterflow ai` uses `FF_API_KEY` or the credential store created by
-  `flutterflow ai init`. `export-code` and `deploy-firebase` use
+- Onboarding can use `FF_API_KEY` or the per-machine store at
+  `~/.flutterflow/credentials.json`. Ordinary initialized-workspace commands use
+  the process environment, workspace `.env`, and `.flutterflow/.env`; the latter
+  is the generated private store. `export-code` and `deploy-firebase` use
   `FLUTTERFLOW_API_TOKEN`.
 - **Recommended in Codex:** use the bundled secure clipboard hand-off. Open
   [your FlutterFlow account](https://app.flutterflow.io/account), copy the API
@@ -110,35 +122,42 @@ fi
 flutterflow ai status <project-id>
 ```
 
-- You can also run `flutterflow ai init` once in a terminal — it prompts for your
-  key and saves it to `~/.flutterflow/credentials.json` (mode `0600`) for later
-  commands.
+- You can also run bare `flutterflow ai` in a terminal; the onboarding wizard
+  prompts for the key, stores machine-level onboarding credentials, and creates
+  or binds a workspace with its own private env file.
 - Avoid the `--api-key` flag: it puts the secret on the process argument list and
-  persists it to disk (both the credential store and the workspace `.env`).
+  persists it to disk (both the credential store and `.flutterflow/.env`).
 - Never commit tokens. This repo's `.gitignore` covers `.env`, `.env.*`, and
-  `credentials.json`; keep any workspace `.env` out of version control too.
+  `credentials.json`; keep workspace env files out of version control too.
+
+## MCP
 
-## MCP (optional)
+FlutterFlow MCP is project-scoped. Current `flutterflow ai init` and intentional
+`refresh-workspace` flows register the workspace's vendored server with supported
+agents, including project-scoped Codex configuration at `.codex/config.toml`.
+Open a new Codex task from that workspace after registration so the new tools
+load.
 
-This plugin does not auto-register an MCP server — `flutterflow ai mcp` needs one
-concrete workspace, while the plugin should work from any Codex thread. For a
-workspace-bound setup, copy
-[mcp.example.json](plugins/flutterflow/mcp.example.json), fill in absolute paths,
-and point `FLUTTERFLOW_AI_WORKSPACE` at your workspace. Smoke-test the launcher:
+For a manual setup, copy
+[mcp.example.json](plugins/flutterflow/mcp.example.json) and fill in the absolute
+workspace paths. The example and helper both launch
+`.flutterflow/sdk/flutterflow_ai/mcp/server.dart` directly; this keeps pub/shim
+status text out of MCP's JSON-RPC stdout. Smoke-test the helper with:
 
 ```bash
 FLUTTERFLOW_AI_WORKSPACE=/absolute/path/to/workspace \
   /absolute/path/to/plugins/flutterflow/scripts/flutterflow-mcp.sh
 ```
 
-Don't rename `mcp.example.json` to `.mcp.json` unless you want Codex to start MCP
-for every thread where this plugin is enabled.
+The helper chooses the workspace from `FLUTTERFLOW_AI_WORKSPACE`, then
+`CODEX_WORKSPACE_ROOT`, then the current directory.
 
 ## Development
 
 The plugin's runtime surface is shell scripts plus the skill and configs. CI
 ([.github/workflows/ci.yml](.github/workflows/ci.yml)) runs `shellcheck`, syntax
-checks, clipboard hand-off tests, and JSON validation on every push.
+checks, exact-once CLI tests, direct MCP-launch tests, clipboard hand-off tests,
+and JSON validation on every push.
 
 > The validation and cachebuster helpers below ship with Codex under
 > `~/.codex/skills/.system/plugin-creator/` (installed by Codex's plugin-creator,

plugins/flutterflow/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "flutterflow",
-  "version": "0.1.0+codex.20260702205233",
-  "description": "Use the FlutterFlow CLI from Codex, with optional workspace-bound MCP setup.",
+  "version": "0.1.0+codex.20260714211821",
+  "description": "Build and edit FlutterFlow projects from Codex with the CLI and workspace-bound MCP.",
   "author": {
     "name": "FlutterFlow",
     "email": "support@flutterflow.io",
@@ -20,13 +20,15 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "FlutterFlow",
-    "shortDescription": "Build and edit FlutterFlow apps with the CLI.",
-    "longDescription": "Adds FlutterFlow AI guidance for CLI-first workflows. Use it to initialize workspaces, inspect projects, plan changes, validate Dart DSL edits, apply updates, refresh workspace context, run diagnostics, and export code through the FlutterFlow CLI. MCP is documented as an optional workspace-bound setup, not started by default.",
+    "shortDescription": "Build and edit FlutterFlow apps from Codex.",
+    "longDescription": "Adds secure FlutterFlow AI onboarding and version-matched workspace guidance for typed project context, branch-aware editing, workspace tests, CLI pushes, diagnostics, code export, and project-scoped MCP. Current FlutterFlow workspaces can auto-register their vendored MCP server with Codex.",
     "developerName": "FlutterFlow",
     "category": "Developer Tools",
     "capabilities": [
       "CLI",
       "Project editing",
+      "Project-scoped MCP",
+      "Branch-aware workflows",
       "Workspace diagnostics"
     ],
     "defaultPrompt": [

plugins/flutterflow/mcp.example.json

@@ -1,11 +1,13 @@
 {
   "mcpServers": {
     "flutterflow": {
-      "command": "/absolute/path/to/plugins/flutterflow/scripts/flutterflow-mcp.sh",
-      "args": [],
-      "env": {
-        "FLUTTERFLOW_AI_WORKSPACE": "/absolute/path/to/flutterflow-ai-workspace"
-      }
+      "command": "dart",
+      "args": [
+        "run",
+        "/absolute/path/to/flutterflow-ai-workspace/.flutterflow/sdk/flutterflow_ai/mcp/server.dart",
+        "--dir",
+        "/absolute/path/to/flutterflow-ai-workspace"
+      ]
     }
   }
 }

plugins/flutterflow/scripts/flutterflow-cli.sh

@@ -1,6 +1,12 @@
 #!/bin/sh
 set -eu
 
+# The upstream CLI cannot currently infer Codex from Codex's environment.
+# Preserve an explicit caller override; otherwise identify direct plugin-driven
+# CLI traffic as Codex for attribution.
+: "${FF_AI_AGENT_CLIENT:=codex}"
+export FF_AI_AGENT_CLIENT
+
 # Resolve the FlutterFlow CLI without changing the caller's working directory.
 # `flutterflow ai` discovers `.flutterflow/config.yaml` from the current
 # workspace for commands such as validate, run, and upgrade, so this wrapper
@@ -16,39 +22,18 @@ run_source_cli() {
   command -v dart >/dev/null 2>&1 || return 1
 
   package_config="$cli_dir/.dart_tool/package_config.json"
-  # Track whether the package config already existed. A 254 exit is only treated
-  # as a stale-config problem worth retrying when the config pre-existed; if we
-  # just resolved it below, a 254 is an application error and must not be re-run.
-  pkg_config_preexisting=1
   if [ ! -f "$package_config" ]; then
-    pkg_config_preexisting=0
     echo "Resolving FlutterFlow CLI dependencies in $cli_dir..." >&2
     if ! (cd "$cli_dir" && dart pub get >/dev/null); then
       echo "Failed to run dart pub get in $cli_dir." >&2
       return 1
     fi
   fi
 
-  if dart --packages="$package_config" "$cli_dir/bin/flutterflow_cli.dart" "$@"; then
-    exit 0
-  else
-    status=$?
-  fi
-
-  # Exit 254 is Dart's general error code: it can mean the CLI couldn't resolve
-  # packages (a stale package config after a pubspec or branch change) OR that the
-  # `flutterflow ai` command itself threw (network/API/app error). Only re-resolve
-  # and retry when the package config pre-existed — i.e. it may be stale. If we
-  # freshly resolved it above, or the status is anything else, propagate unchanged
-  # so a command (including a state-mutating one) is never silently run twice.
-  if [ "$status" -eq 254 ] && [ "$pkg_config_preexisting" -eq 1 ]; then
-    echo "Re-resolving FlutterFlow CLI dependencies in $cli_dir (stale package config)..." >&2
-    if (cd "$cli_dir" && dart pub get >/dev/null); then
-      exec dart --packages="$package_config" "$cli_dir/bin/flutterflow_cli.dart" "$@"
-    fi
-  fi
-
-  exit "$status"
+  # Invoke exactly once. Exit 254 is Dart's general error code and can represent
+  # an application, network, or package-resolution failure. Retrying here could
+  # execute a state-mutating command twice, so propagate every CLI exit unchanged.
+  exec dart --packages="$package_config" "$cli_dir/bin/flutterflow_cli.dart" "$@"
 }
 
 # 1. Explicit source checkout via FLUTTERFLOW_CLI_DIR (for local CLI development).