@floomhq/floom 1.0.14 → 1.0.17

package/dist/doctor.js

@@ -1,11 +1,14 @@
 import { homedir } from "node:os";
+import { execFile as execFileCb } from "node:child_process";
+import { delimiter } from "node:path";
 import { join } from "node:path";
-import { stat, readFile, access, readdir, constants } from "node:fs/promises";
+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 { floomFetch } from "./lib/api.js";
 import { c, symbols } from "./ui.js";
 import { CLI_VERSION, compareSemverish, formatVersionLabel } from "./version.js";
-import { resolveSkillsDir } from "./targets.js";
+const execFile = promisify(execFileCb);
 function statusBadge(s) {
     if (s === "ok")
         return c.green(symbols.ok);
@@ -19,7 +22,7 @@ async function checkAuth() {
         return {
             name: "Auth",
             status: "ok",
-            detail: "Receiver mode ready: add shared links without an account. Sign in to publish, save, follow, list, or sync.",
+            detail: "Receiver mode ready. Sign in only when publishing or listing your own skills.",
         };
     }
     const apiUrl = resolveApiUrl(cfg);
@@ -89,7 +92,7 @@ async function checkMcp() {
         return {
             name: "MCP",
             status: "ok",
-            detail: "Optional MCP not registered. `npx -y @floomhq/floom add` still writes local files; MCP keeps signed-in libraries synced.",
+            detail: "Optional MCP not registered. `npx -y @floomhq/floom add` still writes local skill files.",
         };
     }
     return {
@@ -98,24 +101,31 @@ async function checkMcp() {
         detail: `Registered with: ${found.map((f) => f.name).join(", ")}`,
     };
 }
+function targetSkillsDir(target) {
+    if (target === "codex") {
+        const codexHome = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+        return process.env.CODEX_SKILLS_DIR ?? join(codexHome, "skills");
+    }
+    return process.env.CLAUDE_SKILLS_DIR ?? join(homedir(), ".claude", "skills");
+}
 async function checkTargetDir(target) {
-    const dir = resolveSkillsDir(target);
+    const dir = targetSkillsDir(target);
     try {
         const s = await stat(dir);
         if (!s.isDirectory()) {
             return {
-                name: `${target} dir`,
+                name: "Target dir",
                 status: "fail",
                 detail: `${dir} exists but is not a directory.`,
             };
         }
         try {
             await access(dir, constants.W_OK);
-            return { name: `${target} dir`, status: "ok", detail: `${dir} (writable)` };
+            return { name: "Target dir", status: "ok", detail: `${dir} (writable)` };
         }
         catch {
             return {
-                name: `${target} dir`,
+                name: "Target dir",
                 status: "fail",
                 detail: `${dir} is not writable.`,
                 hint: `Try: chmod u+w ${dir}`,
@@ -125,26 +135,26 @@ async function checkTargetDir(target) {
     catch (err) {
         if (err.code === "ENOENT") {
             return {
-                name: `${target} dir`,
+                name: "Target dir",
                 status: "warn",
                 detail: `${dir} does not exist yet.`,
-                hint: "It will be created on first `npx -y @floomhq/floom add`.",
+                hint: `It will be created on first \`npx -y @floomhq/floom add <link> --target ${target}\`.`,
             };
         }
         throw err;
     }
 }
 async function checkLastSync(target) {
-    const dir = resolveSkillsDir(target);
+    const dir = targetSkillsDir(target);
     try {
         const entries = await readdir(dir);
         const skills = entries.filter((e) => e.endsWith(".md") || !e.startsWith("."));
         if (skills.length === 0) {
             return {
-                name: `${target} sync`,
+                name: "Last sync",
                 status: "warn",
                 detail: "No synced skills found yet.",
-                hint: "Run `npx -y @floomhq/floom add <link>` to install your first skill.",
+                hint: `Run \`npx -y @floomhq/floom add <link> --target ${target}\` to install your first skill.`,
             };
         }
         // Find most recently modified entry
@@ -161,7 +171,7 @@ async function checkLastSync(target) {
         }
         if (newest.mtime === 0) {
             return {
-                name: `${target} sync`,
+                name: "Last sync",
                 status: "warn",
                 detail: `${skills.length} entries, no readable mtime.`,
             };
@@ -175,7 +185,7 @@ async function checkLastSync(target) {
                     ? `${Math.round(ageSec / 3600)}h ago`
                     : `${Math.round(ageSec / 86400)}d ago`;
         return {
-            name: `${target} sync`,
+            name: "Last sync",
             status: "ok",
             detail: `${newest.name} — ${human} (${skills.length} total)`,
         };
@@ -183,13 +193,13 @@ async function checkLastSync(target) {
     catch (err) {
         if (err.code === "ENOENT") {
             return {
-                name: `${target} sync`,
+                name: "Last sync",
                 status: "warn",
                 detail: "Skills dir not created yet.",
             };
         }
         return {
-            name: `${target} sync`,
+            name: "Last sync",
             status: "warn",
             detail: `Cannot read skills dir: ${err.message}`,
         };
@@ -216,7 +226,7 @@ async function checkVersion() {
                 name: "Version",
                 status: "fail",
                 detail: `CLI ${formatVersionLabel(CLI_VERSION)} below required ${formatVersionLabel(data.min)}.`,
-                hint: "Run `npm i -g @floomhq/floom` to upgrade.",
+                hint: "Run `npm i -g @floomhq/floom` to upgrade, then use `floom`.",
             };
         }
         if (data.latest && compareSemverish(CLI_VERSION, data.latest) < 0) {
@@ -224,7 +234,7 @@ async function checkVersion() {
                 name: "Version",
                 status: "warn",
                 detail: `CLI ${formatVersionLabel(CLI_VERSION)}, latest is ${formatVersionLabel(data.latest)}.`,
-                hint: "Run `npm i -g @floomhq/floom` to upgrade.",
+                hint: "Run `npm i -g @floomhq/floom` to upgrade, then use `floom`.",
             };
         }
         return { name: "Version", status: "ok", detail: `CLI ${formatVersionLabel(CLI_VERSION)} (current)` };
@@ -237,32 +247,103 @@ async function checkVersion() {
         };
     }
 }
+async function findPathExecutables(name) {
+    const seen = new Set();
+    const out = [];
+    const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+    for (const dir of pathDirs) {
+        const candidate = join(dir, name);
+        if (seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        try {
+            await access(candidate, constants.X_OK);
+            out.push(candidate);
+        }
+        catch {
+            // not present or not executable
+        }
+    }
+    return out;
+}
+async function safeRealpath(path) {
+    if (!path)
+        return null;
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return null;
+    }
+}
+async function checkCliCommand() {
+    const bins = await findPathExecutables("floom");
+    if (bins.length === 0) {
+        return {
+            name: "CLI command",
+            status: "ok",
+            detail: "`floom` is not globally installed. `npx -y @floomhq/floom ...` is ready.",
+        };
+    }
+    const active = bins[0] ?? "";
+    const activeReal = await safeRealpath(active);
+    const currentReal = await safeRealpath(process.argv[1]);
+    if (activeReal && currentReal && activeReal === currentReal) {
+        return {
+            name: "CLI command",
+            status: "ok",
+            detail: `floom resolves to ${active}`,
+        };
+    }
+    const activeText = await readExecutableSample(active);
+    const activeVersion = await readExecutableVersion(active);
+    const looksLikeOldRuntime = active.includes(".floom/repo") ||
+        active.includes("/skills-minimal/") ||
+        activeText.includes("unknown command") ||
+        activeText.includes("Floom runtime") ||
+        (activeVersion !== null && compareSemverish(activeVersion, CLI_VERSION) < 0);
+    return {
+        name: "CLI command",
+        status: looksLikeOldRuntime ? "warn" : "ok",
+        detail: looksLikeOldRuntime
+            ? `Another floom command is first on PATH: ${active}${activeVersion ? ` (${formatVersionLabel(activeVersion)})` : ""}`
+            : `floom resolves to ${active}`,
+        ...(looksLikeOldRuntime
+            ? {
+                hint: `If \`floom doctor\` opens the old runtime CLI, remove that file or move it later in PATH, then run \`npm i -g @floomhq/floom\`. Inspect with: command -v floom`,
+            }
+            : {}),
+    };
+}
+async function readExecutableSample(path) {
+    try {
+        return (await readFile(path, "utf8")).slice(0, 4000);
+    }
+    catch {
+        return "";
+    }
+}
+async function readExecutableVersion(path) {
+    try {
+        const { stdout, stderr } = await execFile(path, ["--version"], { timeout: 1500 });
+        const text = `${stdout}\n${stderr}`;
+        return text.match(/\d+\.\d+\.\d+(?:[-+][A-Za-z0-9._-]+)?/)?.[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function doctor(opts = {}) {
     const target = opts.target ?? "claude";
+    process.stdout.write(`\n${c.bold("floom doctor")} ${c.dim(`(${formatVersionLabel(CLI_VERSION)}, target: ${target})`)}\n\n`);
     const checks = await Promise.all([
+        checkCliCommand(),
         checkAuth(),
         checkMcp(),
         checkTargetDir(target),
         checkLastSync(target),
         checkVersion(),
     ]);
-    const anyFail = checks.some((c) => c.status === "fail");
-    const anyWarn = checks.some((c) => c.status === "warn");
-    const status = anyFail ? "fail" : anyWarn ? "warn" : "ok";
-    if (opts.json) {
-        process.stdout.write(`${JSON.stringify({
-            ok: !anyFail,
-            status,
-            version: CLI_VERSION,
-            target,
-            config_path: CONFIG_PATH,
-            checks,
-        }, null, 2)}\n`);
-        if (anyFail)
-            process.exit(1);
-        return;
-    }
-    process.stdout.write(`\n${c.bold("floom doctor")} ${c.dim(`(${formatVersionLabel(CLI_VERSION)})`)}\n\n`);
     // Compute column widths for clean table output.
     const nameW = Math.max(...checks.map((c) => c.name.length), 6);
     for (const check of checks) {
@@ -272,6 +353,8 @@ export async function doctor(opts = {}) {
             process.stdout.write(`     ${c.dim("→ " + check.hint)}\n`);
         }
     }
+    const anyFail = checks.some((c) => c.status === "fail");
+    const anyWarn = checks.some((c) => c.status === "warn");
     process.stdout.write("\n");
     if (anyFail) {
         process.stdout.write(`  ${c.red("✗ Some checks failed.")} See hints above.\n\n`);
@@ -279,10 +362,8 @@ export async function doctor(opts = {}) {
     }
     if (anyWarn) {
         process.stdout.write(`  ${c.yellow("! All critical checks passed, with warnings.")}\n\n`);
-        process.stdout.write(`  ${c.dim("MCP sync is optional and account-backed; add still works without MCP.")}\n\n`);
         process.exit(0);
     }
     process.stdout.write(`  ${c.green("✓ All checks passed.")} Floom is healthy.\n\n`);
-    process.stdout.write(`  ${c.dim("MCP sync is optional and account-backed; add still works without MCP.")}\n`);
     process.stdout.write(`  ${c.dim("Config: " + CONFIG_PATH)}\n\n`);
 }

package/dist/errors.js

@@ -23,7 +23,7 @@ export function friendlyHttp(status, action) {
         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.", "Publish as a new skill for now. Publisher-side version updates are planned for a later release.");
+        return new FloomError("Skill not found.", "Run `npx -y @floomhq/floom publish <path>` to create a new one.");
     }
     if (status === 413) {
         return new FloomError("That file is too large to publish.");

package/dist/info.js

@@ -28,7 +28,7 @@ export async function info(opts) {
     const spinner = opts.json ? null : ora({ text: c.dim(`Loading ${slug}...`), color: "yellow" }).start();
     let detail;
     try {
-        detail = await getJson(`${apiUrl}/api/v1/skills/${encodeURIComponent(slug)}`, "info skill metadata", cfg?.accessToken);
+        detail = await getJson(`${apiUrl}/api/v1/skills/${encodeURIComponent(slug)}`, "load skill metadata", cfg?.accessToken);
     }
     finally {
         spinner?.stop();

package/dist/init.js

@@ -1,5 +1,5 @@
-import { writeFile, access } from "node:fs/promises";
-import { dirname, resolve, basename } from "node:path";
+import { writeFile, access, mkdir } from "node:fs/promises";
+import { dirname, resolve, basename, extname, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { c, symbols } from "./ui.js";
@@ -30,7 +30,7 @@ version: 1.0
 `,
     "brand-voice": `---
 title: Brand voice
-description: Help an agent write in our company voice.
+description: Keep agent writing aligned with our company voice.
 type: knowledge
 installs_as: memory
 version: 1.0
@@ -38,29 +38,27 @@ version: 1.0
 
 # Brand Voice
 
-## Use when
-- Writing customer-facing copy
-- Rewriting drafts to match our tone
-- Reviewing messaging before it ships
+## Use this when
+
+- Writing external copy
+- Editing founder posts
+- Drafting website, email, or support text
 
 ## Voice rules
-- Sound clear, direct, and useful.
-- Prefer concrete nouns and short sentences.
-- Avoid hype, filler, and generic AI language.
 
-## Words we use
-- Replace this list with approved terms.
+- Be clear and specific.
+- Use short paragraphs.
+- Avoid hype, filler, and vague claims.
 
-## Words we avoid
-- Replace this list with banned or overused terms.
+## Company facts
 
-## Examples
-- Before:
-- After:
+- Add product facts here.
+- Add banned phrases here.
+- Add preferred examples here.
 `,
     "pr-review": `---
 title: PR review
-description: Review code changes with risk-first feedback.
+description: Review pull requests for correctness, regressions, and missing tests.
 type: workflow
 installs_as: claude_skill
 version: 1.0
@@ -68,21 +66,26 @@ version: 1.0
 
 # PR Review
 
-## Use when
-- Reviewing a pull request or diff
-- Checking a change before merge
+## Goal
+
+Find concrete bugs, regressions, security issues, and missing tests before code merges.
+
+## Inputs
+
+- Diff
+- Test output
+- Relevant files and callers
+
+## Review steps
 
-## Review order
-1. Correctness and regressions
-2. Security and data safety
-3. Tests and missing edge cases
-4. Maintainability
+1. Read the diff and affected call sites.
+2. Check behavior changes against the stated intent.
+3. Look for edge cases, auth/security issues, data loss, and broken contracts.
+4. Verify tests cover the changed behavior.
 
 ## Output
-- Lead with findings.
-- Include file paths and line references.
-- Keep style comments out unless they affect behavior.
-- If no issues are found, say that clearly and name any test gaps.
+
+List findings first, ordered by severity, with file and line references.
 `,
     sales: `---
 title: Sales research
@@ -94,27 +97,25 @@ version: 1.0
 
 # Sales Research
 
-## Use when
-- Preparing for a prospect call
-- Writing a relevant outbound message
-- Summarizing account context for the team
+## Goal
+
+Prepare useful context before contacting an account.
 
-## Gather
-- Company
-- Buyer persona
-- Recent trigger
+## Research checklist
+
+- Company description
+- Current priorities or trigger events
+- Relevant people
 - Likely pain
-- Existing tools or workflow
+- Specific reason to reach out
 
 ## Output
-- 5 bullet account summary
-- 3 likely pain points
-- 2 tailored opener angles
-- 1 clear next action
+
+Return a short account brief and a first-message angle.
 `,
     support: `---
 title: Support tone
-description: Answer support tickets with a clear and calm company voice.
+description: Keep support replies concise, helpful, and calm.
 type: instruction
 installs_as: memory
 version: 1.0
@@ -122,68 +123,59 @@ version: 1.0
 
 # Support Tone
 
-## Use when
-- Replying to customer support messages
-- Summarizing customer issues
-- Drafting escalation notes
-
 ## Rules
-- Acknowledge the issue in plain language.
+
+- Acknowledge the issue directly.
 - Give the next concrete step.
-- Do not over-apologize.
-- Do not invent product behavior.
-- Escalate when data, billing, or account access is involved.
-
-## Reply shape
-1. Short acknowledgement
-2. Direct answer or next step
-3. What happens next
+- Avoid blaming the user.
+- Avoid long explanations unless the user asks.
+
+## Output
+
+Write the reply in plain language with a clear next action.
 `,
     onboarding: `---
-title: Team onboarding
-description: Help a new teammate understand how this team works.
+title: Onboarding context
+description: Give agents the context needed to help new teammates.
 type: knowledge
 installs_as: memory
 version: 1.0
 ---
 
-# Team Onboarding
+# Onboarding Context
 
-## Use when
-- A new teammate asks how work gets done
-- An agent needs company or team context
-- Creating first-week task plans
+## Company
 
-## Team context
-- Mission:
-- Customers:
-- Current priorities:
-- Tools:
+- Add what the company does.
+- Add important product areas.
 
 ## How we work
-- Decision rules:
-- Review process:
-- Communication norms:
-- Definition of done:
-
-## First-week checklist
-- Read:
-- Set up:
-- Ask:
-- Ship:
+
+- Add team norms.
+- Add review expectations.
+- Add recurring workflows.
+
+## Useful links
+
+- Add docs and repositories.
 `,
 };
-export async function init(filename, template = "generic") {
-    const target = filename ?? "skill.md";
-    const filePath = resolve(process.cwd(), target);
-    const body = TEMPLATES[template];
+export const INIT_TEMPLATES = Object.keys(TEMPLATES);
+const CLI_COMMAND = "npx -y @floomhq/floom";
+export async function init(filename, opts = {}) {
+    const target = filename ?? "skill";
+    const template = opts.template ?? "generic";
+    const folderMode = extname(target).toLowerCase() !== ".md";
+    const outputTarget = folderMode ? join(target, "SKILL.md") : target;
+    const folderPath = folderMode ? resolve(process.cwd(), target) : null;
+    const filePath = resolve(process.cwd(), outputTarget);
     const exists = await fileExists(filePath);
     if (exists) {
         if (!process.stdin.isTTY) {
-            throw new FloomError(`${target} already exists.`, "Re-run with a different filename, or delete it first.");
+            throw new FloomError(`${outputTarget} already exists.`, "Re-run with a different filename, or delete it first.");
         }
         const rl = createInterface({ input, output });
-        const answer = (await rl.question(`${c.yellow("?")}  ${target} already exists. Overwrite? ${c.dim("(y/N)")} `)).trim().toLowerCase();
+        const answer = (await rl.question(`${c.yellow("?")}  ${outputTarget} already exists. Overwrite? ${c.dim("(y/N)")} `)).trim().toLowerCase();
         rl.close();
         if (answer !== "y" && answer !== "yes") {
             process.stdout.write(`\n${c.dim("Cancelled. Nothing was written.")}\n\n`);
@@ -191,7 +183,9 @@ export async function init(filename, template = "generic") {
         }
     }
     try {
-        await writeFile(filePath, body, "utf8");
+        if (folderPath)
+            await mkdir(folderPath, { recursive: true });
+        await writeFile(filePath, TEMPLATES[template], "utf8");
     }
     catch (err) {
         const code = err.code;
@@ -201,14 +195,15 @@ export async function init(filename, template = "generic") {
         if (code === "EISDIR") {
             throw new FloomError(`That's a directory, not a file: ${target}`);
         }
-        throw new FloomError(`Couldn't create ${target}: ${err.message}`);
+        throw new FloomError(`Couldn't create ${outputTarget}: ${err.message}`);
     }
-    process.stdout.write(`\n${symbols.ok}  Created ${c.bold(basename(filePath))}\n`);
-    process.stdout.write(`   ${c.dim(`Template: ${template}`)}\n`);
+    process.stdout.write(`\n${symbols.ok}  Created ${c.bold(folderMode ? outputTarget : basename(filePath))}\n`);
+    if (template !== "generic")
+        process.stdout.write(`   ${c.dim(`Template: ${template}`)}\n`);
     process.stdout.write(`\n   ${c.bold("Next")}\n`);
     process.stdout.write(`   ${c.dim("1.")} Fill in the title, description, and instructions.\n`);
-    process.stdout.write(`   ${c.dim("2.")} Check it: ${c.cyan(`npx -y @floomhq/floom scan ${shellQuote(target)}`)}\n`);
-    process.stdout.write(`   ${c.dim("3.")} Publish:  ${c.cyan(`npx -y @floomhq/floom publish ${shellQuote(target)} --public`)}\n\n`);
+    process.stdout.write(`   ${c.dim("2.")} Check it: ${c.cyan(`${CLI_COMMAND} scan ${shellQuote(folderMode ? target : outputTarget)}`)}\n`);
+    process.stdout.write(`   ${c.dim("3.")} Publish:  ${c.cyan(`${CLI_COMMAND} publish ${shellQuote(folderMode ? target : outputTarget)} --type instruction --public`)}\n\n`);
 }
 function shellQuote(value) {
     if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))