@floomhq/floom 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Floom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @floomhq/floom
+
+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 login
+floom publish my-skill.md
+floom add awesome-skill
+floom 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.
+
+## Commands
+
+- `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>`.
+- `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 sync` — preview: pull your own Floom-published skills into `~/.claude/skills/`.
+- `floom watch` — preview: run `floom sync` repeatedly. Optional `--interval <seconds>`; minimum `10`.
+- `floom delete <url-or-slug>` — delete one of your published skills. Optional `--yes`.
+- `floom doctor` — diagnose your Floom setup.
+- `floom whoami` — show the signed-in account.
+- `floom logout` — delete local credentials.
+
+## Skill format
+
+Optional YAML-ish frontmatter (`title`, `description`, `version`), then freeform Markdown.
+
+```markdown
+---
+title: Write a LinkedIn post
+description: Yurii-level value density
+version: 0.1.0
+---
+
+# Instructions
+- ...
+```
+
+## Configuration
+
+Override the API host with `FLOOM_API_URL` (defaults to `https://floom.dev`).
+
+`floom sync` and `floom watch` are Version 1 preview commands for your own published 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.

package/bin/floom.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/dist/cli.js

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+import updateNotifier from "update-notifier";
+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 { list } from "./list.js";
+import { install } from "./install.js";
+import { info } from "./info.js";
+import { deleteSkill } from "./delete.js";
+import { doctor } from "./doctor.js";
+import { sync } from "./sync.js";
+import { c, symbols } from "./ui.js";
+import { printError, FloomError } from "./errors.js";
+const VERSION = "1.0.0";
+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.bold("Share AI agent skills with a link.")}
+ ${c.dim("Publish knowledge, instructions, and workflows from your terminal.")}
+
+ ${c.bold("Usage")}
+   ${c.cyan("floom")} ${c.dim("<command> [options]")}
+
+ ${c.bold("Start Here")}
+   ${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.bold("Commands")}
+   ${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.dim("Create")}
+     ${c.cyan("init")} ${c.dim("[file.md]")}                Create a starter skill file
+     ${c.cyan("publish")} ${c.dim("<file.md>")}             Upload Markdown and print a URL
+
+   ${c.dim("Publish Flags")}
+     ${c.dim("--public | --private | --unlisted")}        ${c.dim("Set link visibility")}
+     ${c.dim("--type <kind>")}                            ${c.dim("knowledge | instruction | workflow | skill")}
+     ${c.dim("--installs-as <target>")}                   ${c.dim("Set install target metadata")}
+       ${c.dim("claude_skill | memory | rule | codex_instruction")}
+     ${c.dim("--version <label>")}                        ${c.dim("Attach a human version label")}
+
+   ${c.dim("Account")}
+     ${c.cyan("login")}                         Sign in with Google
+     ${c.cyan("list")}                          List your published skills ${c.dim("[--json]")}
+     ${c.cyan("delete")} ${c.dim("<url-or-slug>")}          Delete one of your skills ${c.dim("[--yes]")}
+     ${c.cyan("whoami")}                        Show the signed-in account
+     ${c.cyan("logout")}                        Delete local credentials
+
+   ${c.dim("System")}
+     ${c.cyan("sync")}                          Preview: pull your own published skills
+     ${c.cyan("watch")}                         Preview: poll your own published skills ${c.dim("[--interval <seconds>, min 10]")}
+     ${c.cyan("doctor")}                        Diagnose auth, API, and local setup
+     ${c.cyan("--help")}                        Show this help
+     ${c.cyan("--version")}                     Show version
+
+ ${c.bold("Env")}
+   ${c.cyan("FLOOM_API_URL")}                   Override the API host
+
+ ${c.bold("Links")}
+   ${c.dim("Docs")}     https://floom.dev
+   ${c.dim("Source")}   https://github.com/floomhq/floom
+`;
+    process.stdout.write(out);
+}
+const ASSET_TYPES = new Set(["knowledge", "instruction", "workflow", "skill"]);
+const INSTALL_TARGETS = new Set([
+    "claude_skill",
+    "memory",
+    "rule",
+    "codex_instruction",
+    "opencode_instruction",
+    "cursor_rule",
+    "other",
+]);
+const VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+function readFlagValue(argv, index, flag) {
+    const current = argv[index] ?? "";
+    if (current.startsWith(`${flag}=`))
+        return { value: current.slice(flag.length + 1), nextIndex: index };
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new FloomError(`Missing value for ${flag}.`);
+    return { value, nextIndex: index + 1 };
+}
+function parseFlags(argv) {
+    const out = { visibility: "unlisted", update: false, rest: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--public")
+            out.visibility = "public";
+        else if (a === "--private")
+            out.visibility = "private";
+        else if (a === "--unlisted")
+            out.visibility = "unlisted";
+        else if (a === "--update") {
+            throw new FloomError(V1_NOT_AVAILABLE, "`floom publish --update` is planned for a later Floom release.");
+        }
+        else if (a === "--share" || a.startsWith("--share=")) {
+            throw new FloomError(V1_NOT_AVAILABLE, "`floom publish --share` is planned for a later Floom release.");
+        }
+        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.assetType = value;
+            i = nextIndex;
+        }
+        else if (a === "--installs-as" || a.startsWith("--installs-as=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--installs-as");
+            if (!INSTALL_TARGETS.has(value)) {
+                throw new FloomError(`Invalid --installs-as: ${value}`, "Use one of: claude_skill, memory, rule, codex_instruction, opencode_instruction, cursor_rule, other.");
+            }
+            out.installsAs = value;
+            i = nextIndex;
+        }
+        else if (a === "--version" || a.startsWith("--version=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--version");
+            if (!VERSION_RE.test(value)) {
+                throw new FloomError(`Invalid --version: ${value}`, "Use 1-64 characters: letters, numbers, dots, underscores, plus, or hyphen.");
+            }
+            out.version = value;
+            i = nextIndex;
+        }
+        else
+            out.rest.push(a);
+    }
+    return out;
+}
+function parseListFlags(argv) {
+    const out = { json: false };
+    for (const a of argv) {
+        if (a === "--json")
+            out.json = true;
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom list --help` for usage.");
+        }
+    }
+    return out;
+}
+function parseInfoFlags(argv) {
+    const out = { json: false };
+    for (const a of argv) {
+        if (a === "--json")
+            out.json = true;
+        else if (a.startsWith("--"))
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom info <slug> --json`.");
+        else if (!out.slug)
+            out.slug = a;
+    }
+    return out;
+}
+function parseDeleteFlags(argv) {
+    const out = { yes: false };
+    for (const a of argv) {
+        if (a === "--yes" || a === "-y")
+            out.yes = true;
+        else if (a.startsWith("--"))
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom delete <slug> --yes`.");
+        else if (!out.slug)
+            out.slug = a;
+    }
+    return out;
+}
+function parseWatchFlags(argv) {
+    const out = { intervalSeconds: 60 };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--interval" || a.startsWith("--interval=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--interval");
+            const interval = Number(value);
+            if (!Number.isInteger(interval) || interval < 10) {
+                throw new FloomError("Invalid --interval.", "Use an integer number of seconds, minimum 10.");
+            }
+            out.intervalSeconds = interval;
+            i = nextIndex;
+        }
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom watch --interval 60`.");
+        }
+        else {
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom watch --interval 60`.");
+        }
+    }
+    return out;
+}
+function notAvailable(feature) {
+    throw new FloomError(V1_NOT_AVAILABLE, `${feature} is planned for a later Floom release.`);
+}
+function sleep(ms, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+async function watch(intervalSeconds) {
+    const controller = new AbortController();
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        controller.abort();
+        process.stdout.write(`\n${symbols.bullet}  Stopping floom watch\n`);
+        process.exit(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    process.stdout.write(`${symbols.bullet}  Watching Floom sync every ${intervalSeconds}s. Press Ctrl-C to stop.\n`);
+    while (!controller.signal.aborted) {
+        await sync({ spinner: false, quietUnchanged: true });
+        await sleep(intervalSeconds * 1000, controller.signal);
+    }
+}
+async function main() {
+    const [, , cmd, ...rest] = process.argv;
+    // Update notifier — runs in background, prints at process exit if a newer
+    // version is available. Disabled in CI / non-TTY by default.
+    if (cmd !== "watch") {
+        try {
+            updateNotifier({ pkg: PKG, updateCheckInterval: 1000 * 60 * 60 * 24 }).notify({
+                defer: true,
+                isGlobal: true,
+                message: `${symbols.bullet}  ${c.bold("floom")} v{latestVersion} available — run \`npm i -g {packageName}\` to update.`,
+            });
+        }
+        catch {
+            // never block on update-notifier
+        }
+    }
+    // Subcommand --help: any rest arg = --help/-h/help → show top-level usage.
+    // Subcommands are simple enough that one help screen is fine for Version 1.
+    if (rest.includes("--help") || rest.includes("-h") || rest.includes("help")) {
+        usage();
+        return;
+    }
+    try {
+        switch (cmd) {
+            case undefined:
+            case "--help":
+            case "-h":
+            case "help":
+                usage();
+                return;
+            case "--version":
+            case "-v":
+                process.stdout.write(`${VERSION}\n`);
+                return;
+            case "login":
+                await login();
+                return;
+            case "logout":
+                await deleteConfig();
+                process.stdout.write(`\n${symbols.ok}  Signed out\n\n`);
+                return;
+            case "whoami":
+                await whoami();
+                return;
+            case "init": {
+                const file = rest[0];
+                await init(file);
+                return;
+            }
+            case "publish": {
+                const flags = parseFlags(rest);
+                const file = flags.rest[0];
+                if (!file) {
+                    throw new FloomError("Missing file argument.", "Try: `floom publish skill.md`");
+                }
+                await publish({
+                    file,
+                    visibility: flags.visibility,
+                    update: flags.update,
+                    ...(flags.assetType ? { assetType: flags.assetType } : {}),
+                    ...(flags.installsAs ? { installsAs: flags.installsAs } : {}),
+                    ...(flags.version ? { version: flags.version } : {}),
+                });
+                return;
+            }
+            case "share":
+                notAvailable("`floom share`");
+            case "list": {
+                const flags = parseListFlags(rest);
+                await list(flags);
+                return;
+            }
+            case "info":
+                {
+                    const flags = parseInfoFlags(rest);
+                    await info({ slug: flags.slug ?? "", json: flags.json });
+                }
+                return;
+            case "add":
+            case "install": {
+                const slug = rest.find((a) => !a.startsWith("--"));
+                if (!slug) {
+                    throw new FloomError("Missing skill slug.", "Try: `floom add <url-or-slug>`");
+                }
+                await install(slug);
+                return;
+            }
+            case "sync":
+                await sync();
+                return;
+            case "watch": {
+                const flags = parseWatchFlags(rest);
+                await watch(flags.intervalSeconds);
+                return;
+            }
+            case "delete":
+            case "rm": {
+                const flags = parseDeleteFlags(rest);
+                await deleteSkill({ slug: flags.slug ?? "", yes: flags.yes });
+                return;
+            }
+            case "library":
+            case "lib":
+                notAvailable("`floom library`");
+            case "move":
+                notAvailable("`floom move`");
+            case "mcp":
+                notAvailable("`floom mcp setup`");
+            case "doctor":
+                await doctor();
+                return;
+            default:
+                throw new FloomError(`Unknown command: ${cmd}`, "Run `floom --help` to see available commands.");
+        }
+    }
+    catch (e) {
+        printError(e);
+        process.exit(1);
+    }
+}
+void main();

package/dist/config.js

@@ -0,0 +1,44 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { mkdir, readFile, writeFile, chmod, unlink } from "node:fs/promises";
+export const CONFIG_DIR = join(homedir(), ".floom");
+export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+export const DEFAULT_API_URL = "https://floom.dev";
+export const DEFAULT_WEB_URL = "https://floom.dev";
+export function getApiUrl() {
+    return process.env.FLOOM_API_URL?.replace(/\/$/, "") ?? DEFAULT_API_URL;
+}
+export function getWebUrl() {
+    return process.env.FLOOM_WEB_URL?.replace(/\/$/, "") ?? DEFAULT_WEB_URL;
+}
+export async function readConfig() {
+    try {
+        const buf = await readFile(process.env.FLOOM_CONFIG_PATH ?? CONFIG_PATH, "utf8");
+        const parsed = JSON.parse(buf);
+        if (!parsed.accessToken || !parsed.refreshToken)
+            return null;
+        return parsed;
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw e;
+    }
+}
+export async function writeConfig(cfg) {
+    const targetPath = process.env.FLOOM_CONFIG_PATH ?? CONFIG_PATH;
+    const targetDir = dirname(targetPath);
+    await mkdir(targetDir, { recursive: true, mode: 0o700 });
+    await writeFile(targetPath, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+    // belt-and-suspenders: set perms in case the file already existed
+    await chmod(targetPath, 0o600);
+}
+export async function deleteConfig() {
+    try {
+        await unlink(process.env.FLOOM_CONFIG_PATH ?? CONFIG_PATH);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+}

package/dist/delete.js

@@ -0,0 +1,55 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import ora from "ora";
+import { getApiUrl, readConfig } from "./config.js";
+import { deleteRequest } from "./lib/api.js";
+import { c, symbols } from "./ui.js";
+import { FloomError } from "./errors.js";
+function slugFromInput(s) {
+    const trimmed = s.trim();
+    try {
+        const url = new URL(trimmed);
+        return (url.pathname.split("/").filter(Boolean).at(-1) ?? "").replace(/\.(md|json)$/i, "");
+    }
+    catch {
+        return trimmed.replace(/\.(md|json)$/i, "");
+    }
+}
+async function confirm(question) {
+    if (!process.stdin.isTTY) {
+        throw new FloomError("Refusing to delete without confirmation in non-interactive mode.", "Pass `--yes` to skip the prompt.");
+    }
+    const rl = createInterface({ input, output });
+    try {
+        const answer = (await rl.question(`   ${question} (y/N) `)).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function deleteSkill(opts) {
+    const slug = slugFromInput(opts.slug);
+    if (!slug)
+        throw new FloomError("Missing skill slug.", "Try: `floom delete <slug>`");
+    const cfg = await readConfig();
+    if (!cfg)
+        throw new FloomError("Not signed in.", "Run `floom login` first.");
+    if (!opts.yes) {
+        process.stdout.write(`\n${symbols.bullet}  About to delete ${c.bold(slug)}.\n`);
+        const ok = await confirm(`Delete ${c.bold(slug)}? Cannot be undone in CLI.`);
+        if (!ok) {
+            process.stdout.write(`\n${c.dim("Cancelled.")}\n\n`);
+            return;
+        }
+    }
+    const apiUrl = cfg.apiUrl ?? getApiUrl();
+    const spinner = ora({ text: c.dim(`Deleting ${slug}...`), color: "yellow" }).start();
+    try {
+        await deleteRequest(`${apiUrl}/api/v1/skills/${encodeURIComponent(slug)}`, "delete skill", cfg.accessToken);
+    }
+    finally {
+        spinner.stop();
+    }
+    process.stdout.write(`\n${symbols.ok}  Deleted ${c.bold(slug)}\n\n`);
+}