@botdocs/cli 0.3.2 → 0.5.0

package/dist/commands/ingest.js

@@ -1,6 +1,94 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { apiFetch } from '../lib/api.js';
+/**
+ * Single source of truth for ecosystem detection. New ecosystems should be
+ * added here — both auto-detect mode and future `--from-tool` mode consult
+ * this table.
+ */
+const DETECTORS = {
+    claude: {
+        pathPrefix: 'claude/',
+        extensions: ['/SKILL.md'],
+        nested: true,
+        slugFor: (abs, root) => {
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            // Match `<anything>/<slug>/SKILL.md` — slug is the parent dir of SKILL.md.
+            if (!rel.endsWith('/SKILL.md'))
+                return null;
+            const parts = rel.split('/');
+            if (parts.length < 2)
+                return null;
+            return parts[parts.length - 2] ?? null;
+        },
+        canonicalFilename: (slug) => `claude/${slug}/SKILL.md`,
+    },
+    'claude-code': {
+        pathPrefix: 'claude-code/commands/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `claude-code/commands/${slug}.md`,
+    },
+    cursor: {
+        pathPrefix: 'cursor/rules/',
+        extensions: ['.mdc'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.mdc$/, '') || null,
+        canonicalFilename: (slug) => `cursor/rules/${slug}.mdc`,
+    },
+    chatgpt: {
+        pathPrefix: 'chatgpt/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `chatgpt/${slug}.md`,
+    },
+    codex: {
+        pathPrefix: 'codex/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `codex/${slug}.md`,
+    },
+    copilot: {
+        pathPrefix: 'copilot/instructions/',
+        // IMPORTANT: full multi-dot extension — strip BEFORE the .md to get clean slug.
+        extensions: ['.instructions.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.instructions\.md$/, '') || null,
+        canonicalFilename: (slug) => `copilot/instructions/${slug}.instructions.md`,
+    },
+    windsurf: {
+        pathPrefix: 'windsurf/rules/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `windsurf/rules/${slug}.md`,
+    },
+    gemini: {
+        pathPrefix: 'gemini/instructions/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `gemini/instructions/${slug}.md`,
+    },
+    antigravity: {
+        pathPrefix: 'antigravity/skills/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `antigravity/skills/${slug}.md`,
+    },
+    opencode: {
+        pathPrefix: 'opencode/instructions/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `opencode/instructions/${slug}.md`,
+    },
+};
+export const SUPPORTED_TOOLS = Object.keys(DETECTORS);
 const IGNORED_DIRS = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.turbo']);
 function walkFiles(root) {
     const out = [];
@@ -19,65 +107,111 @@ function walkFiles(root) {
     walk(root);
     return out;
 }
-function detectFile(absPath, root, content) {
+/** Does the filename end with any of the detector's declared extensions? */
+function matchesExtension(absPath, detector) {
+    return detector.extensions.some((ext) => absPath.endsWith(ext));
+}
+/**
+ * Auto-detect mode: iterate every detector and pick the first one whose
+ * path-prefix + extension match. Returns null if nothing matches.
+ */
+function detectAuto(absPath, root, content) {
     const rel = path.relative(root, absPath).split(path.sep).join('/');
-    if (rel.startsWith('claude/') && rel.endsWith('/SKILL.md')) {
-        return { filename: rel, content, ecosystem: 'claude' };
-    }
-    if (rel.startsWith('claude-code/commands/') && rel.endsWith('.md')) {
-        return { filename: rel, content, ecosystem: 'claude-code' };
-    }
-    if (rel.startsWith('cursor/rules/') && rel.endsWith('.mdc')) {
-        return { filename: rel, content, ecosystem: 'cursor' };
-    }
-    if (rel.startsWith('chatgpt/') && rel.endsWith('.md')) {
-        return { filename: rel, content, ecosystem: 'chatgpt' };
+    for (const [ecosystem, detector] of Object.entries(DETECTORS)) {
+        if (!rel.startsWith(detector.pathPrefix))
+            continue;
+        if (!matchesExtension(absPath, detector))
+            continue;
+        const slug = detector.slugFor(absPath, root);
+        if (!slug)
+            continue;
+        return {
+            filename: detector.canonicalFilename(slug),
+            content,
+            ecosystem,
+            slug,
+        };
     }
     return null;
 }
-/** Returns the slug for a detected file by stripping ecosystem path prefix and extension. */
-function slugFor(file) {
-    if (file.ecosystem === 'claude') {
-        const dirs = file.filename.split('/');
-        return dirs[1] ?? 'untitled';
-    }
-    return path.basename(file.filename).replace(/\.(md|mdc)$/, '');
+/**
+ * `--from-tool` mode: every file matching the chosen ecosystem's extension
+ * becomes a draft skill for that ecosystem, regardless of path prefix.
+ * Slug + canonical filename come from the detector, so the upload uses the
+ * canonical BotDocs layout — that's what lets downstream `botdocs install`
+ * route the file back to the right on-disk destination.
+ */
+function detectFromTool(absPath, root, content, ecosystem) {
+    const detector = DETECTORS[ecosystem];
+    if (!detector)
+        return null;
+    if (!matchesExtension(absPath, detector))
+        return null;
+    const slug = detector.slugFor(absPath, root);
+    if (!slug)
+        return null;
+    return {
+        filename: detector.canonicalFilename(slug),
+        content,
+        ecosystem,
+        slug,
+    };
 }
 function titleFromContent(content, slug) {
     const m = content.match(/^#\s+(.+)$/m);
     return m?.[1]?.trim() ?? slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
 }
+/** Human-readable list of all canonical path prefixes for the empty-result message. */
+function ecosystemPrefixSummary() {
+    return Object.values(DETECTORS)
+        .map((d) => d.pathPrefix)
+        .join(', ');
+}
 export async function ingest(rootPath, options) {
     const root = path.resolve(rootPath);
     if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
         console.error(`\n  ✗ Not a directory: ${rootPath}\n`);
         process.exit(1);
+        return;
+    }
+    if (options.fromTool && !SUPPORTED_TOOLS.includes(options.fromTool)) {
+        console.error(`\n  ✗ Unknown --from-tool "${options.fromTool}". Supported: ${SUPPORTED_TOOLS.join(', ')}\n`);
+        process.exit(1);
+        return;
     }
     const detected = [];
     for (const filePath of walkFiles(root)) {
         const content = fs.readFileSync(filePath, 'utf-8');
-        const d = detectFile(filePath, root, content);
+        const d = options.fromTool
+            ? detectFromTool(filePath, root, content, options.fromTool)
+            : detectAuto(filePath, root, content);
         if (d)
             detected.push(d);
     }
     if (detected.length === 0) {
-        console.log('\n  No skills detected. Looked for: claude/, claude-code/commands/, cursor/rules/, chatgpt/.\n');
+        if (options.fromTool) {
+            const detector = DETECTORS[options.fromTool];
+            console.log(`\n  ⚠ No files matched ecosystem "${options.fromTool}" (expected ${detector.extensions.join(' or ')} files) in ${root}.\n`);
+        }
+        else {
+            console.log(`\n  No skills detected. Looked for: ${ecosystemPrefixSummary()}.\n`);
+        }
         return;
     }
-    // Group into logical skills by slug
+    // Group into logical skills by slug, merging files that share a slug
+    // across ecosystems (e.g. a `code-review` Claude SKILL.md + a Cursor rule).
     const grouped = new Map();
     for (const f of detected) {
-        const slug = slugFor(f);
-        if (!grouped.has(slug)) {
-            grouped.set(slug, {
-                slug,
-                title: titleFromContent(f.content, slug),
+        if (!grouped.has(f.slug)) {
+            grouped.set(f.slug, {
+                slug: f.slug,
+                title: titleFromContent(f.content, f.slug),
                 description: '',
                 sourceEcosystem: f.ecosystem,
                 files: [],
             });
         }
-        grouped.get(slug).files.push({ filename: f.filename, content: f.content });
+        grouped.get(f.slug).files.push({ filename: f.filename, content: f.content });
     }
     const skills = [...grouped.values()];
     console.log(`\n  ✓ Found ${skills.length} skill(s):`);

package/dist/commands/install.d.ts

@@ -3,6 +3,10 @@ interface InstallOptions {
     flat?: boolean;
     clean?: boolean;
     json?: boolean;
+    /** When true, skip backups before overwriting existing files. Intended for
+     * CI where backups are noise; default behavior backs up untracked or
+     * locally-edited files to `.botdocs-backup/<ts>/` before the overwrite. */
+    noBackup?: boolean;
 }
 export declare function install(rawRef: string, options: InstallOptions): Promise<void>;
 export {};

package/dist/commands/install.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { ApiError, apiFetch, fetchRawContent } from '../lib/api.js';
 import { detectDestination } from '../lib/auto-detect.js';
 import { fingerprintContent, fingerprintFile, loadLockfile, upsertInstall, } from '../lib/lockfile.js';
+import { backupFile, isLockfileOwnedAndUnchanged } from '../lib/backup.js';
 import { syncLibrary } from '../lib/library-sync.js';
 function parseRef(raw) {
     const cleaned = raw.startsWith('@') ? raw.slice(1) : raw;
@@ -25,16 +26,33 @@ function buildContext(scope, slug, options) {
 function ensureDir(filePath) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
 }
-async function downloadAndWrite(file, dest, options) {
+async function downloadAndWrite(file, dest, options, projectDir) {
     const content = await fetchRawContent(file.rawUrl);
     if (fs.existsSync(dest) && !options.clean) {
         const existingFp = fingerprintFile(dest);
         const tmpFp = fingerprintContent(content);
         if (existingFp === tmpFp) {
-            // Already present at same fingerprint — additive no-op.
+            // Already present at same fingerprint — additive no-op. No backup
+            // needed: we're about to write the same bytes anyway.
             return { src: file.filename, dest, fingerprint: existingFp };
         }
     }
+    // About to overwrite. If the existing file isn't something we own and
+    // haven't touched, take a backup first so a hand-written rule at a
+    // colliding path isn't silently lost.
+    if (fs.existsSync(dest) && !options.noBackup && !isLockfileOwnedAndUnchanged(dest)) {
+        const result = backupFile(dest, projectDir);
+        if (!options.json) {
+            if (result.ok) {
+                const relSrc = path.relative(process.cwd(), dest);
+                const relDest = path.relative(process.cwd(), result.dest);
+                console.log(`  ⚠ Backed up existing file: ${relSrc} → ${relDest}`);
+            }
+            else {
+                console.log(`  ⚠ Could not back up ${dest}: ${result.error} — proceeding with overwrite.`);
+            }
+        }
+    }
     ensureDir(dest);
     fs.writeFileSync(dest, content, 'utf-8');
     return { src: file.filename, dest, fingerprint: fingerprintFile(dest) };
@@ -42,6 +60,7 @@ async function downloadAndWrite(file, dest, options) {
 async function installSkill(ref, manifest, options, scope) {
     const ctx = buildContext(scope, ref.slug, options);
     const filesInstalled = [];
+    let manualPromptsShown = 0;
     for (const file of manifest.files) {
         const detection = detectDestination(file.filename, ctx);
         if (detection.kind === 'skip')
@@ -52,12 +71,30 @@ async function installSkill(ref, manifest, options, scope) {
                 const content = await fetchRawContent(file.rawUrl);
                 console.log(`\n  Manual paste required for ${file.filename}:\n${content}\n`);
             }
+            // A manual paste prompt counts as "we surfaced this file to the user",
+            // so don't trigger the no-installable-files warning below.
+            manualPromptsShown += 1;
             continue;
         }
-        const installed = await downloadAndWrite(file, detection.dest, options);
+        const installed = await downloadAndWrite(file, detection.dest, options, ctx.projectDir);
         if (installed)
             filesInstalled.push(installed);
     }
+    // Surface clear feedback when the manifest produced nothing actionable.
+    // Suppressed under --json so machine-readable output stays clean.
+    if (!options.json) {
+        const refStr = `@${ref.username}/${ref.slug}`;
+        if (manifest.files.length === 0) {
+            console.log(`\n  ⚠ ${refStr} has no files. Nothing to install.\n` +
+                `    This BotDoc may have been published before any content was added.\n`);
+        }
+        else if (filesInstalled.length === 0 && manualPromptsShown === 0) {
+            console.log(`\n  ⚠ ${refStr} has files but none target a supported agent.\n` +
+                `    It may be a spec-only BotDoc without compiled per-agent files\n` +
+                `    (claude/SKILL.md, cursor/rules/*.mdc, etc.).\n` +
+                `    Ask the author to run \`botdocs compile\` and re-publish.\n`);
+        }
+    }
     return {
         ref: `@${ref.username}/${ref.slug}`,
         type: 'SKILL',

package/dist/commands/login.d.ts

@@ -1,5 +1,12 @@
 interface LoginOptions {
     syncLibrary?: boolean;
+    /** Skip the browser flow and store this token directly. Used for CI/headless
+     * environments where the user has already minted a token at /settings/tokens. */
+    token?: string;
+    /** Force the plain-text rendering path even on a real TTY. Useful for users
+     * who prefer screen-reader-friendly output, or anyone disturbed by live
+     * redraws. The non-TTY path is taken automatically when stdout is piped. */
+    noInk?: boolean;
 }
 export declare function login(options?: LoginOptions): Promise<void>;
 export {};