@floomhq/floom 1.0.1 → 1.0.3

package/README.md

@@ -4,9 +4,12 @@ Publish AI skills from your terminal. Share them with a link. Add other people's
 
 ```bash
 npm install -g @floomhq/floom
+floom init my-skill.md
 floom login
 floom publish my-skill.md
+floom search review
 floom add awesome-skill
+floom setup --target claude --dry-run
 floom list
 floom library list
 ```
@@ -21,6 +24,10 @@ Returns a shareable link like `https://floom.dev/s/ffas93ud`. Anyone with the UR
 - `floom list` — show your published skills. Optional `--json`.
 - `floom add <url-or-slug>` — fetch a skill into `~/.claude/skills/<slug>.md`.
 - `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`.
+- `floom connect` — alias for `floom setup`.
+- `floom mcp` — print MCP setup commands for supported agent CLIs.
 - `floom sync` — preview: pull your published, saved, and subscribed library skills into `~/.claude/skills/`.
 - `floom watch` — preview: run `floom sync` repeatedly. Optional `--interval <seconds>`; minimum `10`.
 - `floom library list` — list public starter libraries. Optional `--json`.

package/dist/cli.js

@@ -11,20 +11,21 @@ import { info } from "./info.js";
 import { deleteSkill } from "./delete.js";
 import { doctor } from "./doctor.js";
 import { sync } from "./sync.js";
+import { printMcpSetup } from "./mcp.js";
+import { setupAgent } from "./setup.js";
+import { search } from "./search.js";
 import { libraryAddSkill, libraryCreate, libraryList, libraryRemoveSkill, librarySubscribe, libraryUnsubscribe, moveSkill, } from "./library.js";
 import { c, symbols } from "./ui.js";
 import { printError, FloomError } from "./errors.js";
-const VERSION = "1.0.1";
+const VERSION = "1.0.3";
 const PKG = { name: "@floomhq/floom", version: VERSION };
 const V1_NOT_AVAILABLE = "Not available in Floom Version 1.";
 function usage() {
     const out = `
- ${c.coral("     ____       __")}
- ${c.coral("    / __ \\___  / /___ ___  __")}
- ${c.coral("   / /_/ / _ \\/ / __ `/ / / /")}
- ${c.coral("  / _, _/  __/ / /_/ / /_/ /")}
- ${c.coral(" /_/ |_|\\___/_/\\__,_/\\__, /")}   ${c.dim(`v${VERSION}`)}
- ${c.coral("                    /____/")}
+ ${c.coral("  __ _")}
+ ${c.coral(" / _| |___  ___ _ __")}   ${c.dim(`v${VERSION}`)}
+ ${c.coral("|  _| / _ \\/ _ \\ '  \\")}
+ ${c.coral("|_| |_\\___/\\___/_|_|_|")}
 
  ${c.bold("Share AI agent skills with a link.")}
  ${c.dim("Publish knowledge, instructions, and workflows from your terminal.")}
@@ -33,16 +34,22 @@ function usage() {
    ${c.cyan("floom")} ${c.dim("<command> [options]")}
 
  ${c.bold("Start Here")}
+   ${c.dim("Try a shared skill, no account needed:")}
    ${c.cyan("floom add")} ${c.dim("https://floom.dev/s/ffas93ud")}
-      ${c.dim("Install a public skill. No account needed.")}
 
-   ${c.cyan("floom publish")} ${c.dim("./support-tone.md --type instruction --public")}
-      ${c.dim("Publish Markdown and print a share link.")}
+   ${c.dim("Publish your own skill:")}
+   ${c.cyan("floom init")} ${c.dim("support-tone.md")}
+   ${c.cyan("floom login")}
+   ${c.cyan("floom publish")} ${c.dim("support-tone.md --type instruction --public")}
+
+   ${c.dim("Tell your agent where Floom installs skills:")}
+   ${c.cyan("floom setup")} ${c.dim("--target claude --dry-run")}
 
  ${c.bold("Commands")}
-   ${c.dim("Receive")}
+     ${c.dim("Receive")}
      ${c.cyan("add")} ${c.dim("<url-or-slug>")}             Install into ~/.claude/skills/
      ${c.cyan("info")} ${c.dim("<url-or-slug>")}            Show metadata ${c.dim("[--json]")}
+     ${c.cyan("search")} ${c.dim("<query>")}                Search public skills and libraries ${c.dim("[--json]")}
 
    ${c.dim("Create")}
      ${c.cyan("init")} ${c.dim("[file.md]")}                Create a starter skill file
@@ -65,6 +72,9 @@ function usage() {
      ${c.cyan("logout")}                        Delete local credentials
 
    ${c.dim("System")}
+     ${c.cyan("setup")} ${c.dim("[--target claude|codex] [--file path]")}  Add Floom guidance to agent instructions
+     ${c.cyan("connect")} ${c.dim("[--target claude|codex]")}              Alias for setup
+     ${c.cyan("mcp")}                           Print MCP setup guidance
      ${c.cyan("sync")}                          Preview: pull published, saved, and library skills
      ${c.cyan("watch")}                         Preview: poll published, saved, and library skills ${c.dim("[--interval <seconds>, min 10]")}
      ${c.cyan("doctor")}                        Diagnose auth, API, and local setup
@@ -168,6 +178,36 @@ function parseInfoFlags(argv) {
     }
     return out;
 }
+function parseSearchFlags(argv) {
+    const out = { json: false };
+    const terms = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--json")
+            out.json = true;
+        else if (a === "--library" || a.startsWith("--library=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--library");
+            out.library = value;
+            i = nextIndex;
+        }
+        else if (a === "--type" || a.startsWith("--type=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--type");
+            if (!ASSET_TYPES.has(value)) {
+                throw new FloomError(`Invalid --type: ${value}`, "Use one of: knowledge, instruction, workflow, skill.");
+            }
+            out.type = value;
+            i = nextIndex;
+        }
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom search \"support tone\" --type instruction`.");
+        }
+        else {
+            terms.push(a);
+        }
+    }
+    out.query = terms.join(" ").trim();
+    return out;
+}
 function parseDeleteFlags(argv) {
     const out = { yes: false };
     for (const a of argv) {
@@ -180,6 +220,37 @@ function parseDeleteFlags(argv) {
     }
     return out;
 }
+function parseSetupFlags(argv) {
+    const out = { dryRun: false, yes: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--dry-run" || a === "--preview")
+            out.dryRun = true;
+        else if (a === "--yes" || a === "-y")
+            out.yes = true;
+        else if (a === "--target" || a.startsWith("--target=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--target");
+            if (value !== "claude" && value !== "codex") {
+                throw new FloomError("Invalid --target.", "Use `claude` or `codex`.");
+            }
+            out.target = value;
+            i = nextIndex;
+        }
+        else if (a === "--file" || a.startsWith("--file=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--file");
+            out.file = value;
+            i = nextIndex;
+        }
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom setup --target codex --dry-run`.");
+        }
+        else if (!out.file)
+            out.file = a;
+        else
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom setup --target claude --yes`.");
+    }
+    return out;
+}
 function normalizeFolder(value) {
     return value === "root" || value === "/" || value === "." ? null : value;
 }
@@ -440,6 +511,19 @@ async function main() {
                     await info({ slug: flags.slug ?? "", json: flags.json });
                 }
                 return;
+            case "search": {
+                const flags = parseSearchFlags(rest);
+                if (!flags.query) {
+                    throw new FloomError("Missing search query.", "Try: `floom search \"support tone\"`.");
+                }
+                await search({
+                    query: flags.query,
+                    ...(flags.library ? { library: flags.library } : {}),
+                    ...(flags.type ? { type: flags.type } : {}),
+                    json: flags.json,
+                });
+                return;
+            }
             case "add":
             case "install": {
                 const slug = rest.find((a) => !a.startsWith("--"));
@@ -452,6 +536,12 @@ async function main() {
             case "sync":
                 await sync();
                 return;
+            case "setup":
+            case "connect": {
+                const flags = parseSetupFlags(rest);
+                await setupAgent(flags);
+                return;
+            }
             case "watch": {
                 const flags = parseWatchFlags(rest);
                 await watch(flags.intervalSeconds);
@@ -480,7 +570,8 @@ async function main() {
                 return;
             }
             case "mcp":
-                notAvailable("`floom mcp setup`");
+                printMcpSetup();
+                return;
             case "doctor":
                 await doctor();
                 return;

package/dist/doctor.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { stat, readFile, access, readdir, constants } from "node:fs/promises";
 import { getApiUrl, readConfig, CONFIG_PATH } from "./config.js";
 import { c, symbols } from "./ui.js";
-const CLI_VERSION = "1.0.1";
+const CLI_VERSION = "1.0.2";
 function statusBadge(s) {
     if (s === "ok")
         return c.green(symbols.ok);

package/dist/list.js

@@ -41,7 +41,7 @@ export async function list(opts) {
     const spinner = opts.json ? null : ora({ text: c.dim("Loading skills..."), color: "yellow" }).start();
     let published = [];
     try {
-        const mine = await getJson(`${apiUrl}/api/me/skills`, "load your skills", cfg.accessToken);
+        const mine = await getJson(`${apiUrl}/api/v1/me/skills`, "load your skills", cfg.accessToken);
         published = mine.skills ?? [];
     }
     finally {

package/dist/mcp.js

@@ -1,9 +1,10 @@
 import { c } from "./ui.js";
 export function printMcpSetup() {
     const snippet = `## Floom
-- Your installed skills live in ~/.claude/skills/ and auto-sync from Floom on each session
-- To install a skill: ask me "install floom skill <slug>"
-- To publish: ask me "publish this as a floom skill"`;
+- Use Floom skills from ~/.claude/skills/ when they match the task.
+- To install a shared skill, run \`floom add <slug-or-url>\`.
+- To find reusable behavior, run \`floom search <query>\`.
+- MCP sync is optional preview behavior; use it only while the Floom MCP server is configured and running.`;
     process.stdout.write(`\n${c.bold("Floom MCP setup")}\n\n`);
     process.stdout.write(`${c.dim("Pick your tool:")}\n\n`);
     process.stdout.write(`  ${c.bold("Claude Code")}\n`);
@@ -17,6 +18,6 @@ export function printMcpSetup() {
     process.stdout.write(`  ${c.bold("OpenCode")}\n`);
     process.stdout.write(`  ${c.dim("Edit ~/.config/opencode/opencode.json - see guide.")}\n\n`);
     process.stdout.write(`${c.dim("Full guide:")} ${c.cyan("https://floom.dev/docs/mcp")}\n\n`);
-    process.stdout.write(`${c.dim("Recommended CLAUDE.md snippet:")}\n\n`);
+    process.stdout.write(`${c.dim("Recommended agent instruction snippet:")}\n\n`);
     process.stdout.write(`${snippet}\n\n`);
 }

package/dist/search.js

@@ -0,0 +1,54 @@
+import ora from "ora";
+import { getApiUrl, readConfig } from "./config.js";
+import { getJson } from "./lib/api.js";
+import { c, symbols } from "./ui.js";
+function formatSkillRow(skill) {
+    const title = skill.title ?? c.dim("(untitled)");
+    const type = c.dim(`[${skill.asset_type}]`);
+    const libs = skill.libraries.length
+        ? c.dim(` ${skill.libraries.map((lib) => `@${lib.slug}`).join(", ")}`)
+        : "";
+    return `   ${c.cyan(skill.slug.padEnd(22))}  ${title}  ${type}${libs}`;
+}
+function formatLibraryRow(library) {
+    const count = `${library.skill_count} ${library.skill_count === 1 ? "skill" : "skills"}`;
+    return `   ${c.cyan(`@${library.slug}`.padEnd(22))}  ${library.name}  ${c.dim(count)}`;
+}
+export async function search(opts) {
+    const cfg = await readConfig();
+    const apiUrl = cfg?.apiUrl ?? getApiUrl();
+    const params = new URLSearchParams({ q: opts.query });
+    if (opts.library)
+        params.set("library", opts.library);
+    if (opts.type)
+        params.set("type", opts.type);
+    const spinner = opts.json ? null : ora({ text: c.dim("Searching Floom..."), color: "yellow" }).start();
+    let result;
+    try {
+        result = await getJson(`${apiUrl}/api/v1/search?${params.toString()}`, "search skills");
+    }
+    finally {
+        spinner?.stop();
+    }
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`\n${symbols.dot}  ${c.bold("Search results")} ${c.dim(`for "${result.query}"`)}\n\n`);
+    if (result.skills.length === 0 && result.libraries.length === 0) {
+        process.stdout.write(`   ${c.dim("No matching public skills or libraries.")}\n\n`);
+        return;
+    }
+    if (result.skills.length > 0) {
+        process.stdout.write(` ${c.dim("Skills")}\n`);
+        for (const skill of result.skills)
+            process.stdout.write(`${formatSkillRow(skill)}\n`);
+        process.stdout.write("\n");
+    }
+    if (result.libraries.length > 0) {
+        process.stdout.write(` ${c.dim("Libraries")}\n`);
+        for (const library of result.libraries)
+            process.stdout.write(`${formatLibraryRow(library)}\n`);
+        process.stdout.write("\n");
+    }
+}

package/dist/setup.js

@@ -0,0 +1,158 @@
+import { access, lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { FloomError } from "./errors.js";
+import { c, symbols } from "./ui.js";
+const START_MARKER = "<!-- FLOOM SETUP START -->";
+const END_MARKER = "<!-- FLOOM SETUP END -->";
+const TARGETS = {
+    claude: { label: "Claude Code", filename: "CLAUDE.md" },
+    codex: { label: "Codex", filename: "AGENTS.md" },
+};
+export const FLOOM_AGENT_INSTRUCTIONS = `${START_MARKER}
+## Floom
+
+- Before recreating agent behavior from scratch, check Floom for reusable skills.
+- Search or inspect skills with \`floom search <query>\`, \`floom info <slug-or-url>\`, and \`floom list\`.
+- Add shared skills with \`floom add <slug-or-url>\`; public and unlisted links do not require a Floom account.
+- Use installed Markdown skills from the local skills folder when they match the task.
+- \`floom sync\`, \`floom watch\`, and \`@floomhq/floom-mcp-sync\` are preview paths for saved, published, and subscribed library skills; review conflicts before relying on synced output.
+${END_MARKER}`;
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readIfExists(path) {
+    if (!(await fileExists(path)))
+        return null;
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink()) {
+        throw new FloomError("Refusing to update an instruction file that is a symbolic link.", `Inspect ${path}, then pass a regular file path.`);
+    }
+    if (!stat.isFile()) {
+        throw new FloomError("Instruction target is not a file.", path);
+    }
+    return readFile(path, "utf8");
+}
+function parseTargetFromFile(file) {
+    const upper = file.toUpperCase();
+    if (upper.endsWith("CLAUDE.MD"))
+        return "claude";
+    if (upper.endsWith("AGENTS.MD"))
+        return "codex";
+    return undefined;
+}
+async function findUp(filename) {
+    let dir = process.cwd();
+    const home = resolve(homedir());
+    while (true) {
+        const candidate = join(dir, filename);
+        if (await fileExists(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (dir === parent || dir === home)
+            return null;
+        dir = parent;
+    }
+}
+async function detectTarget(opts) {
+    const agent = opts.target ?? (opts.file ? parseTargetFromFile(opts.file) : undefined);
+    if (opts.file) {
+        const resolvedAgent = agent ?? "codex";
+        return {
+            agent: resolvedAgent,
+            label: TARGETS[resolvedAgent].label,
+            path: resolve(process.cwd(), opts.file),
+        };
+    }
+    if (agent) {
+        const existing = await findUp(TARGETS[agent].filename);
+        return {
+            agent,
+            label: TARGETS[agent].label,
+            path: existing ?? resolve(process.cwd(), TARGETS[agent].filename),
+        };
+    }
+    const claude = await findUp(TARGETS.claude.filename);
+    const codex = await findUp(TARGETS.codex.filename);
+    if (claude && codex) {
+        throw new FloomError("Found both Claude Code and Codex instruction files.", "Pass `--target claude` or `--target codex`.");
+    }
+    if (claude)
+        return { agent: "claude", label: TARGETS.claude.label, path: claude };
+    if (codex)
+        return { agent: "codex", label: TARGETS.codex.label, path: codex };
+    throw new FloomError("No agent instruction file found.", "Run `floom setup --target claude --yes` or `floom setup --target codex --yes` from the repo root.");
+}
+function renderPreview(target, existing) {
+    const action = existing === null ? "create" : "append";
+    return [
+        "",
+        `${symbols.bullet}  Floom setup preview for ${c.bold(target.label)}`,
+        `   ${c.dim("Target:")} ${target.path}`,
+        `   ${c.dim("Action:")} ${action}`,
+        "",
+        FLOOM_AGENT_INSTRUCTIONS,
+        "",
+        `${c.dim("MCP setup guidance:")} run ${c.cyan("floom mcp")} to print local agent commands.`,
+        "",
+    ].join("\n");
+}
+async function confirmWrite(target, existing) {
+    if (!process.stdin.isTTY) {
+        throw new FloomError("Refusing to update agent instructions without confirmation in non-interactive mode.", "Pass `--yes` to write, or `--dry-run` to preview.");
+    }
+    const action = existing === null ? "Create" : "Append to";
+    const rl = createInterface({ input, output });
+    try {
+        const answer = (await rl.question(`   ${action} ${target.path} for ${target.label}? ${c.dim("(y/N)")} `)).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function setupAgent(opts) {
+    const target = await detectTarget(opts);
+    const existing = await readIfExists(target.path);
+    if (existing?.includes(START_MARKER) && existing.includes(END_MARKER)) {
+        process.stdout.write(`\n${symbols.ok}  Floom instructions already present in ${c.bold(target.path)}\n\n`);
+        return;
+    }
+    if (opts.dryRun) {
+        process.stdout.write(renderPreview(target, existing));
+        return;
+    }
+    if (!opts.yes) {
+        process.stdout.write(renderPreview(target, existing));
+        const ok = await confirmWrite(target, existing);
+        if (!ok) {
+            process.stdout.write(`\n${c.dim("Cancelled. Nothing was written.")}\n\n`);
+            return;
+        }
+    }
+    await mkdir(dirname(target.path), { recursive: true });
+    const next = existing === null
+        ? `${FLOOM_AGENT_INSTRUCTIONS}\n`
+        : `${existing.replace(/\s*$/, "")}\n\n${FLOOM_AGENT_INSTRUCTIONS}\n`;
+    if (existing === null) {
+        await writeFile(target.path, next, { encoding: "utf8", flag: "wx" }).catch((err) => {
+            if (err instanceof Error && "code" in err && err.code === "EEXIST") {
+                throw new FloomError("Instruction file appeared while setup was running.", "Re-run `floom setup` so Floom can inspect the current file before writing.");
+            }
+            throw err;
+        });
+    }
+    else {
+        await writeFile(target.path, next, "utf8");
+    }
+    process.stdout.write(`\n${symbols.ok}  Added Floom instructions to ${c.bold(target.path)}\n`);
+    process.stdout.write(`   ${c.dim("MCP setup guidance:")} ${c.cyan("floom mcp")}\n\n`);
+}

package/dist/sync.js

@@ -211,7 +211,7 @@ export async function sync(opts = {}) {
     const spinner = opts.spinner === false ? null : ora({ text: c.dim("Syncing skills..."), color: "yellow" }).start();
     let payload;
     try {
-        payload = await getJson(`${apiUrl}/api/me/skills`, "load your skills", cfg.accessToken);
+        payload = await getJson(`${apiUrl}/api/v1/me/skills`, "load your skills", cfg.accessToken);
     }
     catch (err) {
         spinner?.stop();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/floom",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Publish AI skills from your terminal. Share with a link.",
   "license": "MIT",
   "type": "module",