@botdocs/cli 0.2.0 → 0.3.0

package/README.md

@@ -54,15 +54,24 @@ botdocs endorse @alice/agent-router --rating positive \
 
 | Command | Purpose |
 |---|---|
-| `init [name]` | Scaffold a new BotDoc directory with an `index.md` template. |
+| `init [name]` | Scaffold a new BotDoc directory (`--canonical` for a multi-ecosystem skill). |
+| `compile <path>` | Generate per-ecosystem skill drafts from a canonical source (BYOK). |
+| `edit <ref>` | LLM-assisted revision of a published skill ecosystem file (BYOK). |
 | `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. |
+| `install <ref>` | Install a skill or bundle (auto-detects destinations). |
+| `sync [ref]` | Check installed skills/bundles for updates and apply. |
+| `uninstall <ref>` | Remove an installed skill or bundle. |
+| `list` | Show installed skills and bundles. |
+| `ingest <path>` | Walk a directory, detect existing skills, upload as drafts. |
 | `endorse <user/slug>` | Rate a BotDoc after you've built from it (requires a prior clone). |
-| `login` | Authenticate via the GitHub device-code flow. |
+| `check-updates` | Check installed refs for available updates (1h cached). |
+| `install-instructions [target]` | Write/refresh `AGENTS.md` (or install a shell hook with `--shell-hook`). |
+| `login` | Authenticate via the GitHub device-code flow (`--sync-library` enables `/library`). |
 | `whoami` | Show the currently authenticated user. |
 
 Every command accepts `--json` for machine-readable output.
@@ -78,6 +87,114 @@ Run `botdocs <command> --help` for full flags on any command.
 Auth is stored at `~/.botdocs/auth.json` after `botdocs login`. Delete it
 to log out.
 
+## Teaching agents to use this CLI
+
+Run once in any project to drop a managed `AGENTS.md` block that teaches
+Claude Code, Cursor, Codex, and Copilot how to invoke the CLI:
+
+```bash
+botdocs install-instructions
+```
+
+If `AGENTS.md` already exists with markers from a prior run, the block is
+refreshed in place. Use `--print` to dump the snippet to stdout instead of
+writing.
+
+## Library + update notifications
+
+Enable the personalized Library page at https://botdocs.ai/library:
+
+```bash
+botdocs login --sync-library
+```
+
+After install/sync/uninstall, the CLI uploads a sanitized snapshot
+(refs + versions only — never file contents) so the web library can
+show what you have, what your team has, and what's new. Privacy-conscious
+users can leave the flag off; the CLI no-ops silently and the page shows
+an onboarding banner with the command.
+
+Set up a shell hook so new terminals show pending update notices:
+
+```bash
+botdocs install-instructions --shell-hook
+```
+
+Detects your shell (zsh/bash/fish), writes a marker-delimited block to
+the rc file, and runs `botdocs check-updates --quiet` on shell open.
+Silent when there's nothing to report. Remove with
+`--remove-shell-hook` when you want it gone.
+
+Or check manually anytime:
+
+```bash
+botdocs check-updates           # full list of pending updates
+botdocs check-updates --quiet   # one-liner only when updates pending
+```
+
+`check-updates` caches the response for 1 hour so opening many terminals
+in quick succession doesn't hammer the API.
+
+## Multi-ecosystem authoring (BYOK)
+
+Authors write a skill once in their preferred ecosystem (Claude Code,
+Cursor, etc.) and use their own LLM key to generate the other formats
+locally. The server never runs inference — your file content stays on
+your machine.
+
+```bash
+export BOTDOCS_ANTHROPIC_KEY=sk-ant-...    # or BOTDOCS_OPENAI_KEY=sk-...
+
+botdocs init my-skill --canonical          # scaffolds claude-code source
+                                            # + ecosystems list in botdocs.json
+# edit claude-code/commands/my-skill.md
+
+botdocs compile my-skill/                  # generates claude/SKILL.md,
+                                            # cursor/rules/my-skill.mdc, etc.
+
+botdocs publish my-skill/                  # auto-compiles if stale; --no-compile to skip
+```
+
+To revise a published file later via the LLM:
+
+```bash
+botdocs edit @you/my-skill --ecosystem cursor
+# enter your change in plain English
+# review the diff, accept to push as a draft
+# visit botdocs.ai/@you/my-skill to publish
+```
+
+`compile` and `edit` both prefer `BOTDOCS_ANTHROPIC_KEY` (Claude
+Haiku) when set, otherwise fall back to `BOTDOCS_OPENAI_KEY`
+(GPT-4o mini). Use `--key-env <NAME>` to point at a different env var.
+
+## Skills + bundles
+
+Skills are bundles of files that ship to specific destinations on disk
+(Claude skills, Cursor rules, Claude Code commands). A bundle is a
+curated playlist of skills for an org or team. Two key flows:
+
+**Install a team's bundle** — files land in the right places automatically:
+
+```bash
+botdocs install @teamco/eng-skills
+```
+
+**Stay current** — walks the lockfile, applies clean updates, prompts
+on conflicts (skip or overwrite with double confirm):
+
+```bash
+botdocs sync
+```
+
+`botdocs list` shows what you have installed; `botdocs uninstall <ref>`
+removes it.
+
+Authors who want to share their existing collection of skills run
+`botdocs ingest <path>` — the CLI walks the directory, detects each
+skill, and uploads them as drafts in your BotDocs account for review
+before publishing.
+
 ## Endorsing
 
 Endorsements are reserved for builders who actually used the spec — the

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

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

package/dist/commands/check-updates.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { apiFetch } from '../lib/api.js';
+import { loadLockfile } from '../lib/lockfile.js';
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+function cachePath() {
+    return path.join(os.homedir(), '.botdocs', 'check-updates-cache.json');
+}
+/** Hash of (ref, version) tuples — invalidates the cache when the user's
+ * installed set changes (e.g. new install, version bump after sync). */
+function lockfileFingerprint() {
+    const lf = loadLockfile();
+    const summary = lf.installs.map((i) => `${i.ref}@${i.version}`).sort().join('\n');
+    return createHash('sha256').update(summary).digest('hex').slice(0, 16);
+}
+function loadCache(currentFingerprint) {
+    const p = cachePath();
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (raw.fingerprint !== currentFingerprint)
+            return null;
+        const age = Date.now() - new Date(raw.cachedAt).getTime();
+        if (age > CACHE_TTL_MS)
+            return null;
+        return raw.result;
+    }
+    catch {
+        return null;
+    }
+}
+function saveCache(fingerprint, result) {
+    fs.mkdirSync(path.dirname(cachePath()), { recursive: true });
+    fs.writeFileSync(cachePath(), JSON.stringify({ cachedAt: new Date().toISOString(), fingerprint, result }, null, 2));
+}
+export async function checkUpdates(options) {
+    const fingerprint = lockfileFingerprint();
+    const cached = loadCache(fingerprint);
+    let result;
+    if (cached) {
+        result = cached;
+    }
+    else {
+        // Server reads from user_library.lockfile (set by syncLibrary helper).
+        // No body — auth-gated endpoint trusts the server-side snapshot, not the wire.
+        result = await apiFetch('/api/library/check-updates', {
+            method: 'POST',
+            auth: true,
+        });
+        saveCache(fingerprint, result);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(result));
+        return;
+    }
+    if (options.quiet) {
+        if (result.updates.length > 0) {
+            console.log(`\x1b[2mbotdocs: ${result.updates.length} update(s) available — run \`botdocs sync\`\x1b[0m`);
+        }
+        return;
+    }
+    if (result.total === 0) {
+        console.log('\n  All installed skills + bundles are up to date.\n');
+        return;
+    }
+    console.log('');
+    for (const u of result.updates) {
+        console.log(`  ▸ ${u.ref}: ${u.from} → ${u.to}`);
+    }
+    for (const r of result.removed) {
+        console.log(`  ⌀ ${r.ref}: ${r.reason}`);
+    }
+    console.log('\n  Run `botdocs sync` to apply.\n');
+}

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

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

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

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

@@ -0,0 +1,9 @@
+interface CompileOptions {
+    ecosystems?: string;
+    source?: string;
+    regenerate?: string;
+    keyEnv?: string;
+    json?: boolean;
+}
+export declare function compile(skillPath: string, options: CompileOptions): Promise<void>;
+export {};

package/dist/commands/compile.js

@@ -0,0 +1,93 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { complete, detectProvider, LlmError } from '../lib/llm.js';
+import { autoDetectSourceEcosystem, ecosystemDestination, readSourceContent, SUPPORTED_ECOSYSTEMS, } from '../lib/canonical.js';
+import { parseManifest } from '../lib/manifest.js';
+const TEMPLATES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates', 'ecosystem-prompts');
+function loadPromptTemplate(eco) {
+    return fs.readFileSync(path.join(TEMPLATES_DIR, `compile-${eco}.md`), 'utf-8');
+}
+function ensureDir(filePath) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+function ensureEcosystem(value, source) {
+    if (!SUPPORTED_ECOSYSTEMS.includes(value)) {
+        console.error(`\n  ✗ Unsupported ecosystem "${value}" in ${source}. Supported: ${SUPPORTED_ECOSYSTEMS.join(', ')}\n`);
+        process.exit(1);
+    }
+    return value;
+}
+export async function compile(skillPath, options) {
+    const root = path.resolve(skillPath);
+    const manifestPath = path.join(root, 'botdocs.json');
+    if (!fs.existsSync(manifestPath)) {
+        console.error(`\n  ✗ No botdocs.json found at ${root}\n`);
+        process.exit(1);
+    }
+    const manifestRaw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    const manifest = parseManifest(manifestRaw);
+    let sourceEco;
+    if (manifest.sourceEcosystem) {
+        sourceEco = ensureEcosystem(manifest.sourceEcosystem, 'botdocs.json sourceEcosystem');
+    }
+    else {
+        const detected = autoDetectSourceEcosystem(root);
+        if (!detected) {
+            console.error('\n  ✗ Could not detect source ecosystem. Add `sourceEcosystem` to botdocs.json.\n');
+            process.exit(1);
+        }
+        sourceEco = detected;
+    }
+    const declaredEcosystems = manifest.ecosystems ?? [...SUPPORTED_ECOSYSTEMS];
+    let targets = declaredEcosystems.filter((e) => SUPPORTED_ECOSYSTEMS.includes(e));
+    if (options.ecosystems) {
+        const subset = options.ecosystems.split(',').map((s) => ensureEcosystem(s.trim(), '--ecosystems'));
+        targets = targets.filter((e) => subset.includes(e));
+    }
+    if (options.regenerate) {
+        targets = [ensureEcosystem(options.regenerate, '--regenerate')];
+    }
+    // Don't regenerate the source ecosystem — that's the input
+    targets = targets.filter((e) => e !== sourceEco);
+    let providerInfo;
+    try {
+        providerInfo = detectProvider({ keyEnv: options.keyEnv });
+    }
+    catch (err) {
+        if (err instanceof LlmError) {
+            console.error(`\n  ✗ ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    const slug = path.basename(root);
+    const sourceContent = readSourceContent(root, sourceEco, slug);
+    console.log(`\n  ✓ Source: ${ecosystemDestination(sourceEco, slug)} (${providerInfo.provider})`);
+    console.log(`  ✓ Generating drafts for: ${targets.join(', ')}`);
+    let totalIn = 0;
+    let totalOut = 0;
+    const written = [];
+    for (const target of targets) {
+        const system = loadPromptTemplate(target);
+        const prompt = `Skill title: ${manifest.title}\nSkill description: ${manifest.description}\n\nSource (${sourceEco}):\n\n${sourceContent}`;
+        const resp = await complete({ system, prompt, keyEnv: options.keyEnv });
+        totalIn += resp.usage.inputTokens;
+        totalOut += resp.usage.outputTokens;
+        const dest = path.join(root, ecosystemDestination(target, slug));
+        ensureDir(dest);
+        fs.writeFileSync(dest, resp.text, 'utf-8');
+        written.push(ecosystemDestination(target, slug));
+        console.log(`    ↳ ${ecosystemDestination(target, slug)}`);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            written,
+            usage: { inputTokens: totalIn, outputTokens: totalOut },
+            provider: providerInfo.provider,
+        }));
+        return;
+    }
+    console.log(`\n  Cost: ${totalIn} input + ${totalOut} output tokens (your ${providerInfo.provider} key)`);
+    console.log('  Review the generated files before running `botdocs publish`.\n');
+}

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

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

package/dist/commands/compile.test.js

@@ -0,0 +1,110 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { compile } from './compile.js';
+import { captureConsole, withTempDir } from '../test-utils.js';
+vi.mock('../lib/llm.js', () => ({
+    complete: vi.fn(),
+    detectProvider: vi.fn(() => ({ provider: 'anthropic', keyEnv: 'BOTDOCS_ANTHROPIC_KEY' })),
+    LlmError: class extends Error {
+    },
+}));
+import * as llm from '../lib/llm.js';
+describe('compile', () => {
+    let tmp;
+    let captured;
+    beforeEach(() => {
+        tmp = withTempDir();
+        captured = captureConsole();
+        process.env.BOTDOCS_ANTHROPIC_KEY = 'test-key';
+    });
+    afterEach(() => {
+        captured.restore();
+        tmp.cleanup();
+        vi.restoreAllMocks();
+        delete process.env.BOTDOCS_ANTHROPIC_KEY;
+    });
+    function setupSkill() {
+        const root = path.join(tmp.dir, 'my-skill');
+        fs.mkdirSync(path.join(root, 'claude-code', 'commands'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'botdocs.json'), JSON.stringify({
+            type: 'skill',
+            version: '1.0.0',
+            title: 'Code Review',
+            description: 'Reviews PRs',
+            sourceEcosystem: 'claude-code',
+            ecosystems: ['claude', 'claude-code', 'cursor'],
+        }));
+        fs.writeFileSync(path.join(root, 'claude-code', 'commands', 'my-skill.md'), '# Code Review\n\nReview the PR.');
+        return root;
+    }
+    it('generates per-ecosystem files (excluding the source ecosystem)', async () => {
+        vi.mocked(llm.complete).mockResolvedValue({
+            text: 'GENERATED OUTPUT',
+            usage: { inputTokens: 100, outputTokens: 50 },
+            provider: 'anthropic',
+        });
+        const root = setupSkill();
+        await compile(root, {});
+        expect(fs.existsSync(path.join(root, 'claude', 'SKILL.md'))).toBe(true);
+        expect(fs.existsSync(path.join(root, 'cursor', 'rules', 'my-skill.mdc'))).toBe(true);
+        // source-ecosystem file is untouched
+        expect(fs.readFileSync(path.join(root, 'claude-code', 'commands', 'my-skill.md'), 'utf-8'))
+            .toBe('# Code Review\n\nReview the PR.');
+        expect(llm.complete).toHaveBeenCalledTimes(2); // claude + cursor
+    });
+    it('--ecosystems flag subsets the generated set', async () => {
+        vi.mocked(llm.complete).mockResolvedValue({
+            text: 'OUT',
+            usage: { inputTokens: 10, outputTokens: 5 },
+            provider: 'anthropic',
+        });
+        const root = setupSkill();
+        await compile(root, { ecosystems: 'cursor' });
+        expect(fs.existsSync(path.join(root, 'cursor', 'rules', 'my-skill.mdc'))).toBe(true);
+        expect(fs.existsSync(path.join(root, 'claude', 'SKILL.md'))).toBe(false);
+        expect(llm.complete).toHaveBeenCalledTimes(1);
+    });
+    it('errors when no API key is set', async () => {
+        delete process.env.BOTDOCS_ANTHROPIC_KEY;
+        vi.mocked(llm.detectProvider).mockImplementation(() => {
+            throw new llm.LlmError('No LLM key');
+        });
+        const root = setupSkill();
+        await expect(compile(root, {})).rejects.toThrow();
+    });
+    it('exits 1 when sourceEcosystem in botdocs.json is unsupported', async () => {
+        vi.mocked(llm.complete).mockResolvedValue({
+            text: 'X',
+            usage: { inputTokens: 1, outputTokens: 1 },
+            provider: 'anthropic',
+        });
+        const root = path.join(tmp.dir, 'bad-source');
+        fs.mkdirSync(root, { recursive: true });
+        fs.writeFileSync(path.join(root, 'botdocs.json'), JSON.stringify({
+            type: 'skill',
+            version: '1.0.0',
+            title: 'X',
+            description: 'Y',
+            sourceEcosystem: 'claude-codee', // typo
+            ecosystems: ['claude'],
+        }));
+        await expect(compile(root, {})).rejects.toThrow();
+        expect(captured.stderr.join('\n')).toMatch(/Unsupported ecosystem.*claude-codee/);
+    });
+    it('exits 1 when --regenerate target is unsupported', async () => {
+        const root = path.join(tmp.dir, 'good');
+        fs.mkdirSync(path.join(root, 'claude-code', 'commands'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'botdocs.json'), JSON.stringify({
+            type: 'skill',
+            version: '1.0.0',
+            title: 'X',
+            description: 'Y',
+            sourceEcosystem: 'claude-code',
+            ecosystems: ['claude', 'claude-code'],
+        }));
+        fs.writeFileSync(path.join(root, 'claude-code', 'commands', 'good.md'), '# Body');
+        await expect(compile(root, { regenerate: 'cursor-but-typo' })).rejects.toThrow();
+        expect(captured.stderr.join('\n')).toMatch(/Unsupported ecosystem.*cursor-but-typo/);
+    });
+});

package/dist/commands/edit.d.ts

@@ -0,0 +1,7 @@
+interface EditOptions {
+    ecosystem: string;
+    keyEnv?: string;
+    json?: boolean;
+}
+export declare function edit(rawRef: string, options: EditOptions): Promise<void>;
+export {};