@botdocs/cli 0.3.1 → 0.4.0

package/dist/commands/team.js

@@ -0,0 +1,251 @@
+import { ApiError, apiFetch } from '../lib/api.js';
+function reportApiError(err) {
+    if (err instanceof ApiError) {
+        if (err.status === 401) {
+            console.error('\n  ✗ Not authenticated. Run `botdocs login` first.\n');
+            process.exit(1);
+        }
+        console.error(`\n  ✗ ${err.message || `HTTP ${err.status}`}\n`);
+        process.exit(1);
+    }
+    throw err;
+}
+function parseSkillRef(raw) {
+    const cleaned = raw.startsWith('@') ? raw.slice(1) : raw;
+    const parts = cleaned.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error(`Invalid ref: ${raw} (expected @user/slug)`);
+    }
+    return { username: parts[0], slug: parts[1] };
+}
+async function teamList(options) {
+    let resp;
+    try {
+        resp = await apiFetch('/api/teams', { auth: true });
+    }
+    catch (err) {
+        reportApiError(err);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(resp));
+        return;
+    }
+    if (resp.teams.length === 0) {
+        console.log('\n  not a member of any teams yet — try `botdocs team create <slug> --name "..."`\n');
+        return;
+    }
+    console.log('');
+    for (const t of resp.teams) {
+        console.log(`  ${t.slug}  (${t.role}, ${t.memberCount} member${t.memberCount === 1 ? '' : 's'}, ${t.skillCount} skill${t.skillCount === 1 ? '' : 's'})`);
+        console.log(`    ${t.name}`);
+        if (t.description)
+            console.log(`    ${t.description}`);
+    }
+    console.log('');
+}
+async function teamCreate(slug, options) {
+    if (!options.name) {
+        console.error('\n  ✗ --name is required\n');
+        process.exit(1);
+    }
+    let resp;
+    try {
+        resp = await apiFetch('/api/teams', {
+            method: 'POST',
+            auth: true,
+            body: { slug, name: options.name, description: options.description },
+        });
+    }
+    catch (err) {
+        reportApiError(err);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(resp));
+        return;
+    }
+    console.log(`\n  ✓ Created team ${resp.team.slug}`);
+    console.log(`    https://botdocs.ai/teams/${resp.team.slug}\n`);
+}
+async function teamShow(slug, options) {
+    let team;
+    let members;
+    let skills;
+    try {
+        team = await apiFetch(`/api/teams/${slug}`, { auth: true });
+        members = await apiFetch(`/api/teams/${slug}/members`, { auth: true });
+        skills = await apiFetch(`/api/teams/${slug}/skills`, { auth: true });
+    }
+    catch (err) {
+        reportApiError(err);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ team: team.team, role: team.role, members: members.members, skills: skills.skills }));
+        return;
+    }
+    console.log(`\n  ${team.team.slug}  (you are ${team.role})`);
+    console.log(`    ${team.team.name}`);
+    if (team.team.description)
+        console.log(`    ${team.team.description}`);
+    console.log(`\n  Members (${members.members.length}):`);
+    for (const m of members.members) {
+        console.log(`    @${m.username}  (${m.role}) — ${m.displayName}`);
+    }
+    console.log(`\n  Pinned skills (${skills.skills.length}):`);
+    if (skills.skills.length === 0) {
+        console.log('    (none yet — run `botdocs team push <slug> @user/skill` to pin)');
+    }
+    else {
+        for (const s of skills.skills) {
+            const ver = s.versionPin ? `v${s.versionPin} (pinned)` : s.currentVersion ? `v${s.currentVersion}` : 'unpublished';
+            const title = s.title ?? '(unpublished)';
+            console.log(`    @${s.username}/${s.slug}  ${ver}`);
+            console.log(`      ${title}`);
+        }
+    }
+    console.log('');
+}
+async function teamAdd(slug, username, options) {
+    const role = options.role ? options.role.toUpperCase() : 'WRITE';
+    if (!['ADMIN', 'WRITE', 'READ'].includes(role)) {
+        console.error('\n  ✗ Role must be one of: admin, write, read\n');
+        process.exit(1);
+    }
+    let resp;
+    try {
+        resp = await apiFetch(`/api/teams/${slug}/members`, {
+            method: 'POST',
+            auth: true,
+            body: { username, role },
+        });
+    }
+    catch (err) {
+        reportApiError(err);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(resp));
+        return;
+    }
+    console.log(`\n  ✓ Added @${resp.member.username} to ${slug} as ${resp.member.role}\n`);
+}
+async function teamRemove(slug, username, options) {
+    // Resolve username → userId via members list (avoids needing a separate
+    // /api/users/[username] route).
+    let members;
+    try {
+        members = await apiFetch(`/api/teams/${slug}/members`, { auth: true });
+    }
+    catch (err) {
+        reportApiError(err);
+    }
+    const target = members.members.find((m) => m.username === username);
+    if (!target) {
+        console.error(`\n  ✗ @${username} is not a member of ${slug}\n`);
+        process.exit(1);
+    }
+    try {
+        await apiFetch(`/api/teams/${slug}/members/${target.userId}`, {
+            method: 'DELETE',
+            auth: true,
+        });
+    }
+    catch (err) {
+        reportApiError(err);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ removed: { slug, username } }));
+        return;
+    }
+    console.log(`\n  ✓ Removed @${username} from ${slug}\n`);
+}
+async function teamPush(slug, ref, options) {
+    const parsed = parseSkillRef(ref);
+    let resp;
+    try {
+        resp = await apiFetch(`/api/teams/${slug}/skills`, {
+            method: 'POST',
+            auth: true,
+            body: {
+                username: parsed.username,
+                slug: parsed.slug,
+                versionPin: options.version ?? null,
+            },
+        });
+    }
+    catch (err) {
+        reportApiError(err);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(resp));
+        return;
+    }
+    const verNote = resp.skill.versionPin ? ` (pinned to v${resp.skill.versionPin})` : '';
+    console.log(`\n  ✓ Pinned @${parsed.username}/${parsed.slug} to ${slug}${verNote}\n`);
+}
+async function teamUnpush(slug, ref, options) {
+    const parsed = parseSkillRef(ref);
+    try {
+        await apiFetch(`/api/teams/${slug}/skills/${parsed.username}/${parsed.slug}`, {
+            method: 'DELETE',
+            auth: true,
+        });
+    }
+    catch (err) {
+        reportApiError(err);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ unpinned: { slug, ref } }));
+        return;
+    }
+    console.log(`\n  ✓ Unpinned @${parsed.username}/${parsed.slug} from ${slug}\n`);
+}
+export function registerTeamCommands(program) {
+    const team = program
+        .command('team')
+        .description('Manage teams: shared skill libraries for your org');
+    team
+        .command('list')
+        .description('List teams you are a member of')
+        .action(async () => {
+        await teamList({ json: program.opts().json });
+    });
+    team
+        .command('create <slug>')
+        .description('Create a new team (you become its first ADMIN)')
+        .requiredOption('--name <name>', 'Display name for the team')
+        .option('--description <description>', 'Optional description')
+        .action(async (slug, opts) => {
+        await teamCreate(slug, { ...opts, json: program.opts().json });
+    });
+    team
+        .command('show <slug>')
+        .description('Show a team — info, members, and pinned skills')
+        .action(async (slug) => {
+        await teamShow(slug, { json: program.opts().json });
+    });
+    team
+        .command('add <slug> <username>')
+        .description('Add a user to a team by username (ADMIN only)')
+        .option('--role <role>', 'Role: admin, write, or read', 'write')
+        .action(async (slug, username, opts) => {
+        await teamAdd(slug, username, { ...opts, json: program.opts().json });
+    });
+    team
+        .command('remove <slug> <username>')
+        .description('Remove a user from a team (ADMIN only; or self-leave)')
+        .action(async (slug, username) => {
+        await teamRemove(slug, username, { json: program.opts().json });
+    });
+    team
+        .command('push <slug> <ref>')
+        .description('Pin a published skill to a team (WRITE+ only)')
+        .option('--version <v>', 'Pin to a specific version (omit to float to latest)')
+        .action(async (slug, ref, opts) => {
+        await teamPush(slug, ref, { ...opts, json: program.opts().json });
+    });
+    team
+        .command('unpush <slug> <ref>')
+        .description('Unpin a skill from a team (WRITE+ only)')
+        .action(async (slug, ref) => {
+        await teamUnpush(slug, ref, { json: program.opts().json });
+    });
+}

package/dist/commands/undo.d.ts

@@ -0,0 +1,19 @@
+export interface UndoOptions {
+    /** Show the plan but don't write. */
+    dryRun?: boolean;
+    /** Skip the confirmation prompt. */
+    yes?: boolean;
+    /** Don't back up the current state before restoring (advanced). */
+    noBackup?: boolean;
+    /** Output JSON instead of human-readable text. */
+    json?: boolean;
+}
+/** Restore the most recent backup run.
+ *
+ * - Finds the newest run via `listBackupRuns`. If there are none, prints a
+ *   friendly "nothing to undo" and exits.
+ * - Prints a summary of what will be restored, including the note that the
+ *   current state will itself be backed up first (so undo is reversible).
+ * - Prompts y/N unless `--yes`. On cancel, exits gracefully.
+ * - On confirm, calls `restoreBackup` and prints the result. */
+export declare function undo(options?: UndoOptions): Promise<void>;

package/dist/commands/undo.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import * as p from '@clack/prompts';
+import { listBackupRuns, listBackupFiles, restoreBackup, } from '../lib/backup.js';
+/** Restore the most recent backup run.
+ *
+ * - Finds the newest run via `listBackupRuns`. If there are none, prints a
+ *   friendly "nothing to undo" and exits.
+ * - Prints a summary of what will be restored, including the note that the
+ *   current state will itself be backed up first (so undo is reversible).
+ * - Prompts y/N unless `--yes`. On cancel, exits gracefully.
+ * - On confirm, calls `restoreBackup` and prints the result. */
+export async function undo(options = {}) {
+    const projectRoot = process.cwd();
+    const runs = listBackupRuns(projectRoot);
+    if (runs.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify({ undone: null, message: 'No backups to undo.' }));
+        }
+        else {
+            console.log('\n  No backups to undo.\n');
+        }
+        return;
+    }
+    const latest = runs[0];
+    const entries = listBackupFiles(latest.runTimestamp, projectRoot);
+    if (!options.json) {
+        const verb = options.dryRun ? 'Would restore' : 'Restore';
+        console.log(`\n  ${verb} backup run: ${latest.runTimestamp}`);
+        console.log(`  Files: ${entries.length}\n`);
+        for (const e of entries) {
+            const rel = path.relative(projectRoot, e.originalPath) || e.originalPath;
+            console.log(`    ${rel}`);
+        }
+        if (!options.noBackup && !options.dryRun) {
+            console.log('\n  The current files at these paths will themselves be backed up first');
+            console.log('  (you can `botdocs undo` again to swap back).');
+        }
+        console.log('');
+    }
+    if (!options.dryRun && !options.yes && !options.json) {
+        const confirmed = await p.confirm({
+            message: `Restore ${entries.length} file(s) from ${latest.runTimestamp}?`,
+            initialValue: false,
+        });
+        // Clack returns a cancel sentinel on Ctrl-C; treat that as "cancelled" too.
+        if (p.isCancel(confirmed) || !confirmed) {
+            console.log('  Cancelled.\n');
+            return;
+        }
+    }
+    const result = restoreBackup(latest.runTimestamp, projectRoot, {
+        dryRun: options.dryRun,
+        noBackup: options.noBackup,
+    });
+    if (options.json) {
+        console.log(JSON.stringify({
+            runTimestamp: latest.runTimestamp,
+            dryRun: options.dryRun ?? false,
+            restored: result.restored.map((e) => e.originalPath),
+            failed: result.failed.map((f) => ({
+                originalPath: f.entry.originalPath,
+                error: f.error,
+            })),
+            preBackedUp: result.preBackedUp,
+        }));
+        return;
+    }
+    reportRestoreResult(result, projectRoot, options.dryRun ?? false);
+}
+function reportRestoreResult(result, projectRoot, dryRun) {
+    const verb = dryRun ? 'Would restore' : 'Restored';
+    console.log(`  ✓ ${verb} ${result.restored.length} file(s)`);
+    for (const e of result.restored) {
+        const rel = path.relative(projectRoot, e.originalPath) || e.originalPath;
+        console.log(`    ${rel}`);
+    }
+    if (result.failed.length > 0) {
+        console.log(`\n  ⚠ ${result.failed.length} file(s) failed:`);
+        for (const f of result.failed) {
+            const rel = path.relative(projectRoot, f.entry.originalPath) || f.entry.originalPath;
+            console.log(`    ${rel}  (${f.error})`);
+        }
+    }
+    if (!dryRun && result.preBackedUp.length > 0) {
+        console.log(`\n  Pre-backed-up ${result.preBackedUp.length} file(s) — run \`botdocs undo\` again to swap back.`);
+    }
+    console.log('');
+}

package/dist/commands/views/conflict-prompt.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+import type { SyncFileRow } from './sync-state.js';
+/** The three resolutions available on a conflict. Mirrors `ConflictChoice` in
+ * `commands/sync.ts` — kept in sync by hand because pulling that type would
+ * create a circular dep between the views directory and its parent. */
+export type ConflictChoiceValue = 'keep' | 'overwrite' | 'skip';
+export interface ConflictPromptProps {
+    /** The row whose conflict is being resolved. We render the ref + details
+     * line above the select so the user keeps context for what they're deciding. */
+    row: SyncFileRow;
+    /** Fired when the user picks one of the three options. The caller is
+     * responsible for closing the prompt (typically by dispatching the row to
+     * its post-choice state and clearing the conflict resolver). */
+    onChoice: (choice: ConflictChoiceValue) => void;
+}
+/** Inline conflict prompt rendered "under" a conflict row in the live sync
+ * view. Three options match the runner's `ConflictChoice` union — `keep` and
+ * `skip` are semantically identical today but kept distinct for forward
+ * compatibility (and so the UI can label them differently).
+ *
+ * The component is intentionally dumb: it owns no state, no I/O. The Ink view
+ * mounts it when a row enters `conflict` with a resolver attached, and the
+ * resolver fires when the user picks. */
+export declare function ConflictPrompt({ row, onChoice }: ConflictPromptProps): React.ReactElement;

package/dist/commands/views/conflict-prompt.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import SelectInput from 'ink-select-input';
+import { theme } from './theme.js';
+/** Inline conflict prompt rendered "under" a conflict row in the live sync
+ * view. Three options match the runner's `ConflictChoice` union — `keep` and
+ * `skip` are semantically identical today but kept distinct for forward
+ * compatibility (and so the UI can label them differently).
+ *
+ * The component is intentionally dumb: it owns no state, no I/O. The Ink view
+ * mounts it when a row enters `conflict` with a resolver attached, and the
+ * resolver fires when the user picks. */
+export function ConflictPrompt({ row, onChoice }) {
+    return (_jsxs(Box, { flexDirection: "column", marginLeft: 2, marginTop: 1, children: [_jsxs(Text, { children: [_jsx(Text, { color: theme.amber, children: "\u26A0 " }), _jsx(Text, { children: row.ref }), row.details ? (_jsxs(_Fragment, { children: [_jsx(Text, { color: theme.zinc, children: " \u2014 " }), _jsx(Text, { children: row.details })] })) : null] }), _jsx(Text, { color: theme.zinc, children: "  Local edits detected. What should we do?" }), _jsx(Box, { marginLeft: 2, marginTop: 1, children: _jsx(SelectInput, { items: [
+                        { key: 'k', label: 'Keep my local version', value: 'keep' },
+                        { key: 'o', label: 'Overwrite with new version', value: 'overwrite' },
+                        { key: 's', label: 'Skip and continue', value: 'skip' },
+                    ], onSelect: (item) => onChoice(item.value) }) })] }));
+}

package/dist/commands/views/login-app.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+/** All visible states the login flow can be in. The component is a thin
+ * renderer over this status — the actual work (init, polling, save) is driven
+ * by callbacks from the parent so the Ink view stays I/O-free for testing. */
+export type LoginStatus = 'initializing' | 'browser-opening' | 'polling' | 'success' | 'expired' | 'error';
+export interface LoginAppProps {
+    /** Current visible state. Parent updates this as the auth flow progresses. */
+    status: LoginStatus;
+    /** Full URL to display (only relevant during 'polling'). */
+    authUrl?: string;
+    /** Last 6 hex chars of the state — printed as a "Confirm the suffix matches
+     * …xxxxxx" hint so the user can verify the right page in their browser. */
+    stateTail?: string;
+    /** Resolved username after success. Used for the celebratory "Signed in as
+     * @username" line. */
+    username?: string;
+    /** Free-form error message for `status === 'error'`. */
+    errorMessage?: string;
+    /** When sync-library was requested, surface a follow-up hint after success. */
+    syncLibrary?: boolean;
+    /** Terminal width — used to decide whether the BigText wordmark fits. Inject
+     * here (instead of reading at module load) so tests can render at a fixed
+     * width. */
+    columns?: number;
+}
+/** Live Ink view for `botdocs login`. The component is a pure function of
+ * `status`; the parent owns the polling timer and dispatches status changes
+ * via props. On `success`, `expired`, or `error` the parent should call
+ * `unmount()` from `render(...)` shortly after the user has seen the result. */
+export declare function LoginApp(props: LoginAppProps): React.ReactElement;

package/dist/commands/views/login-app.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Box, Text, useApp } from 'ink';
+import Spinner from 'ink-spinner';
+import Gradient from 'ink-gradient';
+import BigText from 'ink-big-text';
+import { theme, BIG_TEXT_MIN_COLS } from './theme.js';
+/** Brand wordmark. Falls back to a bold plain "botdocs" on narrow terminals
+ * where ASCII art would wrap. The `tiny` font keeps the cap height low so the
+ * screen stays scannable. */
+function BrandMark({ columns }) {
+    if (columns < BIG_TEXT_MIN_COLS) {
+        return (_jsx(Text, { bold: true, color: theme.cyan, children: "botdocs" }));
+    }
+    return (_jsx(Gradient, { colors: [theme.cyan, theme.violet], children: _jsx(BigText, { text: "botdocs", font: "tiny" }) }));
+}
+/** Single source of truth for active-state lines. Returns a label + spinner
+ * pair the renderer can drop into the layout — keeps the state-string mapping
+ * in one place. */
+function ActiveLine({ status }) {
+    switch (status) {
+        case 'initializing':
+            return (_jsxs(Text, { children: [_jsx(Text, { color: theme.cyan, children: _jsx(Spinner, { type: "dots" }) }), ' ', _jsx(Text, { children: "Generating session..." })] }));
+        case 'browser-opening':
+            return (_jsxs(Text, { children: [_jsx(Text, { color: theme.cyan, children: _jsx(Spinner, { type: "dots" }) }), ' ', _jsx(Text, { children: "Opening your browser..." })] }));
+        case 'polling':
+            return (_jsxs(Text, { children: [_jsx(Text, { color: theme.cyan, children: _jsx(Spinner, { type: "dots" }) }), ' ', _jsx(Text, { children: "Waiting for authorization..." })] }));
+        default:
+            return null;
+    }
+}
+/** Live Ink view for `botdocs login`. The component is a pure function of
+ * `status`; the parent owns the polling timer and dispatches status changes
+ * via props. On `success`, `expired`, or `error` the parent should call
+ * `unmount()` from `render(...)` shortly after the user has seen the result. */
+export function LoginApp(props) {
+    const { status, authUrl, stateTail, username, errorMessage, syncLibrary, columns } = props;
+    const { exit } = useApp();
+    // Terminal width — fall back to a sensible default for non-TTY paths or
+    // when stdout doesn't expose `columns` yet. The component only branches on
+    // this to choose between the BigText wordmark and the plain fallback.
+    const [cols] = useState(columns ?? process.stdout.columns ?? 80);
+    // Auto-exit after a terminal state. The small delay on `success` gives the
+    // user a moment to read the celebratory line before the screen unmounts.
+    useEffect(() => {
+        if (status === 'success') {
+            const timer = setTimeout(() => exit(), 800);
+            return () => clearTimeout(timer);
+        }
+        if (status === 'expired' || status === 'error') {
+            const timer = setTimeout(() => exit(), 50);
+            return () => clearTimeout(timer);
+        }
+        return undefined;
+    }, [status, exit]);
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, paddingY: 1, children: [_jsx(BrandMark, { columns: cols }), _jsx(Box, { marginTop: 1, children: _jsx(ActiveLine, { status: status }) }), status === 'polling' && authUrl ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: theme.zinc, children: "Authorize this session at:" }), _jsx(Text, { children: authUrl }), stateTail ? (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: theme.zinc, children: ["Confirm the suffix matches: \u2026", stateTail] }) })) : null, _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: theme.zinc, children: "State expires in 10 minutes \u2014 press Ctrl-C to abort." }) })] })) : null, status === 'success' && username ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { color: theme.green, children: ["\u2713 Signed in as @", username] }), syncLibrary ? (_jsx(Text, { color: theme.zinc, children: "Library sync enabled \u2014 your installed-refs will appear at https://botdocs.ai/library." })) : (_jsx(Text, { color: theme.zinc, children: "Library sync is OFF. Re-run with --sync-library to enable the personalized Library page." }))] })) : null, status === 'expired' ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: theme.amber, children: "Authorization expired \u2014 re-run `botdocs login`." }) })) : null, status === 'error' ? (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: theme.red, children: ["\u2717 ", errorMessage ?? 'Login failed.'] }) })) : null] }));
+}

package/dist/commands/views/sync-app.d.ts

@@ -0,0 +1,27 @@
+import React from 'react';
+import { type SyncAction } from './sync-state.js';
+import { type ConflictChoiceValue } from './conflict-prompt.js';
+/** The dependencies the runner receives from the Ink view. `dispatch` updates
+ * the reducer state; `awaitConflictChoice` returns a Promise that resolves
+ * when the inline prompt fires. */
+export interface SyncDeps {
+    dispatch: (action: SyncAction) => void;
+    awaitConflictChoice: (ref: string, file: string) => Promise<ConflictChoiceValue>;
+}
+export interface SyncAppProps {
+    /** Pre-known rows to seed the queued state. Team rows are added later via
+     * `ADD_ROW` once `/api/cli/teams` returns — we don't have them at mount time. */
+    initialRows: Array<{
+        ref: string;
+        team?: string;
+    }>;
+    /** The async work to run on mount. Receives the dispatch/awaiter pair and
+     * is expected to dispatch FINISH when done. The view auto-unmounts ~600ms
+     * after FINISH so the user can read the summary. */
+    runSync: (deps: SyncDeps) => Promise<void>;
+}
+/** Live Ink view for `botdocs sync`. Owns the reducer state and the conflict
+ * resolver Map. On mount it kicks off `runSync` with a dispatch/awaiter pair —
+ * the awaiter parks a Promise resolver keyed by `ref|file` in a ref-held Map,
+ * and the inline `<ConflictPrompt />` resolves it when the user picks. */
+export declare function SyncApp({ initialRows, runSync }: SyncAppProps): React.ReactElement;