@botdocs/cli 0.2.0 → 0.3.0

package/dist/test-utils.d.ts

@@ -0,0 +1,43 @@
+/** Thrown by the mocked process.exit so tests can assert on the exit code
+ * without actually killing the test runner. */
+export declare class ProcessExitError extends Error {
+    readonly code: number;
+    constructor(code: number);
+}
+export interface CapturedConsole {
+    stdout: string[];
+    stderr: string[];
+    restore: () => void;
+}
+/** Patches console.log/console.error and process.exit so commands can be
+ * driven from tests without writing to the real terminal or exiting. */
+export declare function captureConsole(): CapturedConsole;
+export interface MockFetchCall {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: unknown;
+}
+export interface MockFetchResponse {
+    status?: number;
+    body?: unknown;
+    contentType?: string;
+}
+/** Installs a fetch stub that matches requests by (method, urlSubstring) and
+ * returns the configured response. Each handler can fire only once unless
+ * `repeat: true` is set. */
+export declare function mockFetch(handlers: Array<{
+    method?: string;
+    url: string | RegExp;
+    response: MockFetchResponse | ((call: MockFetchCall) => MockFetchResponse);
+    repeat?: boolean;
+}>): {
+    calls: MockFetchCall[];
+    restore: () => void;
+};
+/** Creates a unique temporary directory and changes into it. The returned
+ * cleanup function restores the prior cwd and removes the dir. */
+export declare function withTempDir(): {
+    dir: string;
+    cleanup: () => void;
+};

package/dist/test-utils.js

@@ -0,0 +1,101 @@
+import { vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** Thrown by the mocked process.exit so tests can assert on the exit code
+ * without actually killing the test runner. */
+export class ProcessExitError extends Error {
+    code;
+    constructor(code) {
+        super(`process.exit(${code})`);
+        this.name = 'ProcessExitError';
+        this.code = code;
+    }
+}
+/** Patches console.log/console.error and process.exit so commands can be
+ * driven from tests without writing to the real terminal or exiting. */
+export function captureConsole() {
+    const stdout = [];
+    const stderr = [];
+    const logSpy = vi.spyOn(console, 'log').mockImplementation((...args) => {
+        stdout.push(args.map(String).join(' '));
+    });
+    const errSpy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+        stderr.push(args.map(String).join(' '));
+    });
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code) => {
+        throw new ProcessExitError(code ?? 0);
+    }));
+    return {
+        stdout,
+        stderr,
+        restore: () => {
+            logSpy.mockRestore();
+            errSpy.mockRestore();
+            exitSpy.mockRestore();
+        },
+    };
+}
+/** Installs a fetch stub that matches requests by (method, urlSubstring) and
+ * returns the configured response. Each handler can fire only once unless
+ * `repeat: true` is set. */
+export function mockFetch(handlers) {
+    const calls = [];
+    const used = new Set();
+    const original = global.fetch;
+    global.fetch = vi.fn(async (input, init) => {
+        const url = typeof input === 'string' ? input : input.url;
+        const method = (init?.method || 'GET').toUpperCase();
+        const headers = (init?.headers || {});
+        let body = undefined;
+        if (init?.body) {
+            try {
+                body = JSON.parse(init.body);
+            }
+            catch {
+                body = init.body;
+            }
+        }
+        const call = { url, method, headers, body };
+        calls.push(call);
+        for (let i = 0; i < handlers.length; i++) {
+            const h = handlers[i];
+            if (!h.repeat && used.has(i))
+                continue;
+            const matchUrl = typeof h.url === 'string' ? url.includes(h.url) : h.url.test(url);
+            const matchMethod = !h.method || h.method.toUpperCase() === method;
+            if (matchUrl && matchMethod) {
+                used.add(i);
+                const r = typeof h.response === 'function' ? h.response(call) : h.response;
+                const status = r.status ?? 200;
+                const isJson = r.contentType ? r.contentType.includes('json') : typeof r.body !== 'string';
+                const payload = isJson ? JSON.stringify(r.body ?? {}) : r.body;
+                return new Response(payload, {
+                    status,
+                    headers: { 'content-type': r.contentType ?? (isJson ? 'application/json' : 'text/plain') },
+                });
+            }
+        }
+        throw new Error(`Unhandled fetch ${method} ${url}`);
+    });
+    return {
+        calls,
+        restore: () => {
+            global.fetch = original;
+        },
+    };
+}
+/** Creates a unique temporary directory and changes into it. The returned
+ * cleanup function restores the prior cwd and removes the dir. */
+export function withTempDir() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'botdocs-cli-test-'));
+    const prevCwd = process.cwd();
+    process.chdir(dir);
+    return {
+        dir,
+        cleanup: () => {
+            process.chdir(prevCwd);
+            fs.rmSync(dir, { recursive: true, force: true });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botdocs/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI for BotDocs — clone, search, publish, and endorse concept specifications.",
   "keywords": [
     "botdocs",
@@ -28,6 +28,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/adm-zip": "^0.5.8",
+    "@types/diff": "^8.0.0",
     "@types/node": "^22.14.0",
     "eslint": "^10.2.0",
     "typescript": "^5.8.0",
@@ -36,6 +37,7 @@
   },
   "files": [
     "dist",
+    "templates",
     "README.md"
   ],
   "engines": {
@@ -46,8 +48,12 @@
   },
   "type": "module",
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.91.1",
+    "@inquirer/prompts": "^8.4.2",
     "adm-zip": "^0.5.17",
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "diff": "^9.0.0",
+    "openai": "^6.35.0"
   },
   "scripts": {
     "dev": "tsc -p tsconfig.build.json --watch",

package/templates/agents.md

@@ -0,0 +1,126 @@
+## 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.
+
+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.
+
+### Common workflows
+
+**Find a spec for what the user wants to build**
+
+```bash
+botdocs search "<topic>" --json
+```
+
+Pick the most relevant result and clone it:
+
+```bash
+botdocs clone @user/slug
+```
+
+Files land in `./slug/`. Read `index.md` first — that's always the entry point.
+
+**Build something on top of a cloned spec, then report back**
+
+After delivering something the user is happy with, run:
+
+```bash
+botdocs endorse @user/slug --rating positive \
+  --comment "Built X in Y minutes."
+```
+
+Ratings: `positive` | `neutral` | `negative`.
+
+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.
+
+**Help the user publish their own spec**
+
+```bash
+botdocs init <name>            # scaffolds index.md + botdocs.json
+# edit index.md, fill in description in botdocs.json
+botdocs validate <name>/        # warns + errors before publish
+botdocs publish <name>/
+```
+
+`validate` must pass (no errors; warnings are OK) before `publish`.
+`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
+```
+
+**Install a team's shared skills**
+
+```bash
+botdocs install @teamco/eng-skills
+```
+
+Files land in `~/.claude/skills/teamco/...` (Claude skills) and
+`./.cursor/rules/...` (Cursor rules) for project-local files.
+
+**Stay current**
+
+```bash
+botdocs sync
+```
+
+Walks the lockfile, applies clean updates, prompts before
+overwriting any local edits (with a double confirmation).
+
+**Uninstall**
+
+```bash
+botdocs uninstall @teamco/eng-skills
+```
+
+### Update notifications
+
+If the user has run `botdocs install-instructions --shell-hook`, a brief
+one-line notice appears on new terminals when updates are pending. They
+can also run `botdocs check-updates` manually (1-hour cached). To enable
+the personalized library page at `botdocs.ai/library`, run
+`botdocs login --sync-library`.
+
+### Multi-ecosystem authoring (BYOK)
+
+If the user has set `BOTDOCS_ANTHROPIC_KEY` or `BOTDOCS_OPENAI_KEY`,
+they can generate per-ecosystem skill drafts without leaving their
+machine:
+
+```bash
+botdocs init my-skill --canonical    # scaffolds claude-code source + ecosystems
+botdocs compile my-skill/            # generates claude/, cursor/, etc.
+botdocs edit @user/my-skill --ecosystem cursor   # LLM-assisted revision → draft
+```
+
+Both commands run inference locally with the user's key — BotDocs
+servers never see file contents. If a key isn't set, surface that to
+the user and recommend they set one.
+
+### Reference
+
+| Command | Purpose |
+|---|---|
+| `init [name]` | Scaffold a new BotDoc 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. |
+
+Run `botdocs <command> --help` for full flags. Override the registry with
+`BOTDOCS_API_URL` (defaults to `https://botdocs.ai`).

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

@@ -0,0 +1,9 @@
+You convert agent skill specifications into a ChatGPT custom-GPT instructions
+block — the prose the user pastes into the "Instructions" field when
+creating a custom GPT.
+
+The output should be a clear set of guidelines, written from the perspective
+of an LLM that will follow them. Reference the GPT's persona and the user's
+goals when relevant. Don't reference other ecosystems.
+
+Output ONLY the instructions text, no commentary, no code fences.

package/templates/ecosystem-prompts/compile-claude-code.md

@@ -0,0 +1,11 @@
+You convert agent skill specifications into the format that Claude Code expects
+for slash commands stored at `.claude/commands/<name>.md`.
+
+A Claude Code command file is plain markdown with no frontmatter required.
+It's an instruction the user invokes via `/command-name` in Claude Code.
+
+The body should be a clear directive to the LLM ("when invoked, do X, Y, Z…")
+optionally referencing tools the command can use. It should never reference
+other ecosystems.
+
+Output ONLY the command markdown, no commentary, no code fences.

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

@@ -0,0 +1,20 @@
+You convert agent skill specifications into the format that Claude (claude.ai)
+expects for SKILL.md files.
+
+A Claude SKILL.md uses YAML frontmatter with `name` and `description` fields,
+followed by markdown that explains when to use the skill, what the skill
+does, and how to use it.
+
+The frontmatter looks like:
+---
+name: short-kebab-case-name
+description: One-sentence description of what the skill does and when to use it.
+---
+
+The body should be focused, written from the perspective of an LLM that will
+follow these instructions, and should never reference other ecosystems
+(don't mention Cursor, Claude Code, ChatGPT — this file is just the Claude
+SKILL.md).
+
+Output ONLY the SKILL.md content, no commentary, no code fences around the
+whole output.

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

@@ -0,0 +1,8 @@
+You convert agent skill specifications into the format that OpenAI Codex
+expects for command/skill files.
+
+A Codex skill file is markdown with no required frontmatter, designed to be
+read by the Codex agent as a long-lived context capability. Focus on what
+the skill does, when to invoke it, and what tools or actions to take.
+
+Output ONLY the markdown content, no commentary, no code fences.

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

@@ -0,0 +1,11 @@
+You convert agent skill specifications into the Cursor rule format
+(.cursor/rules/<name>.mdc).
+
+A Cursor `.mdc` rule is markdown with optional frontmatter declaring when the
+rule applies (globs, agent type). For most skills, no frontmatter is needed —
+the rule is always-active when present in the project.
+
+The body should be concise project-level guidance that Cursor's agent will
+treat as background context. It should never reference other ecosystems.
+
+Output ONLY the rule content, no commentary, no code fences.

package/templates/ecosystem-prompts/edit.md

@@ -0,0 +1,12 @@
+You revise a published agent skill file based on a user's plain-English request.
+
+You will be given:
+1. The CURRENT file contents.
+2. The USER REQUEST describing what to change.
+
+Apply the request faithfully, preserving the rest of the file. If the request
+is impossible or ambiguous, output the literal string `EDIT_IMPOSSIBLE`
+followed by a one-line explanation.
+
+Output ONLY the revised file contents, no commentary, no code fences around
+the whole output.