@floomhq/floom 1.0.19 → 1.0.20

package/dist/cli.js

@@ -129,6 +129,112 @@ function commandUsage() {
 `;
     process.stdout.write(out);
 }
+function subcommandUsage(cmd) {
+    const key = cmd === "install" ? "add" : cmd === "rm" ? "delete" : cmd === "connect" ? "setup" : cmd === "paste" ? "agent-prompt" : cmd;
+    const usageByCommand = {
+        add: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} add`)} ${c.dim("<url-or-slug> [flags]")}
+
+Install a Floom skill into a local agent skills folder.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Install for Claude Code or Codex. Default: claude.
+  ${c.cyan("--setup")}                Add Floom guidance to the matching agent instructions file.
+  ${c.cyan("--force")}                Replace the local copy when remote content differs.
+  ${c.cyan("--json")}                 Print machine-readable install output.
+
+${c.bold("Examples")}
+  ${c.cyan(`${CLI_COMMAND} add https://floom.dev/s/ffas93ud --setup`)}
+  ${c.cyan(`${CLI_COMMAND} add ffas93ud --target codex --json`)}
+`,
+        update: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} update`)} ${c.dim("<url-or-slug> [flags]")}
+
+Refresh or migrate one local skill through the same installer as add.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Update Claude Code or Codex local skills. Default: claude.
+  ${c.cyan("--setup")}                Also refresh agent setup instructions.
+  ${c.cyan("--json")}                 Print machine-readable install output.
+`,
+        doctor: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} doctor`)} ${c.dim("[flags]")}
+
+Diagnose auth, API reachability, PATH collisions, MCP setup, and local skills folders.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Check Claude Code or Codex paths. Default: claude.
+  ${c.cyan("--json")}                 Print structured checks for scripts.
+`,
+        publish: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} publish`)} ${c.dim("<path> [flags]")}
+
+Scan and publish a Markdown skill file or skill folder. Prints a Floom share URL.
+
+${c.bold("Flags")}
+  ${c.cyan("--public")} | ${c.cyan("--private")} | ${c.cyan("--unlisted")}   Set visibility. Default: unlisted.
+  ${c.cyan("--type")} ${c.dim("knowledge|instruction|workflow|skill")}
+  ${c.cyan("--installs-as")} ${c.dim("claude_skill|memory|rule|codex_instruction|opencode_instruction|cursor_rule|other")}
+  ${c.cyan("--skill-version")} ${c.dim("<label>")}
+`,
+        init: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} init`)} ${c.dim("[path] [flags]")}
+
+Create a starter skill folder with SKILL.md.
+
+${c.bold("Flags")}
+  ${c.cyan("--template")} ${c.dim(`generic|${INIT_TEMPLATES.filter((t) => t !== "generic").join("|")}`)}
+`,
+        sync: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} sync`)} ${c.dim("[flags]")}
+
+Preview pull of published, saved, and subscribed library skills.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Sync into Claude Code or Codex skills. Default: claude.
+`,
+        watch: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} watch`)} ${c.dim("[flags]")}
+
+Poll sync on an interval. Preview behavior.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Watch Claude Code or Codex skills. Default: claude.
+  ${c.cyan("--interval")} ${c.dim("<seconds>")}    Poll interval. Minimum: 10.
+`,
+        setup: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} setup`)} ${c.dim("[flags]")}
+
+Add Floom guidance to CLAUDE.md or AGENTS.md.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Configure Claude Code or Codex.
+  ${c.cyan("--file")} ${c.dim("<path>")}           Write a specific instructions file.
+  ${c.cyan("--yes")}                  Write without prompting.
+  ${c.cyan("--dry-run")}              Preview the change only.
+`,
+        search: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} search`)} ${c.dim("<query> [flags]")}
+
+Find public skills and libraries.
+
+${c.bold("Flags")}
+  ${c.cyan("--library")} ${c.dim("<slug>")}        Limit search to one library.
+  ${c.cyan("--type")} ${c.dim("knowledge|instruction|workflow|skill")}
+  ${c.cyan("--json")}                 Print machine-readable results.
+`,
+        info: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} info`)} ${c.dim("<url-or-slug> [flags]")}
+
+Show public skill metadata.
+
+${c.bold("Flags")}
+  ${c.cyan("--json")}                 Print machine-readable metadata.
+`,
+        "agent-prompt": `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} agent-prompt`)} ${c.dim("[flags]")}
+
+Print the one-line instruction to paste into your agent.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Print the right local skills path. Default: claude.
+`,
+    };
+    const body = key ? usageByCommand[key] : undefined;
+    if (!body)
+        return false;
+    process.stdout.write(`${body}\n`);
+    return true;
+}
 const ASSET_TYPES = new Set(["knowledge", "instruction", "workflow", "skill"]);
 const INSTALL_TARGETS = new Set([
     "claude_skill",
@@ -722,10 +828,9 @@ async function main() {
             // never block on update-notifier
         }
     }
-    // Subcommand --help: any rest arg = --help/-h/help → show the command reference.
-    // Subcommands are simple enough that one reference screen is fine for Version 1.
     if (rest.includes("--help") || rest.includes("-h") || rest.includes("help")) {
-        commandUsage();
+        if (!subcommandUsage(cmd))
+            commandUsage();
         return;
     }
     try {

package/dist/sync.js

@@ -79,6 +79,17 @@ function skillPath(skill, targetAgent) {
 function syncKey(skill) {
     return `${skill.library_slug ?? ""}\0${skill.folder ?? ""}\0${skill.slug}`;
 }
+function hasStructuredPath(skill) {
+    return Boolean(skill.library_slug || skill.folder);
+}
+function dedupeSyncSkills(skills) {
+    const structuredSlugs = new Set();
+    for (const skill of skills) {
+        if (hasStructuredPath(skill))
+            structuredSlugs.add(skill.slug);
+    }
+    return skills.filter((skill) => !structuredSlugs.has(skill.slug) || hasStructuredPath(skill));
+}
 function validateSyncSkillShape(skill) {
     if (!skill || typeof skill !== "object")
         throw new FloomError("Invalid sync response.");
@@ -288,7 +299,7 @@ export async function sync(opts = {}) {
             for (const skill of payload.skills)
                 validateSyncSkillShape(skill);
             // Version 1 preview syncs published, saved, and subscribed library skills.
-            const all = payload.skills;
+            const all = dedupeSyncSkills(payload.skills);
             const seen = new Set();
             let unchanged = 0;
             let updated = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/floom",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "description": "Sync AI skills across agents and machines.",
   "license": "MIT",
   "type": "module",