@floomhq/skills 0.2.10 → 0.2.12

package/dist/index.js

@@ -2383,8 +2383,7 @@ var log = {
 };
 
 // src/commands/login.ts
-import { exec } from "node:child_process";
-import { promisify as promisify2 } from "node:util";
+import { spawn } from "node:child_process";
 
 // src/config.ts
 import { homedir as homedir2 } from "node:os";
@@ -2395,7 +2394,7 @@ var AUTH_FILE = join3(CONFIG_DIR, "auth.json");
 var DEFAULT_APP_URL = "https://skills.floom.dev";
 var DEFAULT_API_URL = "https://skills.floom.dev/api/v1";
 var LEGACY_API_HOSTS = /* @__PURE__ */ new Set(["floom-v0.vercel.app", "skills.wasm.floom.dev"]);
-var TRUSTED_API_HOSTS = /* @__PURE__ */ new Set(["skills.floom.dev", "skills.wasm.floom.dev", "localhost", "127.0.0.1", "::1"]);
+var TRUSTED_API_HOSTS = /* @__PURE__ */ new Set(["skills.floom.dev", "skills.wasm.floom.dev"]);
 async function ensureDir() {
   await mkdir2(CONFIG_DIR, { recursive: true, mode: 448 });
 }
@@ -2484,19 +2483,33 @@ function isLegacyApiUrl(apiUrl) {
 }
 
 // src/version.ts
-var VERSION = "0.2.10";
+var VERSION = "0.2.12";
 
 // src/api-client.ts
 var DEFAULT_TIMEOUT_MS = 2e4;
+var DEFAULT_RETRY_ATTEMPTS = 2;
 function timeoutMs() {
   const raw = Number(process.env.FLOOM_API_TIMEOUT_MS);
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
 }
+function retryAttempts() {
+  const raw = Number(process.env.FLOOM_API_RETRY_ATTEMPTS);
+  return Number.isInteger(raw) && raw >= 0 ? Math.min(raw, 5) : DEFAULT_RETRY_ATTEMPTS;
+}
+function retryDelayMs(attempt) {
+  const raw = Number(process.env.FLOOM_API_RETRY_DELAY_MS);
+  const base = Number.isFinite(raw) && raw >= 0 ? raw : 150;
+  return base * 2 ** attempt;
+}
+async function sleep(ms) {
+  if (ms <= 0) return;
+  await new Promise((resolve3) => setTimeout(resolve3, ms));
+}
 async function fetchWithTimeout(url, init = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs());
   try {
-    return await fetch(url, { ...init, signal: controller.signal });
+    return await fetch(url, { ...init, redirect: "manual", signal: controller.signal });
   } catch (e) {
     if (e.name === "AbortError") {
       throw new Error(`Request timed out after ${timeoutMs()}ms`);
@@ -2506,6 +2519,19 @@ async function fetchWithTimeout(url, init = {}) {
     clearTimeout(timer);
   }
 }
+function redirectHost(res, requestUrl) {
+  const location = res.headers.get("location");
+  return location ? new URL(location, requestUrl).host : void 0;
+}
+function isRedirect(res) {
+  return res.status >= 300 && res.status < 400;
+}
+function isRetryableStatus(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+function isRetryableMethod(method) {
+  return method === "GET" || method === "HEAD";
+}
 async function api(path, opts = {}) {
   const auth = await readAuth();
   const token = process.env.FLOOM_API_TOKEN?.trim() || auth?.token;
@@ -2515,48 +2541,68 @@ async function api(path, opts = {}) {
   let lastError = null;
   const bases = getApiBaseUrls(auth?.apiUrl);
   for (const base of bases) {
-    const url = new URL(base + path);
-    if (opts.query) {
-      for (const [k, v] of Object.entries(opts.query)) {
-        if (v !== void 0) url.searchParams.set(k, String(v));
+    const method = opts.method ?? "GET";
+    const attempts = isRetryableMethod(method) ? retryAttempts() : 0;
+    for (let attempt = 0; attempt <= attempts; attempt++) {
+      const url = new URL(base + path);
+      if (opts.query) {
+        for (const [k, v] of Object.entries(opts.query)) {
+          if (v !== void 0) url.searchParams.set(k, String(v));
+        }
       }
-    }
-    const headers = {
-      "Content-Type": "application/json",
-      "User-Agent": `floom-cli/${VERSION}`,
-      "x-floom-cli-version": VERSION
-    };
-    const requestToken = opts.tokenOverride ?? token;
-    if (requestToken) headers.Authorization = `Bearer ${requestToken}`;
-    let res;
-    try {
-      res = await fetchWithTimeout(url.toString(), {
-        method: opts.method ?? "GET",
-        headers,
-        body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
-      });
-    } catch (e) {
+      const headers = {
+        "Content-Type": "application/json",
+        "User-Agent": `floom-cli/${VERSION}`,
+        "x-floom-cli-version": VERSION
+      };
+      const requestToken = opts.tokenOverride ?? token;
+      if (requestToken) headers.Authorization = `Bearer ${requestToken}`;
+      let res;
+      try {
+        res = await fetchWithTimeout(url.toString(), {
+          method,
+          headers,
+          body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
+        });
+      } catch (e) {
+        lastError = new FloomError(
+          "INTERNAL_ERROR",
+          `Unable to reach Floom API at ${base}: ${e.message}`,
+          { apiUrl: base }
+        );
+        if (attempt < attempts) {
+          await sleep(retryDelayMs(attempt));
+          continue;
+        }
+        break;
+      }
+      if (isRedirect(res)) {
+        throw new FloomError(
+          "INTERNAL_ERROR",
+          "Floom API returned an unexpected redirect. Refusing to forward credentials.",
+          { status: res.status, apiUrl: base, redirectHost: redirectHost(res, url) }
+        );
+      }
+      const text = await res.text();
+      let json = null;
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch {
+      }
+      if (res.ok) return json;
+      const err = json?.error ?? {};
       lastError = new FloomError(
-        "INTERNAL_ERROR",
-        `Unable to reach Floom API at ${base}: ${e.message}`,
-        { apiUrl: base }
+        err.code ?? "INTERNAL_ERROR",
+        err.message ?? `HTTP ${res.status} ${res.statusText}`,
+        { status: res.status, requestId: err.request_id, apiUrl: base }
       );
-      continue;
-    }
-    const text = await res.text();
-    let json = null;
-    try {
-      json = text ? JSON.parse(text) : null;
-    } catch {
+      if (isRetryableStatus(res.status) && attempt < attempts) {
+        await sleep(retryDelayMs(attempt));
+        continue;
+      }
+      if (res.status !== 404 || json?.error) break;
+      break;
     }
-    if (res.ok) return json;
-    const err = json?.error ?? {};
-    lastError = new FloomError(
-      err.code ?? "INTERNAL_ERROR",
-      err.message ?? `HTTP ${res.status} ${res.statusText}`,
-      { status: res.status, requestId: err.request_id, apiUrl: base }
-    );
-    if (res.status !== 404 || json?.error) break;
   }
   throw lastError ?? new FloomError("INTERNAL_ERROR", "API request failed");
 }
@@ -2572,6 +2618,12 @@ async function rawPut(url, body, contentType = "application/octet-stream") {
   } catch (e) {
     throw new FloomError("UPLOAD_FAILED", `Upload failed: ${e.message}`);
   }
+  if (isRedirect(res)) {
+    throw new FloomError(
+      "UPLOAD_FAILED",
+      `Upload failed: unexpected redirect to ${redirectHost(res, new URL(url)) ?? "unknown"}`
+    );
+  }
   if (!res.ok) {
     throw new FloomError(
       "UPLOAD_FAILED",
@@ -2586,6 +2638,12 @@ async function rawGet(url) {
   } catch (e) {
     throw new FloomError("DOWNLOAD_FAILED", `Download failed: ${e.message}`);
   }
+  if (isRedirect(res)) {
+    throw new FloomError(
+      "DOWNLOAD_FAILED",
+      `Download failed: unexpected redirect to ${redirectHost(res, new URL(url)) ?? "unknown"}`
+    );
+  }
   if (!res.ok) {
     throw new FloomError(
       "DOWNLOAD_FAILED",
@@ -2597,11 +2655,14 @@ async function rawGet(url) {
 }
 
 // src/commands/login.ts
-var sh = promisify2(exec);
 async function openInBrowser(url) {
-  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
   try {
-    await sh(`${opener} ${JSON.stringify(url)}`);
+    const child = spawn(command, args, { detached: true, stdio: "ignore", shell: false });
+    child.on("error", () => {
+    });
+    child.unref();
   } catch {
   }
 }
@@ -2615,7 +2676,7 @@ async function loginCommand() {
   log.info(`Open this URL in your browser:`);
   log.info(`  ${session.verification_uri}`);
   log.info("");
-  log.info(`Your code: ${session.user_code}`);
+  log.info(`Confirm this code in the browser: ${session.user_code}`);
   log.info("");
   log.info("Waiting for approval in the browser. Press Ctrl+C to cancel.");
   openInBrowser(session.verification_uri).catch(() => {
@@ -2684,7 +2745,13 @@ async function whoamiCommand() {
   try {
     me = await api("/me", { authRequired: true });
   } catch (e) {
-    log.err(`Login is not accepted by the Floom API: ${e.message}`);
+    if (e instanceof FloomError && e.code === "TOKEN_EXPIRED") {
+      log.err("Login expired.");
+    } else if (e instanceof FloomError && e.code === "TOKEN_INVALID") {
+      log.err("Login revoked or unknown.");
+    } else {
+      log.err(`Login is not accepted by the Floom API: ${e.message}`);
+    }
     log.info("Run: floom login");
     process.exitCode = 1;
     return;
@@ -3364,8 +3431,12 @@ async function updateCommand(refStr, opts = {}) {
 async function listCommand(opts = {}) {
   const resp = await api("/skills", {
     authRequired: true,
-    query: { q: opts.query, library: opts.workspace ?? opts.library, folder: opts.folder }
+    query: { q: opts.query, library: opts.workspace ?? opts.library, folder: opts.folder, tag: opts.tag }
   });
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
   if (resp.skills.length === 0) {
     log.info("No skills.");
     return;
@@ -3386,7 +3457,8 @@ async function listCommand(opts = {}) {
   for (const [library, rows] of groups.entries()) {
     log.heading(library);
     for (const s of rows) {
-      console.log(`  ${`${s.library.slug}/${s.slug}`.padEnd(40)} ${s.visibility.padEnd(10)} ${s.title}`);
+      const tagText = s.tags?.length ? ` #${s.tags.join(" #")}` : "";
+      console.log(`  ${`${s.library.slug}/${s.slug}`.padEnd(40)} ${s.visibility.padEnd(10)} ${s.title}${tagText}`);
     }
   }
 }
@@ -3414,12 +3486,19 @@ async function infoCommand(refStr) {
 }
 
 // src/commands/share.ts
+function isValidEmail(email) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
 async function shareCommand(refStr, email, opts = {}) {
   const ref = parseSkillRef(refStr);
   if (!ref) {
     log.err(`Invalid skill ref: ${refStr}`);
     process.exit(1);
   }
+  if (!isValidEmail(email)) {
+    log.err(`Invalid email: ${email}`);
+    process.exit(1);
+  }
   const role = opts.role ?? "viewer";
   const r = await api(`/skills/${ref.owner}/${ref.slug}/grants`, {
     method: "POST",
@@ -3435,6 +3514,10 @@ async function unshareCommand(refStr, email) {
     log.err(`Invalid skill ref: ${refStr}`);
     process.exit(1);
   }
+  if (!isValidEmail(email)) {
+    log.err(`Invalid email: ${email}`);
+    process.exit(1);
+  }
   const list = await api(`/skills/${ref.owner}/${ref.slug}/grants`, { authRequired: true });
   const grant = list.grants.find((g) => (g.email ?? "").toLowerCase() === email.toLowerCase());
   if (!grant) {
@@ -3446,6 +3529,9 @@ async function unshareCommand(refStr, email) {
 }
 
 // src/commands/library.ts
+function isValidEmail2(email) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
 async function libraryListCommand() {
   const resp = await api("/libraries", { authRequired: true });
   if (!resp.libraries.length) {
@@ -3461,17 +3547,52 @@ async function libraryCreateCommand(slug, name) {
   log.ok(`Created workspace ${resp.slug}`);
 }
 async function libraryInviteCommand(librarySlug, email, role = "viewer") {
-  await api(`/libraries/${librarySlug}/pending-invites`, {
+  if (!isValidEmail2(email)) {
+    log.err(`Invalid email: ${email}`);
+    process.exit(1);
+  }
+  const resp = await api(`/libraries/${librarySlug}/pending-invites`, {
     method: "POST",
     authRequired: true,
     body: { email, role }
   });
   log.ok(`Invited ${email} to ${librarySlug} as ${role}`);
+  if (resp.invite_url) log.info(`Invite link: ${resp.invite_url}`);
 }
 async function libraryLeaveCommand(librarySlug) {
   await api(`/libraries/${librarySlug}/members/me`, { method: "DELETE", authRequired: true });
   log.ok(`Left workspace ${librarySlug}`);
 }
+async function workspaceInvitesCommand() {
+  const resp = await api("/me/invites", { authRequired: true });
+  if (!resp.invites.length) {
+    log.info("No pending workspace invites.");
+    return;
+  }
+  for (const invite of resp.invites) {
+    const workspace = invite.workspace?.slug ?? "(missing workspace)";
+    const inviter = invite.inviter.handle ? `@${invite.inviter.handle}` : "admin";
+    console.log(`${workspace.padEnd(24)} ${invite.role.padEnd(6)} ${invite.status.padEnd(8)} from ${inviter} expires ${invite.expires_at}`);
+  }
+}
+function inviteToken(input) {
+  try {
+    const url = new URL(input);
+    const parts = url.pathname.split("/").filter(Boolean);
+    const inviteIndex = parts.indexOf("invite");
+    if (inviteIndex >= 0 && parts[inviteIndex + 1]) return parts[inviteIndex + 1];
+  } catch {
+  }
+  return input.trim();
+}
+async function workspaceAcceptCommand(tokenOrUrl) {
+  const token = inviteToken(tokenOrUrl);
+  const resp = await api(`/invites/${encodeURIComponent(token)}/accept`, {
+    method: "POST",
+    authRequired: true
+  });
+  log.ok(`Workspace invite ${resp.status}${resp.role ? ` as ${resp.role}` : ""}`);
+}
 
 // src/lib/config-file.ts
 import { mkdir as mkdir6, readFile as readFile8, writeFile as writeFile4 } from "node:fs/promises";
@@ -3888,18 +4009,33 @@ async function statusCommand(opts = {}) {
   const scope = normalizeScope(opts.scope);
   const config = await readFloomConfig(scope);
   const active = config.targets[target]?.active_workspaces ?? [];
-  log.heading(`Floom status for ${target} (${scope})`);
-  log.kv("Default workspace", config.default_workspace ?? "(none)");
-  log.kv("Active workspaces", active.length ? active.join(", ") : "(none)");
-  log.kv("Local pull policy", "router + pinned skills + instructions only");
+  const workspaces = [];
   for (const workspace of active) {
     const pins = await api(`/libraries/${workspace}/pins`, {
       authRequired: true,
       query: { target }
     });
+    workspaces.push({ workspace, pins: pins.pins });
+  }
+  if (opts.json) {
+    console.log(JSON.stringify({
+      target,
+      scope,
+      default_workspace: config.default_workspace ?? null,
+      active_workspaces: active,
+      pull_policy: "router + pinned skills + instructions only",
+      workspaces
+    }, null, 2));
+    return;
+  }
+  log.heading(`Floom status for ${target} (${scope})`);
+  log.kv("Default workspace", config.default_workspace ?? "(none)");
+  log.kv("Active workspaces", active.length ? active.join(", ") : "(none)");
+  log.kv("Local pull policy", "router + pinned skills + instructions only");
+  for (const workspace of workspaces) {
     log.blank();
-    log.info(`${workspace}: ${pins.pins.length} pinned skill(s) for ${target}`);
-    for (const pin of pins.pins) {
+    log.info(`${workspace.workspace}: ${workspace.pins.length} pinned skill(s) for ${target}`);
+    for (const pin of workspace.pins) {
       log.kv("", `${pin.skill?.slug ?? pin.skill_id}${pin.skill?.latest?.version ? `@${pin.skill.latest.version}` : ""}`);
     }
   }
@@ -3960,6 +4096,29 @@ async function pinCommand(ref, opts = {}) {
   });
   log.ok(`Pinned ${ref} for ${target} in ${workspace}`);
 }
+async function pinnedCommand(opts = {}) {
+  const target = assertTarget(opts.target ?? "codex");
+  const workspace = await resolveWorkspace(opts);
+  const resp = await api(`/libraries/${workspace}/pins`, {
+    authRequired: true,
+    query: { target }
+  });
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  if (resp.pins.length === 0) {
+    log.info(`No pinned skills for ${target} in ${workspace}.`);
+    return;
+  }
+  log.heading(`Pinned skills for ${target} in ${workspace}`);
+  for (const pin of resp.pins) {
+    const ref = pin.skill?.slug ? `${workspace}/${pin.skill.slug}` : pin.skill_id;
+    const version = pin.skill?.latest?.version ? `@${pin.skill.latest.version}` : "";
+    const title = pin.skill?.title ? `  ${pin.skill.title}` : "";
+    console.log(`  ${`${ref}${version}`.padEnd(42)} ${pin.created_at}${title}`);
+  }
+}
 async function unpinCommand(ref, opts = {}) {
   const target = assertTarget(opts.target ?? "codex");
   const workspace = await resolveWorkspace(opts);
@@ -3971,6 +4130,78 @@ async function unpinCommand(ref, opts = {}) {
   log.ok(`Unpinned ${ref} for ${target} in ${workspace}`);
 }
 
+// src/commands/folder.ts
+function slugify(value) {
+  return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+}
+async function folderListCommand(workspace) {
+  const resp = await api(`/libraries/${encodeURIComponent(workspace)}/folders`, { authRequired: true });
+  if (resp.folders.length === 0) {
+    log.info("No folders.");
+    return;
+  }
+  for (const folder of resp.folders) {
+    console.log(`${folder.id}  ${folder.slug.padEnd(24)} ${folder.access_mode.padEnd(10)} ${String(folder.skills_count ?? 0).padStart(3)} skills  ${folder.name}`);
+  }
+}
+async function folderCreateCommand(workspace, name, opts = {}) {
+  const slug = opts.slug ?? slugify(name);
+  const folder = await api(`/libraries/${encodeURIComponent(workspace)}/folders`, {
+    method: "POST",
+    authRequired: true,
+    body: {
+      name,
+      slug,
+      access_mode: opts.access ?? "open",
+      public_release_policy: opts.publicRelease ?? "allowed",
+      default_visibility: opts.visibility ?? "private"
+    }
+  });
+  log.ok(`Created folder ${folder.slug} in ${workspace}.`);
+  log.kv("Folder ID", folder.id);
+}
+async function folderArchiveCommand(workspace, folderId) {
+  await api(`/libraries/${encodeURIComponent(workspace)}/folders/${encodeURIComponent(folderId)}`, {
+    method: "DELETE",
+    authRequired: true
+  });
+  log.ok(`Archived folder ${folderId}.`);
+}
+async function folderMoveCommand(ref, folderId, opts = {}) {
+  const cleaned = ref.replace(/^@/, "");
+  const parts = cleaned.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error("Expected ref format: workspace/skill or @workspace/skill");
+  }
+  const [owner, slug] = parts;
+  const targetFolderId = opts.root ? null : folderId;
+  if (!opts.root && !targetFolderId) throw new Error("Provide a folder id, or pass --root to move to workspace root.");
+  const resp = await api(`/skills/${encodeURIComponent(owner)}/${encodeURIComponent(slug)}/move`, {
+    method: "POST",
+    authRequired: true,
+    body: {
+      target_library_slug: opts.workspace,
+      target_folder_id: targetFolderId
+    }
+  });
+  log.ok(`Moved ${ref} to ${resp.folder_id ? `folder ${resp.folder_id}` : "workspace root"} in ${resp.library_slug}.`);
+}
+async function folderGrantCommand(workspace, folderId, email, role) {
+  await api(`/libraries/${encodeURIComponent(workspace)}/folders/${encodeURIComponent(folderId)}/members`, {
+    method: "POST",
+    authRequired: true,
+    body: { email, role }
+  });
+  log.ok(`Granted ${role} folder access to ${email}.`);
+}
+async function folderRevokeCommand(workspace, folderId, memberId) {
+  await api(`/libraries/${encodeURIComponent(workspace)}/folders/${encodeURIComponent(folderId)}/members/${encodeURIComponent(memberId)}`, {
+    method: "DELETE",
+    authRequired: true
+  });
+  log.ok(`Revoked folder member ${memberId}.`);
+}
+
 // src/commands/mcp.ts
 import { mkdtemp, mkdir as mkdir9, readdir as readdir4, readFile as readFile10, rename as rename3, rm as rm3, writeFile as writeFile7 } from "node:fs/promises";
 import { join as join13 } from "node:path";
@@ -3992,7 +4223,7 @@ async function fetchWithTimeout2(url, init = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), API_TIMEOUT_MS);
   try {
-    return await fetch(url, { ...init, signal: controller.signal });
+    return await fetch(url, { ...init, redirect: "manual", signal: controller.signal });
   } catch (e) {
     if (e.name === "AbortError") throw new Error(`Request timed out after ${API_TIMEOUT_MS}ms`);
     throw e;
@@ -4032,6 +4263,12 @@ async function apiRequest(token, path, query) {
       lastError = new Error(`Unable to reach Floom API at ${base}: ${e.message}`);
       continue;
     }
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers.get("location");
+      const redirectHost2 = location ? new URL(location, url).host : "unknown";
+      lastError = new Error(`Floom API returned an unexpected redirect to ${redirectHost2}. Refusing to forward credentials.`);
+      break;
+    }
     const body = await res.text();
     let json = null;
     try {
@@ -4373,11 +4610,12 @@ program.command("install <ref>").description("Install a skill (default: .agents/
 program.command("installed").description("List installed skills in this project.").option("--json").action(installedCommand);
 program.command("outdated").description("Show installed skills with newer versions available.").action(outdatedCommand);
 program.command("update [ref]").description("Update installed skills to latest.").option("--force", "Overwrite local edits").action((ref, opts) => updateCommand(ref, opts));
-program.command("list").description("List remote skills.").option("--mine", "Only your own skills (default)").option("--workspace <slug>", "Filter by workspace slug").option("--library <slug>", "Legacy alias for --workspace").option("--folder <uuid>", "Filter by folder id").option("--flat", "Print one ref per line").option("--query <q>", "Filter by query").action(listCommand);
+program.command("list").description("List remote skills.").option("--mine", "Only your own skills (default)").option("--workspace <slug>", "Filter by workspace slug").option("--library <slug>", "Legacy alias for --workspace").option("--folder <uuid>", "Filter by folder id").option("--tag <tag>", "Filter by tag").option("--flat", "Print one ref per line").option("--json", "Emit machine-readable JSON").option("--query <q>", "Filter by query").action(listCommand);
 program.command("info <ref>").description("Show details for a remote skill.").action(infoCommand);
-program.command("status").description("Show local vs remote Floom workspace state").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--scope <scope>", "global | local", "local").action((opts) => statusCommand(opts));
+program.command("status").description("Show local vs remote Floom workspace state").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--scope <scope>", "global | local", "local").option("--json", "Emit machine-readable JSON").action((opts) => statusCommand(opts));
 program.command("pull").description("Pull account/workspace instructions for active workspaces").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--scope <scope>", "global | local", "local").option("--apply", "Append managed block when the target file has no Floom block").option("--force", "Write without the first-apply guard").action((opts) => pullCommand(opts));
 program.command("pin <ref>").description("Pin a workspace skill for local pull").option("--workspace <slug>", "Workspace slug").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").action((ref, opts) => pinCommand(ref, opts));
+program.command("pinned").alias("pins").description("List workspace skills pinned for local pull").option("--workspace <slug>", "Workspace slug").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--json", "Emit machine-readable JSON").action((opts) => pinnedCommand(opts));
 program.command("unpin <ref>").description("Unpin a workspace skill for local pull").option("--workspace <slug>", "Workspace slug").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").action((ref, opts) => unpinCommand(ref, opts));
 program.command("share <ref> <email>").description("Invite someone to a skill by email.").option("--role <role>", "viewer (default) or editor").action((ref, email, opts) => shareCommand(ref, email, opts));
 program.command("unshare <ref> <email>").description("Revoke someone's access.").action((ref, email) => unshareCommand(ref, email));
@@ -4387,6 +4625,8 @@ function addWorkspaceCommands(cmd) {
   cmd.command("list").action(libraryListCommand);
   cmd.command("create <slug> <name>").action((slug, name) => libraryCreateCommand(slug, name));
   cmd.command("invite <workspaceSlug> <email>").option("--role <role>", "viewer|editor|admin", "viewer").action((workspaceSlug, email, opts) => libraryInviteCommand(workspaceSlug, email, opts.role));
+  cmd.command("invites").description("List pending workspace invites for the logged-in user").action(workspaceInvitesCommand);
+  cmd.command("accept <tokenOrUrl>").description("Accept a workspace invite token or URL").action((tokenOrUrl) => workspaceAcceptCommand(tokenOrUrl));
   cmd.command("leave <workspaceSlug>").action((workspaceSlug) => libraryLeaveCommand(workspaceSlug));
   cmd.command("activate <workspaceSlug>").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--scope <scope>", "global | local", "local").action((workspaceSlug, opts) => workspaceActivateCommand(workspaceSlug, opts));
   cmd.command("deactivate <workspaceSlug>").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--scope <scope>", "global | local", "local").action((workspaceSlug, opts) => workspaceDeactivateCommand(workspaceSlug, opts));
@@ -4394,6 +4634,13 @@ function addWorkspaceCommands(cmd) {
 }
 addWorkspaceCommands(program.command("workspace").description("Manage workspaces"));
 addWorkspaceCommands(program.command("library").description("Manage workspaces (legacy alias)"));
+var folderCmd = program.command("folder").description("Manage workspace folders");
+folderCmd.command("list <workspace>").description("List folders in a workspace").action((workspace) => folderListCommand(workspace));
+folderCmd.command("create <workspace> <name>").description("Create a flat folder in a workspace").option("--slug <slug>", "Folder slug").option("--access <mode>", "open | restricted", "open").option("--public-release <policy>", "allowed | review_required | blocked", "allowed").option("--visibility <visibility>", "private | unlisted | public", "private").action((workspace, name, opts) => folderCreateCommand(workspace, name, opts));
+folderCmd.command("archive <workspace> <folderId>").description("Archive an empty folder").action((workspace, folderId) => folderArchiveCommand(workspace, folderId));
+folderCmd.command("move <ref> [folderId]").description("Move a skill into a folder or back to workspace root").option("--workspace <slug>", "Move to another workspace").option("--root", "Move to workspace root").action((ref, folderId, opts) => folderMoveCommand(ref, folderId, opts));
+folderCmd.command("grant <workspace> <folderId> <email>").description("Grant an existing workspace member access to a restricted folder").option("--role <role>", "viewer | editor | admin", "viewer").action((workspace, folderId, email, opts) => folderGrantCommand(workspace, folderId, email, opts.role));
+folderCmd.command("revoke <workspace> <folderId> <memberId>").description("Revoke a folder member grant").action((workspace, folderId, memberId) => folderRevokeCommand(workspace, folderId, memberId));
 var instructionCmd = program.command("instruction").description("Manage account and workspace instructions");
 instructionCmd.command("pull").description("Pull an account or workspace instruction into a managed local block").option("--account", "Pull account instruction").option("--workspace <slug>", "Pull workspace instruction").option("--target <target>", "default | claude | codex | cursor | opencode", "codex").option("--scope <scope>", "global | local", "local").option("--path <path>", "Instruction file path override").option("--apply", "Append managed block when the target file has no Floom block").option("--force", "Write without the first-apply guard").action((opts) => instructionPullCommand(opts));
 instructionCmd.command("push <file>").description("Publish an account or workspace instruction from a markdown file").option("--account", "Publish account instruction").option("--workspace <slug>", "Publish workspace instruction").option("--target <target>", "default | claude | codex | cursor | opencode", "default").option("--changelog <text>", "Version changelog").action((file, opts) => instructionPushCommand(file, opts));
@@ -4410,8 +4657,13 @@ async function main() {
       }
       process.exit(1);
     }
-    log.err(e.message ?? "Unknown error");
-    if (process.env.FLOOM_DEBUG) console.error(e);
+    const error = e;
+    log.err(error.message ?? "Unknown error");
+    if (process.env.FLOOM_DEBUG) {
+      const name = error.name || "Error";
+      const code = error.code ? ` code=${error.code}` : "";
+      console.error(`[debug] ${name}${code}`);
+    }
     process.exit(1);
   }
 }