@floomhq/floom 1.0.21 → 1.0.23

package/README.md

@@ -4,7 +4,6 @@ Sync AI skills across agents and machines. Publish from your terminal, then add
 
 ```bash
 npm install -g @floomhq/floom
-floom init my-skill.md
 floom init my-skill
 floom login
 floom publish my-skill
@@ -24,7 +23,7 @@ The package is designed for `npx -y @floomhq/floom ...`. Global installs expose
 
 - `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 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>`, `--skill-version <label>`, and `--update [slug-or-url]`.
 - `npx -y @floomhq/floom share <slug>` — email-share one of your skills. Optional `--add <email>`, `--remove <email>`, and `--list`.
 - `npx -y @floomhq/floom list` — show your published skills. Optional `--json`.
 - `npx -y @floomhq/floom add <url-or-slug>` — fetch a skill into `~/.claude/skills/<slug>/SKILL.md` with supporting package files. Optional `--target claude|codex`, `--setup` to connect the agent, and `--force` to replace an existing local copy.
@@ -33,8 +32,8 @@ The package is designed for `npx -y @floomhq/floom ...`. Global installs expose
 - `npx -y @floomhq/floom setup` — add Floom usage guidance to `CLAUDE.md` or `AGENTS.md`. Optional `--target claude|codex`, `--dry-run`, `--yes`.
 - `npx -y @floomhq/floom connect` — alias for setup.
 - `npx -y @floomhq/floom mcp` — print MCP setup commands for supported agent CLIs.
-- `npx -y @floomhq/floom sync` — preview: pull your published, saved, and subscribed library skills into Claude or Codex. Optional `--target claude|codex`.
-- `npx -y @floomhq/floom watch` — preview: run sync repeatedly. Optional `--interval <seconds>`; minimum `10`.
+- `npx -y @floomhq/floom sync` — pull your published, saved, and subscribed library skills into Claude or Codex. Optional `--target claude|codex`.
+- `npx -y @floomhq/floom watch` — run sync repeatedly. Optional `--interval <seconds>`; minimum `10`.
 - `npx -y @floomhq/floom library list` — list public starter libraries. Optional `--json`.
 - `npx -y @floomhq/floom library create <slug> --name <name>` — create a personal or starter library. Optional `--public` / `--private` / `--unlisted`.
 - `npx -y @floomhq/floom library add <library> <skill> [--folder <path>] [--tags a,b]` — add a skill to a library.
@@ -75,7 +74,7 @@ version: 0.1.0
 
 Override the API host with `FLOOM_API_URL` (defaults to `https://floom.dev`).
 
-`floom sync` and `floom watch` are v1 preview commands for published, saved, and subscribed library skills. They store a machine-local manifest at `~/.floom/sync-manifest.json`.
+`floom sync` and `floom watch` pull 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. Sync writes missing files only.
 Remote updates, existing untracked files, and locally edited tracked files are skipped as conflicts.
 Symlinks are never followed. To replace a local skill manually, run `floom add <url-or-slug> --force`.

package/dist/cli.js

@@ -83,7 +83,7 @@ function commandUsage() {
      ${c.cyan("scan")} ${c.dim("<path>")}        Check for secrets, injection, exfiltration
      ${c.cyan("publish")} ${c.dim("<path>")}     Scan, publish, and print a share link
                        ${c.dim("Flags: --public, --private, --type knowledge|instruction|workflow|skill")}
-                       ${c.dim("       --skill-version <label>")}
+                       ${c.dim("       --skill-version <label>, --update [slug-or-url]")}
      ${c.cyan("share")} ${c.dim("<slug>")}       Email-share one of your skills
                        ${c.dim("Flags: --add <email>, --remove <email>, --list")}
 
@@ -107,9 +107,9 @@ function commandUsage() {
                        ${c.dim("Alias: lib")}
      ${c.cyan("move")} ${c.dim("<slug> --folder <path>")}  Place a saved skill in a local folder
      ${c.cyan("mcp")}                Print optional MCP setup guidance
-     ${c.cyan("sync")}               Preview pull of published, saved, and library skills
+     ${c.cyan("sync")}               Pull published, saved, and library skills
                        ${c.dim("Flags: --target claude|codex (default: claude)")}
-     ${c.cyan("watch")}              Preview polling sync loop
+     ${c.cyan("watch")}              Run a polling sync loop
                        ${c.dim("Flags: --target claude|codex (default: claude), --interval <seconds>")}
      ${c.cyan("agent-prompt")}       Print the one-line agent instruction
                        ${c.dim("Alias: paste")}
@@ -179,6 +179,7 @@ ${c.bold("Flags")}
   ${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>")}
+  ${c.cyan("--update")} ${c.dim("[slug-or-url]")}
 `,
         init: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} init`)} ${c.dim("[path] [flags]")}
 
@@ -189,14 +190,14 @@ ${c.bold("Flags")}
 `,
         sync: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} sync`)} ${c.dim("[flags]")}
 
-Preview pull of published, saved, and subscribed library skills.
+Pull 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.
+Poll sync on an interval.
 
 ${c.bold("Flags")}
   ${c.cyan("--target")} ${c.dim("claude|codex")}   Watch Claude Code or Codex skills. Default: claude.
@@ -292,8 +293,18 @@ function parseFlags(argv) {
             visibilityFlag = nextVisibility;
             out.visibility = nextVisibility;
         }
-        else if (a === "--update") {
-            throw new FloomError(V1_NOT_AVAILABLE, `\`${CLI_COMMAND} publish --update\` is planned for a later Floom release.`);
+        else if (a === "--update" || a.startsWith("--update=")) {
+            out.update = true;
+            if (a.startsWith("--update=")) {
+                out.updateSlug = a.slice("--update=".length);
+            }
+            else {
+                const next = argv[i + 1];
+                if (out.rest.length > 0 && next && !next.startsWith("--")) {
+                    out.updateSlug = next;
+                    i += 1;
+                }
+            }
         }
         else if (a === "--share" || a.startsWith("--share=")) {
             throw new FloomError(V1_NOT_AVAILABLE, `\`${CLI_COMMAND} publish --share\` is planned for a later Floom release.`);
@@ -905,6 +916,7 @@ async function main() {
                     file,
                     visibility: flags.visibility,
                     update: flags.update,
+                    ...(flags.updateSlug ? { updateSlug: flags.updateSlug } : {}),
                     ...(flags.assetType ? { assetType: flags.assetType } : {}),
                     ...(flags.installsAs ? { installsAs: flags.installsAs } : {}),
                     ...(flags.version ? { version: flags.version } : {}),

package/dist/config.js

@@ -5,6 +5,7 @@ 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";
+const REFRESH_SKEW_SECONDS = 5 * 60;
 export function getApiUrl() {
     return process.env.FLOOM_API_URL?.replace(/\/$/, "") ?? DEFAULT_API_URL;
 }
@@ -14,7 +15,7 @@ export function resolveApiUrl(cfg) {
 export function getWebUrl() {
     return process.env.FLOOM_WEB_URL?.replace(/\/$/, "") ?? DEFAULT_WEB_URL;
 }
-export async function readConfig() {
+export async function readRawConfig() {
     try {
         const buf = await readFile(process.env.FLOOM_CONFIG_PATH ?? CONFIG_PATH, "utf8");
         const parsed = JSON.parse(buf);
@@ -28,6 +29,15 @@ export async function readConfig() {
         throw e;
     }
 }
+export async function readConfig() {
+    const cfg = await readRawConfig();
+    if (!cfg)
+        return null;
+    if (!needsRefresh(cfg))
+        return cfg;
+    const refreshed = await refreshConfig(cfg);
+    return refreshed;
+}
 export async function writeConfig(cfg) {
     const targetPath = process.env.FLOOM_CONFIG_PATH ?? CONFIG_PATH;
     const targetDir = dirname(targetPath);
@@ -45,3 +55,43 @@ export async function deleteConfig() {
             throw e;
     }
 }
+export function needsRefresh(cfg) {
+    return !Number.isFinite(cfg.expiresAt) || cfg.expiresAt <= Math.floor(Date.now() / 1000) + REFRESH_SKEW_SECONDS;
+}
+export async function refreshConfig(cfg) {
+    const apiUrl = resolveApiUrl(cfg);
+    let res;
+    try {
+        res = await fetch(`${apiUrl}/api/v1/auth/refresh`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ refresh_token: cfg.refreshToken }),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!res.ok)
+        return null;
+    let data;
+    try {
+        data = (await res.json());
+    }
+    catch {
+        return null;
+    }
+    if (!data.access_token || !data.refresh_token)
+        return null;
+    const expiresAt = Number.isFinite(data.expires_at)
+        ? Number(data.expires_at)
+        : Math.floor(Date.now() / 1000) + (Number.isFinite(data.expires_in) ? Number(data.expires_in) : 3600);
+    const refreshed = {
+        apiUrl,
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt,
+        email: data.email ?? cfg.email ?? null,
+    };
+    await writeConfig(refreshed);
+    return refreshed;
+}

package/dist/doctor.js

@@ -4,7 +4,7 @@ import { delimiter } from "node:path";
 import { join } from "node:path";
 import { stat, readFile, access, readdir, constants, realpath } from "node:fs/promises";
 import { promisify } from "node:util";
-import { readConfig, CONFIG_PATH, resolveApiUrl } from "./config.js";
+import { needsRefresh, readConfig, readRawConfig, CONFIG_PATH, resolveApiUrl } from "./config.js";
 import { floomFetch } from "./lib/api.js";
 import { c, symbols } from "./ui.js";
 import { CLI_VERSION, compareSemverish, formatVersionLabel } from "./version.js";
@@ -17,14 +17,25 @@ function statusBadge(s) {
     return c.red(symbols.fail);
 }
 async function checkAuth() {
-    const cfg = await readConfig();
-    if (!cfg) {
+    const raw = await readRawConfig();
+    if (!raw) {
         return {
             name: "Auth",
             status: "ok",
             detail: "Receiver mode ready. Sign in only when publishing or listing your own skills.",
         };
     }
+    const expired = raw.expiresAt <= Math.floor(Date.now() / 1000);
+    const expiresSoon = needsRefresh(raw);
+    const cfg = await readConfig();
+    if (!cfg) {
+        return {
+            name: "Auth",
+            status: "fail",
+            detail: expired ? "Token expired and refresh failed." : "Token refresh failed.",
+            hint: "Run `npx -y @floomhq/floom logout && npx -y @floomhq/floom login` to sign in again.",
+        };
+    }
     const apiUrl = resolveApiUrl(cfg);
     try {
         const res = await floomFetch(`${apiUrl}/api/me`, "check authentication", {
@@ -48,10 +59,11 @@ async function checkAuth() {
             };
         }
         const data = (await res.json());
+        const suffix = expiresSoon ? " (token refreshed)" : "";
         return {
             name: "Auth",
             status: "ok",
-            detail: data.email ? `Signed in as ${data.email}` : "Signed in",
+            detail: data.email ? `Signed in as ${data.email}${suffix}` : `Signed in${suffix}`,
         };
     }
     catch (err) {

package/dist/errors.js

@@ -20,7 +20,7 @@ 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)) {
+        if (/fetch|inspect|add|install|show|get|search|list|info|load/i.test(action)) {
             return new FloomError("Skill not found.", "Check the link or slug, then try again.");
         }
         return new FloomError("Skill not found.", "Run `npx -y @floomhq/floom publish <path>` to create a new one.");

package/dist/login.js

@@ -174,10 +174,11 @@ function waitForCallback(port, provider) {
         });
         server.listen(port, "127.0.0.1", () => {
             const target = `${apiUrl}/auth/cli?port=${port}&provider=${provider}&state=${encodeURIComponent(state)}`;
+            process.stdout.write(c.dim("If the browser does not open, copy this URL:") +
+                `\n${c.cyan(target)}\n\n`);
             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`) +
-                    c.dim(`Open this URL manually: ${target}\n`));
+                process.stdout.write(c.yellow(`Could not auto-open browser (${msg}).\n`));
             });
         });
     });

package/dist/mcp.js

@@ -4,7 +4,7 @@ export function printMcpSetup() {
 - Use Floom skills from the local Floom skills folder when they match the task.
 - To install a shared skill, run \`npx -y @floomhq/floom add <slug-or-url> --target claude\` or \`npx -y @floomhq/floom add <slug-or-url> --target codex\`.
 - To find reusable behavior, run \`npx -y @floomhq/floom search <query>\`.
-- MCP sync is optional preview behavior; use it only while the Floom MCP server is configured and running.`;
+- MCP sync is optional; use it 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`);

package/dist/publish.js

@@ -19,6 +19,7 @@ const INSTALL_TARGETS = new Set([
     "other",
 ]);
 const VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+const SLUG_RE = /^[A-Za-z0-9_-]{1,128}$/;
 function parseFrontmatter(input) {
     const trimmed = input.replace(/^/, "");
     if (!trimmed.startsWith("---"))
@@ -106,6 +107,33 @@ function parseVersion(value, source) {
         return value;
     throw new FloomError(`Invalid ${source}: ${value}`, "Use 1-64 characters: letters, numbers, dots, underscores, plus, or hyphen.");
 }
+function slugFromInput(input) {
+    const trimmed = input.trim();
+    try {
+        const url = new URL(trimmed);
+        const last = url.pathname.split("/").filter(Boolean).at(-1) ?? "";
+        return last.replace(/\.(md|json)$/i, "");
+    }
+    catch {
+        return trimmed.replace(/\.(md|json)$/i, "");
+    }
+}
+function inferSlugFromPath(path) {
+    return path
+        .replace(/[\\/]+$/, "")
+        .split(/[\\/]+/)
+        .filter(Boolean)
+        .at(-1)
+        ?.replace(/\.md$/i, "") ?? "";
+}
+function resolveUpdateSlug(opts, meta) {
+    const raw = opts.updateSlug ?? meta.slug ?? inferSlugFromPath(opts.file);
+    const slug = slugFromInput(raw);
+    if (!SLUG_RE.test(slug)) {
+        throw new FloomError("Missing or invalid update slug.", "Use `npx -y @floomhq/floom publish <path> --update <slug-or-url>`, or add `slug:` to SKILL.md frontmatter.");
+    }
+    return slug;
+}
 export async function publish(opts) {
     const skillPackage = await readSkillPackage(opts.file);
     const securityFailures = [
@@ -136,11 +164,8 @@ export async function publish(opts) {
     if (!cfg) {
         throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     }
-    // Later version: detect already-published when --update is missing.
-    // The current API does not return a duplicate-skill code, so we leave
-    // the actual dedupe to the server and surface the friendly hint on 409.
     const spinner = ora({
-        text: c.dim(`Publishing ${meta.title ? c.bold(meta.title) : opts.file}...`),
+        text: c.dim(`${opts.update ? "Updating" : "Publishing"} ${meta.title ? c.bold(meta.title) : opts.file}...`),
         color: "yellow",
     }).start();
     const apiUrl = resolveApiUrl(cfg);
@@ -156,12 +181,13 @@ export async function publish(opts) {
         original_filename: skillPackage.originalFilename,
         published_via: "cli",
         ...(opts.sharedWithEmails ? { shared_with_emails: opts.sharedWithEmails } : {}),
-        ...(skillPackage.packageFiles.length > 0 ? { package_files: skillPackage.packageFiles } : {}),
+        ...(opts.update || skillPackage.packageFiles.length > 0 ? { package_files: skillPackage.packageFiles } : {}),
     };
     let res;
     try {
-        res = await floomFetch(`${apiUrl}/api/skills`, "publish your skill", {
-            method: "POST",
+        const updateSlug = opts.update ? resolveUpdateSlug(opts, meta) : null;
+        res = await floomFetch(updateSlug ? `${apiUrl}/api/v1/skills/${encodeURIComponent(updateSlug)}` : `${apiUrl}/api/skills`, updateSlug ? "update your skill" : "publish your skill", {
+            method: updateSlug ? "PATCH" : "POST",
             token: cfg.accessToken,
             checkOk: false,
             body,
@@ -173,11 +199,11 @@ export async function publish(opts) {
     }
     if (res.status === 409) {
         spinner.stop();
-        throw new FloomError("Skill already published.", "Use `--update` to publish a new version (coming in a future release).");
+        throw new FloomError("Skill already published.", "Use `--update <slug-or-url>` to publish a new version of an existing skill.");
     }
     if (!res.ok) {
         spinner.stop();
-        throw friendlyHttp(res.status, "publish your skill");
+        throw friendlyHttp(res.status, opts.update ? "update your skill" : "publish your skill");
     }
     const data = (await res.json());
     // Build a humans-friendly URL: strip the trailing `.md` if the API returned one.
@@ -188,7 +214,7 @@ export async function publish(opts) {
     spinner.stop();
     const versionTag = version ? c.dim(` (${formatVersionLabel(version)})`) : "";
     const titleLabel = data.title ? `"${data.title}"` : opts.file;
-    process.stdout.write(`\n${symbols.ok}  Published ${c.bold(titleLabel)}${versionTag}\n\n`);
+    process.stdout.write(`\n${symbols.ok}  ${opts.update ? "Updated" : "Published"} ${c.bold(titleLabel)}${versionTag}\n\n`);
     process.stdout.write(`   ${c.cyan(humanUrl)}\n\n`);
     if (data.visibility === "shared" && data.shared_with_emails?.length) {
         process.stdout.write(`   ${c.dim(`Shared with ${data.shared_with_emails.join(", ")}`)}\n\n`);

package/dist/setup.js

@@ -16,14 +16,16 @@ function floomAgentInstructions(target) {
     const addCommand = target === "codex"
         ? `${CLI_COMMAND} add <slug-or-url> --target codex`
         : `${CLI_COMMAND} add <slug-or-url> --target claude`;
+    const localSkillsDir = target === "codex" ? "~/.codex/skills" : "~/.claude/skills";
     return `${START_MARKER}
-## Floom
+## Floom Skills
 
-- Before recreating agent behavior from scratch, check Floom for reusable skills.
-- Search or inspect skills with \`${CLI_COMMAND} search <query>\`, \`${CLI_COMMAND} info <slug-or-url>\`, and \`${CLI_COMMAND} list\`.
+- Use Floom skills when they fit the task. Search local skills before recreating behavior from scratch.
+- Local skills live in \`${localSkillsDir}\`.
 - Add shared skills with \`${addCommand}\`; public and unlisted links do not require a Floom account.
-- Use installed Markdown skills from the local skills folder when they match the task.
-- \`${CLI_COMMAND} sync\`, \`${CLI_COMMAND} watch\`, and \`@floomhq/floom-mcp-sync\` are preview paths for saved, published, and subscribed library skills; review conflicts before relying on synced output.
+- Search or inspect skills with \`${CLI_COMMAND} search <query>\` and \`${CLI_COMMAND} info <slug-or-url>\`.
+- If Floom MCP is available, use it for compact skill search/status and load only the specific skill needed.
+- Do not publish, sync, or subscribe without user approval.
 ${END_MARKER}`;
 }
 async function fileExists(path) {

package/dist/sync.js

@@ -298,7 +298,7 @@ export async function sync(opts = {}) {
             }
             for (const skill of payload.skills)
                 validateSyncSkillShape(skill);
-            // Version 1 preview syncs published, saved, and subscribed library skills.
+            // Version 1 syncs published, saved, and subscribed library skills.
             const all = dedupeSyncSkills(payload.skills);
             const seen = new Set();
             let unchanged = 0;

package/package.json

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