@floomhq/floom 2.0.3 → 2.0.5

package/dist/index.js

@@ -2477,6 +2477,46 @@ var ContractDecisionChecklistItemSchema = z2.object({
   title: z2.string().min(1),
   locked: z2.literal(true)
 }).strict();
+var AGENT_TARGETS = ["claude", "codex", "cursor", "gemini", "opencode"];
+var AgentTargetSyncSchema = z2.object({
+  last_pulled_at: IsoDateTimeSchema.nullable()
+}).strict();
+var AgentMachineSchema = z2.object({
+  machine_id: z2.string().uuid(),
+  machine_label: z2.string().min(1),
+  last_seen_at: IsoDateTimeSchema,
+  target_sync: z2.record(z2.enum(AGENT_TARGETS), AgentTargetSyncSchema)
+}).strict();
+var AgentsListResponseSchema = z2.object({
+  machines: z2.array(AgentMachineSchema),
+  total: z2.number().int().nonnegative()
+}).strict();
+var ActivityEventSchema = z2.object({
+  id: IdSchema,
+  event_name: z2.enum(["signup", "workspace_create", "push", "pull", "share_create", "skill_delete"]),
+  source: z2.enum(["web", "cli", "api"]),
+  target: z2.enum(AGENT_TARGETS).nullable(),
+  skill_slug: z2.string().nullable(),
+  created_at: IsoDateTimeSchema
+}).strict();
+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";
@@ -2563,14 +2603,20 @@ async function readRawAuth() {
     const code = e.code;
     if (code === "ENOENT") return null;
     if (code === "EACCES" || code === "EPERM") {
-      throw new Error("Cannot read your Floom auth file (permission denied). Fix its permissions or run: floom login");
+      throw new Error(
+        "Cannot read your Floom auth file (permission denied).\n  Fix: chmod 600 ~/.floom/auth.json\n  Or re-authenticate: npx -y @floomhq/floom login\n  More help: https://floom.dev/docs#troubleshooting"
+      );
     }
-    throw new Error("Cannot read your Floom auth file. Run: floom login");
+    throw new Error(
+      "Cannot read your Floom auth file.\n  Run: npx -y @floomhq/floom login\n  More help: https://floom.dev/docs#troubleshooting"
+    );
   }
   try {
     return JSON.parse(raw);
   } catch {
-    throw new Error("Your Floom auth file is unreadable. Run: floom login");
+    throw new Error(
+      "Your Floom auth file is corrupted.\n  Run: npx -y @floomhq/floom login to generate a fresh one.\n  More help: https://floom.dev/docs#troubleshooting"
+    );
   }
 }
 async function writeAuth(state) {
@@ -2692,7 +2738,7 @@ async function getMachineIdentity() {
 }
 
 // src/version.ts
-var VERSION = "2.0.3";
+var VERSION = "2.0.4";
 
 // src/api-client.ts
 var DEFAULT_TIMEOUT_MS = 2e4;
@@ -2739,11 +2785,54 @@ async function readLimitedText(res, limitBytes = MAX_ERROR_BODY_BYTES) {
   return truncated ? `${text}
 [truncated]` : text;
 }
+var HELP = "https://floom.dev/docs#troubleshooting";
+function friendlyApiErrorMessage(code, raw, status) {
+  if (code === "AUTH_REQUIRED" || code === "TOKEN_INVALID" || status === 401) {
+    return `Not signed in.
+  Run: npx -y @floomhq/floom login
+  More help: ${HELP}`;
+  }
+  if (code === "TOKEN_EXPIRED") {
+    return `Your session has expired.
+  Run: npx -y @floomhq/floom login
+  More help: ${HELP}`;
+  }
+  if (code === "SKILL_ACCESS_DENIED" || status === 403) {
+    return `Access denied. This skill belongs to another workspace or you don't have permission to modify it.
+  If you want your own copy, push it with a different slug. More help: ${HELP}`;
+  }
+  if (code === "SKILL_NOT_FOUND" || status === 404) {
+    return `Skill not found. It may have been deleted or the slug is wrong.
+  Run: npx -y @floomhq/floom list
+  More help: ${HELP}`;
+  }
+  if (code === "RATE_LIMITED" || status === 429) {
+    return `Too many requests. Wait a moment and try again.
+  More help: ${HELP}`;
+  }
+  if (code === "CLI_VERSION_TOO_OLD") {
+    return `Your CLI is out of date.
+  Run: npx -y @floomhq/floom@latest <command>
+  More help: ${HELP}`;
+  }
+  if (code === "FILE_TOO_LARGE" || code === "BUNDLE_TOO_LARGE") {
+    return `${raw}
+  Reduce the size of your skill files before pushing. More help: ${HELP}`;
+  }
+  if (status && status >= 500) {
+    return `Floom service error (${status}). Please try again in a moment.
+  More help: ${HELP}`;
+  }
+  return raw;
+}
 async function api(path, opts = {}) {
   const auth = await readAuth();
   const token = process.env.FLOOM_API_TOKEN?.trim() || auth?.token;
   if (opts.authRequired && !token) {
-    throw new FloomError("AUTH_REQUIRED", "Not logged in. Run: npx -y @floomhq/floom login");
+    throw new FloomError(
+      "AUTH_REQUIRED",
+      "Not signed in.\n  Run: npx -y @floomhq/floom login\n  More help: https://floom.dev/docs#troubleshooting"
+    );
   }
   let lastError = null;
   const bases = getApiBaseUrls(auth?.apiUrl);
@@ -2776,7 +2865,9 @@ async function api(path, opts = {}) {
     } catch (e) {
       lastError = new FloomError(
         "INTERNAL_ERROR",
-        `Unable to reach Floom API at ${base}: ${e.message}`,
+        `Cannot reach Floom (${base}): ${e.message}
+  Check your internet connection or firewall. If on a corporate network, you may need to set a proxy: npm config set proxy http://...
+  More help: https://floom.dev/docs#troubleshooting`,
         { apiUrl: base }
       );
       continue;
@@ -2796,17 +2887,19 @@ async function api(path, opts = {}) {
     }
     const envelopeError = json?.error;
     if (envelopeError && typeof envelopeError === "object" && envelopeError.code) {
+      const rawMsg2 = typeof envelopeError.message === "string" ? envelopeError.message : String(envelopeError.code);
       throw new FloomError(
         envelopeError.code,
-        typeof envelopeError.message === "string" ? envelopeError.message : String(envelopeError.code),
+        friendlyApiErrorMessage(envelopeError.code, rawMsg2, res.status),
         { status: res.status, requestId: envelopeError.request_id, apiUrl: base }
       );
     }
     if (res.ok) return json;
     const err = envelopeError ?? {};
+    const rawMsg = err.message ?? `HTTP ${res.status} ${res.statusText}`;
     lastError = new FloomError(
       err.code ?? "INTERNAL_ERROR",
-      err.message ?? `HTTP ${res.status} ${res.statusText}`,
+      friendlyApiErrorMessage(err.code ?? "INTERNAL_ERROR", rawMsg, res.status),
       { status: res.status, requestId: err.request_id, apiUrl: base }
     );
     if (res.status !== 404 || json?.error) break;
@@ -2862,7 +2955,9 @@ async function loginCommand() {
     if (remaining <= 0) break;
     await sleep(Math.min(interval, remaining));
   }
-  throw new Error("Login timed out.");
+  throw new Error(
+    "Login timed out.\n  The browser approval window expired. Run: npx -y @floomhq/floom login\n  More help: https://floom.dev/docs#troubleshooting"
+  );
 }
 
 // src/commands/mcp.ts
@@ -2936,7 +3031,9 @@ async function readManifest(root) {
     if (err.code === "ENOENT") return null;
     if (error instanceof SyntaxError || error instanceof ZodError) {
       throw new Error(
-        `Corrupted manifest at ${manifestPath(root)}. Remove that file or run: npx -y @floomhq/floom pull`
+        `Corrupted manifest at ${manifestPath(root)}. Remove that file or run floom pull after backing up local edits.
+  Run: rm ${manifestPath(root)} && npx -y @floomhq/floom pull
+  More help: https://floom.dev/docs#troubleshooting`
       );
     }
     throw error;
@@ -3148,8 +3245,11 @@ function printDetectedTargets(targets) {
   for (const target of targets) log.info(`- ${target}`);
 }
 function printNoDetectedTargets() {
-  log.warn(`No installed agents detected. Checked: ${INSTALL_TARGETS.join(", ")}.`);
-  log.info(`Use --target <${INSTALL_TARGETS.join("|")}> to choose one target explicitly.`);
+  log.err(`No AI agent recognized on this machine.`);
+  log.info(`  Floom looks for: ${INSTALL_TARGETS.join(", ")}.`);
+  log.info(`  Make sure one of these is installed, then re-run.`);
+  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) {
   if (!options.target) {
@@ -3563,11 +3663,17 @@ async function findImmediateSkillDirs(root) {
 async function pushOneSkill(root, pushApi) {
   const dirStat = await stat4(root).catch(() => null);
   if (!dirStat || !dirStat.isDirectory()) {
-    throw new Error(`Directory not found: ${root}`);
+    throw new Error(
+      `Folder not found: ${root}
+  Check the path and try again. Run from your skill folder or pass the path: npx -y @floomhq/floom push ./path/to/skill`
+    );
   }
   const bundle = await collectBundle(root);
   const skillMd = bundle.files.find((file) => file.relPath === "SKILL.md");
-  if (!skillMd) throw new Error("SKILL.md is required.");
+  if (!skillMd) throw new Error(
+    `Missing SKILL.md in ${root}.
+  Every skill folder needs a SKILL.md at its root. See: https://floom.dev/docs#concept`
+  );
   const files = await Promise.all(bundle.files.map(async (file) => ({
     path: file.relPath,
     content_base64: (await readFile6(file.absPath)).toString("base64")
@@ -3598,7 +3704,10 @@ async function pushCommand(dir = ".", options = {}, deps = {}) {
     const root = resolve2(dir);
     const dirStat = await stat4(root).catch(() => null);
     if (!dirStat || !dirStat.isDirectory()) {
-      throw new Error(`Directory not found: ${dir}`);
+      throw new Error(
+        `Folder not found: ${dir}
+  Check the path and try again. Run from your skill folder or pass the path: npx -y @floomhq/floom push ./path/to/skill`
+      );
     }
     const pushApi = deps.pushApi ?? api;
     if (await hasSkillMarkdown(root)) {
@@ -3607,7 +3716,10 @@ async function pushCommand(dir = ".", options = {}, deps = {}) {
       return;
     }
     const skillDirs = await findImmediateSkillDirs(root);
-    if (skillDirs.length === 0) throw new Error("SKILL.md is required.");
+    if (skillDirs.length === 0) throw new Error(
+      `No skills found in ${dir}.
+  Neither the folder itself nor any immediate subfolder contains a SKILL.md. See: https://floom.dev/docs#concept`
+    );
     const concurrency = parseConcurrency(options.concurrency);
     const startedAt = Date.now();
     const errors = [];
@@ -3704,6 +3816,221 @@ 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";
+var TOKEN_RE = /^fls_[A-Za-z0-9_-]{32,}$/;
+function parseToken(input) {
+  const trimmed = input.trim();
+  if (TOKEN_RE.test(trimmed)) return trimmed;
+  try {
+    const url = new URL(trimmed);
+    const parts = url.pathname.split("/").filter(Boolean);
+    if (parts.length >= 2 && parts[parts.length - 2] === "s") {
+      const candidate = parts[parts.length - 1];
+      if (candidate && TOKEN_RE.test(candidate)) return candidate;
+    }
+    const last = parts[parts.length - 1];
+    if (last && TOKEN_RE.test(last)) return last;
+  } catch {
+  }
+  return null;
+}
+var SAFE_SLUG_RE2 = /^(?=.{1,80}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var MAX_DECODED_FILE_BYTES2 = 2 * 1024 * 1024;
+function safeSkillSlug2(slug) {
+  if (!slug) throw new Error("Remote skill slug is empty.");
+  if (slug.length > 80) throw new Error(`Remote skill slug "${slug.slice(0, 80)}\u2026" exceeds 80 characters.`);
+  if (!SAFE_SLUG_RE2.test(slug)) throw new Error(`Unsafe remote skill slug: ${slug}`);
+  return slug;
+}
+function safeRemotePath2(path) {
+  const normalized = path.replace(/\\/g, "/");
+  if (!normalized || /[\x00-\x1f\x7f]/.test(normalized) || normalized.startsWith("/") || normalized.split("/").some((part) => part === "" || part === "." || part === "..")) {
+    throw new Error(`Unsafe remote file path: ${path}`);
+  }
+  return normalized;
+}
+function bytesForShareFile(file) {
+  if (file.mode === "text") {
+    const text = file.content_text ?? "";
+    if (Buffer.byteLength(text, "utf8") > MAX_DECODED_FILE_BYTES2) {
+      throw new Error(`Remote file ${file.path} exceeds the 2 MiB decoded file limit.`);
+    }
+    return Buffer.from(text, "utf8");
+  }
+  const url = file.binary?.download_url ?? null;
+  if (!url?.startsWith("data:")) return Buffer.alloc(0);
+  const [, encoded] = url.split(",", 2);
+  const base64 = encoded ?? "";
+  const bytes = Buffer.from(base64, "base64");
+  if (bytes.byteLength > MAX_DECODED_FILE_BYTES2) {
+    throw new Error(`Remote file ${file.path} exceeds the 2 MiB decoded file limit.`);
+  }
+  return bytes;
+}
+function derivedSlug(title) {
+  return title.toLowerCase().replace(/[^a-z0-9 -]/g, "").trim().replace(/\s+/g, "-").replace(/-+/g, "-").slice(0, 80).replace(/^-+|-+$/g, "") || "shared-skill";
+}
+async function fetchPublicShare(token) {
+  const apiBase = getAppUrl().replace(/\/$/, "");
+  const url = `${apiBase}/api/v1/share/${encodeURIComponent(token)}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 3e4);
+  let res;
+  try {
+    res = await fetch(url, {
+      headers: { "User-Agent": "floom-cli/add" },
+      redirect: "manual",
+      signal: controller.signal
+    });
+  } catch (e) {
+    if (e.name === "AbortError") {
+      throw new Error("Request timed out. Check your internet connection and try again.");
+    }
+    throw new Error(`Cannot reach Floom: ${e.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (res.status === 404) {
+    throw new FloomError(
+      "SKILL_NOT_FOUND",
+      "Share link not found or revoked. Ask the sender for a fresh link."
+    );
+  }
+  if (res.status === 429) {
+    throw new FloomError(
+      "RATE_LIMITED",
+      "Too many requests. Try again in a minute."
+    );
+  }
+  if (!res.ok) {
+    throw new Error(`Floom API returned HTTP ${res.status}. Try again in a moment.`);
+  }
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    throw new Error("Unexpected response from Floom API. Try again in a moment.");
+  }
+  if (json && typeof json === "object" && "error" in json) {
+    const errObj = json.error;
+    if (errObj) throw new Error(errObj.message ?? "API error");
+  }
+  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 candidate;
+}
+async function addCommand(input, opts = {}) {
+  const token = parseToken(input);
+  if (!token) {
+    log.err(
+      "That doesn't look like a Floom share link. Should look like: https://floom.dev/s/fls_xxx"
+    );
+    process.exitCode = 1;
+    return;
+  }
+  let target;
+  if (opts.target) {
+    try {
+      target = assertInstallTarget(opts.target);
+    } catch {
+      log.err(`Unknown target "${opts.target}". Use one of: claude, codex, cursor, gemini, opencode`);
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    const detected = await detectInstalledTargets();
+    if (detected.length === 0) {
+      log.err("No AI agent recognized on this machine.");
+      log.info("  Floom looks for: claude, codex, cursor, gemini, opencode.");
+      log.info("  Or pick one explicitly: npx -y @floomhq/floom add <share-url> --target claude");
+      process.exitCode = 1;
+      return;
+    }
+    target = detected[0];
+  }
+  const resolved = resolveInstallDir({ target, global: true });
+  log.step(`Fetching share\u2026`);
+  let shareData;
+  try {
+    shareData = await fetchPublicShare(token);
+  } catch (e) {
+    if (e instanceof FloomError) {
+      log.err(e.message);
+    } else {
+      log.err(e.message ?? "Unknown error");
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const slug = safeSkillSlug2(derivedSlug(shareData.skill.title));
+  for (const file of shareData.file_contents) {
+    safeRemotePath2(file.path);
+  }
+  const cleanup = installCancellationHandler();
+  const tempDir = join8(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 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()}`);
+    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");
+      let existingDir = false;
+      try {
+        await stat5(finalDir);
+        existingDir = true;
+      } catch {
+      }
+      if (existingDir) {
+        await rename2(finalDir, replacedDir);
+        movedExisting = true;
+      }
+      try {
+        await rename2(tempDir, finalDir);
+      } catch (renameErr) {
+        if (movedExisting) {
+          try {
+            await rename2(replacedDir, finalDir);
+          } catch {
+          }
+        }
+        throw new Error(`Failed to install ${slug}: ${renameErr.message}`);
+      }
+      if (movedExisting) await rmFs(replacedDir, { recursive: true, force: true });
+    } catch (e) {
+      throw e;
+    }
+    log.blank();
+    log.ok(`Installed ${shareData.skill.title} ${shareData.skill.version.display} from ${shareData.skill.owner.name}`);
+    log.info(`  \u2192 ${finalDir}`);
+    log.blank();
+    log.info(`Next: in your agent, the skill is now loaded under the slug "${slug}".`);
+  } catch (e) {
+    log.err(e.message ?? "Unknown error");
+    process.exitCode = 1;
+  } finally {
+    cleanup.dispose();
+    try {
+      await rm2(tempDir, { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
+
 // src/index.ts
 async function logoutCommand() {
   const auth = await readAuth();
@@ -3720,7 +4047,9 @@ async function logoutCommand() {
 async function whoamiCommand() {
   const auth = await readAuth();
   if (!auth) {
-    log.info("Not logged in. Run: npx -y @floomhq/floom login");
+    log.err("Not signed in.");
+    log.info("  Run: npx -y @floomhq/floom login");
+    log.info("  More help: https://floom.dev/docs#troubleshooting");
     process.exitCode = 1;
     return;
   }
@@ -3739,12 +4068,9 @@ async function whoamiCommand() {
     }
     log.kv("api url", auth.apiUrl);
   } catch (error) {
-    if (error instanceof FloomError) {
-      log.err(`${error.code}: ${error.message}`);
-    } else {
-      log.err(error.message);
-    }
-    log.warn("Local auth file exists but the server rejected this session. Run: npx -y @floomhq/floom login");
+    log.err(error.message);
+    log.warn("Session invalid. Run: npx -y @floomhq/floom login");
+    log.info("  More help: https://floom.dev/docs#troubleshooting");
     process.exitCode = 1;
   }
 }
@@ -3759,13 +4085,14 @@ program.command("pull").description("Pull the whole workspace library.").option(
 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);
 async function main() {
   try {
     await program.parseAsync(process.argv);
   } catch (e) {
     if (e instanceof FloomError) {
-      log.err(`${e.code}: ${e.message}`);
+      log.err(e.message);
       process.exit(1);
     }
     log.err(e.message ?? "Unknown error");

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "2.0.3";
+export const VERSION = "2.0.5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/floom",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "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",