@floomhq/floom 1.0.19 → 1.0.21

package/README.md

@@ -22,7 +22,7 @@ The package is designed for `npx -y @floomhq/floom ...`. Global installs expose
 
 ## Commands
 
-- `npx -y @floomhq/floom login` — sign in with Google. New accounts are created on first login. Token stored at `~/.floom/config.json`.
+- `npx -y @floomhq/floom login` — sign in with Google. Use `--provider github` for GitHub. New accounts are created on first login. Token stored at `~/.floom/config.json`.
 - `npx -y @floomhq/floom init [path]` — create a starter skill folder at `<path>/SKILL.md`. Passing an existing-style `file.md` path still creates that Markdown file.
 - `npx -y @floomhq/floom publish <path>` — upload a skill folder or Markdown file. Folder packages use `<slug>/SKILL.md` plus optional `references/`, `examples/`, `scripts/`, and `assets/`. Optional `--public` / `--private` / `--unlisted`, `--type knowledge|instruction|workflow|skill`, `--installs-as <target>`, and `--skill-version <label>`.
 - `npx -y @floomhq/floom share <slug>` — email-share one of your skills. Optional `--add <email>`, `--remove <email>`, and `--list`.

package/dist/cli.js

@@ -129,6 +129,119 @@ 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.
+`,
+        login: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} login`)} ${c.dim("[flags]")}
+
+Sign in through browser OAuth.
+
+${c.bold("Flags")}
+  ${c.cyan("--provider")} ${c.dim("google|github")}   OAuth provider. Default: google.
+`,
+        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",
@@ -149,6 +262,23 @@ function readFlagValue(argv, index, flag) {
         throw new FloomError(`Missing value for ${flag}.`);
     return { value, nextIndex: index + 1 };
 }
+function parseLoginArgs(argv) {
+    let provider = "google";
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i] ?? "";
+        if (a === "--provider" || a.startsWith("--provider=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--provider");
+            if (value !== "google" && value !== "github") {
+                throw new FloomError("Invalid --provider.", "Use google or github.");
+            }
+            provider = value;
+            i = nextIndex;
+            continue;
+        }
+        throw new FloomError(`Unknown flag or argument: ${a}`, `Try \`${CLI_COMMAND} login --provider github\`.`);
+    }
+    return { provider };
+}
 function parseFlags(argv) {
     const out = { visibility: "unlisted", update: false, rest: [] };
     let visibilityFlag = null;
@@ -722,10 +852,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 {
@@ -747,8 +876,7 @@ async function main() {
                 process.stdout.write(`${CLI_VERSION}\n`);
                 return;
             case "login":
-                rejectArgs(rest, `Try \`${CLI_COMMAND} login\`.`);
-                await login();
+                await login(parseLoginArgs(rest).provider);
                 return;
             case "logout":
                 rejectArgs(rest, `Try \`${CLI_COMMAND} logout\`.`);

package/dist/login.js

@@ -8,18 +8,19 @@ import { c, header, symbols } from "./ui.js";
 import { FloomError, friendlyHttp, friendlyNetwork } from "./errors.js";
 const DEFAULT_PORT = 7456;
 const TIMEOUT_MS = 5 * 60 * 1000;
-export async function login() {
+export async function login(provider = "google") {
     const apiUrl = getApiUrl();
     const port = await pickPort();
+    const providerLabel = provider === "github" ? "GitHub" : "Google";
     process.stdout.write(header());
-    process.stdout.write(`${symbols.arrow}  Opening browser to sign in with Google...\n\n`);
+    process.stdout.write(`${symbols.arrow}  Opening browser to sign in with ${providerLabel}...\n\n`);
     const spinner = ora({
         text: c.dim("Waiting for sign-in to complete..."),
         color: "yellow",
     }).start();
     let tokens;
     try {
-        tokens = await waitForCallback(port);
+        tokens = await waitForCallback(port, provider);
     }
     catch (err) {
         spinner.stop();
@@ -90,7 +91,7 @@ function reserveEphemeralPort() {
         });
     });
 }
-function waitForCallback(port) {
+function waitForCallback(port, provider) {
     return new Promise((resolve, reject) => {
         const apiUrl = getApiUrl();
         const state = randomBytes(32).toString("base64url");
@@ -172,7 +173,7 @@ function waitForCallback(port) {
             reject(new FloomError(`Local auth server failed on port ${port}.`, `Is port ${port} already in use? (${err.message})`));
         });
         server.listen(port, "127.0.0.1", () => {
-            const target = `${apiUrl}/auth/cli?port=${port}&state=${encodeURIComponent(state)}`;
+            const target = `${apiUrl}/auth/cli?port=${port}&provider=${provider}&state=${encodeURIComponent(state)}`;
             open(target).catch((e) => {
                 const msg = e instanceof Error ? e.message : String(e);
                 process.stdout.write(c.yellow(`Could not auto-open browser (${msg}).\n`) +

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.21",
   "description": "Sync AI skills across agents and machines.",
   "license": "MIT",
   "type": "module",