@floomhq/floom 3.1.0 → 5.0.1

package/LICENSE

@@ -0,0 +1,6 @@
+Floom CLI and MCP Package License
+
+The Floom CLI and MCP package is licensed under the Floom Source
+Available License Version 1.0.
+
+See ../../LICENSE for the full license text.

package/README.md

@@ -1,168 +1,346 @@
-# @floomhq/floom
-
-The Floom CLI: one shared skill library, synced across every AI agent.
-
-Docs: <https://floom.dev/docs>
-
-## Install
-
-```bash
-npm i -g @floomhq/floom
-```
-
-Pinned no-install form for automation:
-
-```bash
-npx -y @floomhq/floom@3.0.2 --help
-```
-
-## Login
-
-```bash
-floom login
-```
-
-The login command starts a browser device flow. Sign in at floom.dev with
-Google or email, approve the device code, and the CLI stores the session at
-`~/.floom/auth.json`.
-
-Check the active account:
-
-```bash
-floom account
-```
-
-## First Skill
-
-```bash
-floom push ~/.claude/skills/my-skill
-```
-
-The folder must contain `SKILL.md`. Each push creates a Library version.
-
-Create a starter skill when the folder does not exist yet:
-
-```bash
-floom new my-skill --agent claude
-```
-
-## Bulk Sync
-
-```bash
-floom sync
-```
-
-Zero-arg `floom sync` detects installed agents and supported scopes, reviews
-local-to-Library and Library-to-local differences, and applies the selected
-plan. Use `--dry-run` to preview the plan without changing files or Library
-records.
-
-Library-to-local only:
-
-```bash
-floom pull
-floom pull --agent claude,codex
-```
-
-Local-to-Library only:
-
-```bash
-floom push
-```
-
-Use the installed `floom` command for interactive terminal work. Use the pinned
-`npx -y @floomhq/floom@3.0.2 <command>` form for automation and agent-run
-commands that need reproducible CLI behavior.
-
-## Releasing
-
-Releases publish to npm and bump the Homebrew tap formula automatically via
-`.github/workflows/publish-cli.yml`, triggered by a `cli-v*` tag.
-
-### Hard pre-publish smoke gate
-
-Every `npm publish` is gated by `packages/cli/scripts/pre-publish-smoke.sh`,
-which packs the tarball, installs it into an isolated `$HOME`, and drives
-every subcommand the way a real user would. If anything fails, the workflow
-fails BEFORE `npm publish` runs — no broken CLI can reach npm `latest`.
-
-Background: in 2026-05 we shipped `3.0.0` → `3.0.1` → `3.0.2` within hours
-because `3.0.0` hit npm `latest` with three P0s that code review missed:
-`--help` ran the destructive body, `--help | head` threw an unhandled EPIPE,
-and unknown commands silently rendered the dashboard. Only an out-of-band
-real-terminal smoke caught them. This script is that smoke, baked into the
-publish pipeline.
-
-### Before pushing a `cli-v*` tag
-
-Run the local pre-tag check from the repo root:
-
-```bash
-./scripts/pre-tag-check.sh
-```
-
-It:
-
-1. Confirms the working tree is clean.
-2. Rebuilds the CLI from a clean `dist/`.
-3. Runs the CLI unit test suite (`pnpm --filter @floomhq/floom test`).
-4. Runs the full pre-publish smoke (same script the workflow runs).
-
-If everything passes, the script prints the exact `git tag` + `git push origin`
-commands. You then push the tag and the workflow takes over.
-
-If anything fails, fix the issue first. Do not push the tag.
-
-### Smoke-only workflow run
-
-To validate the smoke script itself without publishing (e.g. after editing
-`scripts/pre-publish-smoke.sh`):
-
-```
-GitHub → Actions → Publish @floomhq/floom → Run workflow
-  smoke_only: true
-```
-
-The workflow will build, run the smoke, and stop. No `npm publish`, no
-Homebrew dispatch.
-
-### Manual publish (rare)
-
-To publish without a tag (e.g. retag an existing version under a different
-dist-tag), use `workflow_dispatch` with `smoke_only: false` and the desired
-`tag` input. The smoke gate still runs first.
-
-## What the pre-publish smoke checks
-
-See `scripts/pre-publish-smoke.sh` for the full assertion list. Summary:
-
-| Stage | Asserts |
-|------|---------|
-| 1 | Tarball builds, packs, installs cleanly into isolated `$HOME`; installed `floom --version` matches `package.json` |
-| 2 | **Every** subcommand `--help` exits 0, starts with `Usage: floom`, writes no `~/.floom/auth.json`, prints no "Signed (in|out)" / "Waiting for browser" (P0 #1 from 3.0.0) |
-| 3 | `floom --help \| head -3` and `floom push --help \| head -1` print no EPIPE / "Unhandled error event" (P0 #2 from 3.0.0) |
-| 4 | `floom <unknown>` exits non-zero with "unknown command" + "did you mean" hint (P0 #3 from 3.0.0) |
-| 5 | Bare `floom --help` exits 0 with grouped help |
-| 6 | Unauth `whoami` / `account` / `logout` exit 0 idempotent; unauth `status` / `sync --json` / `push --json` exit non-zero with no stack trace |
-| 7 | `floom logout extra-positional` is rejected with non-zero exit AND `~/.floom/auth.json` is preserved (no destructive body) |
-| 8 | **Agent detection** picks up fake `.claude/`, `.codex/`, `.cursor/` marker dirs in the isolated `$HOME` (verified by parsing `floom doctor --json`); bare `floom sync` / `floom pull` with planted agents do not crash unauth (clean `signedIn:false` envelope). Note: fan-out *behaviour itself* requires real auth, so it is exercised at the **unit-test layer** by `src/commands/sync.fanout.test.ts`, which the publish workflow runs as a separate hard gate before the smoke. |
-
-If any assertion fails, the publish job fails. The smoke script exits non-zero
-on the first failure and prints a summary of every failed check.
-
-## Files
-
-```
-packages/cli/
-├── src/                          # TypeScript source
-│   ├── index.ts                  # CLI entry point (commander)
-│   ├── commands/                 # one file per subcommand
-│   ├── lib/                      # shared helpers
-│   └── cli-smoke.test.ts         # unit-level smoke (P0 lock-ins)
-├── scripts/
-│   ├── build-bundle.mjs          # esbuild → dist/index.js
-│   ├── verify-package.mjs        # pre-pack file allowlist check
-│   └── pre-publish-smoke.sh      # E2E smoke driven against tarball
-├── package.json
-└── CHANGELOG.md
-```
+# Floom CLI + MCP
+
+Floom lets agents create, update, run, watch, and delete worker automations through an HTTP MCP endpoint backed by the Floom API. The package installs into Claude Code, Cursor, VS Code, Windsurf, Continue, or any harness that accepts an MCP HTTP or stdio server entry.
+
+Floom ships as a single npm package that exposes:
+
+- **`floom` CLI** - `login`, `workspaces`, `workers`, `run`, `runs`, `secrets`, `mcp`, `whoami`, `logout`, plus an `install` shortcut that wires the MCP server into Claude Code / Cursor / Continue. `workeros` remains a compatibility alias for older installs.
+- **HTTP MCP endpoint** - `floom mcp install` writes an HTTP transport entry (`url` + `headers`) pointing at `/mcp-tools/serve` on the Floom API. No local subprocess is required.
+- **`floom-mcp` stdio server** - legacy stdio path; `workeros-mcp` still works as an alias. Use this for harnesses that do not support HTTP MCP transport.
+
+The CLI targets local, self-hosted, and hosted deployments:
+
+| Mode | API base | Auth | Workspaces |
+|------|----------|------|------------|
+| **Self-hosted** (default) | `http://localhost:8000` or your API URL | `x-floom-secret` when `FLOOM_SECRET` is set | local workspace |
+| **Hosted** | your hosted API URL | bearer token or hosted login flow, legacy `x-workeros-workspace` header | multi-workspace |
+
+## Self-Hosted Quickstart
+
+```bash
+npm i -g @floomhq/floom@latest
+floom login --api http://localhost:8000
+floom workers list
+floom run <worker-id> --input key=value
+```
+
+If your local API runs without `FLOOM_SECRET`, login is not required for basic local development. For a protected self-hosted API, set `FLOOM_SECRET` on the backend and use the matching secret when the CLI prompts.
+
+If the self-hosted engine has user-header scope enabled (it requires `x-floom-user` alongside the shared secret), pass the identity with the `--user` flag or `WORKEROS_USER` env var:
+
+```bash
+WORKEROS_API_BASE=http://127.0.0.1:8011 WORKEROS_API_SECRET=<secret> WORKEROS_USER=<user> floom whoami
+# or
+floom --user <user> whoami
+```
+
+`WORKEROS_API_BASE` + `WORKEROS_API_SECRET` select self-hosted (OSS) mode and take precedence over any saved hosted credentials file; `mcp install` bakes `x-floom-user` into the generated client config when it is set.
+
+Credentials live at `~/.config/floom/credentials.json` (mode 0600). Existing `~/.config/workeros/credentials.json` files are still read for compatibility. `floom logout` clears both paths.
+
+## MCP install
+
+```bash
+npx -y @floomhq/floom mcp install
+```
+
+Auto-detects the first existing config file. To target a specific harness:
+
+```bash
+floom mcp install --target claude     # ~/.claude/settings.json
+floom mcp install --target cursor     # ~/.cursor/mcp.json
+floom mcp install --target vscode     # .vscode/mcp.json  (workspace-local)
+floom mcp install --target windsurf   # ~/.codeium/windsurf/mcp_config.json
+floom mcp install --target continue   # ~/.continue/.continuerc.json
+floom mcp install --target generic    # prints JSON snippet for manual paste
+```
+
+## Switching the active context
+
+```bash
+floom workspace list             # all workspaces your credentials can access, active marked with *
+floom workspace switch <name>    # by name or id; fails (exit 1) if not authenticated for it
+floom mcp list                   # configured MCP servers (connections of kind "mcp")
+floom mcp switch <name>          # set the active MCP server by label
+floom mcp test [name]            # live probe (initialize + tools/list); defaults to the active server
+```
+
+Switches persist in `~/.config/floom/credentials.json` and apply to every later CLI invocation. `workspaces`/`use` remain as aliases of `workspace`/`switch`. Workspace switching works in both modes: hosted deployments scope by membership, self-hosted deployments scope local workspaces via the legacy `x-workeros-workspace` header (which the CLI sends on every request, and `mcp install` bakes into the client config - re-run `mcp install` after switching to repoint installed MCP clients).
+
+Re-running the installer updates the existing `floom` entry, and migrates an older `workeros` entry instead of duplicating it.
+
+## Supported targets
+
+| Target | Config file written | Config shape |
+|---|---|---|
+| `claude` | `~/.claude/settings.json` | `{ mcpServers: { floom: {...} } }` |
+| `cursor` | `~/.cursor/mcp.json` | `{ mcpServers: { floom: {...} } }` |
+| `vscode` | `.vscode/mcp.json` (workspace) | `{ mcpServers: { floom: {...} } }` |
+| `windsurf` | `~/.codeium/windsurf/mcp_config.json` | `{ mcpServers: { floom: {...} } }` |
+| `continue` | `~/.continue/.continuerc.json` | `{ mcpServers: [ { name:"floom", ... } ] }` |
+| `generic` | (no file) | prints JSON snippet to stdout |
+
+All targets write **HTTP MCP transport** (`url` + `headers`) - no local subprocess is spawned. The MCP endpoint is hosted on the Floom API server.
+
+```json
+{
+  "mcpServers": {
+    "floom": {
+      "url": "http://localhost:8000/mcp-tools/serve",
+      "headers": {
+        "x-floom-secret": "<WORKEROS_API_SECRET>"
+      }
+    }
+  }
+}
+```
+
+### HTTP transport (recommended - written by `floom mcp install`)
+
+Claude Code / Cursor / VS Code / Windsurf (`mcpServers` object shape):
+
+```json
+{
+  "mcpServers": {
+    "floom": {
+      "url": "http://localhost:8000/mcp-tools/serve",
+      "headers": {
+        "x-floom-secret": "<WORKEROS_API_SECRET>"
+      }
+    }
+  }
+}
+```
+
+The published binary stays connected for that handshake when launched as `npx -p @floomhq/floom floom-mcp`.
+
+## Manual config
+
+Claude Code / Cursor / VS Code / Windsurf (`mcpServers` object shape, HTTP MCP):
+
+```json
+{
+  "mcpServers": {
+    "floom": {
+      "url": "http://localhost:8000/mcp-tools/serve",
+      "headers": {
+        "x-floom-secret": "<WORKEROS_API_SECRET>"
+      }
+    }
+  }
+}
+```
+
+Continue (`~/.continue/.continuerc.json`, array shape, HTTP MCP):
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "floom",
+      "url": "http://localhost:8000/mcp-tools/serve",
+      "headers": {
+        "x-floom-secret": "<WORKEROS_API_SECRET>"
+      }
+    }
+  ]
+}
+```
+
+Replace `http://localhost:8000` with your deployed API base URL when connecting to a remote self-hosted instance.
+
+### Stdio transport (fallback - for harnesses that do not support HTTP MCP)
+
+```json
+{
+  "mcpServers": {
+    "floom": {
+      "command": "npx",
+      "args": ["-p", "@floomhq/floom", "floom-mcp"],
+      "env": {
+        "WORKEROS_API_SECRET": "<WORKEROS_API_SECRET>",
+        "WORKEROS_API_BASE": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+Or launch directly if the package is already installed: `node /path/to/@floomhq/floom/dist/server.js`.
+
+## Worker bundle CLI flow
+
+Use this path when a fresh agent has a local `workers/<id>/` folder and needs a repeatable create/edit/deploy loop:
+
+```bash
+floom login
+floom workers validate ./workers/<id>
+floom workers push ./workers/<id>
+floom run <id> --inputs-file docs/workers/inputs/<id>.json
+floom workers info <id>
+```
+
+`workers validate` is offline. It checks that `worker.yml` parses, the entry file exists, the runtime is declared, and E2B Composio workers do not use the local `composio execute` CLI. For structured connection declarations it also verifies that referenced tool slugs are covered by `allowed_tools`.
+
+`workers push` uses `POST /workers` for new workers and `PUT /workers/{id}` for existing workers. If an older API returns 404/405 for source updates, upgrade the API before editing workers in place.
+
+## Tools
+
+> **For full worked examples per tool, end-to-end recipes (deploy a worker from prompt, port a Claude skill, schedule + webhook + composio triggers), and the agent draft contract, see [docs/AGENT-COOKBOOK.md](../../docs/AGENT-COOKBOOK.md).**
+
+### Workers
+| Tool | Description |
+| --- | --- |
+| `workers.list` | List available Floom workers. |
+| `workers.get` | Read one worker, including config and recent run metadata. |
+| `workers.create` | Create a script-mode worker from `worker_yml` and `run_py`. |
+| `workers.update` | Patch trigger, cron, default inputs, capabilities, or rotate webhook secret. |
+| `workers.delete` | Delete a worker and dependent run data. |
+| `workers.run` | Start a manual worker run with input values. |
+| `workers.logs` | Fetch cross-run log history, filterable by level and time. |
+| `workers.stats` | 7-day run statistics for a specific worker. |
+| `workers.timeseries` | Daily run counts and success/failure trend over N days. |
+| `workers.sample_input` | Get example input values for a worker's fields. |
+| `workers.archive` | Archive a worker (reversible). |
+| `workers.restore` | Restore an archived worker to active status. |
+| `workers.reload` | Reload all workers from disk on a self-hosted deployment. |
+| `workers.versions` | List saved versions of a worker. |
+| `workers.rollback` | Restore a worker to a previous version. |
+| `workers.alerts.list` | List configured alerts for a worker. |
+| `workers.alerts.create` | Add a failure/approval/success alert via webhook or email. |
+| `workers.alerts.delete` | Remove a worker alert. |
+
+### Runs
+| Tool | Description |
+| --- | --- |
+| `runs.list` | List runs, optionally filtered by worker id or status. |
+| `runs.get` | Read one run with logs, outputs, artifacts, and approval state. |
+| `runs.watch` | Stream SSE run events until a terminal state. |
+| `runs.cancel` | Cancel an in-progress run. |
+| `runs.replay` | Replay a completed or failed run with the same inputs. |
+
+### Approvals
+| Tool | Description |
+| --- | --- |
+| `approvals.list` | List pending approval requests across all workers. |
+| `approvals.approve` | Approve a pending run so it continues executing. |
+| `approvals.reject` | Reject a pending run, stopping it. |
+
+### Secrets
+| Tool | Description |
+| --- | --- |
+| `secrets.list` | List secret names and status. |
+| `secrets.set` | Create or update a secret value. |
+| `secrets.delete` | Delete a secret. |
+| `secrets.test` | Verify a secret exists without revealing its value. |
+
+### Connections
+| Tool | Description |
+| --- | --- |
+| `connections.list` | List configured app connections. |
+| `connections.add_mcp` | Add an MCP server connection. |
+| `connections.delete` | Remove a connection. |
+| `connections.status` | Check connection health and auth status. |
+| `connections.test` | Run a live connectivity check on a connection. |
+
+### Contexts (Brain Packs)
+| Tool | Description |
+| --- | --- |
+| `contexts.list` | List context folders. |
+| `contexts.create` | Create a new brain pack context. |
+| `contexts.delete` | Delete a brain pack and all its files. |
+| `contexts.read` | Read a file from a context. |
+| `contexts.write` | Create or update a file in a context. |
+| `contexts.upload` | Upload a binary file to a context. |
+| `contexts.delete_file` | Delete a specific file from a context. |
+| `contexts.versions` | List saved versions of a brain pack. |
+| `contexts.rollback` | Restore a brain pack to a previous version. |
+
+### Triggers & Integrations
+| Tool | Description |
+| --- | --- |
+| `triggers.list` | List integration triggers, globally or per worker/app. |
+| `integrations.catalog` | Browse all available integrations. |
+
+### Workspace
+| Tool | Description |
+| --- | --- |
+| `workspace.chat` | Send a message to the workspace agent and get a reply. |
+| `workspace.instructions.get` | Read current workspace agent system prompt. |
+| `workspace.instructions.set` | Update workspace agent system prompt. |
+| `workspace.versions` | List version history of workspace instructions. |
+| `workspace.rollback` | Restore workspace instructions to a previous version. |
+
+### Conversations
+| Tool | Description |
+| --- | --- |
+| `conversations.list` | List past workspace agent conversations. |
+| `conversations.get` | Retrieve a full conversation by ID. |
+
+### System
+| Tool | Description |
+| --- | --- |
+| `system.overview` | Full workspace dashboard - health, runs, pending approvals, alerts. |
+| `system.stats` | 7-day aggregate run statistics across the whole workspace. |
+| `system.info` | Platform version and configuration flags. |
+| `system.alerts` | Active system-wide alerts. |
+
+## Quick example - write + deploy + verify a worker in one MCP session
+
+```js
+// 1. Create
+await workers.create({
+  worker_yml: `
+schema_version: "0.3"
+name: text-summarizer
+title: Text Summarizer
+description: Summarizes any text in 3 bullets using GPT-4.1.
+entrypoint: run.py
+exec:
+  command: python run.py
+  runtime: python311
+  runner: e2b
+  entry: run.py
+  inputs:
+    - { name: text, kind: scalar, type: textarea, required: true, label: Text }
+  outputs:
+    - { name: summary, kind: file, media_type: text/markdown, path: out/summary.md, required: true, label: Summary }
+  secrets: [OPENAI_API_KEY]
+capabilities:
+  secrets: [OPENAI_API_KEY]
+  network: { egress: true }
+trigger: { type: manual }
+`,
+  run_py: `
+def run(inputs, context):
+    client = context.openai()
+    r = client.chat.completions.create(
+        model="gpt-4.1-mini",
+        messages=[
+            {"role": "system", "content": "Summarize in 3 bullets."},
+            {"role": "user", "content": inputs["text"]},
+        ],
+    )
+    summary = r.choices[0].message.content
+    context.write_output("summary", summary)
+    return {"summary": summary}
+`,
+});
+
+// 2. Run
+const { run_id } = await workers.run({
+  id: "text-summarizer",
+  inputs: { text: "Lorem ipsum dolor sit amet..." },
+});
+
+// 3. Watch until terminal
+const watched = await runs.watch({ id: run_id });
+console.log(watched.status);
+
+// 4. Verify
+const { run } = await runs.get({ id: run_id });
+console.log(run.status); // "succeeded"
+console.log(run.output?.summary);
+```
+
+See [docs/AGENT-COOKBOOK.md section 1](../../docs/AGENT-COOKBOOK.md) for the full annotated walkthrough plus six more recipes (agent mode, Gmail trigger, cron schedule, webhook, approval gate, claude-skill port).

package/bin/floom-mcp

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Explicit Floom stdio MCP binary. The legacy workeros-mcp wrapper remains for
+// older configs and npm installs.
+import { main } from "../dist/server.js";
+main().catch((/** @type {unknown} */ error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`floom-mcp failed: ${message}`);
+  process.exit(1);
+});

package/bin/workeros-mcp

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// #596: previously this script only imported dist/server.js without calling
+// main(). server.ts guards its main() call with an import.meta.url === argv[1]
+// check — which is FALSE when the binary wrapper is the entry point because
+// process.argv[1] is "bin/workeros-mcp", not "dist/server.js". The guard
+// evaluated to false, main() was never called, and the process exited
+// immediately. The MCP client received "Connection closed" before listTools.
+import { main } from "../dist/server.js";
+main().catch((/** @type {unknown} */ error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`workeros-mcp failed: ${message}`);
+  process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { type CommandName } from "./lib/command-name.js";
+export declare function getPackageVersion(): string;
+export declare function buildCliProgram(commandName?: CommandName): Command;
+export declare function main(argv?: string[]): Promise<void>;