@botdocs/cli 0.3.2 → 0.4.0

package/dist/lib/prompts.js

@@ -1,26 +1,50 @@
-import { confirm, select } from '@inquirer/prompts';
+import * as p from '@clack/prompts';
+/** Helper: convert clack's cancel sentinel into a graceful exit with a
+ * consistent message. clack returns a special `Symbol` from `p.isCancel(...)` —
+ * unlike inquirer, which throws on Ctrl-C. Callers that want different
+ * cancellation behavior should not use these helpers. */
+function bailIfCancelled(value) {
+    if (p.isCancel(value)) {
+        p.cancel('Operation cancelled.');
+        process.exit(0);
+    }
+    return value;
+}
+/** Prompt for a clean-update decision (upstream has new content; local is
+ * unchanged since last install). The "diff" option lets the user inspect the
+ * change before deciding; callers should loop on "diff" themselves. */
 export async function promptCleanUpdate(label) {
-    return select({
+    const result = await p.select({
         message: `Apply update for ${label}?`,
-        choices: [
-            { name: 'apply', value: 'apply' },
-            { name: 'skip', value: 'skip' },
-            { name: 'diff (show before deciding)', value: 'diff' },
+        options: [
+            { value: 'apply', label: 'Apply' },
+            { value: 'skip', label: 'Skip' },
+            { value: 'diff', label: 'Diff (show before deciding)' },
         ],
     });
+    return bailIfCancelled(result);
 }
+/** Prompt for a conflict resolution when local has diverged from the
+ * lockfile fingerprint AND upstream has new content. Distinct from
+ * `promptCleanUpdate` because the user's edits are at risk; the destructive
+ * option ("overwrite") is gated behind `confirmOverwrite` below. */
 export async function promptConflict(label) {
-    return select({
+    const result = await p.select({
         message: `${label}: your local copy differs from upstream`,
-        choices: [
-            { name: 'skip this update (keep your local)', value: 'skip' },
-            { name: 'overwrite local with upstream', value: 'overwrite' },
+        options: [
+            { value: 'skip', label: 'Skip this update (keep your local)' },
+            { value: 'overwrite', label: 'Overwrite local with upstream' },
         ],
     });
+    return bailIfCancelled(result);
 }
+/** Second confirmation for destructive overwrites — the user has already said
+ * "overwrite" via `promptConflict`, but we want a y/N before clobbering their
+ * edits. Defaults to false so a stray Enter doesn't blow away work. */
 export async function confirmOverwrite(label) {
-    return confirm({
+    const result = await p.confirm({
         message: `${label}: this will REPLACE your local edits with the upstream version. Are you sure?`,
-        default: false,
+        initialValue: false,
     });
+    return bailIfCancelled(result);
 }

package/package.json

@@ -1,15 +1,25 @@
 {
   "name": "@botdocs/cli",
-  "version": "0.3.2",
-  "description": "CLI for BotDocs — clone, search, publish, and endorse concept specifications.",
+  "version": "0.4.0",
+  "description": "CLI for BotDocs — author, publish, install, and sync agent skills across Claude, Claude Code, Cursor, Codex, ChatGPT, Windsurf, Copilot, Gemini, Antigravity, and OpenCode.",
   "keywords": [
     "botdocs",
     "ai",
     "agents",
-    "specs",
-    "specification",
+    "agent-skills",
+    "skills",
+    "teams",
     "cli",
-    "llm"
+    "llm",
+    "claude",
+    "claude-code",
+    "cursor",
+    "codex",
+    "copilot",
+    "windsurf",
+    "gemini",
+    "antigravity",
+    "opencode"
   ],
   "homepage": "https://botdocs.ai",
   "bugs": {
@@ -30,7 +40,9 @@
     "@types/adm-zip": "^0.5.8",
     "@types/diff": "^8.0.0",
     "@types/node": "^22.14.0",
+    "@types/react": "^18.3.12",
     "eslint": "^10.2.0",
+    "ink-testing-library": "^4.0.0",
     "typescript": "^5.8.0",
     "typescript-eslint": "^8.58.0",
     "vitest": "^3.1.0"
@@ -49,11 +61,19 @@
   "type": "module",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.91.1",
-    "@inquirer/prompts": "^8.4.2",
+    "@clack/prompts": "^0.11.0",
     "adm-zip": "^0.5.17",
     "commander": "^14.0.3",
     "diff": "^9.0.0",
-    "openai": "^6.35.0"
+    "ink": "^5.2.1",
+    "ink-big-text": "^2.0.0",
+    "ink-gradient": "^3.0.0",
+    "ink-select-input": "^6.2.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "open": "^10.1.0",
+    "openai": "^6.35.0",
+    "react": "^18.3.1"
   },
   "scripts": {
     "dev": "tsc -p tsconfig.build.json --watch",

package/templates/agents.md

@@ -1,46 +1,56 @@
 ## BotDocs CLI
 
-[BotDocs](https://botdocs.ai) is a registry of concept specifications — docs
-an AI agent can build from. The `botdocs` CLI is the interface to that
-registry.
+[BotDocs](https://botdocs.ai) is a registry of agent skills — the
+shared library teams use to keep their AI agents in sync. The
+`botdocs` CLI is the interface to that registry.
 
 Run `botdocs whoami` to confirm you're authenticated; if not, prompt the
-user to run `botdocs login` (it's a GitHub device-code flow). All commands
-accept `--json` for machine-readable output.
+user to run `botdocs login` (it opens their browser; for headless
+environments they can pass `--token bd_xxx` from /settings/tokens). All
+commands accept `--json` for machine-readable output.
 
 ### Common workflows
 
-**Find a spec for what the user wants to build**
+**Find a skill for what the user wants to do**
 
 ```bash
 botdocs search "<topic>" --json
 ```
 
-Pick the most relevant result and clone it:
+**Install a team's shared skills**
 
 ```bash
-botdocs clone @user/slug
+botdocs install @teamco/eng-skills
 ```
 
-Files land in `./slug/`. Read `index.md` first — that's always the entry point.
+Files land under the right paths for whichever agent reads them — for
+example `~/.claude/skills/teamco/...` for Claude skills,
+`./.cursor/rules/...` for Cursor rules,
+`./.github/instructions/...` for GitHub Copilot,
+`./.codeium/windsurf-rules/...` for Windsurf, and
+`~/.gemini/instructions/...` for the Gemini CLI. The CLI auto-detects
+which destinations apply based on what's in the skill.
 
-**Build something on top of a cloned spec, then report back**
-
-After delivering something the user is happy with, run:
+**Stay current**
 
 ```bash
-botdocs endorse @user/slug --rating positive \
-  --comment "Built X in Y minutes."
+botdocs sync
 ```
 
-Ratings: `positive` | `neutral` | `negative`.
+Walks the lockfile, applies clean updates, prompts before
+overwriting any local edits (with a double confirmation). If a file
+would be overwritten, BotDocs backs up the original to
+`.botdocs-backup/` first; pass `--no-backup` to opt out. If you regret
+an overwrite, `botdocs undo` restores the most recent backup (it's
+reversible — run it twice to swap back).
 
-If the server returns a 403 with "clone before endorsing", that means the
-user's account hasn't cloned the spec yet — run `botdocs clone @user/slug`
-first, then retry the endorse. Endorsements are reserved for builders who
-actually used the spec.
+**Uninstall**
 
-**Help the user publish their own spec**
+```bash
+botdocs uninstall @teamco/eng-skills
+```
+
+**Help the user publish their own skill**
 
 ```bash
 botdocs init <name>            # scaffolds index.md + botdocs.json
@@ -53,36 +63,30 @@ botdocs publish <name>/
 `category` in `botdocs.json` must be one of: `KNOWLEDGE_MANAGEMENT`,
 `DEV_WORKFLOW`, `AUTOMATION`, `AGENT_CONFIG`, `PROJECT_SCAFFOLD`, `OTHER`.
 
-**Update a previously cloned spec**
-
-```bash
-botdocs diff @user/slug         # preview what changed
-botdocs pull @user/slug         # apply the update
-```
+### Teams
 
-**Install a team's shared skills**
+Teams curate a shared library of skills for an org. Members install/sync
+the team's pinned skills. Anyone in the team can list its pinned set; a
+team's pinned skills are installed automatically on every `botdocs sync`.
 
 ```bash
-botdocs install @teamco/eng-skills
+botdocs team list                              # which teams am I in?
+botdocs team show @teamco                      # members + pinned skills
+botdocs team push @teamco @user/skill          # WRITE+ pins a skill
+botdocs team push @teamco @user/skill --version 3   # pin to a specific version
+botdocs sync                                   # pulls personal + team-pinned skills
 ```
 
-Files land in `~/.claude/skills/teamco/...` (Claude skills) and
-`./.cursor/rules/...` (Cursor rules) for project-local files.
-
-**Stay current**
+Admins also have:
 
 ```bash
-botdocs sync
+botdocs team create teamco --name "Team Co"
+botdocs team add @teamco @username --role write
+botdocs team remove @teamco @username
 ```
 
-Walks the lockfile, applies clean updates, prompts before
-overwriting any local edits (with a double confirmation).
-
-**Uninstall**
-
-```bash
-botdocs uninstall @teamco/eng-skills
-```
+Skills stay user-owned; teams *pin* user skills (no copy, no fork). Pinning
+is curation, not access control — skills are public in v1.
 
 ### Update notifications
 
@@ -112,15 +116,24 @@ the user and recommend they set one.
 
 | Command | Purpose |
 |---|---|
-| `init [name]` | Scaffold a new BotDoc directory. |
+| `init [name]` | Scaffold a new skill directory. |
 | `validate <source>` | Pre-publish structural check. |
-| `clone <user/slug>` | Download all files. |
 | `search <query>` | Search the registry. |
 | `publish <source>` | Publish from a file, directory, or zip. |
-| `diff <user/slug>` | Preview remote changes before pulling. |
-| `pull <user/slug>` | Apply remote updates. |
-| `endorse <user/slug>` | Rate a spec after building from it. |
-| `login` / `whoami` | Auth via GitHub device code; show current user. |
+| `install <ref>` | Install a skill or bundle (auto-detects destinations). |
+| `sync [ref]` | Apply available updates to installed skills. |
+| `uninstall <ref>` | Remove an installed skill or bundle. |
+| `list` | Show installed skills and bundles. |
+| `check-updates` | Check installed refs for available updates (1h cached). |
+| `undo` | Restore the most recent backup run (reversible). |
+| `backups list / restore / diff / clear` | Browse and manage backup runs. |
+| `compile <path>` | Generate per-ecosystem drafts from a canonical source (BYOK). |
+| `edit <ref>` | LLM-assisted revision of a published skill ecosystem file (BYOK). |
+| `ingest <path>` | Walk a directory, detect existing skills, upload as drafts. |
+| `team list` | List teams you belong to. |
+| `team show <slug>` | Members + pinned skills for a team. |
+| `team push <slug> <ref>` | Pin a skill to a team (WRITE+). |
+| `login` / `whoami` | Sign in (browser-based; `--token bd_xxx` for CI); show current user. |
 
 Run `botdocs <command> --help` for full flags. Override the registry with
 `BOTDOCS_API_URL` (defaults to `https://botdocs.ai`).

package/templates/ecosystem-prompts/compile-antigravity.md

@@ -0,0 +1,14 @@
+You convert agent skill specifications into the format Google Antigravity
+reads from `~/.gemini/antigravity/skills/<name>.md`.
+
+An Antigravity skill is markdown — no required frontmatter — that the
+agent loads as a multi-step capability. Frame the body as an action plan:
+when to invoke the skill, the sequence of steps to take, which tools or
+APIs to call at each step, and how to know when the task is complete.
+
+Be concrete and agentic. Prefer numbered steps over prose paragraphs when
+the procedure has more than two stages. Write in the second person to the
+agent. Don't reference other agents or ecosystems (no mention of Claude,
+Cursor, Copilot — this file is just the Antigravity skill).
+
+Output ONLY the skill content, no commentary, no code fences.

package/templates/ecosystem-prompts/compile-copilot.md

@@ -0,0 +1,14 @@
+You convert agent skill specifications into the GitHub Copilot custom
+instructions format (`.github/instructions/<name>.instructions.md`).
+
+A Copilot instructions file is markdown. It MAY include YAML frontmatter
+with an `applyTo` glob that scopes the instruction to matching files;
+when no scoping is needed, omit the frontmatter and the instruction
+applies to all chat in the repository.
+
+The body should be concise repository-level guidance that Copilot Chat
+will treat as background context. Write in the second person ("When you
+…"), avoid references to other agents or ecosystems, and keep the file
+under ~200 lines.
+
+Output ONLY the instructions content, no commentary, no code fences.

package/templates/ecosystem-prompts/compile-gemini.md

@@ -0,0 +1,14 @@
+You convert agent skill specifications into the format Gemini CLI reads
+from `~/.gemini/instructions/<name>.md`.
+
+A Gemini instruction file is markdown — no required frontmatter — that
+Gemini treats as a system prompt loaded for every session. Open with a
+short persona/role line ("You are …") and then give concrete behavior
+guidance: when to invoke the skill, what tools to reach for, what to
+avoid, what good output looks like.
+
+Write in the second person to the agent. Don't reference other agents or
+ecosystems (no mention of Claude, Cursor, Copilot — this file is just
+the Gemini instruction).
+
+Output ONLY the instruction content, no commentary, no code fences.

package/templates/ecosystem-prompts/compile-opencode.md

@@ -0,0 +1,13 @@
+You convert agent skill specifications into the format OpenCode (SST)
+reads from `~/.config/opencode/instructions/<name>.md`.
+
+An OpenCode instruction file is plain markdown — no required frontmatter
+— scoped to a single, well-defined task. Keep it tight: state what the
+skill does, when to invoke it, and the concrete steps or tool calls to
+make. Avoid background prose that doesn't change the agent's behavior.
+
+Write in the second person to the agent. Don't reference other agents or
+ecosystems (no mention of Claude, Cursor, Copilot — this file is just
+the OpenCode instruction).
+
+Output ONLY the instruction content, no commentary, no code fences.

package/templates/ecosystem-prompts/compile-windsurf.md

@@ -0,0 +1,13 @@
+You convert agent skill specifications into the Windsurf (Codeium)
+project-rule format (`.codeium/windsurf-rules/<name>.md`).
+
+A Windsurf rule is plain markdown with no required frontmatter. The rule
+is always-active for the project when present. Keep the body terse and
+instructional, like a project README's "house rules" section — Cascade
+treats it as background context for every conversation in this repo.
+
+Write in the second person ("When you …"). Don't reference other agents
+or ecosystems (no mention of Cursor, Claude, Copilot — this file is just
+the Windsurf rule).
+
+Output ONLY the rule content, no commentary, no code fences.

package/dist/commands/check-updates.test.d.ts

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

package/dist/commands/check-updates.test.js

@@ -1,128 +0,0 @@
-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 { createHash } from 'node:crypto';
-import { checkUpdates } from './check-updates.js';
-import { captureConsole, mockFetch } from '../test-utils.js';
-import { saveLockfile } from '../lib/lockfile.js';
-import { saveAuth } from '../lib/config.js';
-describe('check-updates', () => {
-    let captured;
-    let restoreFetch = () => { };
-    const origHome = os.homedir;
-    let homeTmp;
-    beforeEach(() => {
-        homeTmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cu-'));
-        os.homedir = () => homeTmp;
-        process.env.BOTDOCS_API_URL = 'http://test.local';
-        captured = captureConsole();
-        saveAuth({ githubToken: 't', username: 'u', displayName: 'U' });
-    });
-    afterEach(() => {
-        restoreFetch();
-        captured.restore();
-        fs.rmSync(homeTmp, { recursive: true, force: true });
-        os.homedir = origHome;
-        vi.restoreAllMocks();
-    });
-    it('--quiet prints a one-liner when there are updates', async () => {
-        saveLockfile({
-            version: 1,
-            installs: [{ ref: '@a/b', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] }],
-        });
-        const fm = mockFetch([
-            {
-                method: 'POST',
-                url: '/api/library/check-updates',
-                response: { body: { total: 1, updates: [{ ref: '@a/b', from: '1.0.0', to: '2.0.0' }], removed: [] } },
-            },
-        ]);
-        restoreFetch = fm.restore;
-        await checkUpdates({ quiet: true });
-        expect(captured.stdout.join('\n')).toMatch(/1 update/);
-        expect(captured.stdout.join('\n')).toMatch(/botdocs sync/);
-    });
-    it('--quiet prints nothing when up-to-date', async () => {
-        saveLockfile({ version: 1, installs: [] });
-        const fm = mockFetch([
-            { method: 'POST', url: '/api/library/check-updates', response: { body: { total: 0, updates: [], removed: [] } } },
-        ]);
-        restoreFetch = fm.restore;
-        await checkUpdates({ quiet: true });
-        expect(captured.stdout.join('\n').trim()).toBe('');
-    });
-    it('full mode prints a list of updates', async () => {
-        saveLockfile({
-            version: 1,
-            installs: [{ ref: '@a/b', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] }],
-        });
-        const fm = mockFetch([
-            {
-                method: 'POST',
-                url: '/api/library/check-updates',
-                response: { body: { total: 1, updates: [{ ref: '@a/b', from: '1.0.0', to: '2.0.0' }], removed: [] } },
-            },
-        ]);
-        restoreFetch = fm.restore;
-        await checkUpdates({});
-        expect(captured.stdout.join('\n')).toMatch(/@a\/b/);
-        expect(captured.stdout.join('\n')).toMatch(/1\.0\.0.*2\.0\.0/);
-    });
-    it('uses the cache when within TTL', async () => {
-        saveLockfile({
-            version: 1,
-            installs: [{ ref: '@a/b', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] }],
-        });
-        fs.mkdirSync(path.join(homeTmp, '.botdocs'), { recursive: true });
-        fs.writeFileSync(path.join(homeTmp, '.botdocs', 'check-updates-cache.json'), JSON.stringify({
-            cachedAt: new Date().toISOString(),
-            fingerprint: createHash('sha256')
-                .update(['@a/b@1.0.0'].sort().join('\n'))
-                .digest('hex')
-                .slice(0, 16),
-            result: { total: 0, updates: [], removed: [] },
-        }));
-        const fm = mockFetch([]);
-        restoreFetch = fm.restore;
-        await checkUpdates({ quiet: true });
-        expect(fm.calls).toHaveLength(0);
-    });
-    it('invalidates cache when the lockfile contents change', async () => {
-        // Pre-populate cache for an OLDER lockfile state
-        saveLockfile({
-            version: 1,
-            installs: [{ ref: '@a/old', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] }],
-        });
-        fs.mkdirSync(path.join(homeTmp, '.botdocs'), { recursive: true });
-        // Cache was written when only @a/old was installed
-        const staleFingerprint = createHash('sha256')
-            .update(['@a/old@1.0.0'].sort().join('\n'))
-            .digest('hex')
-            .slice(0, 16);
-        fs.writeFileSync(path.join(homeTmp, '.botdocs', 'check-updates-cache.json'), JSON.stringify({
-            cachedAt: new Date().toISOString(),
-            fingerprint: staleFingerprint,
-            result: { total: 0, updates: [], removed: [] },
-        }));
-        // Now the lockfile changed — user installed @a/new
-        saveLockfile({
-            version: 1,
-            installs: [
-                { ref: '@a/old', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] },
-                { ref: '@a/new', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] },
-            ],
-        });
-        // The cache is now stale (fingerprint mismatch); fetch happens
-        const fm = mockFetch([
-            {
-                method: 'POST',
-                url: '/api/library/check-updates',
-                response: { body: { total: 0, updates: [], removed: [] } },
-            },
-        ]);
-        restoreFetch = fm.restore;
-        await checkUpdates({ quiet: true });
-        expect(fm.calls).toHaveLength(1);
-    });
-});

package/dist/commands/clone.d.ts

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

package/dist/commands/clone.js

@@ -1,70 +0,0 @@
-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/compile.test.d.ts

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