@botdocs/cli 0.2.0 → 0.3.0

package/dist/lib/llm.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+const anthropicCreate = vi.fn();
+vi.mock('@anthropic-ai/sdk', () => ({
+    default: class {
+        messages = { create: anthropicCreate };
+    },
+}));
+const openaiCreate = vi.fn();
+vi.mock('openai', () => ({
+    default: class {
+        chat = { completions: { create: openaiCreate } };
+    },
+}));
+import { detectProvider, complete, LlmError } from './llm.js';
+describe('detectProvider', () => {
+    const env = { ...process.env };
+    beforeEach(() => {
+        delete process.env.BOTDOCS_ANTHROPIC_KEY;
+        delete process.env.BOTDOCS_OPENAI_KEY;
+    });
+    afterEach(() => {
+        process.env = { ...env };
+    });
+    it('prefers Anthropic when both keys are set', () => {
+        process.env.BOTDOCS_ANTHROPIC_KEY = 'a';
+        process.env.BOTDOCS_OPENAI_KEY = 'o';
+        expect(detectProvider().provider).toBe('anthropic');
+    });
+    it('falls back to OpenAI when only OpenAI key is set', () => {
+        process.env.BOTDOCS_OPENAI_KEY = 'o';
+        expect(detectProvider().provider).toBe('openai');
+    });
+    it('throws LlmError when no key is set', () => {
+        expect(() => detectProvider()).toThrow(LlmError);
+    });
+    it('honors --key-env override', () => {
+        process.env.BOTDOCS_ANTHROPIC_KEY = 'a';
+        process.env.BOTDOCS_OPENAI_KEY = 'o';
+        expect(detectProvider({ keyEnv: 'BOTDOCS_OPENAI_KEY' }).provider).toBe('openai');
+    });
+});
+describe('complete', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        process.env.BOTDOCS_ANTHROPIC_KEY = 'a';
+        delete process.env.BOTDOCS_OPENAI_KEY;
+    });
+    it('calls Anthropic with the system + user prompt and returns text', async () => {
+        anthropicCreate.mockResolvedValue({
+            content: [{ type: 'text', text: 'compiled output' }],
+            usage: { input_tokens: 100, output_tokens: 50 },
+        });
+        const result = await complete({ system: 'sys', prompt: 'usr' });
+        expect(result.text).toBe('compiled output');
+        expect(result.usage).toEqual({ inputTokens: 100, outputTokens: 50 });
+        expect(anthropicCreate).toHaveBeenCalledWith(expect.objectContaining({
+            system: 'sys',
+            messages: [{ role: 'user', content: 'usr' }],
+        }));
+    });
+    it('calls OpenAI when configured', async () => {
+        delete process.env.BOTDOCS_ANTHROPIC_KEY;
+        process.env.BOTDOCS_OPENAI_KEY = 'o';
+        openaiCreate.mockResolvedValue({
+            choices: [{ message: { content: 'openai output' } }],
+            usage: { prompt_tokens: 80, completion_tokens: 40 },
+        });
+        const result = await complete({ system: 'sys', prompt: 'usr' });
+        expect(result.text).toBe('openai output');
+        expect(result.usage).toEqual({ inputTokens: 80, outputTokens: 40 });
+    });
+});

package/dist/lib/lockfile.d.ts

@@ -0,0 +1,30 @@
+export interface InstalledFile {
+    src: string;
+    dest: string;
+    fingerprint: string;
+}
+export interface InstalledRef {
+    ref: string;
+    type: 'SKILL' | 'BUNDLE';
+    version: string;
+    installedAt: string;
+    files: InstalledFile[];
+    /** For bundles: the refs they expanded into. */
+    skills?: string[];
+}
+export interface Lockfile {
+    version: 1;
+    installs: InstalledRef[];
+}
+export declare function loadLockfile(): Lockfile;
+export declare function saveLockfile(lf: Lockfile): void;
+export declare function upsertInstall(entry: InstalledRef): void;
+export declare function removeInstall(ref: string): void;
+/** SHA-256 fingerprint with CRLF normalized to LF so cross-platform
+ * checkouts don't false-positive as conflicts. Files that look like text
+ * (no NUL bytes) get the normalized hash; otherwise we hash raw bytes. */
+export declare function fingerprintFile(filePath: string): string;
+/** Same fingerprint algorithm as `fingerprintFile`, but operating on an
+ * in-memory string. Use this when comparing downloaded content to existing
+ * file fingerprints WITHOUT writing to disk first. */
+export declare function fingerprintContent(content: string): string;

package/dist/lib/lockfile.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+function lockfilePath() {
+    return path.join(os.homedir(), '.botdocs', 'installed.json');
+}
+function configDir() {
+    return path.join(os.homedir(), '.botdocs');
+}
+export function loadLockfile() {
+    const p = lockfilePath();
+    if (!fs.existsSync(p))
+        return { version: 1, installs: [] };
+    try {
+        const data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (!data.version || !Array.isArray(data.installs)) {
+            return { version: 1, installs: [] };
+        }
+        return data;
+    }
+    catch {
+        return { version: 1, installs: [] };
+    }
+}
+export function saveLockfile(lf) {
+    const dir = configDir();
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const target = lockfilePath();
+    const tmp = `${target}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(lf, null, 2), 'utf-8');
+    fs.renameSync(tmp, target);
+}
+export function upsertInstall(entry) {
+    const lf = loadLockfile();
+    const idx = lf.installs.findIndex((i) => i.ref === entry.ref);
+    if (idx >= 0)
+        lf.installs[idx] = entry;
+    else
+        lf.installs.push(entry);
+    saveLockfile(lf);
+}
+export function removeInstall(ref) {
+    const lf = loadLockfile();
+    lf.installs = lf.installs.filter((i) => i.ref !== ref);
+    saveLockfile(lf);
+}
+/** SHA-256 fingerprint with CRLF normalized to LF so cross-platform
+ * checkouts don't false-positive as conflicts. Files that look like text
+ * (no NUL bytes) get the normalized hash; otherwise we hash raw bytes. */
+export function fingerprintFile(filePath) {
+    const buf = fs.readFileSync(filePath);
+    const hasher = createHash('sha256');
+    // Canonical "looks binary" check: presence of a NUL byte.
+    const looksBinary = buf.includes(0);
+    if (looksBinary) {
+        hasher.update(buf);
+    }
+    else {
+        hasher.update(buf.toString('utf-8').replace(/\r\n/g, '\n'));
+    }
+    return hasher.digest('hex');
+}
+/** Same fingerprint algorithm as `fingerprintFile`, but operating on an
+ * in-memory string. Use this when comparing downloaded content to existing
+ * file fingerprints WITHOUT writing to disk first. */
+export function fingerprintContent(content) {
+    return createHash('sha256').update(content.replace(/\r\n/g, '\n')).digest('hex');
+}

package/dist/lib/lockfile.test.d.ts

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

package/dist/lib/lockfile.test.js

@@ -0,0 +1,99 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadLockfile, saveLockfile, upsertInstall, removeInstall, fingerprintFile, fingerprintContent, } from './lockfile.js';
+describe('lockfile', () => {
+    const origHome = os.homedir;
+    let tmp;
+    beforeEach(() => {
+        tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lockfile-test-'));
+        os.homedir = () => tmp;
+    });
+    afterEach(() => {
+        os.homedir = origHome;
+        fs.rmSync(tmp, { recursive: true, force: true });
+    });
+    it('loadLockfile returns empty when file does not exist', () => {
+        const lf = loadLockfile();
+        expect(lf).toEqual({ version: 1, installs: [] });
+    });
+    it('saveLockfile writes a valid JSON file', () => {
+        const lf = { version: 1, installs: [{ ref: '@a/b', type: 'SKILL', version: '1.0.0', installedAt: '2026-04-29T00:00:00Z', files: [] }] };
+        saveLockfile(lf);
+        const read = loadLockfile();
+        expect(read.installs).toHaveLength(1);
+        expect(read.installs[0].ref).toBe('@a/b');
+    });
+    it('upsertInstall replaces an existing entry with the same ref', () => {
+        saveLockfile({
+            version: 1,
+            installs: [{ ref: '@a/b', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] }],
+        });
+        upsertInstall({
+            ref: '@a/b',
+            type: 'SKILL',
+            version: '2.0.0',
+            installedAt: 't2',
+            files: [],
+        });
+        const lf = loadLockfile();
+        expect(lf.installs).toHaveLength(1);
+        expect(lf.installs[0].version).toBe('2.0.0');
+    });
+    it('removeInstall removes the entry by ref', () => {
+        saveLockfile({
+            version: 1,
+            installs: [
+                { ref: '@a/b', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] },
+                { ref: '@a/c', type: 'SKILL', version: '1.0.0', installedAt: 't', files: [] },
+            ],
+        });
+        removeInstall('@a/b');
+        const lf = loadLockfile();
+        expect(lf.installs).toHaveLength(1);
+        expect(lf.installs[0].ref).toBe('@a/c');
+    });
+    it('fingerprintFile normalizes CRLF to LF before hashing', () => {
+        const lf = path.join(tmp, 'lf.txt');
+        const crlf = path.join(tmp, 'crlf.txt');
+        fs.writeFileSync(lf, 'one\ntwo\nthree\n');
+        fs.writeFileSync(crlf, 'one\r\ntwo\r\nthree\r\n');
+        expect(fingerprintFile(lf)).toBe(fingerprintFile(crlf));
+    });
+    it('fingerprintFile hashes binary files (NUL bytes) as raw bytes', () => {
+        const binPath = path.join(tmp, 'bin.dat');
+        // A buffer with a NUL byte — looks binary
+        fs.writeFileSync(binPath, Buffer.from([0x00, 0x01, 0xff, 0xfe, 0x80]));
+        // Same buffer twice should give the same fingerprint
+        expect(fingerprintFile(binPath)).toBe(fingerprintFile(binPath));
+    });
+    it('fingerprintFile treats files with U+FFFD as text (no false binary classification)', () => {
+        const txtPath = path.join(tmp, 'with-replacement.md');
+        // Text content that legitimately contains U+FFFD — should still be text-hashed
+        fs.writeFileSync(txtPath, '# Header\n\nReplacement: �\n');
+        const fp1 = fingerprintFile(txtPath);
+        // Same content with CRLF — should fingerprint identically (text path normalized)
+        const txtCrlfPath = path.join(tmp, 'with-replacement-crlf.md');
+        fs.writeFileSync(txtCrlfPath, '# Header\r\n\r\nReplacement: �\r\n');
+        expect(fingerprintFile(txtCrlfPath)).toBe(fp1);
+    });
+    it('fingerprintContent agrees with fingerprintFile for the same text content', () => {
+        const filePath = path.join(tmp, 'agree.txt');
+        const content = 'hello\nworld\n';
+        fs.writeFileSync(filePath, content);
+        expect(fingerprintContent(content)).toBe(fingerprintFile(filePath));
+    });
+    it('fingerprintContent normalizes CRLF the same way as fingerprintFile', () => {
+        const filePath = path.join(tmp, 'crlf.txt');
+        fs.writeFileSync(filePath, 'a\r\nb\r\n');
+        expect(fingerprintContent('a\nb\n')).toBe(fingerprintFile(filePath));
+    });
+    it('loadLockfile returns empty when JSON is corrupt (does not throw)', () => {
+        const lf = path.join(tmp, '.botdocs', 'installed.json');
+        fs.mkdirSync(path.dirname(lf), { recursive: true });
+        fs.writeFileSync(lf, '{ this is not valid JSON');
+        const result = loadLockfile();
+        expect(result).toEqual({ version: 1, installs: [] });
+    });
+});

package/dist/lib/manifest.d.ts

@@ -0,0 +1,18 @@
+export type BotDocType = 'SPEC' | 'SKILL' | 'BUNDLE';
+export declare class ManifestError extends Error {
+    constructor(message: string);
+}
+export interface SkillRef {
+    username: string;
+    slug: string;
+}
+export interface ParsedManifest {
+    type: BotDocType;
+    version: string;
+    title: string;
+    description: string;
+    sourceEcosystem?: string;
+    ecosystems?: string[];
+    skills: SkillRef[];
+}
+export declare function parseManifest(input: unknown): ParsedManifest;

package/dist/lib/manifest.js

@@ -0,0 +1,77 @@
+export class ManifestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ManifestError';
+    }
+}
+const SEMVER = /^\d+\.\d+\.\d+(-[\w.-]+)?(\+[\w.-]+)?$/;
+function parseSkillRef(raw) {
+    const cleaned = raw.startsWith('@') ? raw.slice(1) : raw;
+    const parts = cleaned.split('/');
+    if (parts.length !== 2) {
+        throw new ManifestError(`Invalid skill ref: "${raw}" (expected username/slug)`);
+    }
+    const [username, slug] = parts;
+    if (!username || !slug) {
+        throw new ManifestError(`Invalid skill ref: "${raw}" (expected username/slug)`);
+    }
+    return { username, slug };
+}
+export function parseManifest(input) {
+    if (!input || typeof input !== 'object') {
+        throw new ManifestError('Manifest must be a JSON object');
+    }
+    const data = input;
+    if (data.type !== undefined && typeof data.type !== 'string') {
+        throw new ManifestError(`Invalid type: must be a string, got ${typeof data.type}`);
+    }
+    const rawType = data.type ?? 'spec';
+    const upper = rawType.toUpperCase();
+    if (upper !== 'SPEC' && upper !== 'SKILL' && upper !== 'BUNDLE') {
+        throw new ManifestError(`Invalid type: "${rawType}" (expected spec, skill, or bundle)`);
+    }
+    const type = upper;
+    if (data.version !== undefined && typeof data.version !== 'string') {
+        throw new ManifestError(`Invalid version: must be a string, got ${typeof data.version}`);
+    }
+    const version = data.version ?? '1.0.0';
+    if (type !== 'SPEC' && !SEMVER.test(version)) {
+        throw new ManifestError(`Version must be semver (e.g. 1.0.0), got: "${version}"`);
+    }
+    if (typeof data.title !== 'string' || typeof data.description !== 'string' || !data.title || !data.description) {
+        throw new ManifestError('title and description are required');
+    }
+    const title = data.title;
+    const description = data.description;
+    let skills = [];
+    if (type === 'BUNDLE') {
+        if (!Array.isArray(data.skills)) {
+            throw new ManifestError('Bundle manifest must include a `skills` array');
+        }
+        skills = data.skills.map((entry) => {
+            if (typeof entry !== 'string') {
+                throw new ManifestError(`Bundle skills entries must be strings, got: ${JSON.stringify(entry)}`);
+            }
+            return parseSkillRef(entry);
+        });
+    }
+    let sourceEcosystem;
+    if (type === 'SKILL' && data.sourceEcosystem !== undefined) {
+        if (typeof data.sourceEcosystem !== 'string') {
+            throw new ManifestError(`Invalid sourceEcosystem: must be a string, got ${typeof data.sourceEcosystem}`);
+        }
+        sourceEcosystem = data.sourceEcosystem;
+    }
+    let ecosystems;
+    if (data.ecosystems !== undefined) {
+        if (!Array.isArray(data.ecosystems)) {
+            throw new ManifestError('ecosystems must be an array of strings');
+        }
+        ecosystems = data.ecosystems.map((e, i) => {
+            if (typeof e !== 'string')
+                throw new ManifestError(`ecosystems[${i}] must be a string`);
+            return e;
+        });
+    }
+    return { type, version, title, description, sourceEcosystem, ecosystems, skills };
+}

package/dist/lib/manifest.test.d.ts

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

package/dist/lib/manifest.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { parseManifest, ManifestError } from './manifest.js';
+describe('parseManifest', () => {
+    it('parses a SKILL manifest', () => {
+        const m = parseManifest({
+            type: 'skill',
+            version: '1.0.0',
+            title: 'Code Review',
+            description: 'Reviews PRs',
+            sourceEcosystem: 'claude-code',
+        });
+        expect(m.type).toBe('SKILL');
+        expect(m.version).toBe('1.0.0');
+        expect(m.sourceEcosystem).toBe('claude-code');
+    });
+    it('parses a BUNDLE manifest with refs', () => {
+        const m = parseManifest({
+            type: 'bundle',
+            version: '1.0.0',
+            title: 'Eng Skills',
+            description: 'All engineering skills',
+            skills: ['@alice/code-review', '@alice/pr-summary'],
+        });
+        expect(m.type).toBe('BUNDLE');
+        expect(m.skills).toEqual([
+            { username: 'alice', slug: 'code-review' },
+            { username: 'alice', slug: 'pr-summary' },
+        ]);
+    });
+    it('defaults type to SPEC when missing', () => {
+        const m = parseManifest({ title: 't', description: 'd' });
+        expect(m.type).toBe('SPEC');
+    });
+    it('throws on non-semver version', () => {
+        expect(() => parseManifest({ type: 'skill', version: 'latest', title: 't', description: 'd' })).toThrow(ManifestError);
+    });
+    it('throws when bundle skills entry is malformed', () => {
+        expect(() => parseManifest({ type: 'bundle', version: '1.0.0', title: 't', description: 'd', skills: ['not-a-ref'] })).toThrow(ManifestError);
+    });
+    it('accepts skills with leading @', () => {
+        const m = parseManifest({
+            type: 'bundle',
+            version: '1.0.0',
+            title: 't',
+            description: 'd',
+            skills: ['@alice/x', 'bob/y'],
+        });
+        expect(m.skills).toHaveLength(2);
+    });
+    it('throws on non-object input', () => {
+        expect(() => parseManifest(null)).toThrow(ManifestError);
+        expect(() => parseManifest('string')).toThrow(ManifestError);
+        expect(() => parseManifest(42)).toThrow(ManifestError);
+    });
+    it('throws on non-string type field', () => {
+        expect(() => parseManifest({ type: 42, title: 't', description: 'd' })).toThrow(ManifestError);
+    });
+    it('throws when bundle is missing skills array', () => {
+        expect(() => parseManifest({ type: 'bundle', version: '1.0.0', title: 't', description: 'd' })).toThrow(ManifestError);
+    });
+    it('parses ecosystems[] field on a SKILL manifest', () => {
+        const m = parseManifest({
+            type: 'skill',
+            version: '1.0.0',
+            title: 'X',
+            description: 'Y',
+            sourceEcosystem: 'claude-code',
+            ecosystems: ['claude', 'claude-code', 'cursor'],
+        });
+        expect(m.ecosystems).toEqual(['claude', 'claude-code', 'cursor']);
+    });
+});

package/dist/lib/prompts.d.ts

@@ -0,0 +1,5 @@
+export type CleanUpdateChoice = 'apply' | 'skip' | 'diff';
+export declare function promptCleanUpdate(label: string): Promise<CleanUpdateChoice>;
+export type ConflictChoice = 'skip' | 'overwrite';
+export declare function promptConflict(label: string): Promise<ConflictChoice>;
+export declare function confirmOverwrite(label: string): Promise<boolean>;

package/dist/lib/prompts.js

@@ -0,0 +1,26 @@
+import { confirm, select } from '@inquirer/prompts';
+export async function promptCleanUpdate(label) {
+    return select({
+        message: `Apply update for ${label}?`,
+        choices: [
+            { name: 'apply', value: 'apply' },
+            { name: 'skip', value: 'skip' },
+            { name: 'diff (show before deciding)', value: 'diff' },
+        ],
+    });
+}
+export async function promptConflict(label) {
+    return 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' },
+        ],
+    });
+}
+export async function confirmOverwrite(label) {
+    return confirm({
+        message: `${label}: this will REPLACE your local edits with the upstream version. Are you sure?`,
+        default: false,
+    });
+}

package/dist/lib/shell-hook.d.ts

@@ -0,0 +1,12 @@
+export declare const BEGIN = "# BEGIN @botdocs/cli";
+export declare const END = "# END @botdocs/cli";
+export type Shell = 'zsh' | 'bash' | 'fish';
+export declare function detectShell(env?: NodeJS.ProcessEnv): Shell | null;
+export declare function installShellHook(shell: Shell): {
+    action: 'created' | 'updated';
+    path: string;
+};
+export declare function uninstallShellHook(shell: Shell): {
+    removed: boolean;
+    path: string;
+};

package/dist/lib/shell-hook.js

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const BEGIN = '# BEGIN @botdocs/cli';
+export const END = '# END @botdocs/cli';
+export function detectShell(env = process.env) {
+    // Prefer the login shell from $SHELL — that's what the user actually uses.
+    // ZSH_VERSION / BASH only fire when invoked FROM that shell, so they're
+    // less reliable when users run this command via bash -c or similar.
+    const shell = env.SHELL ?? '';
+    if (shell.endsWith('zsh'))
+        return 'zsh';
+    if (shell.endsWith('bash'))
+        return 'bash';
+    if (shell.endsWith('fish'))
+        return 'fish';
+    if (env.ZSH_VERSION)
+        return 'zsh';
+    if (env.BASH || env.BASH_VERSION)
+        return 'bash';
+    return null;
+}
+function rcPath(shell) {
+    const home = os.homedir();
+    if (shell === 'zsh')
+        return path.join(home, '.zshrc');
+    if (shell === 'bash')
+        return path.join(home, '.bashrc');
+    return path.join(home, '.config', 'fish', 'config.fish');
+}
+function snippet(shell) {
+    if (shell === 'fish') {
+        return [
+            BEGIN,
+            'if type -q botdocs',
+            '  botdocs check-updates --quiet 2>/dev/null',
+            'end',
+            END,
+        ].join('\n');
+    }
+    return [
+        BEGIN,
+        'if command -v botdocs >/dev/null 2>&1; then',
+        '  botdocs check-updates --quiet 2>/dev/null',
+        'fi',
+        END,
+    ].join('\n');
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function installShellHook(shell) {
+    const filePath = rcPath(shell);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const block = snippet(shell);
+    if (!fs.existsSync(filePath)) {
+        fs.writeFileSync(filePath, `${block}\n`, 'utf-8');
+        return { action: 'created', path: filePath };
+    }
+    const existing = fs.readFileSync(filePath, 'utf-8');
+    const re = new RegExp(`${escapeRegExp(BEGIN)}[\\s\\S]*?${escapeRegExp(END)}\\n?`);
+    if (re.test(existing)) {
+        fs.writeFileSync(filePath, existing.replace(re, `${block}\n`), 'utf-8');
+        return { action: 'updated', path: filePath };
+    }
+    const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+    fs.writeFileSync(filePath, existing + sep + block + '\n', 'utf-8');
+    return { action: 'updated', path: filePath };
+}
+export function uninstallShellHook(shell) {
+    const filePath = rcPath(shell);
+    if (!fs.existsSync(filePath))
+        return { removed: false, path: filePath };
+    const existing = fs.readFileSync(filePath, 'utf-8');
+    const re = new RegExp(`${escapeRegExp(BEGIN)}[\\s\\S]*?${escapeRegExp(END)}\\n?`);
+    if (!re.test(existing))
+        return { removed: false, path: filePath };
+    fs.writeFileSync(filePath, existing.replace(re, ''), 'utf-8');
+    return { removed: true, path: filePath };
+}

package/dist/lib/shell-hook.test.d.ts

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

package/dist/lib/shell-hook.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { detectShell, installShellHook, uninstallShellHook, BEGIN, END } from './shell-hook.js';
+describe('shell-hook', () => {
+    const origHome = os.homedir;
+    let homeTmp;
+    beforeEach(() => {
+        homeTmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sh-'));
+        os.homedir = () => homeTmp;
+    });
+    afterEach(() => {
+        fs.rmSync(homeTmp, { recursive: true, force: true });
+        os.homedir = origHome;
+    });
+    it('detectShell returns zsh for ZSH_VERSION env', () => {
+        expect(detectShell({ ZSH_VERSION: '5.9' })).toBe('zsh');
+    });
+    it('detectShell returns bash from BASH env', () => {
+        expect(detectShell({ BASH: '/bin/bash' })).toBe('bash');
+    });
+    it('detectShell falls back to SHELL env', () => {
+        expect(detectShell({ SHELL: '/usr/bin/fish' })).toBe('fish');
+        expect(detectShell({ SHELL: '/bin/zsh' })).toBe('zsh');
+    });
+    it('detectShell returns null for unknown shells', () => {
+        expect(detectShell({ SHELL: '/bin/csh' })).toBeNull();
+    });
+    it('detectShell prefers $SHELL over BASH env var (handles bash -c from zsh)', () => {
+        // User's login shell is zsh; they ran the command via `bash -c botdocs ...`
+        // which exports BASH=/bin/bash. We want zsh, not bash.
+        expect(detectShell({ SHELL: '/bin/zsh', BASH: '/bin/bash' })).toBe('zsh');
+    });
+    it('installShellHook creates a delimited block in .zshrc', () => {
+        const result = installShellHook('zsh');
+        const rc = fs.readFileSync(path.join(homeTmp, '.zshrc'), 'utf-8');
+        expect(rc).toContain(BEGIN);
+        expect(rc).toContain(END);
+        expect(rc).toContain('botdocs check-updates --quiet');
+        expect(result.action).toBe('created');
+    });
+    it('installShellHook is idempotent on re-run', () => {
+        installShellHook('zsh');
+        const r2 = installShellHook('zsh');
+        const rc = fs.readFileSync(path.join(homeTmp, '.zshrc'), 'utf-8');
+        expect(rc.match(new RegExp(BEGIN.replace(/[/\\$.*+?()[\]{}|]/g, '\\$&'), 'g'))).toHaveLength(1);
+        expect(r2.action).toBe('updated');
+    });
+    it('installShellHook preserves user content outside the markers', () => {
+        fs.writeFileSync(path.join(homeTmp, '.bashrc'), 'export EDITOR=vim\n', 'utf-8');
+        installShellHook('bash');
+        const rc = fs.readFileSync(path.join(homeTmp, '.bashrc'), 'utf-8');
+        expect(rc).toContain('export EDITOR=vim');
+        expect(rc).toContain(BEGIN);
+    });
+    it('uninstallShellHook removes the block', () => {
+        installShellHook('zsh');
+        uninstallShellHook('zsh');
+        const rc = fs.readFileSync(path.join(homeTmp, '.zshrc'), 'utf-8');
+        expect(rc).not.toContain(BEGIN);
+    });
+    it('writes the fish-syntax variant for fish', () => {
+        installShellHook('fish');
+        const rc = fs.readFileSync(path.join(homeTmp, '.config', 'fish', 'config.fish'), 'utf-8');
+        expect(rc).toContain('botdocs check-updates --quiet');
+    });
+});