@botdocs/cli 0.2.0

package/README.md

@@ -0,0 +1,118 @@
+# botdocs
+
+The official CLI for [BotDocs](https://botdocs.ai) — clone, search,
+publish, and endorse concept specifications.
+
+A BotDoc is a structured spec an AI agent can build from. This CLI is the
+fastest way to pull one onto your machine, ship one of your own, or report
+back after you've built something on top.
+
+## Install
+
+```bash
+# one-off
+npx @botdocs/cli <command>
+
+# global (preferred — gives you the `botdocs` command)
+npm i -g @botdocs/cli
+# or
+pnpm add -g @botdocs/cli
+```
+
+After a global install the binary is just `botdocs`:
+
+```bash
+botdocs --help
+```
+
+Requires Node.js 20 or newer.
+
+## Quick start
+
+```bash
+# scaffold a new spec in ./my-spec/
+botdocs init my-spec
+
+# validate before publishing
+botdocs validate my-spec/
+
+# log in (GitHub device code, one time)
+botdocs login
+
+# publish from a directory
+botdocs publish my-spec/
+
+# clone someone else's spec
+botdocs clone @alice/agent-router
+
+# tell them how it went after you built from it
+botdocs endorse @alice/agent-router --rating positive \
+  --comment "Built a working POC in 40 minutes."
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `init [name]` | Scaffold a new BotDoc directory with an `index.md` template. |
+| `validate <source>` | Pre-publish structural check on a directory or file. |
+| `clone <user/slug>` | Download every file in a BotDoc to a local directory. |
+| `search <query>` | Search the public registry. |
+| `publish <source>` | Publish from a file, directory, or zip archive. |
+| `diff <user/slug>` | Preview remote changes before pulling. |
+| `pull <user/slug>` | Update a previously-cloned BotDoc. |
+| `endorse <user/slug>` | Rate a BotDoc after you've built from it (requires a prior clone). |
+| `login` | Authenticate via the GitHub device-code flow. |
+| `whoami` | Show the currently authenticated user. |
+
+Every command accepts `--json` for machine-readable output.
+
+Run `botdocs <command> --help` for full flags on any command.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `BOTDOCS_API_URL` | `https://botdocs.ai` | Override the registry API endpoint (useful for local development). |
+
+Auth is stored at `~/.botdocs/auth.json` after `botdocs login`. Delete it
+to log out.
+
+## Endorsing
+
+Endorsements are reserved for builders who actually used the spec — the
+server will reject an endorsement if it can't see a prior clone from the
+same account. If you hit that error the CLI will point you at:
+
+```bash
+botdocs clone @user/slug
+```
+
+…build something on top, then come back and run `endorse`.
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter @botdocs/cli build       # tsc -> dist/
+pnpm --filter @botdocs/cli test        # vitest
+pnpm --filter @botdocs/cli typecheck
+```
+
+## Releasing
+
+Versioning and publishing run on
+[changesets](https://github.com/changesets/changesets):
+
+1. After making changes, run `pnpm changeset` from the repo root. Pick
+   `@botdocs/cli`, choose patch/minor/major, write a one-line summary.
+2. Commit the generated `.changeset/<slug>.md` along with your code.
+3. When your PR merges to `master`, a "Version Packages" PR is opened
+   automatically with the bumped version and CHANGELOG entries.
+4. Reviewing and merging that PR triggers `npm publish` from CI.
+
+No manual tagging or version bumps required.
+
+## License
+
+MIT © BotDocs contributors

package/dist/commands/clone.d.ts

@@ -0,0 +1,3 @@
+export declare function clone(ref: string, options?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/clone.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { apiFetch, fetchRawContent } from '../lib/api.js';
+export async function clone(ref, options = {}) {
+    const parsed = parseRef(ref);
+    if (!parsed) {
+        console.error('Invalid reference. Use format: username/slug');
+        process.exit(1);
+    }
+    const { username, slug } = parsed;
+    // Fetch manifest
+    console.log(`Fetching ${username}/${slug}...`);
+    let manifest;
+    try {
+        manifest = await apiFetch(`/@${username}/${slug}/manifest`);
+    }
+    catch {
+        console.error(`BotDoc not found: ${username}/${slug}`);
+        process.exit(1);
+    }
+    // Create output directory
+    const outDir = path.resolve(slug);
+    if (fs.existsSync(outDir)) {
+        console.error(`Directory already exists: ${slug}/`);
+        console.error('Use `botdocs pull` to update existing clones.');
+        process.exit(1);
+    }
+    fs.mkdirSync(outDir, { recursive: true });
+    // Download all files
+    for (const file of manifest.files) {
+        console.log(`  ${file.filename}`);
+        const content = await fetchRawContent(file.rawUrl);
+        fs.writeFileSync(path.join(outDir, file.filename), content, 'utf-8');
+    }
+    // Save metadata for pull
+    const metadata = {
+        username,
+        slug,
+        clonedAt: new Date().toISOString(),
+        files: manifest.files.map((f) => f.filename),
+    };
+    fs.writeFileSync(path.join(outDir, '.botdocs.json'), JSON.stringify(metadata, null, 2), 'utf-8');
+    // Record clone on server
+    try {
+        await apiFetch('/api/cli/clone', {
+            method: 'POST',
+            body: { username, slug },
+        });
+    }
+    catch {
+        // Non-fatal — clone succeeded locally even if recording fails
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ success: true, directory: slug, files: manifest.files.map(f => f.filename) }));
+    }
+    else {
+        console.log(`\nCloned ${manifest.files.length} file(s) to ./${slug}/`);
+        console.log('');
+        console.log(`  After building from this BotDoc, share your experience:`);
+        console.log(`  botdocs endorse ${ref} --rating positive`);
+    }
+}
+function parseRef(ref) {
+    // Accept: username/slug or @username/slug
+    const cleaned = ref.startsWith('@') ? ref.slice(1) : ref;
+    const parts = cleaned.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        return null;
+    return { username: parts[0], slug: parts[1] };
+}

package/dist/commands/diff.d.ts

@@ -0,0 +1,3 @@
+export declare function diff(ref: string, options: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/diff.js

@@ -0,0 +1,65 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { apiFetch, fetchRawContent } from '../lib/api.js';
+export async function diff(ref, options) {
+    const parts = ref.replace(/^@/, '').split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        console.error('Usage: botdocs diff <username/slug>');
+        process.exit(1);
+    }
+    const [username, slug] = parts;
+    const localDir = join(process.cwd(), slug);
+    if (!existsSync(localDir)) {
+        console.error(`No local directory found: ${slug}/`);
+        console.error(`Run 'botdocs clone ${ref}' first.`);
+        process.exit(1);
+    }
+    const manifest = await apiFetch(`/@${username}/${slug}/manifest`);
+    const changes = [];
+    const localFiles = new Set();
+    const metaPath = join(localDir, '.botdocs.json');
+    if (existsSync(metaPath)) {
+        const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
+        if (meta.files) {
+            for (const f of meta.files) {
+                localFiles.add(f);
+            }
+        }
+    }
+    for (const remoteFile of manifest.files) {
+        const localPath = join(localDir, remoteFile.filename);
+        if (!existsSync(localPath)) {
+            changes.push({ filename: remoteFile.filename, status: 'added' });
+            continue;
+        }
+        const localContent = readFileSync(localPath, 'utf-8');
+        const remoteContent = await fetchRawContent(remoteFile.rawUrl);
+        if (localContent !== remoteContent) {
+            changes.push({ filename: remoteFile.filename, status: 'modified' });
+        }
+        else {
+            changes.push({ filename: remoteFile.filename, status: 'unchanged' });
+        }
+        localFiles.delete(remoteFile.filename);
+    }
+    for (const filename of localFiles) {
+        if (filename === '.botdocs.json')
+            continue;
+        changes.push({ filename, status: 'removed' });
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ref, changes }));
+        return;
+    }
+    const modified = changes.filter((c) => c.status !== 'unchanged');
+    if (modified.length === 0) {
+        console.log('\n  Up to date — no remote changes.\n');
+        return;
+    }
+    console.log('');
+    for (const change of modified) {
+        const icon = change.status === 'added' ? '+' : change.status === 'removed' ? '-' : '~';
+        console.log(`  ${icon} ${change.filename}`);
+    }
+    console.log(`\n  ${modified.length} file(s) changed. Run 'botdocs pull ${ref}' to update.\n`);
+}

package/dist/commands/endorse.d.ts

@@ -0,0 +1,7 @@
+interface EndorseOptions {
+    rating: string;
+    comment?: string;
+    json?: boolean;
+}
+export declare function endorse(ref: string, options: EndorseOptions): Promise<void>;
+export {};

package/dist/commands/endorse.js

@@ -0,0 +1,70 @@
+import { ApiError, apiFetch } from '../lib/api.js';
+const VALID_RATINGS = ['positive', 'neutral', 'negative'];
+function parseRef(ref) {
+    const parts = ref.replace(/^@/, '').split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        return null;
+    return { username: parts[0], slug: parts[1] };
+}
+/** Treat any 403 whose message mentions "clone" as the server's
+ * clone-required guard. The web detail page surfaces the same hint inline;
+ * here we point users at the CLI command that fixes it. */
+function isCloneRequired(err) {
+    return err.status === 403 && /clone/i.test(err.message);
+}
+export async function endorse(ref, options) {
+    const parsed = parseRef(ref);
+    if (!parsed) {
+        console.error('Usage: botdocs endorse <username/slug> --rating <positive|neutral|negative>');
+        process.exit(1);
+    }
+    const { username, slug } = parsed;
+    const rating = options.rating?.toLowerCase();
+    if (!rating || !VALID_RATINGS.includes(rating)) {
+        console.error('Rating must be: positive, neutral, or negative');
+        process.exit(1);
+    }
+    let result;
+    try {
+        result = await apiFetch(`/api/endorsements/${username}/${slug}`, {
+            method: 'POST',
+            body: {
+                rating: rating.toUpperCase(),
+                comment: options.comment,
+                source: 'CLI',
+            },
+            auth: true,
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiError) {
+            if (isCloneRequired(err)) {
+                console.error(`\n  ✗ ${err.message}\n` +
+                    `\n    Endorsements are reserved for builders who actually used the spec. Run:\n` +
+                    `      botdocs clone @${username}/${slug}\n` +
+                    `    …build something on top, then come back and endorse it.\n`);
+                process.exit(1);
+            }
+            if (err.status === 401) {
+                console.error('\n  ✗ Not authenticated. Run `botdocs login` first.\n');
+                process.exit(1);
+            }
+            if (err.status === 404) {
+                console.error(`\n  ✗ BotDoc not found: @${username}/${slug}\n`);
+                process.exit(1);
+            }
+            console.error(`\n  ✗ ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(result));
+        return;
+    }
+    console.log(`\n  ✓ Endorsed @${username}/${slug} as ${rating}.`);
+    if (options.comment) {
+        console.log(`    Comment: "${options.comment}"`);
+    }
+    console.log('');
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,7 @@
+interface InitOptions {
+    title?: string;
+    category?: string;
+    json?: boolean;
+}
+export declare function init(dirName: string | undefined, options: InitOptions): Promise<void>;
+export {};

package/dist/commands/init.js

@@ -0,0 +1,57 @@
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+export async function init(dirName, options) {
+    const name = dirName || 'my-botdoc';
+    const dir = join(process.cwd(), name);
+    if (existsSync(dir)) {
+        if (options.json) {
+            console.log(JSON.stringify({ error: `Directory ${name} already exists` }));
+        }
+        else {
+            console.error(`Error: Directory ${name} already exists.`);
+        }
+        process.exit(1);
+    }
+    mkdirSync(dir, { recursive: true });
+    const title = options.title || name.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+    const indexContent = `# ${title}
+
+## Overview
+
+Describe what this concept specification is about. What problem does it solve? What should an agent build from it?
+
+## Architecture
+
+Describe the high-level architecture. What are the main components? How do they interact?
+
+## Features
+
+List the key features this system should have.
+
+## Data Model
+
+Describe the entities and their relationships.
+
+## Success Criteria
+
+How do you know when an implementation of this spec is correct?
+`;
+    writeFileSync(join(dir, 'index.md'), indexContent, 'utf-8');
+    const botdocsJson = {
+        title,
+        description: '',
+        category: options.category?.toUpperCase() || 'OTHER',
+        tags: [],
+        license: 'MIT',
+    };
+    writeFileSync(join(dir, 'botdocs.json'), JSON.stringify(botdocsJson, null, 2), 'utf-8');
+    if (options.json) {
+        console.log(JSON.stringify({ success: true, directory: name, files: ['index.md', 'botdocs.json'] }));
+    }
+    else {
+        console.log(`\n  Created ${name}/`);
+        console.log(`    index.md       — your spec starts here`);
+        console.log(`    botdocs.json   — metadata for publishing`);
+        console.log(`\n  Next: edit index.md, then run botdocs publish ${name}/\n`);
+    }
+}

package/dist/commands/login.d.ts

@@ -0,0 +1 @@
+export declare function login(): Promise<void>;

package/dist/commands/login.js

@@ -0,0 +1,84 @@
+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);
+    }
+    // Step 1: Request device code
+    const deviceResponse = await fetch('https://github.com/login/device/code', {
+        method: 'POST',
+        headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            client_id: GITHUB_CLIENT_ID,
+            scope: 'read:user',
+        }),
+    });
+    if (!deviceResponse.ok) {
+        console.error('Failed to initiate device code flow.');
+        process.exit(1);
+    }
+    const deviceData = (await deviceResponse.json());
+    // Step 2: Display user code
+    console.log('\nTo authenticate, visit:');
+    console.log(`\n  ${deviceData.verification_uri}\n`);
+    console.log(`Enter code: ${deviceData.user_code}\n`);
+    console.log('Waiting for authorization...');
+    // Step 3: Poll for token
+    const interval = (deviceData.interval || 5) * 1000;
+    const expiresAt = Date.now() + deviceData.expires_in * 1000;
+    while (Date.now() < expiresAt) {
+        await new Promise((resolve) => setTimeout(resolve, interval));
+        const tokenResponse = await fetch('https://github.com/login/oauth/access_token', {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                client_id: GITHUB_CLIENT_ID,
+                device_code: deviceData.device_code,
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            }),
+        });
+        const tokenData = (await tokenResponse.json());
+        if (tokenData.access_token) {
+            // Step 4: Get user info
+            const userResponse = await fetch('https://api.github.com/user', {
+                headers: {
+                    Authorization: `Bearer ${tokenData.access_token}`,
+                    Accept: 'application/vnd.github+json',
+                },
+            });
+            if (!userResponse.ok) {
+                console.error('Failed to get user info from GitHub.');
+                process.exit(1);
+            }
+            const user = (await userResponse.json());
+            // Step 5: Save credentials
+            saveAuth({
+                githubToken: tokenData.access_token,
+                username: user.login,
+                displayName: user.name || user.login,
+            });
+            console.log(`\nAuthenticated as ${user.login}`);
+            return;
+        }
+        if (tokenData.error === 'expired_token') {
+            console.error('\nDevice code expired. Please try again.');
+            process.exit(1);
+        }
+        if (tokenData.error &&
+            tokenData.error !== 'authorization_pending' &&
+            tokenData.error !== 'slow_down') {
+            console.error(`\nAuthentication error: ${tokenData.error_description || tokenData.error}`);
+            process.exit(1);
+        }
+    }
+    console.error('\nAuthentication timed out. Please try again.');
+    process.exit(1);
+}

package/dist/commands/publish.d.ts

@@ -0,0 +1,10 @@
+interface PublishOptions {
+    title?: string;
+    description?: string;
+    category?: string;
+    tags?: string;
+    license?: string;
+    json?: boolean;
+}
+export declare function publish(source: string, options: PublishOptions): Promise<void>;
+export {};

package/dist/commands/publish.js

@@ -0,0 +1,172 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import AdmZip from 'adm-zip';
+import { apiFetch } from '../lib/api.js';
+const VALID_CATEGORIES = [
+    'KNOWLEDGE_MANAGEMENT',
+    'DEV_WORKFLOW',
+    'AUTOMATION',
+    'AGENT_CONFIG',
+    'PROJECT_SCAFFOLD',
+    'OTHER',
+];
+const VALID_LICENSES = ['MIT', 'CC_BY_4_0', 'CC_BY_SA_4_0', 'CC0', 'ALL_RIGHTS_RESERVED'];
+export async function publish(source, options) {
+    const resolved = path.resolve(source);
+    if (!fs.existsSync(resolved)) {
+        console.error(`Source not found: ${source}`);
+        process.exit(1);
+    }
+    // Determine source type and collect files
+    let files;
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        files = collectFromDirectory(resolved);
+    }
+    else if (resolved.endsWith('.zip')) {
+        files = collectFromZip(resolved);
+    }
+    else {
+        // Single markdown file
+        files = collectFromFile(resolved);
+    }
+    if (files.length === 0) {
+        console.error('No markdown files found.');
+        process.exit(1);
+    }
+    // Ensure index.md exists
+    const hasIndex = files.some((f) => f.filename === 'index.md');
+    if (!hasIndex) {
+        // For single file, rename to index.md
+        if (files.length === 1) {
+            files[0].filename = 'index.md';
+        }
+        else {
+            console.error('Multi-file BotDocs must include an index.md file.');
+            process.exit(1);
+        }
+    }
+    // Resolve metadata from flags
+    const title = options.title || deriveTitle(source, files);
+    const description = options.description || '';
+    const category = resolveCategory(options.category);
+    const tags = options.tags
+        ? options.tags
+            .split(',')
+            .map((t) => t.trim())
+            .filter(Boolean)
+        : [];
+    const license = resolveLicense(options.license);
+    if (!description) {
+        console.error('Description is required. Use --description "..."');
+        process.exit(1);
+    }
+    console.log(`Publishing "${title}" (${files.length} file(s))...`);
+    const result = await apiFetch('/api/botdocs', {
+        method: 'POST',
+        auth: true,
+        body: {
+            title,
+            description,
+            category,
+            tags,
+            license,
+            files,
+        },
+    });
+    if (options.json) {
+        console.log(JSON.stringify(result));
+    }
+    else {
+        console.log(`\nPublished: ${result.url}`);
+    }
+}
+function collectFromFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const filename = path.basename(filePath);
+    return [{ filename, content, sortOrder: 0 }];
+}
+function collectFromDirectory(dirPath) {
+    const entries = fs.readdirSync(dirPath);
+    const files = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry.startsWith('.'))
+            continue;
+        const fullPath = path.join(dirPath, entry);
+        const stat = fs.statSync(fullPath);
+        if (stat.isFile() && (entry.endsWith('.md') || entry.endsWith('.markdown'))) {
+            files.push({
+                filename: entry,
+                content: fs.readFileSync(fullPath, 'utf-8'),
+                sortOrder: entry === 'index.md' ? 0 : i + 1,
+            });
+        }
+    }
+    // Ensure index.md is first
+    files.sort((a, b) => a.sortOrder - b.sortOrder);
+    return files;
+}
+function collectFromZip(zipPath) {
+    const zip = new AdmZip(zipPath);
+    const entries = zip.getEntries();
+    const files = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry.isDirectory)
+            continue;
+        // Get the filename (strip any directory prefix)
+        const filename = path.basename(entry.entryName);
+        if (!filename.endsWith('.md') && !filename.endsWith('.markdown'))
+            continue;
+        if (filename.startsWith('.'))
+            continue;
+        files.push({
+            filename,
+            content: entry.getData().toString('utf-8'),
+            sortOrder: filename === 'index.md' ? 0 : i + 1,
+        });
+    }
+    files.sort((a, b) => a.sortOrder - b.sortOrder);
+    return files;
+}
+function deriveTitle(source, files) {
+    // Try to extract title from first heading in index.md
+    const indexFile = files.find((f) => f.filename === 'index.md');
+    if (indexFile) {
+        const match = indexFile.content.match(/^#\s+(.+)$/m);
+        if (match?.[1])
+            return match[1].trim();
+    }
+    // Fall back to source name
+    const basename = path.basename(source, path.extname(source));
+    return basename.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function resolveCategory(input) {
+    if (!input)
+        return 'OTHER';
+    const upper = input.toUpperCase().replace(/[\s-]/g, '_');
+    // Try exact match
+    if (VALID_CATEGORIES.includes(upper))
+        return upper;
+    // Try fuzzy match
+    const found = VALID_CATEGORIES.find((c) => c.includes(upper) || upper.includes(c));
+    return found ?? 'OTHER';
+}
+function resolveLicense(input) {
+    if (!input)
+        return 'MIT';
+    const upper = input.toUpperCase().replace(/[\s-]/g, '_');
+    if (VALID_LICENSES.includes(upper))
+        return upper;
+    // Common aliases
+    const aliases = {
+        CC_BY: 'CC_BY_4_0',
+        'CC-BY': 'CC_BY_4_0',
+        CC_BY_SA: 'CC_BY_SA_4_0',
+        'CC-BY-SA': 'CC_BY_SA_4_0',
+        CC0: 'CC0',
+        ALL_RIGHTS: 'ALL_RIGHTS_RESERVED',
+    };
+    return aliases[upper] ?? 'MIT';
+}

package/dist/commands/pull.d.ts

@@ -0,0 +1,3 @@
+export declare function pull(ref: string, options?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/pull.js

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { apiFetch, fetchRawContent } from '../lib/api.js';
+export async function pull(ref, options = {}) {
+    const parsed = parseRef(ref);
+    if (!parsed) {
+        console.error('Invalid reference. Use format: username/slug');
+        process.exit(1);
+    }
+    const { username, slug } = parsed;
+    const outDir = path.resolve(slug);
+    // Check for existing clone metadata
+    const metaPath = path.join(outDir, '.botdocs.json');
+    if (!fs.existsSync(metaPath)) {
+        console.error(`No clone found at ./${slug}/`);
+        console.error('Use `botdocs clone` first.');
+        process.exit(1);
+    }
+    console.log(`Updating ${username}/${slug}...`);
+    // Fetch latest manifest
+    let manifest;
+    try {
+        manifest = await apiFetch(`/@${username}/${slug}/manifest`);
+    }
+    catch {
+        console.error(`BotDoc not found: ${username}/${slug}`);
+        process.exit(1);
+    }
+    // Download all files (overwrite)
+    let updated = 0;
+    for (const file of manifest.files) {
+        const filePath = path.join(outDir, file.filename);
+        const content = await fetchRawContent(file.rawUrl);
+        const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : null;
+        if (existing !== content) {
+            fs.writeFileSync(filePath, content, 'utf-8');
+            console.log(`  Updated: ${file.filename}`);
+            updated++;
+        }
+    }
+    // Remove files that no longer exist in the BotDoc
+    const metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    const remoteFiles = new Set(manifest.files.map((f) => f.filename));
+    for (const oldFile of metadata.files) {
+        if (!remoteFiles.has(oldFile)) {
+            const oldPath = path.join(outDir, oldFile);
+            if (fs.existsSync(oldPath)) {
+                fs.unlinkSync(oldPath);
+                console.log(`  Removed: ${oldFile}`);
+                updated++;
+            }
+        }
+    }
+    // Update metadata
+    const newMetadata = {
+        username,
+        slug,
+        clonedAt: metadata.clonedAt,
+        files: manifest.files.map((f) => f.filename),
+    };
+    fs.writeFileSync(metaPath, JSON.stringify(newMetadata, null, 2), 'utf-8');
+    if (options.json) {
+        console.log(JSON.stringify({ success: true, updated, files: manifest.files.map(f => f.filename) }));
+    }
+    else if (updated === 0) {
+        console.log('Already up to date.');
+    }
+    else {
+        console.log(`\nUpdated ${updated} file(s).`);
+    }
+}
+function parseRef(ref) {
+    const cleaned = ref.startsWith('@') ? ref.slice(1) : ref;
+    const parts = cleaned.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        return null;
+    return { username: parts[0], slug: parts[1] };
+}

package/dist/commands/search.d.ts

@@ -0,0 +1,3 @@
+export declare function search(query: string, options?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/search.js

@@ -0,0 +1,58 @@
+import { apiFetch } from '../lib/api.js';
+export async function search(query, options = {}) {
+    if (!query.trim()) {
+        console.error('Please provide a search query.');
+        process.exit(1);
+    }
+    const encoded = encodeURIComponent(query);
+    const data = await apiFetch(`/api/search?q=${encoded}`);
+    if (options.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    if (data.results.length === 0) {
+        console.log(`No results for "${query}".`);
+        return;
+    }
+    console.log(`${data.total} result(s) for "${query}":\n`);
+    // Print formatted table
+    const maxTitle = Math.min(40, Math.max(...data.results.map((r) => r.title.length)));
+    const maxAuthor = Math.max(...data.results.map((r) => r.author.length));
+    const header = [
+        'Title'.padEnd(maxTitle),
+        'Author'.padEnd(maxAuthor),
+        'Stars'.padStart(5),
+        'Clones'.padStart(6),
+        'Category',
+    ].join('  ');
+    const separator = '-'.repeat(header.length);
+    console.log(header);
+    console.log(separator);
+    for (const result of data.results) {
+        const title = result.title.length > maxTitle
+            ? result.title.slice(0, maxTitle - 1) + '…'
+            : result.title.padEnd(maxTitle);
+        const row = [
+            title,
+            result.author.padEnd(maxAuthor),
+            String(result.starCount).padStart(5),
+            String(result.cloneCount).padStart(6),
+            formatCategory(result.category),
+        ].join('  ');
+        console.log(row);
+    }
+    if (data.totalPages > 1) {
+        console.log(`\nPage ${data.page}/${data.totalPages}`);
+    }
+}
+function formatCategory(category) {
+    const labels = {
+        KNOWLEDGE_MANAGEMENT: 'Knowledge',
+        DEV_WORKFLOW: 'Dev Workflow',
+        AUTOMATION: 'Automation',
+        AGENT_CONFIG: 'Agent Config',
+        PROJECT_SCAFFOLD: 'Scaffold',
+        OTHER: 'Other',
+    };
+    return labels[category] ?? category;
+}

package/dist/commands/validate.d.ts

@@ -0,0 +1,3 @@
+export declare function validate(source: string, options: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/validate.js

@@ -0,0 +1,79 @@
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+export async function validate(source, options) {
+    const errors = [];
+    const stat = statSync(source, { throwIfNoEntry: false });
+    if (!stat) {
+        errors.push({ file: source, message: 'Path does not exist', severity: 'error' });
+        return outputResults(errors, options.json);
+    }
+    let files;
+    let baseDir;
+    if (stat.isDirectory()) {
+        baseDir = source;
+        files = readdirSync(source).filter((f) => (extname(f) === '.md' || extname(f) === '.markdown') && statSync(join(source, f)).isFile());
+        if (files.length === 0) {
+            errors.push({ file: source, message: 'No markdown files found', severity: 'error' });
+        }
+        if (!files.includes('index.md')) {
+            errors.push({ file: 'index.md', message: 'Missing index.md (required entry point)', severity: 'error' });
+        }
+        if (existsSync(join(source, 'botdocs.json'))) {
+            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' });
+            }
+            catch {
+                errors.push({ file: 'botdocs.json', message: 'Invalid JSON', severity: 'error' });
+            }
+        }
+        else {
+            errors.push({ file: 'botdocs.json', message: 'Missing botdocs.json metadata file', severity: 'warning' });
+        }
+    }
+    else {
+        baseDir = '.';
+        files = [source];
+    }
+    for (const file of files) {
+        const filePath = stat.isDirectory() ? join(baseDir, file) : file;
+        const content = readFileSync(filePath, 'utf-8');
+        if (content.trim().length === 0) {
+            errors.push({ file, message: 'File is empty', severity: 'error' });
+            continue;
+        }
+        if (!content.match(/^#\s+/m)) {
+            errors.push({ file, message: 'No markdown heading found', severity: 'warning' });
+        }
+        if (content.length < 100) {
+            errors.push({ file, message: 'Content is very short (< 100 chars)', severity: 'warning' });
+        }
+    }
+    outputResults(errors, options.json);
+}
+function outputResults(errors, json) {
+    const errorCount = errors.filter((e) => e.severity === 'error').length;
+    const warnCount = errors.filter((e) => e.severity === 'warning').length;
+    const valid = errorCount === 0;
+    if (json) {
+        console.log(JSON.stringify({ valid, errors, errorCount, warningCount: warnCount }));
+        if (!valid)
+            process.exit(1);
+        return;
+    }
+    if (errors.length === 0) {
+        console.log('\n  Valid! Ready to publish.\n');
+        return;
+    }
+    console.log('');
+    for (const err of errors) {
+        const icon = err.severity === 'error' ? 'x' : '!';
+        console.log(`  ${icon} ${err.file}: ${err.message}`);
+    }
+    console.log(`\n  ${errorCount} error(s), ${warnCount} warning(s)\n`);
+    if (!valid)
+        process.exit(1);
+}

package/dist/commands/whoami.d.ts

@@ -0,0 +1,3 @@
+export declare function whoami(options?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/whoami.js

@@ -0,0 +1,26 @@
+import { loadAuth } from '../lib/config.js';
+export async function whoami(options = {}) {
+    const auth = loadAuth();
+    if (!auth) {
+        console.log('Not logged in. Run `botdocs login` to authenticate.');
+        process.exit(1);
+    }
+    // Verify token is still valid
+    const response = await fetch('https://api.github.com/user', {
+        headers: {
+            Authorization: `Bearer ${auth.githubToken}`,
+            Accept: 'application/vnd.github+json',
+        },
+    });
+    if (!response.ok) {
+        console.log('Session expired. Run `botdocs login` to re-authenticate.');
+        process.exit(1);
+    }
+    const user = (await response.json());
+    if (options.json) {
+        console.log(JSON.stringify({ login: user.login, name: user.name }));
+    }
+    else {
+        console.log(`Logged in as ${user.login}${user.name ? ` (${user.name})` : ''}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { clone } from './commands/clone.js';
+import { search } from './commands/search.js';
+import { publish } from './commands/publish.js';
+import { pull } from './commands/pull.js';
+import { login } from './commands/login.js';
+import { whoami } from './commands/whoami.js';
+import { init } from './commands/init.js';
+import { validate } from './commands/validate.js';
+import { diff } from './commands/diff.js';
+import { endorse } from './commands/endorse.js';
+const program = new Command();
+program
+    .name('botdocs')
+    .description('CLI for BotDocs — clone, search, and publish concept specifications')
+    .version('0.1.0')
+    .option('--json', 'Output results as JSON');
+program
+    .command('init [name]')
+    .description('Scaffold a new BotDoc directory with index.md template')
+    .option('--title <title>', 'BotDoc title')
+    .option('--category <category>', 'Category')
+    .action(async (name, opts) => {
+    await init(name, { ...opts, json: program.opts().json });
+});
+program
+    .command('validate <source>')
+    .description('Validate a BotDoc directory or file before publishing')
+    .action(async (source) => {
+    await validate(source, { json: program.opts().json });
+});
+program
+    .command('clone <username/slug>')
+    .description('Download all BotDoc files to a local directory')
+    .action(async (ref) => {
+    await clone(ref, { json: program.opts().json });
+});
+program
+    .command('search <query>')
+    .description('Search for BotDocs')
+    .action(async (query) => {
+    await search(query, { json: program.opts().json });
+});
+program
+    .command('publish <source>')
+    .description('Publish a BotDoc from a file, directory, or zip archive')
+    .option('--title <title>', 'BotDoc title')
+    .option('--description <description>', 'BotDoc description')
+    .option('--category <category>', 'Category (knowledge_management, dev_workflow, automation, agent_config, project_scaffold, other)')
+    .option('--tags <tags>', 'Comma-separated tags')
+    .option('--license <license>', 'License (MIT, CC_BY_4_0, CC_BY_SA_4_0, CC0, ALL_RIGHTS_RESERVED)')
+    .action(async (source, options) => {
+    await publish(source, { ...options, json: program.opts().json });
+});
+program
+    .command('diff <username/slug>')
+    .description('Preview remote changes before pulling')
+    .action(async (ref) => {
+    await diff(ref, { json: program.opts().json });
+});
+program
+    .command('pull <username/slug>')
+    .description('Update previously cloned BotDoc files with the latest version')
+    .action(async (ref) => {
+    await pull(ref, { json: program.opts().json });
+});
+program
+    .command('endorse <username/slug>')
+    .description('Endorse a BotDoc after building from it')
+    .requiredOption('--rating <rating>', 'Rating: positive, neutral, or negative')
+    .option('--comment <comment>', 'Optional feedback about the build experience')
+    .action(async (ref, opts) => {
+    await endorse(ref, { ...opts, json: program.opts().json });
+});
+program
+    .command('login')
+    .description('Authenticate via GitHub device code flow')
+    .action(async () => {
+    await login();
+});
+program
+    .command('whoami')
+    .description('Display the current authenticated user')
+    .action(async () => {
+    await whoami({ json: program.opts().json });
+});
+program.parse();

package/dist/lib/api.d.ts

@@ -0,0 +1,17 @@
+export declare function getApiUrl(): string;
+/** Thrown by apiFetch when the server returns a non-2xx response. Carries the
+ * status code and the server-provided message so callers can branch on it
+ * (e.g. the `endorse` command surfaces a friendly hint on the 403 returned by
+ * the clone-required guard). */
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+interface FetchOptions {
+    method?: string;
+    body?: unknown;
+    auth?: boolean;
+}
+export declare function apiFetch<T>(path: string, options?: FetchOptions): Promise<T>;
+export declare function fetchRawContent(rawUrl: string): Promise<string>;
+export {};

package/dist/lib/api.js

@@ -0,0 +1,66 @@
+import { loadAuth } from './config.js';
+const DEFAULT_API_URL = 'https://botdocs.ai';
+export function getApiUrl() {
+    return process.env.BOTDOCS_API_URL || DEFAULT_API_URL;
+}
+/** Thrown by apiFetch when the server returns a non-2xx response. Carries the
+ * status code and the server-provided message so callers can branch on it
+ * (e.g. the `endorse` command surfaces a friendly hint on the 403 returned by
+ * the clone-required guard). */
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+    }
+}
+export async function apiFetch(path, options = {}) {
+    const { method = 'GET', body, auth = false } = options;
+    const baseUrl = getApiUrl();
+    const url = `${baseUrl}${path}`;
+    const headers = {
+        Accept: 'application/json',
+    };
+    if (body) {
+        headers['Content-Type'] = 'application/json';
+    }
+    if (auth) {
+        const config = loadAuth();
+        if (!config?.githubToken) {
+            throw new Error('Not authenticated. Run `botdocs login` first.');
+        }
+        headers['Authorization'] = `Bearer ${config.githubToken}`;
+    }
+    const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        let message;
+        try {
+            const json = JSON.parse(text);
+            message = json.error || text;
+        }
+        catch {
+            message = text;
+        }
+        throw new ApiError(response.status, message);
+    }
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+        return (await response.json());
+    }
+    return (await response.text());
+}
+export async function fetchRawContent(rawUrl) {
+    const baseUrl = getApiUrl();
+    const url = rawUrl.startsWith('http') ? rawUrl : `${baseUrl}${rawUrl}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new ApiError(response.status, `Failed to fetch ${rawUrl}`);
+    }
+    return await response.text();
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,9 @@
+interface AuthConfig {
+    githubToken: string;
+    username: string;
+    displayName: string;
+}
+export declare function saveAuth(config: AuthConfig): void;
+export declare function loadAuth(): AuthConfig | null;
+export declare function clearAuth(): void;
+export {};

package/dist/lib/config.js

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const CONFIG_DIR = path.join(os.homedir(), '.botdocs');
+const AUTH_FILE = path.join(CONFIG_DIR, 'auth.json');
+function ensureConfigDir() {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+}
+export function saveAuth(config) {
+    ensureConfigDir();
+    fs.writeFileSync(AUTH_FILE, JSON.stringify(config, null, 2), 'utf-8');
+}
+export function loadAuth() {
+    if (!fs.existsSync(AUTH_FILE))
+        return null;
+    try {
+        const data = fs.readFileSync(AUTH_FILE, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+export function clearAuth() {
+    if (fs.existsSync(AUTH_FILE)) {
+        fs.unlinkSync(AUTH_FILE);
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@botdocs/cli",
+  "version": "0.2.0",
+  "description": "CLI for BotDocs — clone, search, publish, and endorse concept specifications.",
+  "keywords": [
+    "botdocs",
+    "ai",
+    "agents",
+    "specs",
+    "specification",
+    "cli",
+    "llm"
+  ],
+  "homepage": "https://botdocs.ai",
+  "bugs": {
+    "url": "https://github.com/trev91/Botdocs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trev91/Botdocs.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "author": "BotDocs contributors",
+  "bin": {
+    "botdocs": "./dist/index.js"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/adm-zip": "^0.5.8",
+    "@types/node": "^22.14.0",
+    "eslint": "^10.2.0",
+    "typescript": "^5.8.0",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^3.1.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "dependencies": {
+    "adm-zip": "^0.5.17",
+    "commander": "^14.0.3"
+  },
+  "scripts": {
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}