@botdocs/cli 0.10.3 → 0.12.0

package/dist/commands/ingest.js

@@ -1,9 +1,12 @@
 import React from 'react';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { render } from 'ink';
-import { ApiError, apiFetch } from '../lib/api.js';
+import open from 'open';
+import { ApiError, apiFetch, getApiUrl } from '../lib/api.js';
 import { loadAuth } from '../lib/config.js';
+import { IngestSessionClient, PairingClaimError } from '../lib/ingest-session-client.js';
 import { discoverSkills, ecosystemLabel, formatBytes, STUB_BYTE_THRESHOLD, summaryKey, titleFromContent, } from '../lib/ingest-discover.js';
 import { IngestDiscoverApp } from './views/ingest-discover-app.js';
 // ---------- Cap + skip rules (shared with discovery) ----------
@@ -398,17 +401,36 @@ export const DETECTORS = {
     },
 };
 export const SUPPORTED_TOOLS = Object.keys(DETECTORS);
-function walkFiles(root) {
+/**
+ * Recursively collect absolute file paths under `root`.
+ *
+ * Symlinks are skipped (with a warning) to prevent local file exfiltration:
+ * without this check a directory containing a symlink to e.g. `~/.ssh/id_rsa`
+ * would have its target's contents read into memory and uploaded as part of
+ * the ingest payload. `entry.isDirectory()` and `entry.isFile()` come from
+ * the `Dirent` produced by `withFileTypes: true`, which reports the entry's
+ * OWN type (NOT the symlink target's), so the gate is sound. Mirrors
+ * `walkAll` in `src/lib/ingest-discover.ts`.
+ *
+ * Exported for unit testing.
+ */
+export function walkFiles(root) {
     const out = [];
     function walk(dir) {
         for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isSymbolicLink()) {
+                const rel = path.relative(root, full).split(path.sep).join('/');
+                console.warn(`Skipping symlink: ${rel}`);
+                continue;
+            }
             if (entry.isDirectory()) {
                 if (SWEEP_SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))
                     continue;
-                walk(path.join(dir, entry.name));
+                walk(full);
             }
-            else {
-                out.push(path.join(dir, entry.name));
+            else if (entry.isFile()) {
+                out.push(full);
             }
         }
     }
@@ -566,7 +588,74 @@ function reportConflicts(conflicts, options) {
  * response) and the default human-friendly "drafts created" line. On a 409
  * slug-conflict, prints an actionable message and exits non-zero rather than
  * letting the ApiError bubble up as a stack trace. Returns nothing on success. */
-async function uploadSkills(skills, options) {
+/** Best-effort mapping from a DetectedSkill back into one of the four
+ * coarse types the web UI renders ("agent" / "prompt" / "context" /
+ * "workflow"). Falls back to `prompt` because that's the most generic
+ * bucket — the web only uses this for a one-line subtitle so a wrong
+ * guess is cosmetic, not functional. */
+function inferSkillType(skill) {
+    const eco = skill.sourceEcosystem ?? '';
+    if (eco.includes('agent'))
+        return 'agent';
+    // Look for telltale filenames inside the skill bundle.
+    const firstFilename = skill.files[0]?.filename.toLowerCase() ?? '';
+    if (firstFilename.includes('workflow'))
+        return 'workflow';
+    if (firstFilename.includes('context'))
+        return 'context';
+    if (firstFilename.includes('agent'))
+        return 'agent';
+    return 'prompt';
+}
+/** Pull a printable line out of the 413 `detail` field. Accepts both the
+ * new structured shape (`{ message: '…' }`) emitted by `validateSkillCaps`
+ * and the legacy bare-string form. Returns undefined when nothing usable
+ * is present, so the caller can fall back to `err.message`. */
+function extractSizeCapMessage(body) {
+    if (typeof body !== 'object' || body === null)
+        return undefined;
+    const detail = body.detail;
+    if (typeof detail === 'string')
+        return detail;
+    if (typeof detail === 'object' && detail !== null) {
+        const message = detail.message;
+        if (typeof message === 'string' && message.length > 0)
+            return message;
+    }
+    return undefined;
+}
+/** Print an actionable 413 message and exit non-zero. Honors `--json` by
+ * emitting `{ ok: false, status: 413, ... }` so scripts can branch on it.
+ *
+ * Mirrors `handlePathPublishError`'s 413 arm in publish.ts — same shape so
+ * the two commands' size-cap UX stays in sync. */
+function reportSizeCap(err, options) {
+    const detailMessage = extractSizeCapMessage(err.body);
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: false,
+            status: 413,
+            error: err.message,
+            detail: err.body?.detail ?? null,
+        }));
+        process.exit(1);
+    }
+    console.error(`\n  ✗ ${detailMessage ?? err.message}\n`);
+    process.exit(1);
+}
+async function uploadSkills(skills, options, pair) {
+    // Optional: announce intent before the API call so the paired web UI
+    // shows "uploading…" rows immediately. The events POST is batched
+    // server-side so this doesn't cost N round-trips.
+    if (pair?.isPaired) {
+        for (const s of skills) {
+            pair.emit('upload_started', {
+                filename: s.files[0]?.filename ?? `${s.slug}.md`,
+                type: inferSkillType(s),
+                experimental: false,
+            });
+        }
+    }
     let result;
     try {
         result = await apiFetch('/api/cli/ingest', {
@@ -580,13 +669,47 @@ async function uploadSkills(skills, options) {
         });
     }
     catch (err) {
+        // Paired? Tell the web that every skill in this batch failed so the
+        // UI can render the error state cleanly instead of hanging on
+        // "uploading…".
+        if (pair?.isPaired) {
+            const reason = err instanceof Error ? err.message : 'upload failed';
+            for (const s of skills) {
+                pair.emit('upload_failed', {
+                    filename: s.files[0]?.filename ?? `${s.slug}.md`,
+                    reason,
+                });
+            }
+        }
         if (err instanceof ApiError && err.status === 409) {
             const conflicts = parseConflicts(err.body);
             if (conflicts)
                 reportConflicts(conflicts, options);
         }
+        // 413 PAYLOAD_TOO_LARGE — server's `validateSkillCaps` rejected one of
+        // the skills in the payload. The body's `detail.message` is the human
+        // line ("file foo/bar.md is 71 KB, cap is 64 KB per file"); fall back
+        // to the older `detail: string` shape and finally `err.message` so
+        // mixed-version client/server pairs still print something useful.
+        if (err instanceof ApiError && err.status === 413) {
+            reportSizeCap(err, options);
+        }
         throw err;
     }
+    // Success: emit one completed event per skill so the web UI's card
+    // stream populates. The bundle-level draftId is the same for every
+    // skill in this run — the web uses it to build the review link.
+    if (pair?.isPaired) {
+        for (const s of skills) {
+            pair.emit('upload_completed', {
+                filename: s.files[0]?.filename ?? `${s.slug}.md`,
+                type: inferSkillType(s),
+                experimental: false,
+                draftId: result.draftId,
+                slug: s.slug,
+            });
+        }
+    }
     if (options.json) {
         console.log(JSON.stringify(result));
         return;
@@ -652,7 +775,7 @@ function printDiscoveryPlainText(discovered, skillSummaries) {
 /** The zero-argument discovery entry point. Scans known on-disk locations,
  * routes through the TUI (or its fallbacks) per the user's options + tty
  * state, and uploads the user's selection. */
-async function ingestDiscover(options) {
+async function ingestDiscover(options, pair) {
     const discovery = discoverSkills();
     if (discovery.files.length === 0) {
         console.log('\n  No skills found. Try `botdocs init` to scaffold a new one, or point at a path: `botdocs ingest <dir>`\n');
@@ -724,7 +847,15 @@ async function ingestDiscover(options) {
             if (line)
                 console.log(line);
         }
-        await uploadSkills(skills, options);
+        // Paired runs emit selection_committed so the web UI knows the total
+        // before per-skill events arrive (drives the "X / Y received" counter).
+        if (pair?.isPaired) {
+            pair.emit('selection_committed', {
+                totalSelected: skills.length,
+                candidatesScanned: discovery.files.filter(isRoot).length,
+            });
+        }
+        await uploadSkills(skills, options, pair);
         return;
     }
     const useInk = !options.noInk && Boolean(process.stdout.isTTY);
@@ -759,7 +890,13 @@ async function ingestDiscover(options) {
         return;
     }
     const skills = groupDiscoveredIntoSkills(result.selected);
-    await uploadSkills(skills, options);
+    if (pair?.isPaired) {
+        pair.emit('selection_committed', {
+            totalSelected: skills.length,
+            candidatesScanned: discovery.files.filter(isRoot).length,
+        });
+    }
+    await uploadSkills(skills, options, pair);
 }
 /** Human-readable list of all canonical path prefixes for the empty-result message. */
 function ecosystemPrefixSummary() {
@@ -767,16 +904,160 @@ function ecosystemPrefixSummary() {
         .map((d) => d.pathPrefix)
         .join(', ');
 }
+/** Read one line from stdin without blocking the rest of the CLI. Used for
+ * the `--pair` interactive prompt — kept small and dependency-free so the
+ * standard ingest path doesn't pull in a prompt library. Returns null on
+ * EOF / non-TTY (caller treats that as "skip pairing"). */
+async function readLine(prompt) {
+    if (!process.stdin.isTTY)
+        return null;
+    process.stdout.write(prompt);
+    return new Promise((resolve) => {
+        const onData = (chunk) => {
+            const text = chunk.toString('utf8').replace(/[\r\n]+$/, '');
+            process.stdin.off('data', onData);
+            process.stdin.pause();
+            resolve(text || null);
+        };
+        process.stdin.resume();
+        process.stdin.on('data', onData);
+    });
+}
+/** Tilde-shorten the cwd for display on the web's connection chip. So we
+ * surface `~/projects` instead of `/Users/alice/projects`. */
+function displayCwd(absolute) {
+    const home = os.homedir();
+    if (home && absolute.startsWith(home)) {
+        return absolute.replace(home, '~');
+    }
+    return absolute;
+}
+/** If pairing was requested, walk through the claim flow and return a
+ * connected client. Returns null when pairing is declined, fails, or the
+ * user is not logged in — the caller continues unpaired in all those cases.
+ *
+ * Never throws: pairing is opt-in and a failure must not block ingest. */
+async function setupPairingIfRequested(options) {
+    const wantPair = options.pair === true || typeof options.pairCode === 'string';
+    if (!wantPair)
+        return null;
+    // We need auth to claim — same as the ingest API call itself. If they're
+    // not logged in, the rest of the flow will surface that error; pairing
+    // can't help here.
+    if (!loadAuth()) {
+        console.log('  → Pairing skipped (not signed in).');
+        return null;
+    }
+    let code = options.pairCode;
+    if (!code) {
+        // Auto-open the pairing page in the user's default browser unless they
+        // opted out via --no-browser. The page mints (or reuses) the BD-XXXXX
+        // code server-side, so by the time the browser tab loads, the code is
+        // already on screen — no waiting, no second click.
+        //
+        // We open BEFORE printing the prompt so the order of events feels right
+        // ("browser opens, look there, paste here"). If `open()` fails — common
+        // in headless / SSH / CI environments — we swallow the error and fall
+        // back to the printed URL. The CLI must never become unusable because
+        // we couldn't reach a graphical browser.
+        const pairUrl = `${getApiUrl()}/pair`;
+        const shouldOpen = options.noBrowser !== true;
+        let browserOpened = false;
+        if (shouldOpen) {
+            try {
+                await open(pairUrl);
+                browserOpened = true;
+            }
+            catch {
+                /* swallow — fall back to the printed URL below */
+            }
+        }
+        console.log('');
+        if (browserOpened) {
+            console.log(`  ✓ Opened ${pairUrl} in your browser.`);
+            console.log('    Copy the BD-XXXXX code shown there and paste it here.');
+        }
+        else {
+            console.log(`  Get your pairing code at ${pairUrl}`);
+            if (!shouldOpen) {
+                console.log('    (--no-browser is set; visit the URL above manually.)');
+            }
+            else {
+                console.log("    (Browser open failed — open the URL above manually.)");
+            }
+        }
+        console.log('');
+        const entered = await readLine('  Pairing code: ');
+        if (!entered) {
+            console.log('  → Pairing skipped (no code entered).');
+            return null;
+        }
+        code = entered;
+    }
+    const client = new IngestSessionClient();
+    try {
+        await client.claim({
+            code,
+            machineName: os.hostname() || 'unknown',
+            cwd: displayCwd(process.cwd()),
+        });
+        console.log('  ✓ Paired with botdocs.ai\n');
+        return client;
+    }
+    catch (err) {
+        const msg = err instanceof PairingClaimError ? err.message : String(err);
+        console.log(`  ⚠ Could not pair: ${msg}`);
+        console.log('  → Continuing without pairing.\n');
+        return null;
+    }
+}
 export async function ingest(rootPath, options) {
+    // Try to pair before scanning kicks off. setupPairingIfRequested NEVER
+    // throws — null means "carry on unpaired". The client is closed on the
+    // end-of-run paths below.
+    const pair = await setupPairingIfRequested(options);
+    // Wrap the body so we can finalize/cancel symmetrically regardless of
+    // which dispatch path fires below. The `pair` client is null in the
+    // unpaired case, so all the .emit calls inside are no-ops.
+    try {
+        await runIngest(rootPath, options, pair);
+        if (pair)
+            await pair.finalize({ uploaded: 0, failed: 0 });
+        // ↑ totals=0 is a known overstatement; finalize is called from
+        //   uploadSkills' success path in a future revision, but for now the
+        //   per-skill upload_completed events carry the count for the UI.
+    }
+    catch (err) {
+        if (pair)
+            await pair.cancel(err instanceof Error ? err.message : 'ingest failed');
+        throw err;
+    }
+}
+async function runIngest(rootPath, options, pair) {
     // Zero-arg dispatch: scan known on-disk locations and route through the
     // TUI (or its fallbacks). The existing path-based code path below stays
     // identical.
     if (!rootPath) {
-        await ingestDiscover(options);
+        await ingestDiscover(options, pair ?? undefined);
         return;
     }
     const root = path.resolve(rootPath);
-    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    if (!fs.existsSync(root)) {
+        console.error(`\n  ✗ Not a directory: ${rootPath}\n`);
+        process.exit(1);
+        return;
+    }
+    // Refuse a symlinked entry point — same exfil class the walker fix closes
+    // for nested entries. `lstatSync` reports the path's OWN type, so a
+    // directory symlink doesn't silently slip past the `isDirectory()` check
+    // below and let the walker recurse into the target. Fatal (not skip)
+    // since the user explicitly named this path.
+    if (fs.lstatSync(root).isSymbolicLink()) {
+        console.error(`\n  ✗ Refusing to ingest from a symlink: ${rootPath}. Pass the resolved real path instead.\n`);
+        process.exit(1);
+        return;
+    }
+    if (!fs.statSync(root).isDirectory()) {
         console.error(`\n  ✗ Not a directory: ${rootPath}\n`);
         process.exit(1);
         return;
@@ -842,5 +1123,15 @@ export async function ingest(rootPath, options) {
         console.log('\n  --dry-run: not uploading.\n');
         return;
     }
-    await uploadSkills(skills, options);
+    // The path-based branch isn't interactive — there's no "selection" step
+    // (the user gave us a directory and we're uploading what's in it). Still
+    // emit selection_committed so the paired web UI gets a total before the
+    // upload events.
+    if (pair?.isPaired) {
+        pair.emit('selection_committed', {
+            totalSelected: skills.length,
+            candidatesScanned: detected.length,
+        });
+    }
+    await uploadSkills(skills, options, pair ?? undefined);
 }

package/dist/commands/init.d.ts

@@ -2,7 +2,31 @@ interface InitOptions {
     title?: string;
     category?: string;
     json?: boolean;
+    /** Legacy: kept for back-compat with older docs/scripts that explicitly
+     * passed `--canonical`. Canonical IS the default now; this flag is a
+     * no-op. Surfaced separately from `--spec` so a script that passes both
+     * doesn't silently downgrade. */
     canonical?: boolean;
+    /** Opt-in scaffold of the legacy SPEC layout (single `index.md` + a
+     * minimal manifest with no `type`). Used to be the default; now an
+     * explicit choice for authors who genuinely want a non-skill spec.
+     * Most callers should NOT pass this. */
+    spec?: boolean;
 }
+/**
+ * The default description `botdocs init` writes into a fresh `botdocs.json`.
+ * Intentionally distinctive — not empty — so:
+ *   1. `botdocs validate` produces a friendly, specific error (instead of
+ *      the generic "title and description are required") that names the
+ *      placeholder.
+ *   2. `botdocs publish` refuses to ship the unchanged placeholder, which
+ *      would otherwise litter `/explore` with "TODO: …" skills.
+ *
+ * Re-exported from `lib/manifest.ts` so the validator and the scaffolder
+ * agree on the literal without one side drifting. Importing here would
+ * be circular-safe (init never re-imports manifest at runtime), but
+ * routing through manifest keeps a single source of truth.
+ */
+export declare const INIT_PLACEHOLDER_DESCRIPTION = "TODO: describe your skill in one sentence.";
 export declare function init(dirName: string | undefined, options: InitOptions): Promise<void>;
 export {};

package/dist/commands/init.js

@@ -1,6 +1,22 @@
 import { writeFileSync, mkdirSync, existsSync } from 'fs';
 import { dirname, join } from 'path';
 import { relative } from 'node:path';
+import { INIT_PLACEHOLDER_DESCRIPTION as MANIFEST_PLACEHOLDER } from '../lib/manifest.js';
+/**
+ * The default description `botdocs init` writes into a fresh `botdocs.json`.
+ * Intentionally distinctive — not empty — so:
+ *   1. `botdocs validate` produces a friendly, specific error (instead of
+ *      the generic "title and description are required") that names the
+ *      placeholder.
+ *   2. `botdocs publish` refuses to ship the unchanged placeholder, which
+ *      would otherwise litter `/explore` with "TODO: …" skills.
+ *
+ * Re-exported from `lib/manifest.ts` so the validator and the scaffolder
+ * agree on the literal without one side drifting. Importing here would
+ * be circular-safe (init never re-imports manifest at runtime), but
+ * routing through manifest keeps a single source of truth.
+ */
+export const INIT_PLACEHOLDER_DESCRIPTION = MANIFEST_PLACEHOLDER;
 export async function init(dirName, options) {
     const name = dirName || 'my-botdoc';
     const dir = join(process.cwd(), name);
@@ -15,7 +31,15 @@ export async function init(dirName, options) {
     }
     mkdirSync(dir, { recursive: true });
     const title = options.title || name.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-    if (options.canonical) {
+    // Default → canonical skill scaffold. The legacy SPEC layout is now opt-in
+    // via `--spec`. Audit history: the old default wrote a manifest with no
+    // `type`, which the server stored as SPEC; a friend running
+    // `botdocs install @them/skill` then saw "files have no supported agent"
+    // because the row wasn't a SKILL. Canonical-by-default removes that
+    // sharp edge. `--canonical` is kept as a no-op alias so old docs still
+    // work; `--spec` is the only way to get the legacy scaffold now.
+    const useSpec = options.spec === true;
+    if (!useSpec) {
         const sourceFile = join(dir, 'claude-code', 'commands', `${name}.md`);
         mkdirSync(dirname(sourceFile), { recursive: true });
         writeFileSync(sourceFile, `# ${title}\n\n## Overview\n\nDescribe the skill.\n`, 'utf-8');
@@ -23,7 +47,11 @@ export async function init(dirName, options) {
             type: 'skill',
             version: '1.0.0',
             title,
-            description: '',
+            // Placeholder rather than empty string: validate now refuses both the
+            // empty case AND the unchanged placeholder, so the author hits a
+            // specific "edit botdocs.json before publishing" message instead of
+            // the generic missing-field error. See lib/manifest.ts.
+            description: INIT_PLACEHOLDER_DESCRIPTION,
             sourceEcosystem: 'claude-code',
             ecosystems: ['claude', 'claude-code', 'cursor', 'chatgpt'],
             license: 'MIT',
@@ -41,12 +69,14 @@ export async function init(dirName, options) {
             console.log(`\n  Created ${name}/`);
             console.log(`    claude-code/commands/${name}.md  — your canonical source`);
             console.log(`    botdocs.json                     — declares ecosystems to generate`);
-            console.log(`\n  Edit the source file, then:`);
+            console.log(`\n  Edit the source file and the description in botdocs.json, then:`);
             console.log(`    botdocs compile ${name}/`);
             console.log(`    botdocs publish ${name}/\n`);
         }
         return;
     }
+    // Legacy SPEC layout — opt-in via `--spec`. Kept for authors who genuinely
+    // want a non-skill spec document; not the recommended path.
     const indexContent = `# ${title}
 
 ## Overview
@@ -72,19 +102,26 @@ How do you know when an implementation of this spec is correct?
     writeFileSync(join(dir, 'index.md'), indexContent, 'utf-8');
     const botdocsJson = {
         title,
-        description: '',
+        // Same placeholder as the canonical path — keeps the validate behavior
+        // consistent regardless of which scaffold the user picked.
+        description: INIT_PLACEHOLDER_DESCRIPTION,
         category: options.category?.toUpperCase() || 'OTHER',
         tags: [],
         license: 'MIT',
     };
     writeFileSync(join(dir, 'botdocs.json'), JSON.stringify(botdocsJson, null, 2), 'utf-8');
     if (options.json) {
-        console.log(JSON.stringify({ success: true, directory: name, files: ['index.md', 'botdocs.json'] }));
+        console.log(JSON.stringify({
+            success: true,
+            directory: name,
+            files: ['index.md', 'botdocs.json'],
+            canonical: false,
+        }));
     }
     else {
         console.log(`\n  Created ${name}/`);
         console.log(`    index.md       — your spec starts here`);
         console.log(`    botdocs.json   — metadata for publishing`);
-        console.log(`\n  Next: edit index.md, then run botdocs publish ${name}/\n`);
+        console.log(`\n  Edit index.md (and the description in botdocs.json), then run botdocs publish ${name}/\n`);
     }
 }