@floomhq/floom 3.0.1 → 3.0.3

package/README.md

@@ -0,0 +1,168 @@
+# @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
+```

package/dist/index.js

@@ -3253,7 +3253,7 @@ async function getMachineIdentity() {
 }
 
 // src/version.ts
-var VERSION = "3.0.1";
+var VERSION = "3.0.3";
 
 // src/api-client.ts
 var DEFAULT_TIMEOUT_MS = 2e4;
@@ -3721,17 +3721,35 @@ async function loginCommand() {
 }
 
 // src/commands/logout.ts
-async function logoutCommand() {
-  const auth = await readAuth();
+async function logoutCommand(opts = {}, deps = {}) {
+  const readAuth2 = deps.readAuth ?? readAuth;
+  const clearAuth2 = deps.clearAuth ?? clearAuth;
+  const api2 = deps.api ?? api;
+  const auth = await readAuth2();
+  let remoteRevokeFailed = false;
   if (auth) {
     try {
-      await api("/cli/session/revoke", { method: "POST", authRequired: true });
+      await api2("/cli/session/revoke", {
+        method: "POST",
+        authRequired: true,
+        query: opts.all ? { scope: "all" } : void 0
+      });
     } catch (error) {
-      log.warn(`Remote session revoke failed: ${error.message}`);
+      if (opts.all) {
+        remoteRevokeFailed = true;
+        process.exitCode = 1;
+        log.err(
+          "Local session cleared. Other devices are still authenticated.\nSign in at https://floom.dev/settings to revoke other sessions from the web."
+        );
+      } else {
+        log.warn(`Remote session revoke failed: ${error.message}`);
+      }
     }
   }
-  await clearAuth();
-  log.ok("Signed out of Floom on this machine.");
+  await clearAuth2();
+  log.ok(
+    remoteRevokeFailed ? "Local sign-out only \u2014 remote revoke failed." : opts.all ? "Signed out of Floom CLI on all machines." : "Signed out of Floom on this machine."
+  );
   log.blank();
   log.info("Your local skill files in ~/.claude/skills, ~/.codex/skills, etc. were not changed.");
   printNext([{ command: "floom login", description: "sign in again" }]);
@@ -5674,6 +5692,9 @@ async function pullCommand(skillArg, rawOpts = {}) {
   }
 }
 
+// src/commands/sync.ts
+import chalk5 from "chalk";
+
 // src/commands/sync-runner.ts
 init_src();
 import { cp as cp2, mkdtemp, readdir as readdir4, rm as rm2, stat as stat6 } from "node:fs/promises";
@@ -5845,7 +5866,9 @@ async function runSyncForTarget(options = {}, deps = {}) {
     process.exitCode = 1;
     return { ok: false, pushFailures, hasConflicts: false };
   }
-  log.ok(`Sync complete. Pulled ${plan.pull.length} skills. Pushed ${pushed}/${plan.push.length} skills.`);
+  if (!options.quietSuccess) {
+    log.ok(`Sync complete. Pulled ${plan.pull.length} skills. Pushed ${pushed}/${plan.push.length} skills.`);
+  }
   return { ok: true, pushFailures: [], hasConflicts: false };
 }
 
@@ -5877,9 +5900,12 @@ function buildApplyJson(workspaceName, applied, opts) {
     next: ["floom status"]
   };
 }
-async function planForAgent(agent, scope, skillsDir) {
+function formatAgentLabel(plan) {
+  return `${AGENT_LABELS[plan.agent]}${plan.scope === "project" ? " (project)" : ""}`;
+}
+async function planForAgent(agent, scope, skillsDir, statusFn = statusLibrary) {
   try {
-    const status = await statusLibrary(agent, { installDir: skillsDir });
+    const status = await statusFn(agent, { installDir: skillsDir });
     return {
       agent,
       scope,
@@ -5892,7 +5918,12 @@ async function planForAgent(agent, scope, skillsDir) {
     return { agent, scope, skillsDir, pull: [], push: [], conflicts: [] };
   }
 }
-async function syncCommand(rawOpts = {}) {
+async function syncCommand(rawOpts = {}, deps = {}) {
+  const detectAgentsFn = deps.detectAgents ?? detectAgents;
+  const runSyncFn = deps.runSyncForTarget ?? runSyncForTarget;
+  const statusFn = deps.statusLibrary ?? statusLibrary;
+  const fetchMeFn = deps.fetchMe ?? fetchMe;
+  const readAuthFn = deps.readAuth ?? readAuth;
   const cleanup = installCancellationHandler();
   try {
     let flags;
@@ -5908,7 +5939,7 @@ async function syncCommand(rawOpts = {}) {
     }
     const json = flags.json;
     const planMode = isPlanMode(flags);
-    if (!await readAuth()) {
+    if (!await readAuthFn()) {
       if (json) {
         emitJson({ workspace: { name: "Library", signedIn: false }, mode: "plan", applied: false, wouldMutate: false, hasSkipped: false, agents: [], next: ["floom login"] });
       } else {
@@ -5918,30 +5949,30 @@ async function syncCommand(rawOpts = {}) {
       process.exitCode = 2;
       return;
     }
-    const detected = await detectAgents();
+    const detected = await detectAgentsFn();
     if (detected.length === 0) {
       if (json) {
-        emitJson({ workspace: { name: "Library", signedIn: true }, mode: "plan", applied: false, wouldMutate: false, hasSkipped: false, agents: [], next: ["floom sync --agent claude"] });
+        emitJson({ workspace: { name: "Library", signedIn: true }, mode: "plan", applied: false, wouldMutate: false, hasSkipped: false, agents: [], error: "no agents detected \u2014 install Claude, Codex, Cursor, Gemini, or OpenCode", next: ["floom sync --agent claude"] });
       } else {
-        log.info("No AI agents found on this machine.");
-        log.info("Floom looks for Claude, Codex, Cursor, Gemini, or OpenCode.");
+        log.err("No agents detected \u2014 install Claude, Codex, Cursor, Gemini, or OpenCode, then re-run.");
+        log.info("Floom syncs into one of: Claude, Codex, Cursor, Gemini, OpenCode.");
+        log.info("More: https://floom.dev/docs#agents");
       }
       process.exitCode = 1;
       return;
     }
+    const defaultedToAll = flags.agents.length === 0 && !flags.allAgents;
     const selectedAgents = flags.agents.length > 0 ? flags.agents : detected;
-    if (!planMode && flags.agents.length === 0 && !flags.allAgents && !isInteractive()) {
+    if (!planMode && !flags.yes && !isInteractive()) {
       if (json) {
-        emitJson({ workspace: { name: "Library", signedIn: true }, error: "floom sync needs to know which agents to update", next: ["floom sync --all-agents --yes"] });
+        emitJson({ workspace: { name: "Library", signedIn: true }, error: "floom sync needs --yes to apply changes in a non-interactive shell", next: ["floom sync --yes"] });
       } else {
-        log.err("floom sync needs to know which agents to update.");
-        log.blank();
-        log.info("Pass --agent <name>, repeat --agent, or use --all-agents.");
+        log.err("floom sync needs --yes to apply changes in a non-interactive shell.");
         log.blank();
         log.info("Examples:");
+        log.command("floom sync --yes                       # sync every detected agent");
         log.command("floom sync --agent claude --yes");
         log.command("floom sync --agent claude,codex --yes");
-        log.command("floom sync --all-agents --yes");
       }
       process.exitCode = 2;
       return;
@@ -5951,7 +5982,7 @@ async function syncCommand(rawOpts = {}) {
       process.exitCode = 2;
       return;
     }
-    const me = await fetchMe().catch(() => null);
+    const me = await fetchMeFn().catch(() => null);
     const workspaceName = me?.workspace?.name ?? "your Workspace";
     const hasProjectScope = await projectSkillsDirExists(process.cwd());
     const scopeChoice = flags.allScopes ? ["global", "project"] : flags.scope === "project" ? ["project"] : planMode && flags.scope === null && hasProjectScope ? ["global", "project"] : ["global"];
@@ -5960,7 +5991,7 @@ async function syncCommand(rawOpts = {}) {
       for (const scope of scopeChoice) {
         const dir = scope === "project" ? resolve6(projectSkillsDir(agent)) : resolve6(globalSkillsDir(agent));
         if (scope === "project" && !await projectSkillsDirExists(process.cwd())) continue;
-        plans.push(await planForAgent(agent, scope, dir));
+        plans.push(await planForAgent(agent, scope, dir, statusFn));
       }
     }
     const actionable = plans.filter((p) => p.pull.length > 0 || p.push.length > 0);
@@ -6013,12 +6044,24 @@ async function syncCommand(rawOpts = {}) {
       return;
     }
     if (!wouldMutate && !hasSkipped) {
+      if (json) {
+        const noopApplied = plans.map((p) => ({ plan: p, ok: true, message: "up to date" }));
+        emitJson(buildApplyJson(workspaceName, noopApplied, { failed: false, hasSkipped: false }));
+        return;
+      }
+      if (defaultedToAll && detected.length > 1) {
+        log.info(`Syncing every detected agent (${detected.map((a) => AGENT_LABELS[a]).join(", ")}).`);
+      }
       log.info("Everything is in sync.");
       log.blank();
       for (const p of plans) log.row([AGENT_LABELS[p.agent], "up to date"], [10]);
       printNext([{ command: "floom status" }]);
       return;
     }
+    if (defaultedToAll && detected.length > 1) {
+      log.info(`Syncing every detected agent (${detected.map((a) => AGENT_LABELS[a]).join(", ")}).`);
+      log.blank();
+    }
     log.heading("Sync plan for this machine");
     log.blank();
     for (const p of plans) {
@@ -6056,7 +6099,7 @@ async function syncCommand(rawOpts = {}) {
     const applied = [];
     for (const p of toSync) {
       try {
-        const result = await runSyncForTarget({ target: p.agent, yes: true, installDir: p.skillsDir });
+        const result = await runSyncFn({ target: p.agent, yes: true, installDir: p.skillsDir, quietSuccess: true });
         const entry = appliedFromResult(p, result);
         if (!entry.ok) failed = true;
         applied.push(entry);
@@ -6071,6 +6114,32 @@ async function syncCommand(rawOpts = {}) {
       if (failed || hasSkipped) process.exitCode = 1;
       return;
     }
+    if (failed) {
+      const failedCount = applied.filter((a) => !a.ok).length;
+      const succeededCount = applied.filter((a) => a.ok).length;
+      log.blank();
+      log.info(`Sync completed with ${failedCount} target(s) failing (${succeededCount} succeeded).`);
+      for (const entry of applied) {
+        const marker = entry.ok ? chalk5.green("\u2713") : chalk5.red("\u2717");
+        log.info(`  ${marker} ${formatAgentLabel(entry.plan)}    ${entry.message}`);
+      }
+      log.blank();
+      printNext([{ command: "floom status" }]);
+      if (hasSkipped) {
+        for (const p of plans) {
+          for (const slug of p.conflicts) {
+            log.warn(`${AGENT_LABELS[p.agent]} skipped ${slug}, changed in two places`);
+          }
+        }
+      }
+      process.exitCode = 1;
+      return;
+    }
+    if (!hasSkipped) {
+      const pulled = applied.reduce((n, a) => n + a.plan.pull.length, 0);
+      const pushed = applied.reduce((n, a) => n + a.plan.push.length, 0);
+      log.ok(`Sync complete. Pulled ${pulled} skill${pulled === 1 ? "" : "s"}. Pushed ${pushed}/${pushed} skill${pushed === 1 ? "" : "s"}.`);
+    }
     for (const p of plans) {
       for (const slug of p.conflicts) {
         log.warn(`${AGENT_LABELS[p.agent]} skipped ${slug}, changed in two places`);
@@ -6087,7 +6156,7 @@ async function syncCommand(rawOpts = {}) {
       log.info("Backups of any replaced skills are in each agent's .floom/backups/ folder (run floom restore --list to see them).");
       printNext([{ command: "floom status" }]);
     }
-    if (failed || hasSkipped) process.exitCode = 1;
+    if (hasSkipped) process.exitCode = 1;
   } finally {
     cleanup.dispose();
   }
@@ -6095,20 +6164,20 @@ async function syncCommand(rawOpts = {}) {
 
 // src/commands/status.ts
 import { resolve as resolve7 } from "node:path";
-import chalk5 from "chalk";
+import chalk6 from "chalk";
 init_runtime();
 var AGENT_TIMEOUT_MS = 1e4;
 var MAX_ATTENTION_ROWS = 15;
 function toFloomState(state) {
   switch (state) {
     case "active":
-      return { state: "up_to_date", label: "up to date", color: chalk5.green };
+      return { state: "up_to_date", label: "up to date", color: chalk6.green };
     case "stale":
-      return { state: "update_available", label: "update available", color: chalk5.yellow };
+      return { state: "update_available", label: "update available", color: chalk6.yellow };
     case "dirty":
-      return { state: "local_changes", label: "local changes", color: chalk5.yellow };
+      return { state: "local_changes", label: "local changes", color: chalk6.yellow };
     case "conflict":
-      return { state: "changed_in_two_places", label: "changed in two places", color: chalk5.red };
+      return { state: "changed_in_two_places", label: "changed in two places", color: chalk6.red };
     case "missing":
       return { state: "not_installed", label: "not installed", color: (s) => s };
     case "unsupported_target":
@@ -6291,7 +6360,7 @@ async function statusCommand(rawOpts = {}) {
   log.blank();
   const shown = attention.slice(0, MAX_ATTENTION_ROWS);
   for (const item of shown) {
-    log.info(`  ${chalk5.bold(item.slug)}`);
+    log.info(`  ${chalk6.bold(item.slug)}`);
     for (const loc of item.locations) {
       const c = toFloomLabel(loc.state);
       log.info(`    ${AGENT_LABELS[loc.agent].padEnd(10)} ${c.color(c.label.padEnd(22))}${tildePath(loc.path)}`);
@@ -6368,13 +6437,13 @@ function summarize(skills) {
 function toFloomLabel(state) {
   switch (state) {
     case "up_to_date":
-      return { label: "up to date", color: chalk5.green };
+      return { label: "up to date", color: chalk6.green };
     case "local_changes":
-      return { label: "local changes", color: chalk5.yellow };
+      return { label: "local changes", color: chalk6.yellow };
     case "update_available":
-      return { label: "update available", color: chalk5.yellow };
+      return { label: "update available", color: chalk6.yellow };
     case "changed_in_two_places":
-      return { label: "changed in two places", color: chalk5.red };
+      return { label: "changed in two places", color: chalk6.red };
     case "not_in_library_never_published":
       return { label: "not in Library", color: (s) => s };
     case "not_in_library_removed":
@@ -7890,7 +7959,7 @@ async function dashboardCommand() {
 }
 
 // src/lib/help.ts
-import chalk6 from "chalk";
+import chalk7 from "chalk";
 var GROUPS = [
   {
     title: "Sign in",
@@ -7960,21 +8029,21 @@ var COMMON_FLAGS = `Common flags
   --no-secret-check  with push, skip the pre-publish secret scan`;
 function printGroupedHelp() {
   const out2 = process.stdout;
-  out2.write("\n" + chalk6.bold("Usage: floom [command]") + "\n\n");
-  out2.write(`  ${chalk6.cyan.bold("floom")}              your dashboard \u2014 Library and agent status at a glance
+  out2.write("\n" + chalk7.bold("Usage: floom [command]") + "\n\n");
+  out2.write(`  ${chalk7.cyan.bold("floom")}              your dashboard \u2014 Library and agent status at a glance
 `);
   const allNames = GROUPS.flatMap((g) => g.rows.map((r) => r.name));
   const width = Math.max(...allNames.map((n) => n.length), 14);
   for (const group of GROUPS) {
-    out2.write("\n" + chalk6.bold(group.title) + "\n");
+    out2.write("\n" + chalk7.bold(group.title) + "\n");
     for (const row of group.rows) {
-      const aliasNote = row.alias ? chalk6.dim(`   ${row.alias} (alias)`) : "";
-      out2.write(`  ${chalk6.cyan.bold(row.name.padEnd(width + 2))}${row.description}${aliasNote}
+      const aliasNote = row.alias ? chalk7.dim(`   ${row.alias} (alias)`) : "";
+      out2.write(`  ${chalk7.cyan.bold(row.name.padEnd(width + 2))}${row.description}${aliasNote}
 `);
     }
   }
   out2.write("\n" + COMMON_FLAGS + "\n");
-  out2.write("\n" + chalk6.dim("More help: https://floom.dev/docs") + "\n");
+  out2.write("\n" + chalk7.dim("More help: https://floom.dev/docs") + "\n");
 }
 
 // src/index.ts
@@ -8037,7 +8106,7 @@ function editDistance(a, b) {
   return curr[b.length];
 }
 helpOpt(program.command("login").description("sign in to your Floom workspace")).action(loginCommand);
-helpOpt(program.command("logout").description("sign out on this machine")).action(logoutCommand);
+helpOpt(program.command("logout").description("sign out on this machine").option("--all", "sign out all CLI sessions for this account")).action((opts) => logoutCommand(opts));
 helpOpt(program.command("account").description("show account details").option("--json", "print account state as JSON")).action((opts) => accountCommand(opts));
 helpOpt(program.command("whoami").description("show account details (alias)").option("--json", "print account state as JSON")).action((opts) => {
   aliasNotice("whoami", "account");

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "3.0.1";
+export const VERSION = "3.0.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/floom",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "Floom CLI \u2014 one shared skill library, pulled into the AI agent you choose (Claude, Codex, Cursor, Gemini, OpenCode).",
   "license": "MIT",
   "homepage": "https://floom.dev",