@floomhq/floom 1.0.25 → 1.0.27

package/dist/package.js

@@ -6,40 +6,117 @@ import { promisify } from "node:util";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { FloomError } from "./errors.js";
 const ALLOWED_PACKAGE_DIRS = new Set([
+    ".github",
     "agents",
     "assets",
+    "bin",
     "canvas-fonts",
     "checks",
+    "claude",
+    "codex",
+    "contrib",
     "core",
+    "cursor",
+    "design",
+    "docs",
     "evidence",
     "examples",
+    "extension",
     "helpers",
+    "hosts",
+    "kimi",
+    "lib",
+    "migrations",
+    "model-overlays",
+    "openclaw",
+    "opencode",
     "reference",
     "references",
-    "schemas",
+    "remotion-starter",
     "scripts",
-    "spreadsheets",
+    "sdk",
+    "schemas",
+    "src",
+    "specialists",
+    "supabase",
     "templates",
+    "test",
     "tests",
     "themes",
+    "vendor",
 ]);
 const ALLOWED_PACKAGE_ROOT_FILES = new Set(["SKILL.md", ".gitignore"]);
-const IGNORED_PACKAGE_ROOT_ENTRIES = new Set([".DS_Store", ".git", ".pytest_cache"]);
-const ALLOWED_PACKAGE_ROOT_EXTENSIONS = new Set([
+const ALLOWED_PACKAGE_ROOT_SUPPORT_FILES = new Set([
     ".env.example",
-    ".js",
-    ".json",
-    ".md",
-    ".py",
-    ".sh",
-    ".toml",
-    ".ts",
-    ".txt",
-    ".yaml",
-    ".yml",
+    "ACKNOWLEDGEMENTS.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "LICENSE.md",
+    "LICENSE.txt",
+    "README.md",
+    "AGENTS.md",
+    "ARCHITECTURE.md",
+    "BROWSER.md",
+    "CLAUDE.md",
+    "CONTRIBUTING.md",
+    "DESIGN.md",
+    "ETHOS.md",
+    "PLAN-snapshot-dropdown-interactive.md",
+    "REMOTION_PROTOCOL.md",
+    "SKILL.md.tmpl",
+    "TODOS.md",
+    "TODOS-format.md",
+    "USING_GBRAIN_WITH_GSTACK.md",
+    "VERSION",
+    ".gitlab-ci.yml",
+    "actionlint.yaml",
+    "bun.lock",
+    "checklist.md",
+    "conductor.json",
+    "design-checklist.md",
+    "dx-hall-of-fame.md",
+    "editing.md",
+    "forms.md",
+    "instructions.md",
+    "nanobanana.py",
+    "package.json",
+    "plan.md",
+    "pptxgenjs.md",
+    "reference.md",
+    "requirements.txt",
+    "greptile-triage.md",
+    "setup",
+    "skill.md",
+    "slop-scan.config.json",
+    "style_guidelines.md",
+    "theme-showcase.pdf",
+]);
+const GENERATED_PACKAGE_DIRS = new Set([
+    ".agents",
+    ".cache",
+    ".cursor",
+    ".factory",
+    ".gbrain",
+    ".git",
+    ".hermes",
+    ".kiro",
+    ".next",
+    ".openclaw",
+    ".opencode",
+    ".pytest_cache",
+    ".slate",
+    "__pycache__",
+    "build",
+    "coverage",
+    "dist",
+    "fixtures",
+    "node_modules",
+    "out",
 ]);
-const PACKAGE_FILE_LIMIT = 100;
-const PACKAGE_TOTAL_BYTES_LIMIT = 1_000_000;
+const GENERATED_PACKAGE_FILES = new Set([".DS_Store"]);
+const GENERATED_PACKAGE_FILE_SUFFIXES = [".icns", ".log", ".mov", ".mp3", ".mp4", ".pyc", ".pyo", ".wav", ".webm"];
+const PACKAGE_FILE_LIMIT = 1000;
+const PACKAGE_TOTAL_BYTES_LIMIT = 8_000_000;
 const PACKAGE_FILE_BYTES_LIMIT = 500_000;
 const PACKAGE_SEGMENT_RE = /^[A-Za-z0-9._-]{1,128}$/;
 const BASE64_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
@@ -126,40 +203,41 @@ async function collectPackageFiles(root) {
     const isIgnored = gitIgnoreChecker(root);
     const rootEntries = await readdir(root, { withFileTypes: true });
     for (const entry of rootEntries) {
-        if (await isIgnored(entry.name))
+        if (ALLOWED_PACKAGE_ROOT_FILES.has(entry.name) || ALLOWED_PACKAGE_DIRS.has(entry.name))
             continue;
-        if (IGNORED_PACKAGE_ROOT_ENTRIES.has(entry.name))
+        if (ALLOWED_PACKAGE_ROOT_SUPPORT_FILES.has(entry.name)) {
+            if (entry.isSymbolicLink())
+                continue;
+            if (!entry.isFile())
+                throw new FloomError(`Package path is not a regular file: ${entry.name}`);
             continue;
-        if (ALLOWED_PACKAGE_ROOT_FILES.has(entry.name))
+        }
+        if (isGeneratedPackageEntry(entry.name, entry.isDirectory()))
             continue;
-        if (entry.isDirectory() && ALLOWED_PACKAGE_DIRS.has(entry.name))
+        if (await isIgnored(entry.name))
             continue;
-        if (entry.isFile() && isAllowedRootPackageFile(entry.name)) {
-            const rel = entry.name;
-            validatePackageRelativePath(rel);
-            const fullPath = join(root, entry.name);
-            const stat = await lstat(fullPath);
-            if (files.length >= PACKAGE_FILE_LIMIT) {
-                throw new FloomError("Skill package has too many files.", "A skill package is capped at 100 supporting files.");
-            }
-            if (stat.size > PACKAGE_FILE_BYTES_LIMIT) {
-                throw new FloomError(`File too large: ${rel}`, "Each package file is capped at 500KB.");
-            }
-            totalBytes += stat.size;
-            ensurePackageSize(totalBytes);
-            const bytes = await readFile(fullPath);
-            files.push({
-                path: rel,
-                content_base64: bytes.toString("base64"),
-                encoding: "base64",
-                size_bytes: bytes.length,
-                sha256: sha256Bytes(bytes),
-            });
+        if (entry.isDirectory() && await isNestedSkillDir(join(root, entry.name)))
             continue;
-        }
-        const hint = `Move supporting files under one of: ${Array.from(ALLOWED_PACKAGE_DIRS).sort().join(", ")}.`;
+        if (entry.isSymbolicLink())
+            continue;
+        const hint = "Move supporting files under references/, examples/, scripts/, or assets/.";
         throw new FloomError(`Unsupported root package entry: ${entry.name}`, hint);
     }
+    for (const entry of rootEntries) {
+        if (!ALLOWED_PACKAGE_ROOT_SUPPORT_FILES.has(entry.name))
+            continue;
+        if (entry.isSymbolicLink())
+            continue;
+        const fullPath = join(root, entry.name);
+        if (await isIgnored(entry.name))
+            continue;
+        await collectFile(fullPath, entry.name, files, (size) => {
+            totalBytes += size;
+            if (totalBytes > PACKAGE_TOTAL_BYTES_LIMIT) {
+                throw new FloomError("Skill package is too large.", "A skill package is capped at 8MB total.");
+            }
+        });
+    }
     for (const dirName of ALLOWED_PACKAGE_DIRS) {
         const dirPath = join(root, dirName);
         let stat;
@@ -174,30 +252,23 @@ async function collectPackageFiles(root) {
         if (await isIgnored(dirName))
             continue;
         if (stat.isSymbolicLink())
-            throw new FloomError(`Package directory is a symbolic link: ${dirName}`);
+            continue;
         if (!stat.isDirectory())
             throw new FloomError(`Package entry must be a directory: ${dirName}`);
         await collectDir(root, dirPath, files, isIgnored, (size) => {
             totalBytes += size;
-            ensurePackageSize(totalBytes);
+            if (totalBytes > PACKAGE_TOTAL_BYTES_LIMIT) {
+                throw new FloomError("Skill package is too large.", "A skill package is capped at 8MB total.");
+            }
         });
     }
     return files.sort((a, b) => a.path.localeCompare(b.path));
 }
-function isAllowedRootPackageFile(name) {
-    if (name.startsWith(".") && name !== ".env.example")
-        return false;
-    const lower = name.toLowerCase();
-    return Array.from(ALLOWED_PACKAGE_ROOT_EXTENSIONS).some((ext) => lower.endsWith(ext));
-}
-function ensurePackageSize(totalBytes) {
-    if (totalBytes > PACKAGE_TOTAL_BYTES_LIMIT) {
-        throw new FloomError("Skill package is too large.", "A skill package is capped at 1MB total.");
-    }
-}
 async function collectDir(root, dir, files, isIgnored, addBytes) {
     const entries = await readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
+        if (isGeneratedPackageEntry(entry.name, entry.isDirectory()))
+            continue;
         if (!PACKAGE_SEGMENT_RE.test(entry.name)) {
             throw new FloomError(`Invalid package path segment: ${entry.name}`);
         }
@@ -206,35 +277,58 @@ async function collectDir(root, dir, files, isIgnored, addBytes) {
         if (await isIgnored(rel))
             continue;
         if (entry.isSymbolicLink())
-            throw new FloomError(`Package path is a symbolic link: ${rel}`);
+            continue;
         if (entry.isDirectory()) {
             await collectDir(root, fullPath, files, isIgnored, addBytes);
             continue;
         }
         if (!entry.isFile())
             throw new FloomError(`Package path is not a regular file: ${rel}`);
-        if (files.length >= PACKAGE_FILE_LIMIT) {
-            throw new FloomError("Skill package has too many files.", "A skill package is capped at 100 supporting files.");
-        }
-        const stat = await lstat(fullPath);
-        if (stat.isSymbolicLink())
-            throw new FloomError(`Package path is a symbolic link: ${rel}`);
-        if (!stat.isFile())
-            throw new FloomError(`Package path is not a regular file: ${rel}`);
-        if (stat.size > PACKAGE_FILE_BYTES_LIMIT) {
-            throw new FloomError(`File too large: ${rel}`, "Each package file is capped at 500KB.");
-        }
-        addBytes(stat.size);
-        const bytes = await readFile(fullPath);
-        files.push({
-            path: rel,
-            content_base64: bytes.toString("base64"),
-            encoding: "base64",
-            size_bytes: bytes.length,
-            sha256: sha256Bytes(bytes),
-        });
+        await collectFile(fullPath, rel, files, addBytes);
     }
 }
+async function isNestedSkillDir(path) {
+    try {
+        const stat = await lstat(join(path, "SKILL.md"));
+        return stat.isFile();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+async function collectFile(fullPath, rel, files, addBytes) {
+    const normalized = rel.split(sep).join("/");
+    validatePackageRelativePath(normalized);
+    if (files.length >= PACKAGE_FILE_LIMIT) {
+        throw new FloomError("Skill package has too many files.", "A skill package is capped at 100 supporting files.");
+    }
+    const stat = await lstat(fullPath);
+    if (stat.isSymbolicLink())
+        throw new FloomError(`Package path is a symbolic link: ${normalized}`);
+    if (!stat.isFile())
+        throw new FloomError(`Package path is not a regular file: ${normalized}`);
+    if (stat.size > PACKAGE_FILE_BYTES_LIMIT) {
+        throw new FloomError(`File too large: ${normalized}`, "Each package file is capped at 500KB.");
+    }
+    addBytes(stat.size);
+    const bytes = await readFile(fullPath);
+    files.push({
+        path: normalized,
+        content_base64: bytes.toString("base64"),
+        encoding: "base64",
+        size_bytes: bytes.length,
+        sha256: sha256Bytes(bytes),
+    });
+}
+function isGeneratedPackageEntry(name, isDirectory) {
+    if (isDirectory && GENERATED_PACKAGE_DIRS.has(name))
+        return true;
+    if (GENERATED_PACKAGE_FILES.has(name))
+        return true;
+    return GENERATED_PACKAGE_FILE_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
 function gitIgnoreChecker(root) {
     const cache = new Map();
     let localRules = null;
@@ -304,11 +398,13 @@ export function validatePackageRelativePath(path) {
         throw new FloomError(`Invalid package file path: ${path}`);
     }
     const segments = path.split("/");
-    if (segments.length === 1 && !isAllowedRootPackageFile(segments[0] ?? "")) {
-        throw new FloomError(`Invalid package file path: ${path}`, "Root package files must be safe text files such as .md, .txt, .json, .yaml, .toml, .py, .sh, .js, or .ts.");
+    if (segments.length === 1) {
+        if (ALLOWED_PACKAGE_ROOT_SUPPORT_FILES.has(path) && PACKAGE_SEGMENT_RE.test(path))
+            return;
+        throw new FloomError(`Invalid package file path: ${path}`, "Package root files must be approved support files.");
     }
-    if (segments.length > 1 && !ALLOWED_PACKAGE_DIRS.has(segments[0] ?? "")) {
-        throw new FloomError(`Invalid package file path: ${path}`, `Package files must be root text files or live under one of: ${Array.from(ALLOWED_PACKAGE_DIRS).sort().join(", ")}.`);
+    if (!ALLOWED_PACKAGE_DIRS.has(segments[0] ?? "")) {
+        throw new FloomError(`Invalid package file path: ${path}`, "Package files must be under an approved support directory.");
     }
     if (segments.some((segment) => segment === "." || segment === ".." || !PACKAGE_SEGMENT_RE.test(segment))) {
         throw new FloomError(`Invalid package file path: ${path}`);

package/dist/publish.js

@@ -107,34 +107,7 @@ 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) {
+export async function publishSkillPath(opts) {
     const skillPackage = await readSkillPackage(opts.file);
     const securityFailures = [
         { path: "SKILL.md", body: skillPackage.skillBody },
@@ -150,7 +123,9 @@ export async function publish(opts) {
         throw new FloomError("Security scan failed. Publish stopped.", `${securityFailures.join("\n")}\nRemove secrets, prompt-injection text, or data-exfiltration instructions before publishing.`);
     }
     const fileCount = 1 + skillPackage.packageFiles.length;
-    process.stdout.write(`\n${symbols.ok}  Pre-publish security scan passed (${fileCount} file${fileCount === 1 ? "" : "s"}, 3 checks).\n`);
+    if (!opts.quiet) {
+        process.stdout.write(`\n${symbols.ok}  Pre-publish security scan passed (${fileCount} file${fileCount === 1 ? "" : "s"}, 3 checks).\n`);
+    }
     const { meta, error: fmError } = parseFrontmatter(skillPackage.skillBody);
     if (fmError) {
         throw new FloomError(`Couldn't parse frontmatter — check your YAML.`, `Line ${fmError.line}: ${fmError.message}`);
@@ -160,20 +135,23 @@ export async function publish(opts) {
     const assetType = opts.assetType ?? parseAssetType(meta.asset_type ?? meta.type, "frontmatter type") ?? "skill";
     const installsAs = opts.installsAs ?? parseInstallsAs(meta.installs_as, "frontmatter installs_as") ?? null;
     const version = opts.version ?? parseVersion(meta.version, "frontmatter version") ?? null;
+    const updateSlug = opts.update ? (opts.updateSlug ?? meta.slug) : undefined;
+    if (opts.update && !updateSlug) {
+        throw new FloomError("Missing update slug.", "Use `--update <slug>` or add `slug:` to the skill frontmatter.");
+    }
+    if (updateSlug !== undefined && !SLUG_RE.test(updateSlug)) {
+        throw new FloomError(`Invalid update slug: ${updateSlug}`, "Use the Floom skill slug from its share URL.");
+    }
     const cfg = await readConfig();
     if (!cfg) {
         throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     }
-    const spinner = ora({
-        text: c.dim(`${opts.update ? "Updating" : "Publishing"} ${meta.title ? c.bold(meta.title) : opts.file}...`),
-        color: "yellow",
-    }).start();
     const apiUrl = resolveApiUrl(cfg);
     const body = {
         title: meta.title ?? null,
         description: meta.description ?? null,
         body_md: skillPackage.skillBody,
-        visibility: opts.visibility,
+        ...((opts.visibility ?? (!updateSlug ? "unlisted" : undefined)) ? { visibility: opts.visibility ?? "unlisted" } : {}),
         asset_type: assetType,
         source: "markdown",
         installs_as: installsAs,
@@ -181,12 +159,11 @@ export async function publish(opts) {
         original_filename: skillPackage.originalFilename,
         published_via: "cli",
         ...(opts.sharedWithEmails ? { shared_with_emails: opts.sharedWithEmails } : {}),
-        ...(opts.update || skillPackage.packageFiles.length > 0 ? { package_files: skillPackage.packageFiles } : {}),
+        ...(skillPackage.packageFiles.length > 0 ? { package_files: skillPackage.packageFiles } : {}),
     };
     let res;
     try {
-        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", {
+        res = await floomFetch(updateSlug ? `${apiUrl}/api/v1/skills/${updateSlug}` : `${apiUrl}/api/skills`, updateSlug ? "update your skill" : "publish your skill", {
             method: updateSlug ? "PATCH" : "POST",
             token: cfg.accessToken,
             checkOk: false,
@@ -194,16 +171,13 @@ export async function publish(opts) {
         });
     }
     catch (err) {
-        spinner.stop();
         throw err;
     }
     if (res.status === 409) {
-        spinner.stop();
-        throw new FloomError("Skill already published.", "Use `--update <slug-or-url>` to publish a new version of an existing skill.");
+        throw new FloomError("Skill already published.", "Use `--update <slug>` to publish a new version of an existing skill.");
     }
     if (!res.ok) {
-        spinner.stop();
-        throw friendlyHttp(res.status, opts.update ? "update your skill" : "publish your skill");
+        throw friendlyHttp(res.status, updateSlug ? "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.
@@ -211,17 +185,33 @@ export async function publish(opts) {
     const humanUrl = data.url
         ? data.url.replace(/\.md$/, "")
         : `${webBase}/s/${data.slug}`;
-    spinner.stop();
-    const versionTag = version ? c.dim(` (${formatVersionLabel(version)})`) : "";
     const titleLabel = data.title ? `"${data.title}"` : opts.file;
-    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`);
+    return { data, humanUrl, version, titleLabel };
+}
+export async function publish(opts) {
+    const spinner = ora({
+        text: c.dim(`${opts.update ? "Updating" : "Publishing"} ${opts.file}...`),
+        color: "yellow",
+    }).start();
+    let result;
+    try {
+        result = await publishSkillPath(opts);
+    }
+    catch (err) {
+        spinner.stop();
+        throw err;
+    }
+    spinner.stop();
+    const versionTag = result.version ? c.dim(` (${formatVersionLabel(result.version)})`) : "";
+    const verb = opts.update ? "Updated" : "Published";
+    process.stdout.write(`\n${symbols.ok}  ${verb} ${c.bold(result.titleLabel)}${versionTag}\n\n`);
+    process.stdout.write(`   ${c.cyan(result.humanUrl)}\n\n`);
+    if (result.data.visibility === "shared" && result.data.shared_with_emails?.length) {
+        process.stdout.write(`   ${c.dim(`Shared with ${result.data.shared_with_emails.join(", ")}`)}\n\n`);
     }
     let copied = false;
     try {
-        await clipboard.write(humanUrl);
+        await clipboard.write(result.humanUrl);
         copied = true;
     }
     catch {
@@ -234,9 +224,9 @@ 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} --setup`)}\n`);
+    process.stdout.write(`   ${c.dim("1.")} Test locally: ${c.cyan(`npx -y @floomhq/floom add ${result.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} --setup`)}\n`);
+    process.stdout.write(`   ${c.dim("3.")} Receiver runs ${c.cyan(`npx -y @floomhq/floom add ${result.humanUrl} --setup`)}\n`);
     process.stdout.write(`   ${c.dim("4.")} Agent reads the installed Markdown from the local skills folder.\n\n`);
 }
 function validateTextMeta(value, label, maxLength) {