@floomhq/floom 1.0.6 → 1.0.7

package/README.md

@@ -3,28 +3,29 @@
 Publish AI skills from your terminal. Share them with a link. Add other people's skills with one command.
 
 ```bash
-npm install -g @floomhq/floom
-floom init my-skill.md
-floom login
-floom publish my-skill.md
-floom share my-skill --add teammate@example.com
-floom search review
-floom add awesome-skill
-floom setup --target claude --dry-run
-floom list
-floom library list
+npx -y @floomhq/floom init my-skill.md
+npx -y @floomhq/floom login
+npx -y @floomhq/floom publish my-skill.md
+npx -y @floomhq/floom share my-skill --add teammate@example.com
+npx -y @floomhq/floom search review
+npx -y @floomhq/floom add awesome-skill --setup
+npx -y @floomhq/floom setup --target claude --dry-run
+npx -y @floomhq/floom list
+npx -y @floomhq/floom library list
 ```
 
 Returns a shareable link like `https://floom.dev/s/ffas93ud`. Anyone with the URL can read the raw Markdown — drop it into any AI tool that accepts skills.
 
+The package is designed for `npx -y @floomhq/floom ...`. Global installs expose `floom-skills` to avoid colliding with any older local Floom runtime CLI.
+
 ## Commands
 
-- `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. New accounts are created on first login. Token stored at `~/.floom/config.json`.
 - `floom init [file.md]` — create a starter skill file.
-- `floom publish <file.md>` — upload a Markdown file. Optional `--public` / `--private` / `--unlisted`, `--type knowledge|instruction|workflow|skill`, `--installs-as <target>`, and `--version <label>`.
+- `npx -y @floomhq/floom publish <file.md>` — upload a Markdown file. Optional `--public` / `--private` / `--unlisted`, `--type knowledge|instruction|workflow|skill`, `--installs-as <target>`, and `--skill-version <label>`.
 - `floom share <slug>` — email-share one of your skills. Optional `--add <email>`, `--remove <email>`, and `--list`.
 - `floom list` — show your published skills. Optional `--json`.
-- `floom add <url-or-slug>` — fetch a skill into `~/.claude/skills/<slug>.md`.
+- `npx -y @floomhq/floom add <url-or-slug>` — fetch a skill into `~/.claude/skills/<slug>.md`. Optional `--setup` connects Claude Code and `--force` replaces an existing local copy.
 - `floom info <url-or-slug>` — show skill metadata. Optional `--json`.
 - `floom search <query>` — search public skills and starter libraries. Optional `--library <slug>`, `--type knowledge|instruction|workflow|skill`, and `--json`.
 - `floom setup` — add Floom usage guidance to `CLAUDE.md` or `AGENTS.md`. Optional `--target claude|codex`, `--dry-run`, `--yes`.
@@ -38,7 +39,7 @@ Returns a shareable link like `https://floom.dev/s/ffas93ud`. Anyone with the UR
 - `floom library subscribe <slug>` — subscribe to a public or unlisted library so sync can pull it locally.
 - `floom move <slug> --folder <path>` — set your local folder override for a saved or library skill.
 - `floom delete <url-or-slug>` — delete one of your published skills. Optional `--yes`.
-- `floom doctor` — diagnose your Floom setup.
+- `npx -y @floomhq/floom doctor` — diagnose your Floom setup.
 - `floom whoami` — show the signed-in account.
 - `floom logout` — delete local credentials.
 
@@ -64,5 +65,5 @@ Override the API host with `FLOOM_API_URL` (defaults to `https://floom.dev`).
 `floom sync` and `floom watch` are Version 1 preview commands for published, saved, and subscribed library skills. They store a machine-local manifest at `~/.floom/sync-manifest.json`.
 The manifest records hashes for files Floom previously wrote. Version 1 sync writes missing files
 only. Remote updates, existing untracked files, and locally edited tracked files are skipped as
-conflicts. Symlinks are never followed. To accept the Floom version, move or delete the local file
-and run `floom sync` again.
+conflicts. Symlinks are never followed. To replace a local skill manually, run
+`npx -y @floomhq/floom add <url-or-slug> --force`.

package/dist/cli.js

@@ -4,7 +4,7 @@ import { login } from "./login.js";
 import { publish } from "./publish.js";
 import { whoami } from "./whoami.js";
 import { init } from "./init.js";
-import { deleteConfig } from "./config.js";
+import { deleteConfig, readConfig } from "./config.js";
 import { list } from "./list.js";
 import { install } from "./install.js";
 import { info } from "./info.js";
@@ -63,13 +63,14 @@ function usage() {
 }
 function commandUsage() {
     const out = `
- ${c.bold("Usage:")} ${c.cyan("floom")} ${c.dim("<command> [flags]")}
+ ${c.bold("Usage:")} ${c.cyan("npx -y @floomhq/floom")} ${c.dim("<command> [flags]")}
+ ${c.dim("Global install binary:")} ${c.cyan("floom-skills")} ${c.dim("<command> [flags]")}
 
  ${c.bold("Commands")}
    ${c.dim("Skills")}
      ${c.cyan("add")} ${c.dim("<url>")}          Install a skill into the local agent skills folder
                        ${c.dim("Alias: install")}
-                       ${c.dim("Flags: --target claude|codex (default: claude), --setup")}
+                       ${c.dim("Flags: --target claude|codex (default: claude), --setup, --force")}
      ${c.cyan("search")} ${c.dim("<query>")}     Find public skills and libraries
      ${c.cyan("info")} ${c.dim("<url>")}         Show skill metadata
 
@@ -105,16 +106,16 @@ function commandUsage() {
      ${c.cyan("watch")}              Preview polling sync loop
 
  ${c.bold("Examples")}
-   ${c.cyan("floom add")} ${c.dim("https://floom.dev/s/ffas93ud")}
-   ${c.cyan("floom publish")} ${c.dim("support-tone.md --type instruction --public")}
-   ${c.cyan("floom setup")} ${c.dim("--target claude --yes")}
+   ${c.cyan("npx -y @floomhq/floom add")} ${c.dim("https://floom.dev/s/ffas93ud --setup")}
+   ${c.cyan("npx -y @floomhq/floom publish")} ${c.dim("support-tone.md --type instruction --public")}
+   ${c.cyan("npx -y @floomhq/floom setup")} ${c.dim("--target claude --yes")}
 
  ${c.bold("Help")}
-   ${c.cyan("floom commands")}       Show this reference
+   ${c.cyan("npx -y @floomhq/floom commands")}  Show this reference
    ${c.cyan("--help")}               Show this reference
    ${c.cyan("--version")}            Show CLI version
 
- ${c.dim("Run")} ${c.cyan("floom")} ${c.dim("with no command for the guided start screen.")}
+ ${c.dim("Run")} ${c.cyan("npx -y @floomhq/floom")} ${c.dim("with no command for the guided start screen.")}
 `;
     process.stdout.write(out);
 }
@@ -173,15 +174,17 @@ function parseFlags(argv) {
             out.installsAs = value;
             i = nextIndex;
         }
-        else if (a === "--skill-version" || a.startsWith("--skill-version=") || a === "--version" || a.startsWith("--version=")) {
-            const flagName = a.startsWith("--skill-version") ? "--skill-version" : "--version";
-            const { value, nextIndex } = readFlagValue(argv, i, flagName);
+        else if (a === "--skill-version" || a.startsWith("--skill-version=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--skill-version");
             if (!VERSION_RE.test(value)) {
-                throw new FloomError(`Invalid ${flagName}: ${value}`, "Use 1-64 characters: letters, numbers, dots, underscores, plus, or hyphen.");
+                throw new FloomError(`Invalid --skill-version: ${value}`, "Use 1-64 characters: letters, numbers, dots, underscores, plus, or hyphen.");
             }
             out.version = value;
             i = nextIndex;
         }
+        else if (a === "--version" || a.startsWith("--version=")) {
+            throw new FloomError("`--version` prints the Floom CLI version at the top level.", "For skill version labels, use `--skill-version <label>`.");
+        }
         else if (a.startsWith("--")) {
             throw new FloomError(`Unknown flag: ${a}`, "Try `floom publish skill.md --type instruction --public`.");
         }
@@ -272,6 +275,7 @@ function parseAddArgs(argv) {
     let slug;
     let target;
     let setup = false;
+    let force = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] ?? "";
         if (a === "--target" || a.startsWith("--target=")) {
@@ -285,6 +289,9 @@ function parseAddArgs(argv) {
         else if (a === "--setup") {
             setup = true;
         }
+        else if (a === "--force") {
+            force = true;
+        }
         else if (a.startsWith("--")) {
             throw new FloomError(`Unknown flag: ${a}`, "Try `floom add <url-or-slug> --setup`.");
         }
@@ -297,7 +304,7 @@ function parseAddArgs(argv) {
     if (!slug) {
         throw new FloomError("Missing skill slug.", "Try: `floom add <url-or-slug> --setup`");
     }
-    return target ? { slug, target, setup } : { slug, setup };
+    return target ? { slug, target, setup, force } : { slug, setup, force };
 }
 function parseSearchFlags(argv) {
     const out = { json: false };
@@ -571,6 +578,10 @@ function sleep(ms, signal) {
     });
 }
 async function watch(intervalSeconds) {
+    const cfg = await readConfig();
+    if (!cfg) {
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` before watch, or use `npx -y @floomhq/floom add <link>` without an account.");
+    }
     const controller = new AbortController();
     let stopping = false;
     const stop = () => {
@@ -712,6 +723,7 @@ async function main() {
                 await install(flags.slug, {
                     ...(flags.target ? { target: flags.target } : {}),
                     setup: flags.setup,
+                    force: flags.force,
                 });
                 if (flags.setup) {
                     await setupAgent({ target: flags.target ?? "claude", dryRun: false, yes: true });
@@ -771,7 +783,7 @@ async function main() {
         }
     }
     catch (e) {
-        printError(e);
+        printError(e, { json: rest.includes("--json") });
         process.exit(1);
     }
 }

package/dist/errors.js

@@ -20,6 +20,9 @@ export function friendlyHttp(status, action) {
         return new FloomError(`You don't have permission to ${action}.`);
     }
     if (status === 404) {
+        if (/fetch|inspect|add|install|show|get|search|list|info/i.test(action)) {
+            return new FloomError("Skill not found.", "Check the link or slug, then try again.");
+        }
         return new FloomError("Skill not found.", "Run `floom publish` without `--update` to create a new one.");
     }
     if (status === 413) {
@@ -37,7 +40,14 @@ export function friendlyNetwork(err) {
     }
     return new FloomError(msg);
 }
-export function printError(err) {
+export function printError(err, opts = {}) {
+    if (opts.json) {
+        const error = err instanceof FloomError
+            ? { error: err.message, hint: err.hint ?? null }
+            : { error: err instanceof Error ? err.message : String(err), hint: null };
+        process.stderr.write(`${JSON.stringify(error)}\n`);
+        return;
+    }
     if (err instanceof FloomError) {
         process.stderr.write(`\n${symbols.fail}  ${err.message}\n`);
         if (err.hint) {

package/dist/install.js

@@ -77,6 +77,18 @@ async function writeInstallFile(root, target, body) {
         await parent.close();
     }
 }
+async function overwriteInstallFile(target, body) {
+    const handle = await open(target, constants.O_WRONLY | constants.O_TRUNC | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new FloomError("Local path is blocked by an existing file or directory.");
+        await writeAll(handle, body);
+    }
+    finally {
+        await handle.close();
+    }
+}
 async function openSafeParentDirectory(root, target) {
     await ensureSafeParentDirectory(root, target);
     return open(dirname(target), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
@@ -175,8 +187,20 @@ export async function install(slugInput, opts = {}) {
     if (existing === remoteHash) {
         action = "unchanged";
     }
+    else if (existing !== null && opts.force) {
+        try {
+            await overwriteInstallFile(target, detail.body_md);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ELOOP")
+                throw new FloomError("Local path is a symbolic link.", "Move or delete the local path, then run `floom add` again.");
+            throw err;
+        }
+        action = "updated";
+    }
     else if (existing !== null) {
-        throw new FloomError("Local skill already exists with different content.", "Move or delete the local file, then run `floom add` again.");
+        throw new FloomError("Local skill already exists with different content.", "Run `npx -y @floomhq/floom add <link> --force` to replace it, or move the local file first.");
     }
     else {
         try {
@@ -185,7 +209,7 @@ export async function install(slugInput, opts = {}) {
         catch (err) {
             const code = err.code;
             if (code === "EEXIST") {
-                throw new FloomError("Local skill already exists with different content.", "Move or delete the local file, then run `floom add` again.");
+                throw new FloomError("Local skill already exists with different content.", "Run `npx -y @floomhq/floom add <link> --force` to replace it, or move the local file first.");
             }
             if (code === "ELOOP") {
                 throw new FloomError("Local path is a symbolic link.", "Move or delete the local path, then run `floom add` again.");

package/dist/login.js

@@ -8,7 +8,6 @@ const DEFAULT_PORT = 7456;
 const TIMEOUT_MS = 5 * 60 * 1000;
 export async function login() {
     const apiUrl = getApiUrl();
-    const port = await pickPort();
     process.stdout.write(header());
     process.stdout.write(`${symbols.arrow}  Opening browser to sign in with Google...\n\n`);
     const spinner = ora({
@@ -17,7 +16,7 @@ export async function login() {
     }).start();
     let tokens;
     try {
-        tokens = await waitForCallback(port);
+        tokens = await waitForCallback();
     }
     catch (err) {
         spinner.stop();
@@ -57,16 +56,11 @@ export async function login() {
     process.stdout.write(`${symbols.ok}  Signed in as ${c.bold(me.email ?? me.id)}\n`);
     process.stdout.write(`   ${c.dim("Your token is saved at ~/.floom/config.json")}\n\n`);
 }
-/** Reserve a free port. Defaults to 7456 (must be in Supabase uri_allow_list). */
-async function pickPort() {
-    // Supabase uri_allow_list whitelists 7456 explicitly. If it's busy, we fail
-    // loudly rather than silently using a port that won't be allowed.
-    return DEFAULT_PORT;
-}
-function waitForCallback(port) {
+function waitForCallback() {
     return new Promise((resolve, reject) => {
         const apiUrl = getApiUrl();
         let settled = false;
+        let retriedEphemeralPort = false;
         const server = createServer((req, res) => {
             // CORS preflight from the browser bridge page.
             const origin = req.headers.origin ?? "*";
@@ -128,13 +122,27 @@ function waitForCallback(port) {
             server.close();
         }
         server.on("error", (err) => {
+            const code = err.code;
+            if (!settled && !retriedEphemeralPort && code === "EADDRINUSE") {
+                retriedEphemeralPort = true;
+                server.listen(0, "127.0.0.1");
+                return;
+            }
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
-            reject(new FloomError(`Local auth server failed on port ${port}.`, `Is port ${port} already in use? (${err.message})`));
+            reject(new FloomError("Local auth server failed.", err.message));
         });
-        server.listen(port, "127.0.0.1", () => {
+        server.listen(DEFAULT_PORT, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                settled = true;
+                cleanup();
+                reject(new FloomError("Could not reserve a local sign-in port."));
+                return;
+            }
+            const port = address.port;
             const target = `${apiUrl}/auth/cli?port=${port}`;
             open(target).catch((e) => {
                 const msg = e instanceof Error ? e.message : String(e);

package/dist/publish.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { basename, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
 import ora from "ora";
 import clipboard from "clipboardy";
 import { getWebUrl, readConfig, resolveApiUrl } from "./config.js";
@@ -34,21 +35,27 @@ function parseFrontmatter(input) {
     const headerBlock = trimmed.slice(3, end).trim();
     const rest = trimmed.slice(end + 4).replace(/^\r?\n/, "");
     const meta = {};
-    const lines = headerBlock.split(/\r?\n/);
-    for (let i = 0; i < lines.length; i++) {
-        const rawLine = lines[i] ?? "";
-        const line = rawLine.trim();
-        if (!line || line.startsWith("#"))
+    let parsed;
+    try {
+        parsed = headerBlock ? parseYaml(headerBlock) : {};
+    }
+    catch (err) {
+        return {
+            meta,
+            body: rest,
+            error: {
+                message: err instanceof Error ? err.message.replace(/\n.*/s, "") : "Invalid YAML.",
+                line: yamlErrorLine(err),
+            },
+        };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return { meta, body: rest };
+    for (const [rawKey, rawValue] of Object.entries(parsed)) {
+        const key = rawKey.trim().toLowerCase();
+        const value = frontmatterScalar(rawValue);
+        if (value === undefined)
             continue;
-        const colon = line.indexOf(":");
-        if (colon === -1) {
-            return { meta, body: rest, error: { message: `Couldn't parse line: \`${rawLine}\``, line: i + 2 } };
-        }
-        const key = line.slice(0, colon).trim().toLowerCase();
-        let value = line.slice(colon + 1).trim();
-        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-        }
         if (key === "title"
             || key === "description"
             || key === "version"
@@ -67,6 +74,18 @@ function parseFrontmatter(input) {
     }
     return { meta, body: rest };
 }
+function yamlErrorLine(err) {
+    const linePos = err.linePos;
+    const line = linePos?.[0]?.line;
+    return typeof line === "number" && Number.isFinite(line) ? line + 1 : 2;
+}
+function frontmatterScalar(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return undefined;
+}
 function parseAssetType(value, source) {
     if (!value)
         return undefined;
@@ -193,8 +212,8 @@ export async function publish(opts) {
         process.stdout.write(`   ${c.dim("Share it anywhere.")}\n\n`);
     }
     process.stdout.write(`   ${c.bold("Next")}\n`);
-    process.stdout.write(`   ${c.dim("1.")} Test locally: ${c.cyan(`npx -y @floomhq/floom add ${humanUrl} --target claude`)}\n`);
+    process.stdout.write(`   ${c.dim("1.")} Test locally: ${c.cyan(`npx -y @floomhq/floom add ${humanUrl} --setup`)}\n`);
     process.stdout.write(`   ${c.dim("2.")} Send the link.\n`);
-    process.stdout.write(`   ${c.dim("3.")} Receiver runs ${c.cyan(`npx -y @floomhq/floom add ${humanUrl} --target claude`)}\n`);
+    process.stdout.write(`   ${c.dim("3.")} Receiver runs ${c.cyan(`npx -y @floomhq/floom add ${humanUrl} --setup`)}\n`);
     process.stdout.write(`   ${c.dim("4.")} Agent reads the installed Markdown from the local skills folder.\n\n`);
 }

package/dist/scan.js

@@ -17,6 +17,9 @@ export async function scanSkill(file) {
             throw new FloomError(`That's a directory, not a file: ${file}`);
         throw new FloomError(`Couldn't read ${file}: ${err.message}`);
     }
+    if (!raw.trim()) {
+        throw new FloomError(`File is empty: ${file}`, "Add skill instructions before scanning or publishing.");
+    }
     const findings = detectSkillSecurityFindings(raw);
     if (findings.length > 0) {
         throw new FloomError("Security scan failed.", `${formatSecurityFindings(findings)}\nRemove secrets, prompt-injection text, or data-exfiltration instructions before publishing.`);

package/dist/secrets.js

@@ -12,7 +12,8 @@ const SECRET_PATTERNS = [
     { label: "Private key", regex: /-----BEGIN (?:RSA |EC |OPENSSH |)PRIVATE KEY-----/g },
 ];
 const GENERIC_ASSIGNMENT_RE = /\b(?:api[_-]?key|secret|access[_-]?token|auth[_-]?token|bearer[_-]?token)\b\s*[:=]\s*["']?([A-Za-z0-9_./+=-]{24,})["']?/gi;
-const PLACEHOLDER_RE = /^(?:your|example|placeholder|replace|changeme|todo|xxx|test|demo|dummy|redacted)/i;
+const PROVIDER_LIKE_ASSIGNMENT_RE = /\b(?:api[_-]?key|secret|access[_-]?token|auth[_-]?token|bearer[_-]?token)\b\s*[:=]\s*["']?((?:sk|pk|rk)-[A-Za-z0-9_-]{8,}|sbp_[A-Za-z0-9]{12,}|xox[baprs]-[A-Za-z0-9-]{12,})["']?/gi;
+const PLACEHOLDER_RE = /(?:^|[_./+=-])(?:your|example|placeholder|replace|changeme|todo|xxx|test|demo|dummy|fake|redacted)(?:$|[_./+=-])/i;
 const PROMPT_INJECTION_PATTERNS = [
     { label: "Prompt injection instruction", regex: /\bignore (?:all )?(?:previous|prior|above|earlier) instructions\b/gi },
     { label: "Prompt injection instruction", regex: /\bdisregard (?:all )?(?:previous|prior|above|earlier) instructions\b/gi },
@@ -62,6 +63,13 @@ export function detectSecrets(input) {
             continue;
         pushFinding(findings, seen, "Possible secret assignment", lineNumberAt(input, match.index ?? 0), value);
     }
+    PROVIDER_LIKE_ASSIGNMENT_RE.lastIndex = 0;
+    for (const match of input.matchAll(PROVIDER_LIKE_ASSIGNMENT_RE)) {
+        const value = match[1] ?? "";
+        if (!value)
+            continue;
+        pushFinding(findings, seen, "Provider-like secret assignment", lineNumberAt(input, match.index ?? 0), value);
+    }
     return findings.sort((a, b) => a.line - b.line || a.label.localeCompare(b.label));
 }
 function detectPatternFindings(input, patterns, category) {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@floomhq/floom",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Publish AI skills from your terminal. Share with a link.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "floom": "bin/floom.js"
+    "floom-skills": "bin/floom.js"
   },
   "files": [
     "bin",
@@ -30,7 +30,8 @@
     "open": "10.1.0",
     "ora": "8.1.1",
     "picocolors": "1.1.1",
-    "update-notifier": "7.3.1"
+    "update-notifier": "7.3.1",
+    "yaml": "2.8.4"
   },
   "devDependencies": {
     "@types/node": "22.10.5",