@botdocs/cli 0.2.0 → 0.3.1

package/dist/commands/install.js

@@ -0,0 +1,143 @@
+import fs from 'node:fs';
+import os from 'node:os';
+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 { syncLibrary } from '../lib/library-sync.js';
+function parseRef(raw) {
+    const cleaned = raw.startsWith('@') ? raw.slice(1) : raw;
+    const parts = cleaned.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error(`Invalid ref: ${raw} (expected @user/slug)`);
+    }
+    return { username: parts[0], slug: parts[1] };
+}
+function buildContext(scope, slug, options) {
+    return {
+        scope,
+        slug,
+        homeDir: os.homedir(),
+        projectDir: path.resolve(options.project ?? process.cwd()),
+        flatScope: options.flat ?? false,
+    };
+}
+function ensureDir(filePath) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+async function downloadAndWrite(file, dest, options) {
+    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.
+            return { src: file.filename, dest, fingerprint: existingFp };
+        }
+    }
+    ensureDir(dest);
+    fs.writeFileSync(dest, content, 'utf-8');
+    return { src: file.filename, dest, fingerprint: fingerprintFile(dest) };
+}
+async function installSkill(ref, manifest, options, scope) {
+    const ctx = buildContext(scope, ref.slug, options);
+    const filesInstalled = [];
+    for (const file of manifest.files) {
+        const detection = detectDestination(file.filename, ctx);
+        if (detection.kind === 'skip')
+            continue;
+        if (detection.kind === 'manual') {
+            // Print for user paste (ChatGPT case). Suppressed under --json so output stays parseable.
+            if (!options.json) {
+                const content = await fetchRawContent(file.rawUrl);
+                console.log(`\n  Manual paste required for ${file.filename}:\n${content}\n`);
+            }
+            continue;
+        }
+        const installed = await downloadAndWrite(file, detection.dest, options);
+        if (installed)
+            filesInstalled.push(installed);
+    }
+    return {
+        ref: `@${ref.username}/${ref.slug}`,
+        type: 'SKILL',
+        version: manifest.version,
+        installedAt: new Date().toISOString(),
+        files: filesInstalled,
+    };
+}
+export async function install(rawRef, options) {
+    const ref = parseRef(rawRef);
+    const refStr = `@${ref.username}/${ref.slug}`;
+    if (options.clean) {
+        const lf = loadLockfile();
+        const prior = lf.installs.find((i) => i.ref === refStr);
+        if (prior) {
+            for (const f of prior.files) {
+                if (fs.existsSync(f.dest))
+                    fs.unlinkSync(f.dest);
+            }
+            // For bundles, also clean each contained skill's files
+            if (prior.type === 'BUNDLE' && prior.skills) {
+                for (const skillRef of prior.skills) {
+                    const skillEntry = lf.installs.find((i) => i.ref === skillRef);
+                    if (skillEntry) {
+                        for (const f of skillEntry.files) {
+                            if (fs.existsSync(f.dest))
+                                fs.unlinkSync(f.dest);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    let manifest;
+    try {
+        manifest = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/manifest`);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+            console.error(`\n  ✗ Skill or bundle not found: ${refStr}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    const installedSummaries = [];
+    if (manifest.type === 'SKILL') {
+        const entry = await installSkill(ref, manifest, options, ref.username);
+        upsertInstall(entry);
+        installedSummaries.push(entry);
+    }
+    else {
+        const skills = [];
+        for (const skill of manifest.skills) {
+            const entry = await installSkill(skill.ref, skill, options, ref.username);
+            upsertInstall(entry);
+            installedSummaries.push(entry);
+            skills.push(`@${skill.ref.username}/${skill.ref.slug}`);
+        }
+        const bundleEntry = {
+            ref: refStr,
+            type: 'BUNDLE',
+            version: manifest.version,
+            installedAt: new Date().toISOString(),
+            files: [],
+            skills,
+        };
+        upsertInstall(bundleEntry);
+        installedSummaries.push(bundleEntry);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ref: refStr, installed: installedSummaries }));
+        await syncLibrary();
+        return;
+    }
+    console.log(`\n  ✓ Installed ${refStr}`);
+    for (const entry of installedSummaries) {
+        if (entry.type === 'BUNDLE')
+            continue;
+        console.log(`    ${entry.ref}: ${entry.files.length} file(s)`);
+    }
+    console.log('');
+    await syncLibrary();
+}

package/dist/commands/install.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/install.test.js

@@ -0,0 +1,253 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { install } from './install.js';
+import { captureConsole, mockFetch, withTempDir } from '../test-utils.js';
+import { loadLockfile } from '../lib/lockfile.js';
+vi.mock('../lib/library-sync.js', () => ({
+    syncLibrary: vi.fn(),
+}));
+import * as librarySync from '../lib/library-sync.js';
+describe('install', () => {
+    let tmp;
+    let captured;
+    let restoreFetch = () => { };
+    const origHome = os.homedir;
+    let homeTmp;
+    beforeEach(() => {
+        tmp = withTempDir();
+        homeTmp = fs.mkdtempSync(path.join(os.tmpdir(), 'install-home-'));
+        os.homedir = () => homeTmp;
+        process.env.BOTDOCS_API_URL = 'http://test.local';
+        captured = captureConsole();
+    });
+    afterEach(() => {
+        restoreFetch();
+        captured.restore();
+        tmp.cleanup();
+        fs.rmSync(homeTmp, { recursive: true, force: true });
+        os.homedir = origHome;
+        vi.restoreAllMocks();
+    });
+    it('installs a SKILL bundle to the right destinations', async () => {
+        const fm = mockFetch([
+            {
+                url: '/api/skills/alice/code-review/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'alice', slug: 'code-review' },
+                        type: 'SKILL',
+                        version: '1.0.0',
+                        sourceEcosystem: 'claude-code',
+                        files: [
+                            { filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/skill' },
+                            { filename: 'cursor/rules/code-review.mdc', rawUrl: 'http://test.local/raw/cursor' },
+                        ],
+                    },
+                },
+            },
+            { url: '/raw/skill', response: { body: '# Claude SKILL\n\nbody', contentType: 'text/plain' } },
+            { url: '/raw/cursor', response: { body: '# Cursor rule', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        await install('@alice/code-review', { project: tmp.dir });
+        const claudePath = path.join(homeTmp, '.claude', 'skills', 'alice', 'code-review', 'SKILL.md');
+        const cursorPath = path.join(tmp.dir, '.cursor', 'rules', 'code-review.mdc');
+        expect(fs.existsSync(claudePath)).toBe(true);
+        expect(fs.existsSync(cursorPath)).toBe(true);
+        const lf = loadLockfile();
+        expect(lf.installs).toHaveLength(1);
+        expect(lf.installs[0].ref).toBe('@alice/code-review');
+        expect(lf.installs[0].files).toHaveLength(2);
+    });
+    it('installs a BUNDLE by recursively installing each skill', async () => {
+        const fm = mockFetch([
+            {
+                url: '/api/skills/teamco/eng-skills/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'teamco', slug: 'eng-skills' },
+                        type: 'BUNDLE',
+                        version: '1.0.0',
+                        skills: [
+                            {
+                                ref: { username: 'teamco', slug: 'code-review' },
+                                version: '1.0.0',
+                                sourceEcosystem: 'claude-code',
+                                files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/cr' }],
+                            },
+                            {
+                                ref: { username: 'teamco', slug: 'pr-summary' },
+                                version: '1.0.0',
+                                sourceEcosystem: 'claude-code',
+                                files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/ps' }],
+                            },
+                        ],
+                    },
+                },
+            },
+            { url: '/raw/cr', response: { body: '# CR', contentType: 'text/plain' } },
+            { url: '/raw/ps', response: { body: '# PS', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        await install('@teamco/eng-skills', { project: tmp.dir });
+        expect(fs.existsSync(path.join(homeTmp, '.claude', 'skills', 'teamco', 'code-review', 'SKILL.md'))).toBe(true);
+        expect(fs.existsSync(path.join(homeTmp, '.claude', 'skills', 'teamco', 'pr-summary', 'SKILL.md'))).toBe(true);
+        const lf = loadLockfile();
+        expect(lf.installs.map((i) => i.ref).sort()).toEqual([
+            '@teamco/code-review',
+            '@teamco/eng-skills',
+            '@teamco/pr-summary',
+        ]);
+    });
+    it('emits JSON on --json', async () => {
+        const fm = mockFetch([
+            {
+                url: '/api/skills/alice/x/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'alice', slug: 'x' },
+                        type: 'SKILL',
+                        version: '1.0.0',
+                        sourceEcosystem: null,
+                        files: [],
+                    },
+                },
+            },
+        ]);
+        restoreFetch = fm.restore;
+        await install('@alice/x', { project: tmp.dir, json: true });
+        const out = JSON.parse(captured.stdout[0]);
+        expect(out.ref).toBe('@alice/x');
+        expect(out.installed).toBeDefined();
+    });
+    it('exits 1 on bad ref', async () => {
+        await expect(install('not-a-ref', {})).rejects.toThrow();
+    });
+    it('--clean removes files from the prior install before re-installing', async () => {
+        const dest = path.join(homeTmp, '.claude', 'skills', 'alice', 'x', 'OLD.md');
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, 'old content');
+        const { saveLockfile } = await import('../lib/lockfile.js');
+        saveLockfile({
+            version: 1,
+            installs: [
+                {
+                    ref: '@alice/x',
+                    type: 'SKILL',
+                    version: '1.0.0',
+                    installedAt: 't',
+                    files: [{ src: 'claude/OLD.md', dest, fingerprint: 'old-fp' }],
+                },
+            ],
+        });
+        const fm = mockFetch([
+            {
+                url: '/api/skills/alice/x/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'alice', slug: 'x' },
+                        type: 'SKILL',
+                        version: '2.0.0',
+                        sourceEcosystem: null,
+                        files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/new' }],
+                    },
+                },
+            },
+            { url: '/raw/new', response: { body: 'new content', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        await install('@alice/x', { project: tmp.dir, clean: true });
+        // Old file should be gone, new one should be present
+        expect(fs.existsSync(dest)).toBe(false);
+        expect(fs.existsSync(path.join(homeTmp, '.claude', 'skills', 'alice', 'x', 'SKILL.md'))).toBe(true);
+    });
+    it('--clean cascades file removal across a bundle\'s child skills', async () => {
+        // Pre-populate a bundle and child skill in the lockfile + on disk
+        const childDest = path.join(homeTmp, '.claude', 'skills', 'teamco', 'old-skill', 'SKILL.md');
+        fs.mkdirSync(path.dirname(childDest), { recursive: true });
+        fs.writeFileSync(childDest, 'old child content', 'utf-8');
+        const { saveLockfile } = await import('../lib/lockfile.js');
+        saveLockfile({
+            version: 1,
+            installs: [
+                { ref: '@teamco/eng', type: 'BUNDLE', version: '1.0.0', installedAt: 't', files: [], skills: ['@teamco/old-skill'] },
+                { ref: '@teamco/old-skill', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [{ src: 'claude/SKILL.md', dest: childDest, fingerprint: 'old' }] },
+            ],
+        });
+        // New manifest replaces old-skill with new-skill
+        const fm = mockFetch([
+            {
+                url: '/api/skills/teamco/eng/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'teamco', slug: 'eng' },
+                        type: 'BUNDLE',
+                        version: '1.1.0',
+                        skills: [
+                            {
+                                ref: { username: 'teamco', slug: 'new-skill' },
+                                version: '1.0.0',
+                                sourceEcosystem: 'claude',
+                                files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/new' }],
+                            },
+                        ],
+                    },
+                },
+            },
+            { url: '/raw/new', response: { body: 'new content', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        await install('@teamco/eng', { project: tmp.dir, clean: true });
+        // Old child file should be deleted by the cascade
+        expect(fs.existsSync(childDest)).toBe(false);
+        // New skill installed
+        expect(fs.existsSync(path.join(homeTmp, '.claude', 'skills', 'teamco', 'new-skill', 'SKILL.md'))).toBe(true);
+    });
+    it('--json suppresses the manual-paste console.log for chatgpt files', async () => {
+        const fm = mockFetch([
+            {
+                url: '/api/skills/alice/x/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'alice', slug: 'x' },
+                        type: 'SKILL',
+                        version: '1.0.0',
+                        sourceEcosystem: null,
+                        files: [{ filename: 'chatgpt/instructions.md', rawUrl: 'http://test.local/raw/cg' }],
+                    },
+                },
+            },
+            // Note: under --json, the manual-paste branch should NOT call fetchRawContent at all
+            // (it's wrapped in `if (!options.json)`), so no /raw/cg mock is needed.
+        ]);
+        restoreFetch = fm.restore;
+        await install('@alice/x', { project: tmp.dir, json: true });
+        // stdout has exactly one entry — the JSON output
+        expect(captured.stdout).toHaveLength(1);
+        const out = JSON.parse(captured.stdout[0]);
+        expect(out.ref).toBe('@alice/x');
+        // Verify no manual-paste content leaked into stdout
+        expect(captured.stdout.join('\n')).not.toMatch(/Manual paste required/);
+    });
+    it('invokes syncLibrary after a successful install', async () => {
+        const fm = mockFetch([
+            {
+                url: '/api/skills/alice/x/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'alice', slug: 'x' },
+                        type: 'SKILL',
+                        version: '1.0.0',
+                        sourceEcosystem: null,
+                        files: [],
+                    },
+                },
+            },
+        ]);
+        restoreFetch = fm.restore;
+        await install('@alice/x', { project: tmp.dir });
+        expect(librarySync.syncLibrary).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/commands/list.d.ts

@@ -0,0 +1,6 @@
+interface ListOptions {
+    outdated?: boolean;
+    json?: boolean;
+}
+export declare function list(options: ListOptions): Promise<void>;
+export {};

package/dist/commands/list.js

@@ -0,0 +1,35 @@
+import { loadLockfile } from '../lib/lockfile.js';
+export async function list(options) {
+    const lf = loadLockfile();
+    if (options.json) {
+        console.log(JSON.stringify({ installs: lf.installs }));
+        return;
+    }
+    if (lf.installs.length === 0) {
+        console.log('\n  nothing installed yet — try `botdocs install @user/slug`\n');
+        return;
+    }
+    const bundles = lf.installs.filter((i) => i.type === 'BUNDLE');
+    const skills = lf.installs.filter((i) => i.type === 'SKILL');
+    const skillsByRef = new Map(skills.map((s) => [s.ref, s]));
+    const claimed = new Set();
+    console.log('');
+    for (const bundle of bundles) {
+        console.log(`  ${bundle.ref}  (bundle, v${bundle.version})`);
+        for (const ref of bundle.skills ?? []) {
+            claimed.add(ref);
+            const s = skillsByRef.get(ref);
+            if (s)
+                console.log(`    • ${s.ref}  (v${s.version}, ${s.files.length} file(s))`);
+        }
+        console.log('');
+    }
+    const standalone = skills.filter((s) => !claimed.has(s.ref));
+    if (standalone.length > 0) {
+        console.log('  Standalone skills:');
+        for (const s of standalone) {
+            console.log(`    • ${s.ref}  (v${s.version}, ${s.files.length} file(s))`);
+        }
+        console.log('');
+    }
+}

package/dist/commands/list.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/list.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { list } from './list.js';
+import { captureConsole } from '../test-utils.js';
+import { saveLockfile } from '../lib/lockfile.js';
+describe('list', () => {
+    let captured;
+    const origHome = os.homedir;
+    let homeTmp;
+    beforeEach(() => {
+        homeTmp = fs.mkdtempSync(path.join(os.tmpdir(), 'list-home-'));
+        os.homedir = () => homeTmp;
+        captured = captureConsole();
+    });
+    afterEach(() => {
+        captured.restore();
+        fs.rmSync(homeTmp, { recursive: true, force: true });
+        os.homedir = origHome;
+    });
+    it('says "nothing installed" when lockfile is empty', async () => {
+        await list({});
+        expect(captured.stdout.join('\n')).toMatch(/nothing installed/i);
+    });
+    it('groups skills by their parent bundle', async () => {
+        saveLockfile({
+            version: 1,
+            installs: [
+                { ref: '@a/eng', type: 'BUNDLE', version: '1.0.0', installedAt: 't', files: [], skills: ['@a/cr', '@a/ps'] },
+                { ref: '@a/cr', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] },
+                { ref: '@a/ps', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] },
+                { ref: '@a/standalone', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] },
+            ],
+        });
+        await list({});
+        const out = captured.stdout.join('\n');
+        expect(out).toContain('@a/eng');
+        expect(out).toContain('@a/cr');
+        expect(out).toContain('@a/standalone');
+    });
+    it('emits JSON on --json', async () => {
+        saveLockfile({
+            version: 1,
+            installs: [{ ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] }],
+        });
+        await list({ json: true });
+        const out = JSON.parse(captured.stdout[0]);
+        expect(out.installs).toHaveLength(1);
+    });
+});

package/dist/commands/login.d.ts

@@ -1 +1,5 @@
-export declare function login(): Promise<void>;
+interface LoginOptions {
+    syncLibrary?: boolean;
+}
+export declare function login(options?: LoginOptions): Promise<void>;
+export {};

package/dist/commands/login.js

@@ -1,11 +1,7 @@
 import { saveAuth } from '../lib/config.js';
-const GITHUB_CLIENT_ID = process.env.GITHUB_CLIENT_ID || process.env.GITHUB_ID || '';
-export async function login() {
-    if (!GITHUB_CLIENT_ID) {
-        console.error('Error: GitHub Client ID not configured.\n' +
-            'Set GITHUB_CLIENT_ID or GITHUB_ID environment variable.');
-        process.exit(1);
-    }
+const DEFAULT_GITHUB_CLIENT_ID = 'Ov23lizUYDKJOhumsyee';
+const GITHUB_CLIENT_ID = process.env.GITHUB_CLIENT_ID || process.env.GITHUB_ID || DEFAULT_GITHUB_CLIENT_ID;
+export async function login(options) {
     // Step 1: Request device code
     const deviceResponse = await fetch('https://github.com/login/device/code', {
         method: 'POST',
@@ -64,8 +60,15 @@ export async function login() {
                 githubToken: tokenData.access_token,
                 username: user.login,
                 displayName: user.name || user.login,
+                syncLibrary: options?.syncLibrary === true,
             });
             console.log(`\nAuthenticated as ${user.login}`);
+            if (options?.syncLibrary) {
+                console.log('  Library sync enabled. Your installed-refs list will appear at https://botdocs.ai/library after install/sync/uninstall.');
+            }
+            else {
+                console.log('  Library sync is OFF. Re-run `botdocs login --sync-library` to enable the personalized Library page.');
+            }
             return;
         }
         if (tokenData.error === 'expired_token') {

package/dist/commands/publish.d.ts

@@ -5,6 +5,7 @@ interface PublishOptions {
     tags?: string;
     license?: string;
     json?: boolean;
+    noCompile?: boolean;
 }
 export declare function publish(source: string, options: PublishOptions): Promise<void>;
 export {};

package/dist/commands/publish.js

@@ -2,6 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import AdmZip from 'adm-zip';
 import { apiFetch } from '../lib/api.js';
+import { parseManifest } from '../lib/manifest.js';
+import { compile } from './compile.js';
+import { ecosystemDestination } from '../lib/canonical.js';
 const VALID_CATEGORIES = [
     'KNOWLEDGE_MANAGEMENT',
     'DEV_WORKFLOW',
@@ -21,6 +24,7 @@ export async function publish(source, options) {
     let files;
     const stat = fs.statSync(resolved);
     if (stat.isDirectory()) {
+        await maybeAutoCompile(resolved, options);
         files = collectFromDirectory(resolved);
     }
     else if (resolved.endsWith('.zip')) {
@@ -81,6 +85,39 @@ export async function publish(source, options) {
         console.log(`\nPublished: ${result.url}`);
     }
 }
+async function maybeAutoCompile(source, options) {
+    if (options.noCompile)
+        return;
+    const manifestPath = path.join(source, 'botdocs.json');
+    if (!fs.existsSync(manifestPath))
+        return;
+    let manifest;
+    try {
+        const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        manifest = parseManifest(raw);
+    }
+    catch {
+        return;
+    }
+    if (manifest.type !== 'SKILL' || !manifest.ecosystems || !manifest.sourceEcosystem)
+        return;
+    const sourceEco = manifest.sourceEcosystem;
+    const slug = path.basename(source);
+    const sourceFile = path.join(source, ecosystemDestination(sourceEco, slug));
+    if (!fs.existsSync(sourceFile))
+        return;
+    const sourceMtime = fs.statSync(sourceFile).mtimeMs;
+    const stale = manifest.ecosystems
+        .filter((e) => e !== sourceEco)
+        .some((e) => {
+        const dest = path.join(source, ecosystemDestination(e, slug));
+        return !fs.existsSync(dest) || fs.statSync(dest).mtimeMs < sourceMtime;
+    });
+    if (stale) {
+        console.log('  Auto-compiling stale ecosystem files…');
+        await compile(source, {});
+    }
+}
 function collectFromFile(filePath) {
     const content = fs.readFileSync(filePath, 'utf-8');
     const filename = path.basename(filePath);

package/dist/commands/publish.test.d.ts

@@ -0,0 +1 @@
+export {};