@botdocs/cli 0.2.0 → 0.3.0

package/dist/commands/sync.d.ts

@@ -0,0 +1,7 @@
+interface SyncOptions {
+    yes?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+}
+export declare function sync(rawRef: string | undefined, options: SyncOptions): Promise<void>;
+export {};

package/dist/commands/sync.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ApiError, apiFetch, fetchRawContent } from '../lib/api.js';
+import { loadLockfile, fingerprintFile, upsertInstall } from '../lib/lockfile.js';
+import { renderDiff, hasChanges } from '../lib/diff.js';
+import { promptConflict, confirmOverwrite, promptCleanUpdate } from '../lib/prompts.js';
+import { syncLibrary } from '../lib/library-sync.js';
+async function syncSkill(entry, manifest, options) {
+    let updatedCount = 0;
+    let skippedCount = 0;
+    const newFiles = [];
+    for (const installedFile of entry.files) {
+        const upstream = manifest.files.find((f) => f.filename === installedFile.src);
+        if (!upstream) {
+            // Upstream removed this file — delete the local copy and drop the lockfile entry.
+            if (fs.existsSync(installedFile.dest))
+                fs.unlinkSync(installedFile.dest);
+            console.log(`  ⌀ ${entry.ref}: removed ${installedFile.src} (no longer in upstream)`);
+            // Don't push to newFiles — let it drop from the lockfile.
+            continue;
+        }
+        const upstreamContent = await fetchRawContent(upstream.rawUrl);
+        if (!fs.existsSync(installedFile.dest)) {
+            fs.mkdirSync(path.dirname(installedFile.dest), { recursive: true });
+            fs.writeFileSync(installedFile.dest, upstreamContent, 'utf-8');
+            const fp = fingerprintFile(installedFile.dest);
+            newFiles.push({ ...installedFile, fingerprint: fp });
+            updatedCount++;
+            continue;
+        }
+        const localContent = fs.readFileSync(installedFile.dest, 'utf-8');
+        const localFp = fingerprintFile(installedFile.dest);
+        if (!hasChanges(localContent, upstreamContent)) {
+            newFiles.push({ ...installedFile, fingerprint: localFp });
+            continue;
+        }
+        const localUnchangedSinceLockfile = localFp === installedFile.fingerprint;
+        if (localUnchangedSinceLockfile) {
+            let choice;
+            if (options.yes) {
+                choice = 'apply';
+            }
+            else {
+                choice = await promptCleanUpdate(`${entry.ref}:${installedFile.src}`);
+                while (choice === 'diff') {
+                    console.log(renderDiff(localContent, upstreamContent));
+                    choice = await promptCleanUpdate(`${entry.ref}:${installedFile.src}`);
+                }
+            }
+            if (choice === 'apply') {
+                if (!options.dryRun) {
+                    fs.writeFileSync(installedFile.dest, upstreamContent, 'utf-8');
+                }
+                const fp = options.dryRun ? installedFile.fingerprint : fingerprintFile(installedFile.dest);
+                newFiles.push({ ...installedFile, fingerprint: fp });
+                updatedCount++;
+            }
+            else {
+                newFiles.push(installedFile);
+                skippedCount++;
+            }
+            continue;
+        }
+        // Conflict: local has been edited.
+        console.log(renderDiff(localContent, upstreamContent));
+        const conflict = await promptConflict(`${entry.ref}:${installedFile.src}`);
+        if (conflict === 'skip') {
+            newFiles.push(installedFile);
+            skippedCount++;
+            continue;
+        }
+        const sure = await confirmOverwrite(`${entry.ref}:${installedFile.src}`);
+        if (!sure) {
+            newFiles.push(installedFile);
+            skippedCount++;
+            continue;
+        }
+        if (!options.dryRun) {
+            fs.writeFileSync(installedFile.dest, upstreamContent, 'utf-8');
+        }
+        const fp = options.dryRun ? installedFile.fingerprint : fingerprintFile(installedFile.dest);
+        newFiles.push({ ...installedFile, fingerprint: fp });
+        updatedCount++;
+    }
+    if (!options.dryRun) {
+        // Only bump the lockfile version when no files were skipped — otherwise
+        // the local copy still represents the old version on at least one file.
+        const canBumpVersion = skippedCount === 0;
+        const filesShrunk = newFiles.length < entry.files.length;
+        const shouldWrite = updatedCount > 0 || filesShrunk || (canBumpVersion && manifest.version !== entry.version);
+        if (shouldWrite) {
+            upsertInstall({
+                ...entry,
+                version: canBumpVersion ? manifest.version : entry.version,
+                files: newFiles,
+                installedAt: new Date().toISOString(),
+            });
+        }
+    }
+    return { updated: updatedCount > 0, skipped: skippedCount };
+}
+function refToPath(ref) {
+    const cleaned = ref.startsWith('@') ? ref.slice(1) : ref;
+    const [username, slug] = cleaned.split('/');
+    if (!username || !slug)
+        throw new Error(`Invalid ref in lockfile: ${ref}`);
+    return { username, slug };
+}
+export async function sync(rawRef, options) {
+    const lf = loadLockfile();
+    const targets = rawRef
+        ? lf.installs.filter((i) => i.ref === rawRef)
+        : lf.installs.filter((i) => i.type === 'SKILL');
+    if (targets.length === 0) {
+        console.log('\n  nothing installed to sync\n');
+        await syncLibrary();
+        return;
+    }
+    const summary = [];
+    for (const entry of targets) {
+        if (entry.type !== 'SKILL')
+            continue;
+        const { username, slug } = refToPath(entry.ref);
+        let manifest;
+        try {
+            const resp = await apiFetch(`/api/skills/${username}/${slug}/manifest`);
+            if (resp.type !== 'SKILL')
+                continue;
+            manifest = resp;
+        }
+        catch (err) {
+            if (err instanceof ApiError) {
+                if (err.status === 401) {
+                    console.error('\n  ✗ Not authenticated. Run `botdocs login` first.\n');
+                    process.exit(1);
+                }
+                summary.push({ ref: entry.ref, status: 'skipped' });
+                continue;
+            }
+            throw err;
+        }
+        const { updated, skipped } = await syncSkill(entry, manifest, options);
+        summary.push({ ref: entry.ref, status: updated ? 'updated' : skipped > 0 ? 'skipped' : 'up-to-date' });
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ summary }));
+        await syncLibrary();
+        return;
+    }
+    console.log('');
+    for (const s of summary) {
+        if (s.status === 'up-to-date')
+            console.log(`  ✓ ${s.ref}: up to date`);
+        else if (s.status === 'updated')
+            console.log(`  ✓ ${s.ref}: updated`);
+        else
+            console.log(`  ⌀ ${s.ref}: changes skipped`);
+    }
+    console.log('');
+    await syncLibrary();
+}

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

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

package/dist/commands/sync.test.js

@@ -0,0 +1,263 @@
+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 { sync } from './sync.js';
+import { captureConsole, mockFetch, withTempDir } from '../test-utils.js';
+import { loadLockfile, saveLockfile } from '../lib/lockfile.js';
+vi.mock('../lib/prompts.js', () => ({
+    promptCleanUpdate: vi.fn(),
+    promptConflict: vi.fn(),
+    confirmOverwrite: vi.fn(),
+}));
+vi.mock('../lib/library-sync.js', () => ({
+    syncLibrary: vi.fn(),
+}));
+import * as prompts from '../lib/prompts.js';
+import * as librarySync from '../lib/library-sync.js';
+describe('sync', () => {
+    let tmp;
+    let captured;
+    let restoreFetch = () => { };
+    const origHome = os.homedir;
+    let homeTmp;
+    beforeEach(() => {
+        tmp = withTempDir();
+        homeTmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sync-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.resetAllMocks();
+    });
+    it('reports up-to-date when fingerprints match upstream', async () => {
+        const dest = path.join(homeTmp, '.claude', 'skills', 'a', 'x', 'SKILL.md');
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, 'body', 'utf-8');
+        const { fingerprintFile } = await import('../lib/lockfile.js');
+        const fp = fingerprintFile(dest);
+        saveLockfile({
+            version: 1,
+            installs: [{ ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [{ src: 'claude/SKILL.md', dest, fingerprint: fp }] }],
+        });
+        const fm = mockFetch([
+            {
+                url: '/api/skills/a/x/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'a', slug: 'x' },
+                        type: 'SKILL',
+                        version: '1.0.0',
+                        sourceEcosystem: null,
+                        files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/x' }],
+                    },
+                },
+            },
+            { url: '/raw/x', response: { body: 'body', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        await sync(undefined, { yes: true });
+        expect(captured.stdout.join('\n')).toMatch(/up to date/i);
+    });
+    it('overwrites local when upstream changed and double-confirm passes', async () => {
+        const dest = path.join(homeTmp, '.claude', 'skills', 'a', 'x', 'SKILL.md');
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, 'local edits here\n', 'utf-8');
+        saveLockfile({
+            version: 1,
+            installs: [{
+                    ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't',
+                    files: [{ src: 'claude/SKILL.md', dest, fingerprint: 'OLD_FINGERPRINT_THAT_DIFFERS' }],
+                }],
+        });
+        const fm = mockFetch([
+            {
+                url: '/api/skills/a/x/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'a', slug: 'x' },
+                        type: 'SKILL',
+                        version: '1.1.0',
+                        sourceEcosystem: null,
+                        files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/x' }],
+                    },
+                },
+            },
+            { url: '/raw/x', response: { body: 'upstream new content\n', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        vi.mocked(prompts.promptConflict).mockResolvedValue('overwrite');
+        vi.mocked(prompts.confirmOverwrite).mockResolvedValue(true);
+        await sync(undefined, {});
+        expect(fs.readFileSync(dest, 'utf-8')).toBe('upstream new content\n');
+        expect(loadLockfile().installs[0].version).toBe('1.1.0');
+    });
+    it('skips local when user picks skip', async () => {
+        const dest = path.join(homeTmp, '.claude', 'skills', 'a', 'x', 'SKILL.md');
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, 'local edits\n', 'utf-8');
+        saveLockfile({
+            version: 1,
+            installs: [{
+                    ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't',
+                    files: [{ src: 'claude/SKILL.md', dest, fingerprint: 'OLD' }],
+                }],
+        });
+        const fm = mockFetch([
+            {
+                url: '/api/skills/a/x/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'a', slug: 'x' },
+                        type: 'SKILL',
+                        version: '1.1.0',
+                        sourceEcosystem: null,
+                        files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/x' }],
+                    },
+                },
+            },
+            { url: '/raw/x', response: { body: 'upstream', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        vi.mocked(prompts.promptConflict).mockResolvedValue('skip');
+        await sync(undefined, {});
+        expect(fs.readFileSync(dest, 'utf-8')).toBe('local edits\n');
+        expect(loadLockfile().installs[0].version).toBe('1.0.0');
+    });
+    it('overwrite with explicit double-confirm cancellation skips the file', async () => {
+        const dest = path.join(homeTmp, '.claude', 'skills', 'a', 'x', 'SKILL.md');
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, 'local\n', 'utf-8');
+        saveLockfile({
+            version: 1,
+            installs: [{ ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [{ src: 'claude/SKILL.md', dest, fingerprint: 'OLD' }] }],
+        });
+        const fm = mockFetch([
+            {
+                url: '/api/skills/a/x/manifest',
+                response: {
+                    body: { ref: { username: 'a', slug: 'x' }, type: 'SKILL', version: '1.1.0', sourceEcosystem: null, files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/x' }] },
+                },
+            },
+            { url: '/raw/x', response: { body: 'upstream', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        vi.mocked(prompts.promptConflict).mockResolvedValue('overwrite');
+        vi.mocked(prompts.confirmOverwrite).mockResolvedValue(false);
+        await sync(undefined, {});
+        expect(fs.readFileSync(dest, 'utf-8')).toBe('local\n');
+    });
+    it('removes local files that no longer exist upstream and drops the lockfile entry', async () => {
+        const dest = path.join(homeTmp, '.claude', 'skills', 'a', 'x', 'OLD.md');
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, 'old', 'utf-8');
+        const { fingerprintFile } = await import('../lib/lockfile.js');
+        const fp = fingerprintFile(dest);
+        saveLockfile({
+            version: 1,
+            installs: [{
+                    ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't',
+                    files: [{ src: 'claude/OLD.md', dest, fingerprint: fp }],
+                }],
+        });
+        const fm = mockFetch([
+            {
+                url: '/api/skills/a/x/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'a', slug: 'x' },
+                        type: 'SKILL',
+                        version: '1.1.0',
+                        sourceEcosystem: null,
+                        // OLD.md no longer in upstream — manifest has zero files
+                        files: [],
+                    },
+                },
+            },
+        ]);
+        restoreFetch = fm.restore;
+        await sync(undefined, { yes: true });
+        expect(fs.existsSync(dest)).toBe(false);
+        // The lockfile entry's files array should now be empty
+        expect(loadLockfile().installs[0].files).toHaveLength(0);
+    });
+    it('exits 1 with a login hint when the manifest endpoint returns 401', async () => {
+        saveLockfile({
+            version: 1,
+            installs: [{ ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] }],
+        });
+        const fm = mockFetch([
+            {
+                url: '/api/skills/a/x/manifest',
+                response: { status: 401, body: { error: 'Unauthorized' } },
+            },
+        ]);
+        restoreFetch = fm.restore;
+        await expect(sync(undefined, {})).rejects.toThrow();
+        expect(captured.stderr.join('\n')).toMatch(/botdocs login/);
+    });
+    it('--dry-run does not write to disk on conflict overwrite', async () => {
+        const dest = path.join(homeTmp, '.claude', 'skills', 'a', 'x', 'SKILL.md');
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, 'local edits\n', 'utf-8');
+        saveLockfile({
+            version: 1,
+            installs: [{
+                    ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't',
+                    files: [{ src: 'claude/SKILL.md', dest, fingerprint: 'OLD' }],
+                }],
+        });
+        const fm = mockFetch([
+            {
+                url: '/api/skills/a/x/manifest',
+                response: {
+                    body: { ref: { username: 'a', slug: 'x' }, type: 'SKILL', version: '1.1.0', sourceEcosystem: null, files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/x' }] },
+                },
+            },
+            { url: '/raw/x', response: { body: 'upstream', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        vi.mocked(prompts.promptConflict).mockResolvedValue('overwrite');
+        vi.mocked(prompts.confirmOverwrite).mockResolvedValue(true);
+        await sync(undefined, { dryRun: true });
+        // File on disk should be unchanged
+        expect(fs.readFileSync(dest, 'utf-8')).toBe('local edits\n');
+        // Lockfile version should NOT have been bumped (dry-run = no upsert)
+        expect(loadLockfile().installs[0].version).toBe('1.0.0');
+    });
+    it('invokes syncLibrary after a successful sync', async () => {
+        const dest = path.join(homeTmp, '.claude', 'skills', 'a', 'x', 'SKILL.md');
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, 'body', 'utf-8');
+        const { fingerprintFile } = await import('../lib/lockfile.js');
+        const fp = fingerprintFile(dest);
+        saveLockfile({
+            version: 1,
+            installs: [{ ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [{ src: 'claude/SKILL.md', dest, fingerprint: fp }] }],
+        });
+        const fm = mockFetch([
+            {
+                url: '/api/skills/a/x/manifest',
+                response: {
+                    body: {
+                        ref: { username: 'a', slug: 'x' },
+                        type: 'SKILL',
+                        version: '1.0.0',
+                        sourceEcosystem: null,
+                        files: [{ filename: 'claude/SKILL.md', rawUrl: 'http://test.local/raw/x' }],
+                    },
+                },
+            },
+            { url: '/raw/x', response: { body: 'body', contentType: 'text/plain' } },
+        ]);
+        restoreFetch = fm.restore;
+        await sync(undefined, { yes: true });
+        expect(librarySync.syncLibrary).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/commands/uninstall.d.ts

@@ -0,0 +1,5 @@
+interface UninstallOptions {
+    json?: boolean;
+}
+export declare function uninstall(rawRef: string, options: UninstallOptions): Promise<void>;
+export {};

package/dist/commands/uninstall.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import { loadLockfile, removeInstall } from '../lib/lockfile.js';
+import { syncLibrary } from '../lib/library-sync.js';
+export async function uninstall(rawRef, options) {
+    const lf = loadLockfile();
+    const entry = lf.installs.find((i) => i.ref === rawRef);
+    if (!entry) {
+        console.error(`\n  ✗ Not installed: ${rawRef}\n`);
+        process.exit(1);
+    }
+    const refsToRemove = entry.type === 'BUNDLE'
+        ? [entry.ref, ...(entry.skills ?? [])]
+        : [entry.ref];
+    for (const ref of refsToRemove) {
+        const e = lf.installs.find((i) => i.ref === ref);
+        if (!e)
+            continue;
+        for (const f of e.files) {
+            if (fs.existsSync(f.dest))
+                fs.unlinkSync(f.dest);
+        }
+        removeInstall(ref);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ uninstalled: refsToRemove }));
+        await syncLibrary();
+        return;
+    }
+    console.log(`\n  ✓ Uninstalled ${rawRef}\n`);
+    await syncLibrary();
+}

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

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

package/dist/commands/uninstall.test.js

@@ -0,0 +1,67 @@
+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 { uninstall } from './uninstall.js';
+import { captureConsole } from '../test-utils.js';
+import { saveLockfile, loadLockfile } from '../lib/lockfile.js';
+vi.mock('../lib/library-sync.js', () => ({
+    syncLibrary: vi.fn(),
+}));
+import * as librarySync from '../lib/library-sync.js';
+describe('uninstall', () => {
+    let captured;
+    const origHome = os.homedir;
+    let homeTmp;
+    beforeEach(() => {
+        homeTmp = fs.mkdtempSync(path.join(os.tmpdir(), 'uninstall-'));
+        os.homedir = () => homeTmp;
+        captured = captureConsole();
+        vi.mocked(librarySync.syncLibrary).mockClear();
+    });
+    afterEach(() => {
+        captured.restore();
+        fs.rmSync(homeTmp, { recursive: true, force: true });
+        os.homedir = origHome;
+    });
+    it('removes the lockfile entry and deletes installed files', async () => {
+        const fileDest = path.join(homeTmp, 'fake-installed.md');
+        fs.writeFileSync(fileDest, 'body', 'utf-8');
+        saveLockfile({
+            version: 1,
+            installs: [
+                { ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [{ src: 's', dest: fileDest, fingerprint: 'f' }] },
+            ],
+        });
+        await uninstall('@a/x', {});
+        expect(fs.existsSync(fileDest)).toBe(false);
+        expect(loadLockfile().installs).toHaveLength(0);
+    });
+    it('uninstalls a bundle and all its child skills', async () => {
+        saveLockfile({
+            version: 1,
+            installs: [
+                { ref: '@a/eng', type: 'BUNDLE', version: '1.0.0', installedAt: 't', files: [], skills: ['@a/cr'] },
+                { ref: '@a/cr', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] },
+            ],
+        });
+        await uninstall('@a/eng', {});
+        expect(loadLockfile().installs).toHaveLength(0);
+    });
+    it('errors when ref is not installed', async () => {
+        saveLockfile({ version: 1, installs: [] });
+        await expect(uninstall('@a/nope', {})).rejects.toThrow();
+    });
+    it('invokes syncLibrary after a successful uninstall', async () => {
+        const fileDest = path.join(homeTmp, 'fake-installed.md');
+        fs.writeFileSync(fileDest, 'body', 'utf-8');
+        saveLockfile({
+            version: 1,
+            installs: [
+                { ref: '@a/x', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [{ src: 's', dest: fileDest, fingerprint: 'f' }] },
+            ],
+        });
+        await uninstall('@a/x', {});
+        expect(librarySync.syncLibrary).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/commands/validate.js

@@ -1,5 +1,6 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { join, extname } from 'path';
+import { parseManifest, ManifestError } from '../lib/manifest.js';
 export async function validate(source, options) {
     const errors = [];
     const stat = statSync(source, { throwIfNoEntry: false });
@@ -19,15 +20,29 @@ export async function validate(source, options) {
             errors.push({ file: 'index.md', message: 'Missing index.md (required entry point)', severity: 'error' });
         }
         if (existsSync(join(source, 'botdocs.json'))) {
+            let raw;
             try {
-                const meta = JSON.parse(readFileSync(join(source, 'botdocs.json'), 'utf-8'));
-                if (!meta.title)
-                    errors.push({ file: 'botdocs.json', message: 'Missing title', severity: 'error' });
-                if (!meta.description)
-                    errors.push({ file: 'botdocs.json', message: 'Missing description', severity: 'warning' });
+                raw = JSON.parse(readFileSync(join(source, 'botdocs.json'), 'utf-8'));
             }
             catch {
                 errors.push({ file: 'botdocs.json', message: 'Invalid JSON', severity: 'error' });
+                raw = null;
+            }
+            if (raw !== null) {
+                try {
+                    const parsed = parseManifest(raw);
+                    if (!parsed.description) {
+                        errors.push({ file: 'botdocs.json', message: 'Missing description', severity: 'warning' });
+                    }
+                }
+                catch (err) {
+                    if (err instanceof ManifestError) {
+                        errors.push({ file: 'botdocs.json', message: err.message, severity: 'error' });
+                    }
+                    else {
+                        throw err; // unexpected error type; let it bubble so the user sees a real stack
+                    }
+                }
             }
         }
         else {