@floomhq/floom 2.0.4 → 2.0.6

package/dist/index.js

@@ -111,13 +111,13 @@ var require_bcrypt = __commonJS({
             throw Error("Illegal callback: " + typeof callback);
           _async(callback);
         } else
-          return new Promise(function(resolve3, reject) {
+          return new Promise(function(resolve4, reject) {
             _async(function(err, res) {
               if (err) {
                 reject(err);
                 return;
               }
-              resolve3(res);
+              resolve4(res);
             });
           });
       };
@@ -146,13 +146,13 @@ var require_bcrypt = __commonJS({
             throw Error("Illegal callback: " + typeof callback);
           _async(callback);
         } else
-          return new Promise(function(resolve3, reject) {
+          return new Promise(function(resolve4, reject) {
             _async(function(err, res) {
               if (err) {
                 reject(err);
                 return;
               }
-              resolve3(res);
+              resolve4(res);
             });
           });
       };
@@ -197,13 +197,13 @@ var require_bcrypt = __commonJS({
             throw Error("Illegal callback: " + typeof callback);
           _async(callback);
         } else
-          return new Promise(function(resolve3, reject) {
+          return new Promise(function(resolve4, reject) {
             _async(function(err, res) {
               if (err) {
                 reject(err);
                 return;
               }
-              resolve3(res);
+              resolve4(res);
             });
           });
       };
@@ -431,21 +431,21 @@ var require_bcrypt = __commonJS({
         var utfx2 = {};
         utfx2.MAX_CODEPOINT = 1114111;
         utfx2.encodeUTF8 = function(src, dst) {
-          var cp2 = null;
+          var cp3 = null;
           if (typeof src === "number")
-            cp2 = src, src = function() {
+            cp3 = src, src = function() {
               return null;
             };
-          while (cp2 !== null || (cp2 = src()) !== null) {
-            if (cp2 < 128)
-              dst(cp2 & 127);
-            else if (cp2 < 2048)
-              dst(cp2 >> 6 & 31 | 192), dst(cp2 & 63 | 128);
-            else if (cp2 < 65536)
-              dst(cp2 >> 12 & 15 | 224), dst(cp2 >> 6 & 63 | 128), dst(cp2 & 63 | 128);
+          while (cp3 !== null || (cp3 = src()) !== null) {
+            if (cp3 < 128)
+              dst(cp3 & 127);
+            else if (cp3 < 2048)
+              dst(cp3 >> 6 & 31 | 192), dst(cp3 & 63 | 128);
+            else if (cp3 < 65536)
+              dst(cp3 >> 12 & 15 | 224), dst(cp3 >> 6 & 63 | 128), dst(cp3 & 63 | 128);
             else
-              dst(cp2 >> 18 & 7 | 240), dst(cp2 >> 12 & 63 | 128), dst(cp2 >> 6 & 63 | 128), dst(cp2 & 63 | 128);
-            cp2 = null;
+              dst(cp3 >> 18 & 7 | 240), dst(cp3 >> 12 & 63 | 128), dst(cp3 >> 6 & 63 | 128), dst(cp3 & 63 | 128);
+            cp3 = null;
           }
         };
         utfx2.decodeUTF8 = function(src, dst) {
@@ -487,43 +487,43 @@ var require_bcrypt = __commonJS({
           if (c2 !== null) dst(c2);
         };
         utfx2.UTF8toUTF16 = function(src, dst) {
-          var cp2 = null;
+          var cp3 = null;
           if (typeof src === "number")
-            cp2 = src, src = function() {
+            cp3 = src, src = function() {
               return null;
             };
-          while (cp2 !== null || (cp2 = src()) !== null) {
-            if (cp2 <= 65535)
-              dst(cp2);
+          while (cp3 !== null || (cp3 = src()) !== null) {
+            if (cp3 <= 65535)
+              dst(cp3);
             else
-              cp2 -= 65536, dst((cp2 >> 10) + 55296), dst(cp2 % 1024 + 56320);
-            cp2 = null;
+              cp3 -= 65536, dst((cp3 >> 10) + 55296), dst(cp3 % 1024 + 56320);
+            cp3 = null;
           }
         };
         utfx2.encodeUTF16toUTF8 = function(src, dst) {
-          utfx2.UTF16toUTF8(src, function(cp2) {
-            utfx2.encodeUTF8(cp2, dst);
+          utfx2.UTF16toUTF8(src, function(cp3) {
+            utfx2.encodeUTF8(cp3, dst);
           });
         };
         utfx2.decodeUTF8toUTF16 = function(src, dst) {
-          utfx2.decodeUTF8(src, function(cp2) {
-            utfx2.UTF8toUTF16(cp2, dst);
+          utfx2.decodeUTF8(src, function(cp3) {
+            utfx2.UTF8toUTF16(cp3, dst);
           });
         };
-        utfx2.calculateCodePoint = function(cp2) {
-          return cp2 < 128 ? 1 : cp2 < 2048 ? 2 : cp2 < 65536 ? 3 : 4;
+        utfx2.calculateCodePoint = function(cp3) {
+          return cp3 < 128 ? 1 : cp3 < 2048 ? 2 : cp3 < 65536 ? 3 : 4;
         };
         utfx2.calculateUTF8 = function(src) {
-          var cp2, l = 0;
-          while ((cp2 = src()) !== null)
-            l += utfx2.calculateCodePoint(cp2);
+          var cp3, l = 0;
+          while ((cp3 = src()) !== null)
+            l += utfx2.calculateCodePoint(cp3);
           return l;
         };
         utfx2.calculateUTF16asUTF8 = function(src) {
           var n = 0, l = 0;
-          utfx2.UTF16toUTF8(src, function(cp2) {
+          utfx2.UTF16toUTF8(src, function(cp3) {
             ++n;
-            l += utfx2.calculateCodePoint(cp2);
+            l += utfx2.calculateCodePoint(cp3);
           });
           return [n, l];
         };
@@ -2233,6 +2233,10 @@ var InviteCreateResponseSchema = z2.object({
   invite: InviteSchema,
   accept_url: UrlSchema
 }).strict();
+var InviteLinkRotateResponseSchema = z2.object({
+  invite: InviteSchema,
+  accept_url: UrlSchema
+}).strict();
 var InvitesListResponseSchema = z2.object({
   invites: z2.array(InviteSchema),
   total: z2.number().int().nonnegative()
@@ -2503,6 +2507,20 @@ var ActivityFeedResponseSchema = z2.object({
   events: z2.array(ActivityEventSchema),
   total: z2.number().int().nonnegative()
 }).strict();
+var SkillSyncTargetEntrySchema = z2.object({
+  target: TargetSchema,
+  last_pulled_at: IsoDateTimeSchema
+}).strict();
+var SkillSyncMachineSchema = z2.object({
+  machine_id: IdSchema,
+  machine_label: z2.string().min(1),
+  targets: z2.array(SkillSyncTargetEntrySchema)
+}).strict();
+var SkillSyncStateResponseSchema = z2.object({
+  machines: z2.array(SkillSyncMachineSchema),
+  total_machines: z2.number().int().nonnegative(),
+  total_targets_synced: z2.number().int().nonnegative()
+}).strict();
 
 // src/lib/output.ts
 import chalk from "chalk";
@@ -2531,6 +2549,21 @@ var log = {
   },
   blank: () => {
     process.stdout.write("\n");
+  },
+  // A runnable command rendered cyan+bold — the one thing the eye should catch.
+  cmd: (s) => chalk.cyan.bold(s),
+  // Codex-style next-step block: description line, then the command indented in cyan+bold.
+  next: (description, command) => {
+    process.stdout.write(`
+${description}
+  ${chalk.cyan.bold(command)}
+`);
+  },
+  // Aligned-column row for list/status tables.
+  // col widths: [slug col, state col, rest]. Pass strings pre-padded or let row pad them.
+  row: (cols, widths) => {
+    const padded = cols.map((col, i) => widths[i] !== void 0 ? col.padEnd(widths[i]) : col);
+    process.stdout.write("  " + padded.join("  ") + "\n");
   }
 };
 
@@ -2651,26 +2684,26 @@ import { spawn } from "node:child_process";
 var CONFIG_DIR2 = join4(homedir3(), ".floom");
 var MACHINE_FILE = join4(CONFIG_DIR2, "machine.json");
 async function tryCommand(cmd, args) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     let child;
     try {
       child = spawn(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
     } catch {
-      resolve3(null);
+      resolve4(null);
       return;
     }
     let out = "";
     child.stdout?.on("data", (d) => {
       out += d.toString();
     });
-    child.on("close", (code) => resolve3(code === 0 ? out.trim() : null));
-    child.on("error", () => resolve3(null));
+    child.on("close", (code) => resolve4(code === 0 ? out.trim() : null));
+    child.on("error", () => resolve4(null));
     const timer = setTimeout(() => {
       try {
         child.kill();
       } catch {
       }
-      resolve3(null);
+      resolve4(null);
     }, 800);
     child.on("close", () => clearTimeout(timer));
   });
@@ -2724,7 +2757,7 @@ async function getMachineIdentity() {
 }
 
 // src/version.ts
-var VERSION = "2.0.4";
+var VERSION = "2.0.6";
 
 // src/api-client.ts
 var DEFAULT_TIMEOUT_MS = 2e4;
@@ -2894,8 +2927,33 @@ async function api(path, opts = {}) {
 }
 
 // src/commands/login.ts
+import { spawn as spawn2 } from "node:child_process";
+import chalk2 from "chalk";
+function tryOpenBrowser(url) {
+  if (process.env.FLOOM_NO_OPEN === "1") return;
+  const platform2 = process.platform;
+  let cmd;
+  let args;
+  if (platform2 === "darwin") {
+    cmd = "open";
+    args = [url];
+  } else if (platform2 === "win32") {
+    cmd = "cmd";
+    args = ["/c", "start", "", url];
+  } else {
+    cmd = "xdg-open";
+    args = [url];
+  }
+  try {
+    const child = spawn2(cmd, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
 function sleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 async function loginCommand() {
   const session = await api("/cli/device/start", {
@@ -2905,10 +2963,11 @@ async function loginCommand() {
       client: `floom-cli/${VERSION}`
     }
   });
-  log.heading("CLI login");
-  log.info(`Open: ${session.verification_uri}`);
-  log.info(`Code: ${session.user_code}`);
+  log.heading("Sign in to Floom");
+  log.info(`Open:  ${session.verification_uri}`);
+  log.info(`Code:  ${chalk2.bold(session.user_code)}`);
   log.info("Waiting for browser approval. Press Ctrl+C to cancel.");
+  tryOpenBrowser(session.verification_uri);
   const deadline = new Date(session.expires_at).getTime();
   const interval = Math.max(2, session.poll_interval_seconds) * 1e3;
   while (Date.now() < deadline) {
@@ -2926,7 +2985,9 @@ async function loginCommand() {
           email: token.user?.email ?? "unknown@example.com",
           apiUrl: getApiUrl()
         });
-        log.ok(`Logged in to ${token.workspace?.name ?? "Floom"}.`);
+        const emailDisplay = token.user?.email ? ` as ${token.user.email}` : "";
+        log.ok(`Logged in to ${token.workspace?.name ?? "Floom"}${emailDisplay}.`);
+        log.next("Next: pull your workspace skills into your AI agents.", "floom pull");
         return;
       }
     } catch (error) {
@@ -2954,9 +3015,10 @@ import { z as z3 } from "zod";
 // src/commands/sync.ts
 import { createHash as createHash3, randomUUID as randomUUID2 } from "node:crypto";
 import { cp, lstat as lstat2, mkdir as mkdir4, readdir as readdir2, readFile as readFile5, rename, rm, stat as stat3, writeFile as writeFile3 } from "node:fs/promises";
-import { dirname, join as join5, sep as sep3 } from "node:path";
+import { dirname, join as join5, resolve as resolve2, sep as sep3 } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { ZodError } from "zod";
+import chalk3 from "chalk";
 
 // src/lib/signals.ts
 import { rmSync } from "node:fs";
@@ -3080,6 +3142,83 @@ async function fileExists(path) {
     return false;
   }
 }
+async function dirExists(path) {
+  try {
+    return (await stat3(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function resolvePullDirs(target, _cwd = process.cwd(), homeDir) {
+  const primary = resolveInstallDir({ target, global: true, homeDir }).dir;
+  return uniqueResolvedDirs([primary]);
+}
+async function hasStatusVisibleProjectLocalDir(dir) {
+  if (await fileExists(manifestPath(dir))) return true;
+  return await dirExists(dir) && await hasAnySkillSubdir(dir);
+}
+async function resolveProjectLocalStatusDirs(target, cwd = process.cwd()) {
+  const projectLocal = presetDir(target, { cwd });
+  if (!await hasStatusVisibleProjectLocalDir(projectLocal)) return [];
+  return uniqueResolvedDirs([projectLocal]);
+}
+async function resolveStatusDirs(target, cwd = process.cwd(), homeDir) {
+  const primary = resolveInstallDir({ target, global: true, homeDir }).dir;
+  const projectLocalDirs = await resolveProjectLocalStatusDirs(target, cwd);
+  return uniqueResolvedDirs([primary, ...projectLocalDirs]);
+}
+async function resolveAutoStatusTargets(cwd = process.cwd(), homeDir) {
+  const detected = new Set(await detectInstalledTargets({ homeDir }));
+  const resolved = [];
+  for (const target of INSTALL_TARGETS) {
+    if (detected.has(target)) {
+      resolved.push({ target, dirs: await resolveStatusDirs(target, cwd, homeDir) });
+      continue;
+    }
+    const projectLocalDirs = await resolveProjectLocalStatusDirs(target, cwd);
+    if (projectLocalDirs.length > 0) resolved.push({ target, dirs: projectLocalDirs });
+  }
+  return resolved;
+}
+async function hasAnySkillSubdir(root) {
+  let entries;
+  try {
+    entries = await readdir2(root, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (await fileExists(join5(root, entry.name, "SKILL.md"))) return true;
+  }
+  return false;
+}
+async function listSkillSubdirs(root) {
+  let entries;
+  try {
+    entries = await readdir2(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const matches = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const candidate = join5(root, entry.name);
+    if (await fileExists(join5(candidate, "SKILL.md"))) matches.push(candidate);
+  }
+  return matches.sort();
+}
+function uniqueResolvedDirs(dirs) {
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  for (const dir of dirs) {
+    const resolved = resolve2(dir);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    unique.push(resolved);
+  }
+  return unique;
+}
 async function liveSkillHash(root, workspaceSlug, skill) {
   const slug = safeSkillSlug(skill.slug);
   const fileHashes = [];
@@ -3237,41 +3376,119 @@ function printNoDetectedTargets() {
   log.info(`  Or pick one explicitly: npx -y @floomhq/floom pull --target claude`);
   log.info(`  More help: https://floom.dev/docs#agents`);
 }
-async function statusCommand(options) {
+async function runStatusForDir(target, dir, deps) {
+  const hasFloomManifest = await fileExists(manifestPath(dir));
+  if (!hasFloomManifest) {
+    const localSkillDirs = await listSkillSubdirs(dir);
+    if (localSkillDirs.length > 0) {
+      printRawLocalSkillsHint(target, dir, localSkillDirs);
+      return { ok: true };
+    }
+  }
+  try {
+    const status = await statusLibrary(target, { ...deps, installDir: dir });
+    printFloomManagedStatus(target, dir, status);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+function shellSingleQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function printRawLocalSkillsHint(target, dir, localSkillDirs) {
+  log.heading(`Local skills found (${target})`);
+  log.info(`dir  ${dir}`);
+  log.info(`  Floom does not manage these yet. Push them to your library:`);
+  for (const skillDir of localSkillDirs) {
+    log.info(`  - ${skillDir}`);
+  }
+  log.info(`  Push a single skill: npx -y @floomhq/floom push ${shellSingleQuote(localSkillDirs[0])}`);
+  log.info(`  Push them all:       npx -y @floomhq/floom push ${shellSingleQuote(dir)}`);
+}
+function stateLabel(state) {
+  switch (state) {
+    case "active":
+      return chalk3.green("up to date");
+    case "stale":
+      return chalk3.yellow("needs pull");
+    case "dirty":
+      return chalk3.yellow("local edits");
+    case "conflict":
+      return chalk3.red("conflict");
+    case "missing":
+      return "not installed";
+    case "unsupported_target":
+      return "other agent";
+  }
+}
+function printFloomManagedStatus(target, dir, status) {
+  log.info(`${status.workspaceName} \xB7 ${target} \xB7 ${dir}`);
+  log.blank();
+  const slugWidth = Math.max(...status.skills.map((s) => s.slug.length), 4);
+  const labelWidth = 14;
+  for (const line of status.skills) {
+    const label = stateLabel(line.state);
+    process.stdout.write(`  ${line.slug.padEnd(slugWidth)}  ${label.padEnd(labelWidth + (label.length - stripAnsiLength(label)))}  ${line.version}
+`);
+  }
+  log.blank();
+  const needsPull = status.skills.filter((s) => s.state === "stale").length;
+  const localEdits = status.skills.filter((s) => s.state === "dirty").length;
+  const conflicts = status.skills.filter((s) => s.state === "conflict").length;
+  const parts = [`${status.skills.length} skill${status.skills.length !== 1 ? "s" : ""}`];
+  if (needsPull > 0) parts.push(`${needsPull} needs pull`);
+  if (localEdits > 0) parts.push(`${localEdits} with local edits`);
+  if (conflicts > 0) parts.push(`${conflicts} conflict${conflicts !== 1 ? "s" : ""}`);
+  log.info(parts.join(" \xB7 "));
+  const showPull = needsPull > 0 || conflicts > 0;
+  const showPush = localEdits > 0 || conflicts > 0;
+  if (showPull || showPush) {
+    log.blank();
+    log.info("Next:");
+    if (showPull) log.info(`  ${log.cmd("floom pull")}            update skills that are behind`);
+    if (showPush) log.info(`  ${log.cmd("floom push <dir>")}      publish your local edits`);
+  }
+}
+var ANSI_STRIP_RE = /\x1b\[[0-9;]*m/g;
+function stripAnsiLength(s) {
+  return s.replace(ANSI_STRIP_RE, "").length;
+}
+async function statusCommand(options, deps = {}) {
   if (!options.target) {
-    const targets = await detectInstalledTargets();
-    if (targets.length === 0) {
+    const targetDirs = await resolveAutoStatusTargets();
+    if (targetDirs.length === 0) {
       printNoDetectedTargets();
       process.exitCode = 1;
       return;
     }
-    printDetectedTargets(targets);
-    const results = [];
-    for (const target2 of targets) {
-      try {
-        results.push({ target: target2, ok: true, status: await statusLibrary(target2) });
-      } catch (error) {
-        results.push({ target: target2, ok: false, error });
-      }
-    }
-    for (const result of results) {
-      if (!result.ok) {
-        log.err(`${result.target}  ${result.error.message}`);
-        continue;
+    printDetectedTargets(targetDirs.map(({ target: target2 }) => target2));
+    let anyFailed2 = false;
+    for (const { target: target2, dirs } of targetDirs) {
+      for (const dir of dirs) {
+        const result = await runStatusForDir(target2, dir, deps);
+        if (!result.ok) {
+          log.err(`${target2}  ${dir}  ${result.error.message}`);
+          anyFailed2 = true;
+        }
       }
-      log.heading(`${result.status.workspaceName} (${result.target})`);
-      for (const line of result.status.skills) log.info(`${line.slug}  ${line.state}  ${line.version}`);
     }
-    if (results.some((result) => !result.ok)) process.exitCode = 1;
+    if (anyFailed2) process.exitCode = 1;
     return;
   }
   const target = assertInstallTarget(options.target);
-  const status = await statusLibrary(target);
-  log.heading(`${status.workspaceName} (${target})`);
-  for (const line of status.skills) log.info(`${line.slug}  ${line.state}  ${line.version}`);
+  let anyFailed = false;
+  for (const dir of await resolveStatusDirs(target)) {
+    const result = await runStatusForDir(target, dir, deps);
+    if (!result.ok) {
+      log.err(`${target}  ${dir}  ${result.error.message}`);
+      anyFailed = true;
+    }
+  }
+  if (anyFailed) process.exitCode = 1;
 }
 async function statusLibrary(target, deps = {}) {
-  const resolved = resolveInstallDir({ target, global: true });
+  const resolved = { dir: deps.installDir ?? resolveInstallDir({ target, global: true }).dir };
   const remote = await (deps.fetchLibrary ?? fetchLibrary)(target, "status");
   const manifest = await readManifest(resolved.dir);
   if (!manifest) {
@@ -3309,7 +3526,7 @@ async function statusLibrary(target, deps = {}) {
   }
   return { workspaceName: remote.workspace.name, skills };
 }
-async function pullCommand(options) {
+async function pullCommand(options, deps = {}) {
   const cleanup = installCancellationHandler();
   try {
     if (!options.target) {
@@ -3324,39 +3541,50 @@ async function pullCommand(options) {
         log.info("Cancelled.");
         return;
       }
+      const dirsByTarget = /* @__PURE__ */ new Map();
       for (const target2 of targets) {
-        const resolved2 = resolveInstallDir({ target: target2, global: true });
-        cleanup.trackDir(join5(resolved2.dir, ".floom", "tmp"));
+        const dirs2 = await resolvePullDirs(target2);
+        dirsByTarget.set(target2, dirs2);
+        for (const dir of dirs2) cleanup.trackDir(join5(dir, ".floom", "tmp"));
       }
       const results = [];
       for (const target2 of targets) {
         try {
-          const result2 = await pullLibrary(target2);
-          results.push({ target: target2, ok: true, ...result2 });
+          const dirs2 = dirsByTarget.get(target2) ?? [];
+          let skillCount2 = 0;
+          for (const dir of dirs2) {
+            const result = await pullLibrary(target2, { ...deps, installDir: dir });
+            skillCount2 = result.skillCount;
+          }
+          results.push({ target: target2, ok: true, skillCount: skillCount2, dirs: dirs2 });
         } catch (error) {
           results.push({ target: target2, ok: false, error });
         }
       }
       log.heading("Pull summary:");
-      for (const result2 of results) {
-        if (result2.ok) log.ok(`${result2.target}  ${result2.skillCount} skills  ${result2.dir}`);
-        else log.err(`${result2.target}  ${result2.error.message}`);
+      for (const result of results) {
+        if (result.ok) log.ok(`${result.target}  ${result.skillCount} skills  ${result.dirs.join(", ")}`);
+        else log.err(`${result.target}  ${result.error.message}`);
       }
-      if (results.some((result2) => !result2.ok)) process.exitCode = 1;
+      if (results.some((result) => !result.ok)) process.exitCode = 1;
       return;
     }
     const target = assertInstallTarget(options.target);
-    const resolved = resolveInstallDir({ target, global: true });
-    cleanup.trackDir(join5(resolved.dir, ".floom", "tmp"));
-    const result = await pullLibrary(target);
-    log.ok(`Pulled ${result.skillCount} skills into ${target} (${result.dir}).`);
+    const dirs = await resolvePullDirs(target);
+    for (const dir of dirs) cleanup.trackDir(join5(dir, ".floom", "tmp"));
+    let skillCount = 0;
+    for (const dir of dirs) {
+      const result = await pullLibrary(target, { ...deps, installDir: dir });
+      skillCount = result.skillCount;
+    }
+    log.ok(`Pulled ${skillCount} skills into ${target} (${dirs.join(", ")}).`);
     log.info(`This syncs ${target} only. For another agent: npx -y @floomhq/floom pull --target <claude|codex|cursor|gemini|opencode>`);
   } finally {
     cleanup.dispose();
   }
 }
 async function pullLibrary(target, deps = {}) {
-  const resolved = resolveInstallDir({ target, global: true });
+  const resolved = { dir: deps.installDir ?? resolveInstallDir({ target, global: true }).dir };
   const remote = await (deps.fetchLibrary ?? fetchLibrary)(target, "pull");
   for (const skill of remote.skills) safeSkillSlug(skill.slug);
   const manifest = await readManifest(resolved.dir);
@@ -3616,13 +3844,19 @@ function createMcpServer(deps = {}) {
   return server;
 }
 async function mcpCommand() {
+  if (process.stderr.isTTY || process.stdin.isTTY) {
+    process.stderr.write("Floom MCP server running (stdio).\n");
+    process.stderr.write("This is launched by your AI agent, not run by hand.\n");
+    process.stderr.write("Add it to Claude:  claude mcp add floom -- npx -y @floomhq/floom mcp\n");
+    process.stderr.write("Ctrl+C to stop.\n");
+  }
   const server = createMcpServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
 
 // src/commands/push.ts
-import { basename, join as join6, resolve as resolve2 } from "node:path";
+import { basename, join as join6, resolve as resolve3 } from "node:path";
 import { readdir as readdir3, readFile as readFile6, stat as stat4 } from "node:fs/promises";
 function parseConcurrency(value) {
   const raw = value ?? 6;
@@ -3687,7 +3921,7 @@ async function runBounded(items, concurrency, worker) {
 async function pushCommand(dir = ".", options = {}, deps = {}) {
   const cleanup = installCancellationHandler();
   try {
-    const root = resolve2(dir);
+    const root = resolve3(dir);
     const dirStat = await stat4(root).catch(() => null);
     if (!dirStat || !dirStat.isDirectory()) {
       throw new Error(
@@ -3699,6 +3933,7 @@ async function pushCommand(dir = ".", options = {}, deps = {}) {
     if (await hasSkillMarkdown(root)) {
       const result = await pushOneSkill(root, pushApi);
       log.ok(`Pushed ${result.skill.slug} ${result.skill.latest.display}.`);
+      log.next("Next: pull this skill into your AI agents.", "floom pull");
       return;
     }
     const skillDirs = await findImmediateSkillDirs(root);
@@ -3715,7 +3950,7 @@ async function pushCommand(dir = ".", options = {}, deps = {}) {
       try {
         const result = await pushOneSkill(skillDir, pushApi);
         pushed += 1;
-        log.info(`\u2713 ${result.skill.slug}  ${result.skill.latest.display}`);
+        log.ok(`${result.skill.slug}  ${result.skill.latest.display}`);
       } catch (error) {
         errors.push({ slug, message: error.message });
       }
@@ -3752,19 +3987,196 @@ async function deleteCommand(slug, opts = {}, deps = defaultDeps) {
 async function listCommand() {
   const result = await api("/skills", { authRequired: true });
   if (result.total === 0) {
-    log.info("No skills in this workspace.");
+    log.info("No skills in this workspace yet.");
+    log.next("Next: publish your first skill.", "floom push ./path/to/skill-folder");
     return;
   }
+  const slugWidth = Math.max(...result.skills.map((s) => s.slug.length), 4);
+  const verWidth = Math.max(...result.skills.map((s) => s.latest_version.display.length), 3);
   for (const skill of result.skills) {
-    log.info(`${skill.slug}  ${skill.latest_version.display}  ${skill.title}`);
+    log.row([skill.slug, skill.latest_version.display, skill.title], [slugWidth, verWidth, 0]);
+  }
+}
+
+// src/commands/sync-command.ts
+import { cp as cp2, mkdtemp, readdir as readdir4, rm as rm2, stat as stat5 } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join as join7 } from "node:path";
+import { createInterface as createInterface2 } from "node:readline/promises";
+async function hasSkillMarkdown2(dir) {
+  try {
+    const skillMd = await stat5(join7(dir, "SKILL.md"));
+    return skillMd.isFile();
+  } catch {
+    return false;
+  }
+}
+async function findImmediateSkillDirs2(root) {
+  let entries;
+  try {
+    entries = await readdir4(root, { withFileTypes: true });
+  } catch (error) {
+    const err = error;
+    if (err.code === "ENOENT") return [];
+    throw error;
+  }
+  const dirs = entries.filter((entry) => entry.isDirectory() && entry.name !== ".floom").map((entry) => ({ slug: entry.name, dir: join7(root, entry.name) })).sort((a, b) => a.slug.localeCompare(b.slug));
+  const checks = await Promise.all(dirs.map(async (entry) => await hasSkillMarkdown2(entry.dir) ? entry : null));
+  return checks.filter((entry) => Boolean(entry));
+}
+function formatSlugs(slugs) {
+  return slugs.length > 0 ? slugs.join(", ") : "none";
+}
+function printPreview(plan) {
+  log.info(
+    `Pull: ${plan.pull.length} skills (${formatSlugs(plan.pull.map((skill) => skill.slug))}). Push: ${plan.push.length} skills (${formatSlugs(plan.push.map((skill) => skill.slug))}). Skip (conflict): ${plan.conflicts.length} skills (${formatSlugs(plan.conflicts.map((skill) => skill.slug))}).`
+  );
+  if (plan.conflicts.length > 0) {
+    const count = plan.conflicts.length;
+    const noun = count === 1 ? "skill changed" : "skills changed";
+    log.err(`${count} ${noun} both locally and on the server: Floom won't guess which wins.`);
+    for (const skill of plan.conflicts) {
+      log.err(`  - ${skill.slug} (${skill.version})`);
+      log.err(`    Keep the server version:  floom pull --target ${plan.target}`);
+      log.err(`    Keep your local version:  floom push <${skill.slug}-dir>`);
+    }
+    log.err("Your local copy is always backed up to .floom/backups/ first.");
+    log.err("More: https://floom.dev/docs#conflicts");
+  }
+}
+async function defaultConfirmProceed() {
+  if (!process.stdin.isTTY) {
+    log.err("Aborted: confirmation is required in non-interactive mode. Re-run with --yes to proceed.");
+    return false;
+  }
+  const rl = createInterface2({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question("Proceed? [Y/n] ")).trim().toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+async function resolveTarget(options, deps) {
+  if (options.target) return assertInstallTarget(options.target);
+  const targets = await (deps.detectInstalledTargets ?? detectInstalledTargets)();
+  if (targets.length === 0) {
+    log.err("No AI agent recognized on this machine. Re-run with --target <claude|codex|cursor|gemini|opencode>.");
+    process.exitCode = 1;
+    return null;
+  }
+  if (targets.length > 1) {
+    log.err(`Multiple AI agents detected (${targets.join(", ")}). Re-run with --target <agent>.`);
+    process.exitCode = 1;
+    return null;
+  }
+  return targets[0];
+}
+async function createPushSnapshots(pushes) {
+  const root = await mkdtemp(join7(tmpdir(), "floom-sync-push-"));
+  const dirs = [];
+  try {
+    for (const push of pushes) {
+      const dest = join7(root, push.slug);
+      await cp2(push.dir, dest, { recursive: true });
+      dirs.push({ slug: push.slug, dir: dest });
+    }
+    return { root, dirs };
+  } catch (error) {
+    await rm2(root, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function buildPlan(options, deps) {
+  const target = await resolveTarget(options, deps);
+  if (!target) return null;
+  const status = await (deps.statusLibrary ?? statusLibrary)(target);
+  const dirtySlugs = new Set(status.skills.filter((skill) => skill.state === "dirty").map((skill) => skill.slug));
+  const installDir = resolveInstallDir({ target, global: true }).dir;
+  const localSkillDirs = await findImmediateSkillDirs2(installDir);
+  return {
+    target,
+    pull: status.skills.filter((skill) => skill.state === "missing" || skill.state === "stale"),
+    push: localSkillDirs.filter((entry) => dirtySlugs.has(entry.slug)),
+    conflicts: status.skills.filter((skill) => skill.state === "conflict")
+  };
+}
+async function syncCommand(options = {}, deps = {}) {
+  const plan = await buildPlan(options, deps);
+  if (!plan) return;
+  if (plan.pull.length === 0 && plan.push.length === 0 && plan.conflicts.length === 0) {
+    log.info("Already in sync.");
+    return;
+  }
+  printPreview(plan);
+  if (plan.conflicts.length > 0) {
+    process.exitCode = 1;
+    return;
+  }
+  if (plan.pull.length === 0 && plan.push.length === 0) return;
+  if (options.yes) {
+    log.info("Proceeding (--yes).");
+  } else if (!await (deps.confirmProceed ?? defaultConfirmProceed)()) {
+    log.info("Aborted.");
+    return;
+  }
+  const snapshots = await createPushSnapshots(plan.push);
+  const pushFailures = [];
+  let pushed = 0;
+  let preserveSnapshotsForRecovery = false;
+  try {
+    try {
+      await (deps.pullLibrary ?? pullLibrary)(plan.target);
+    } catch (error) {
+      log.err(`Pull failed: ${error.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    for (const snapshot of snapshots.dirs) {
+      try {
+        await (deps.pushSkill ?? ((dir) => pushCommand(dir)))(snapshot.dir);
+        pushed += 1;
+      } catch (error) {
+        pushFailures.push({
+          slug: snapshot.slug,
+          message: error.message,
+          snapshotDir: snapshot.dir
+        });
+      }
+    }
+  } finally {
+    if (pushFailures.length === 0) {
+      await rm2(snapshots.root, { recursive: true, force: true });
+    } else {
+      preserveSnapshotsForRecovery = true;
+    }
+  }
+  if (pushFailures.length > 0) {
+    log.err(`Push failed for ${pushFailures.length} of ${plan.push.length} skill(s).`);
+    log.err("Your local edits are preserved in two places (nothing is lost):");
+    log.err(`  1. Snapshot taken before pull:  ${snapshots.root}`);
+    log.err(`  2. Pull backup of pre-pull dir: ${plan.target} \u2192 .floom/backups/<latest>/`);
+    log.err("");
+    log.err("Failed skills:");
+    for (const failure of pushFailures) {
+      log.err(`  - ${failure.slug}: ${failure.message}`);
+      log.err(`    snapshot at: ${failure.snapshotDir}`);
+    }
+    log.err("");
+    log.err(`Re-run \`floom sync --target ${plan.target}\` after the network recovers.`);
+    process.exitCode = 1;
+  }
+  void preserveSnapshotsForRecovery;
+  if (pushFailures.length === 0) {
+    log.ok(`Sync complete. Pulled ${plan.pull.length} skills. Pushed ${pushed}/${plan.push.length} skills.`);
   }
 }
 
 // src/commands/rename-machine.ts
 import { readFile as readFile7, writeFile as writeFile4 } from "node:fs/promises";
-import { join as join7 } from "node:path";
+import { join as join8 } from "node:path";
 import { homedir as homedir4 } from "node:os";
-var MACHINE_FILE2 = join7(homedir4(), ".floom", "machine.json");
+var MACHINE_FILE2 = join8(homedir4(), ".floom", "machine.json");
 async function renameMachineCommand(newLabel, _opts) {
   const trimmed = newLabel.trim().slice(0, 80);
   if (!trimmed) {
@@ -3803,8 +4215,8 @@ async function renameMachineCommand(newLabel, _opts) {
 }
 
 // src/commands/add.ts
-import { mkdir as mkdir5, rm as rm2, writeFile as writeFile5 } from "node:fs/promises";
-import { join as join8 } from "node:path";
+import { mkdir as mkdir5, rm as rm3, writeFile as writeFile5 } from "node:fs/promises";
+import { join as join9 } from "node:path";
 var TOKEN_RE = /^fls_[A-Za-z0-9_-]{32,}$/;
 function parseToken(input) {
   const trimmed = input.trim();
@@ -3899,13 +4311,15 @@ async function fetchPublicShare(token) {
   } catch {
     throw new Error("Unexpected response from Floom API. Try again in a moment.");
   }
-  if (json.error) {
-    throw new Error(json.error.message ?? "API error");
+  if (json && typeof json === "object" && "error" in json) {
+    const errObj = json.error;
+    if (errObj) throw new Error(errObj.message ?? "API error");
   }
-  if (!json.data) {
+  const candidate = json;
+  if (!candidate || typeof candidate !== "object" || !candidate.skill || !Array.isArray(candidate.file_contents)) {
     throw new Error("Unexpected response shape from Floom API.");
   }
-  return json.data;
+  return candidate;
 }
 async function addCommand(input, opts = {}) {
   const token = parseToken(input);
@@ -3955,27 +4369,27 @@ async function addCommand(input, opts = {}) {
     safeRemotePath2(file.path);
   }
   const cleanup = installCancellationHandler();
-  const tempDir = join8(resolved.dir, ".floom", "tmp", `${slug}-add-${Date.now()}`);
+  const tempDir = join9(resolved.dir, ".floom", "tmp", `${slug}-add-${Date.now()}`);
   cleanup.trackDir(tempDir);
   try {
     await mkdir5(tempDir, { recursive: true });
     for (const file of shareData.file_contents) {
       const safePath = safeRemotePath2(file.path);
-      const dest = join8(tempDir, ...safePath.split("/"));
+      const dest = join9(tempDir, ...safePath.split("/"));
       const destDir = dest.substring(0, dest.lastIndexOf("/"));
       if (destDir !== tempDir) await mkdir5(destDir, { recursive: true });
       await writeFile5(dest, bytesForShareFile(file));
     }
-    const finalDir = join8(resolved.dir, slug);
-    const replacedDir = join8(resolved.dir, ".floom", "tmp", `${slug}-previous-${Date.now()}`);
+    const finalDir = join9(resolved.dir, slug);
+    const replacedDir = join9(resolved.dir, ".floom", "tmp", `${slug}-previous-${Date.now()}`);
     let movedExisting = false;
     try {
       const { rename: rename2, rm: rmFs } = await import("node:fs/promises");
       await mkdir5(resolved.dir, { recursive: true });
-      const { stat: stat5 } = await import("node:fs/promises");
+      const { stat: stat6 } = await import("node:fs/promises");
       let existingDir = false;
       try {
-        await stat5(finalDir);
+        await stat6(finalDir);
         existingDir = true;
       } catch {
       }
@@ -4009,7 +4423,7 @@ async function addCommand(input, opts = {}) {
   } finally {
     cleanup.dispose();
     try {
-      await rm2(tempDir, { recursive: true, force: true });
+      await rm3(tempDir, { recursive: true, force: true });
     } catch {
     }
   }
@@ -4059,18 +4473,30 @@ async function whoamiCommand() {
   }
 }
 var program = new Command();
-program.name("floom").description("Floom CLI \u2014 one shared skill library, pulled into the AI agent you choose.").version(VERSION);
-program.command("login").description("Log in via browser device flow.").action(loginCommand);
-program.command("logout").description("Clear local Floom auth.").action(logoutCommand);
-program.command("whoami").description("Show local auth state.").action(whoamiCommand);
-program.command("push [dir]").description("Push a skill folder.").option("--concurrency <n>", "Bulk push concurrency, 1-16", "6").action(pushCommand);
-program.command("delete <slug>").description("Delete a workspace skill.").option("--yes", "Skip confirmation").action((slug, opts) => deleteCommand(slug, opts));
-program.command("pull").description("Pull the whole workspace library.").option("--target <target>", "claude | codex | cursor | gemini | opencode").action(pullCommand);
+program.name("floom").description("Floom: one shared skill library, synced across every AI agent.").version(VERSION).addHelpCommand(false).hook("preAction", () => {
+});
+program.action(() => {
+  log.info("Floom: one shared skill library, synced across every AI agent.");
+  log.blank();
+  log.info("New here?");
+  log.info(`  1.  ${log.cmd("floom login")}          sign in`);
+  log.info(`  2.  ${log.cmd("floom pull")}            get your team's skills   (or  ${log.cmd("floom push <dir>")}  to publish)`);
+  log.info(`  3.  ${log.cmd("floom status")}          see what's synced`);
+  log.blank();
+  log.info(`All commands:  ${log.cmd("floom --help")}`);
+});
+program.command("login").description("Sign in via browser.").action(loginCommand);
+program.command("logout").description("Sign out and clear local auth.").action(logoutCommand);
+program.command("whoami").description("Show who you are signed in as.").action(whoamiCommand);
+program.command("push [dir]").description("Publish a skill folder to your workspace.").option("--concurrency <n>", "Bulk push concurrency, 1-16", "6").action(pushCommand);
+program.command("delete <slug>").description("Delete a skill from your workspace.").option("--yes", "Skip confirmation").action((slug, opts) => deleteCommand(slug, opts));
+program.command("pull").description("Pull the workspace library into your AI agents.").option("--target <target>", "claude | codex | cursor | gemini | opencode").action(pullCommand);
+program.command("sync").description("Pull remote changes, then push any local edits.").option("--target <target>", "claude | codex | cursor | gemini | opencode").option("--yes", "Skip confirmation").action(syncCommand);
 program.command("list").description("List workspace skills.").action(listCommand);
 program.command("status").description("Show local workspace sync status.").option("--target <target>", "claude | codex | cursor | gemini | opencode").action(statusCommand);
 program.command("mcp").description("Run the local MCP server over stdio.").action(mcpCommand);
 program.command("add <share-url-or-token>").description("Install a skill from a Floom share link.").option("--target <target>", "claude | codex | cursor | gemini | opencode").action((input, opts) => addCommand(input, opts));
-program.command("rename-machine <label>").description('Set the friendly name for THIS machine (e.g. "Office Server", "Travel Mac").').action(renameMachineCommand);
+program.command("rename-machine <label>").description('Set the friendly name for this machine (e.g. "Office Server", "Travel Mac").').action(renameMachineCommand);
 async function main() {
   try {
     await program.parseAsync(process.argv);

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "2.0.4";
+export const VERSION = "2.0.6";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/floom",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "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",
@@ -41,6 +41,7 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@floom/shared": "workspace:*",
     "esbuild": "^0.27.7",
     "@types/node": "^22.0.0",
     "@types/prompts": "^2.4.9",