@botdocs/cli 0.10.3 → 0.11.0

package/README.md

@@ -10,6 +10,8 @@ publish your own.
 
 ## Install
 
+**Requires Node.js 20+.** [Don't have it? Install from nodejs.org →](https://nodejs.org)
+
 ```bash
 # one-off
 npx @botdocs/cli <command>
@@ -26,8 +28,6 @@ After a global install the binary is just `botdocs`:
 botdocs --help
 ```
 
-Requires Node.js 20 or newer.
-
 ## Quick start
 
 ```bash
@@ -50,7 +50,7 @@ botdocs publish my-skill/
 
 | Command | Purpose |
 |---|---|
-| `init [name]` | Scaffold a new skill directory (`--canonical` for a multi-ecosystem skill). |
+| `init [name]` | Scaffold a new skill directory (canonical multi-ecosystem layout by default; `--spec` for the legacy SPEC scaffold). |
 | `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. |
@@ -164,8 +164,10 @@ 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
+botdocs init my-skill                       # canonical scaffold by default:
+                                            # claude-code source + ecosystems list
+                                            # in botdocs.json
+
 # edit claude-code/commands/my-skill.md
 
 botdocs compile my-skill/                  # generates claude/SKILL.md,

package/bin/botdocs.cjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * CommonJS preflight shim.
+ *
+ * This file is the actual `bin` entry — `package.json#bin.botdocs` points
+ * here, not at the ESM `dist/index.js`. The shim's only job is to gate the
+ * Node version BEFORE the ESM entry is loaded.
+ *
+ * Why this exists:
+ *   The previous preflight at the top of `src/index.ts` was structurally
+ *   defeated by ESM import hoisting. `import { checkNodeVersion } from …`
+ *   syntactically runs before the `{ … process.exit(1) }` block, but Node
+ *   evaluates the WHOLE module graph (every `import` in `index.ts` AND
+ *   every transitively-imported file) before any top-level statement
+ *   executes. On Node 16/18 that means a `SyntaxError` from any modern-
+ *   syntax dep (commander, Ink, the openai SDK, etc.) fires first, and
+ *   the user never sees our friendly "install Node 20" line.
+ *
+ *   A CJS shim sidesteps the problem entirely: CommonJS evaluates this
+ *   file synchronously, top-to-bottom, with NO module graph eagerly
+ *   loaded. We can read `process.versions.node`, print a stderr line,
+ *   and exit cleanly before requiring `dist/index.js`. The only globals
+ *   used here (`process`, `String.prototype.split`, `parseInt`) exist on
+ *   every Node version, including the legacy ones we're trying to reject.
+ *
+ * Keep this file LANGUAGE-MINIMAL — no optional chaining, no nullish
+ * coalescing, no `const` at top level (technically fine, but staying
+ * conservative makes the shim robust against any future runtime quirk
+ * on a very old Node). The downstream ESM code can use whatever it wants.
+ */
+
+var MIN_NODE_MAJOR = 20;
+
+function preflight() {
+  var version = process.versions && process.versions.node ? String(process.versions.node) : '';
+  var firstSegment = version.split('.')[0] || '0';
+  var major = parseInt(firstSegment, 10);
+  if (!isFinite(major) || major < MIN_NODE_MAJOR) {
+    process.stderr.write(
+      'BotDocs CLI requires Node.js ' +
+        MIN_NODE_MAJOR +
+        " or newer. You're on Node " +
+        version +
+        '. Install from https://nodejs.org\n',
+    );
+    process.exit(1);
+  }
+}
+
+preflight();
+
+// Hand off to the ESM entry. `require()` of an ES module works in Node 22+
+// via `require(esm)`, but for portability across Node 20.x we use a
+// dynamic import — `import()` is available in CJS on every Node ≥ 13.2.
+// The promise rejection is funneled through the same process-wide
+// unhandledRejection handler that `dist/index.js` installs once it loads,
+// so we don't need a local catch here.
+//
+// `__dirname` is set in CJS; we resolve the ESM entry relative to this
+// file so the shim works whether it's invoked from the local checkout
+// (`packages/cli/bin/botdocs.cjs` next to `packages/cli/dist/index.js`)
+// or from a published install (`node_modules/@botdocs/cli/bin/...` next
+// to `node_modules/@botdocs/cli/dist/...`).
+var path = require('path');
+var url = require('url');
+var entry = path.join(__dirname, '..', 'dist', 'index.js');
+import(url.pathToFileURL(entry).href).catch(function (err) {
+  // Should be unreachable in practice — dist/index.js installs its own
+  // unhandledRejection handler the moment it's loaded. This catch only
+  // fires if loading the module itself fails (e.g. missing dist/, which
+  // would only happen for a broken install).
+  process.stderr.write(
+    'Failed to load BotDocs CLI entry: ' + (err && err.message ? err.message : String(err)) + '\n',
+  );
+  process.exit(1);
+});

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

@@ -2,5 +2,27 @@ interface CheckUpdatesOptions {
     quiet?: boolean;
     json?: boolean;
 }
+export interface UpdateResult {
+    /** When false, the server didn't actually check anything — the user
+     * hasn't opted in via `botdocs login --sync-library` so there's no
+     * snapshot to diff against. Older servers omit this field; the CLI
+     * defaults to the legacy "trusted result" interpretation in that case
+     * (so a fresh CLI against an older server doesn't regress). */
+    enabled?: boolean;
+    total: number;
+    updates: Array<{
+        ref: string;
+        from: string;
+        to: string;
+    }>;
+    removed: Array<{
+        ref: string;
+        reason: string;
+    }>;
+}
+/** Fetch the current update result, served from the cache when fresh. Shared
+ * with `botdocs list --outdated` so the two commands don't duplicate
+ * fingerprint + cache + fetch logic. */
+export declare function fetchUpdates(): Promise<UpdateResult>;
 export declare function checkUpdates(options: CheckUpdatesOptions): Promise<void>;
 export {};

package/dist/commands/check-updates.js

@@ -3,17 +3,24 @@ import os from 'node:os';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { apiFetch } from '../lib/api.js';
+import { loadAuth } from '../lib/config.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). */
+/** Hash of (ref, version) tuples PLUS the current logged-in username —
+ * invalidates the cache both when the user's installed set changes (e.g.
+ * new install, version bump after sync) AND when the user switches
+ * accounts on a shared machine via `botdocs login`. The "anon" sentinel
+ * keeps the fingerprint stable across unauthenticated runs (no auth file)
+ * so the cache still works for users who haven't logged in. */
 function lockfileFingerprint() {
     const lf = loadLockfile();
+    const auth = loadAuth();
+    const username = auth?.username ?? 'anon';
     const summary = lf.installs.map((i) => `${i.ref}@${i.version}`).sort().join('\n');
-    return createHash('sha256').update(summary).digest('hex').slice(0, 16);
+    return createHash('sha256').update(`${username}\n${summary}`).digest('hex').slice(0, 16);
 }
 function loadCache(currentFingerprint) {
     const p = cachePath();
@@ -36,22 +43,25 @@ 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) {
+/** Fetch the current update result, served from the cache when fresh. Shared
+ * with `botdocs list --outdated` so the two commands don't duplicate
+ * fingerprint + cache + fetch logic. */
+export async function fetchUpdates() {
     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 (cached)
+        return cached;
+    // Server reads from user_library.lockfile (set by syncLibrary helper).
+    // No body — auth-gated endpoint trusts the server-side snapshot, not the wire.
+    const result = await apiFetch('/api/library/check-updates', {
+        method: 'POST',
+        auth: true,
+    });
+    saveCache(fingerprint, result);
+    return result;
+}
+export async function checkUpdates(options) {
+    const result = await fetchUpdates();
     if (options.json) {
         console.log(JSON.stringify(result));
         return;
@@ -63,6 +73,19 @@ export async function checkUpdates(options) {
         return;
     }
     if (result.total === 0) {
+        // When the server reports `enabled: false`, it didn't actually compare
+        // anything — the user never opted in to library-sync, so there's no
+        // server-side lockfile snapshot to diff against. Don't lie with "all up
+        // to date"; surface the opt-in path. `auth.syncLibrary` is also checked
+        // as a belt-and-suspenders for older servers that don't return the
+        // flag (the local flag is set by `botdocs login --sync-library`).
+        const auth = loadAuth();
+        const enabled = result.enabled !== false && (auth?.syncLibrary === true || !auth);
+        if (!enabled && auth) {
+            console.log('\n  No library snapshot to check.');
+            console.log('  Run `botdocs login --sync-library` to enable check-updates.\n');
+            return;
+        }
         console.log('\n  All installed skills + bundles are up to date.\n');
         return;
     }
@@ -73,5 +96,37 @@ export async function checkUpdates(options) {
     for (const r of result.removed) {
         console.log(`  ⌀ ${r.ref}: ${r.reason}`);
     }
-    console.log('\n  Run `botdocs sync` to apply.\n');
+    // Branch the suffix on what's actionable. `botdocs sync` does NOT remove
+    // entries for removed-upstream refs (it just skips them), so telling the
+    // user "sync to apply" when their only diff is removals would do nothing.
+    // Surface specific uninstall commands when the list is small enough to
+    // print inline.
+    const hasUpdates = result.updates.length > 0;
+    const hasRemovals = result.removed.length > 0;
+    console.log('');
+    if (hasUpdates && hasRemovals) {
+        console.log('  Run `botdocs sync` to apply updates.');
+        if (result.removed.length <= 3) {
+            for (const r of result.removed) {
+                console.log(`  Run \`botdocs uninstall ${r.ref}\` to remove the stale skill.`);
+            }
+        }
+        else {
+            console.log('  Run `botdocs uninstall <ref>` to remove stale skills.');
+        }
+    }
+    else if (hasUpdates) {
+        console.log('  Run `botdocs sync` to apply.');
+    }
+    else if (hasRemovals) {
+        if (result.removed.length <= 3) {
+            for (const r of result.removed) {
+                console.log(`  Run \`botdocs uninstall ${r.ref}\` to clean up.`);
+            }
+        }
+        else {
+            console.log('  Run `botdocs uninstall <ref>` to clean up.');
+        }
+    }
+    console.log('');
 }

package/dist/commands/edit.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
-import { ApiError, apiFetch, fetchRawContent } from '../lib/api.js';
+import { ApiError, apiFetch, fetchRawContent, friendlyApiErrorDetail } from '../lib/api.js';
 import { complete, detectProvider, LlmError } from '../lib/llm.js';
 import { renderDiff } from '../lib/diff.js';
 const TEMPLATES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates', 'ecosystem-prompts');
@@ -42,12 +42,20 @@ export async function edit(rawRef, options) {
         throw err;
     }
     let manifest;
+    const refStr = `@${ref.username}/${ref.slug}`;
     try {
         manifest = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/manifest`);
     }
     catch (err) {
         if (err instanceof ApiError && err.status === 404) {
-            console.error(`\n  ✗ Skill not found: @${ref.username}/${ref.slug}\n`);
+            console.error(`\n  ✗ Skill not found: ${refStr}\n`);
+            process.exit(1);
+        }
+        // Route 403/429/5xx through the shared helper so users get the same
+        // wording sync/install give (lost team access, rate-limited, server
+        // error) instead of a raw ApiError stack.
+        if (err instanceof ApiError) {
+            console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
             process.exit(1);
         }
         throw err;

package/dist/commands/ingest.d.ts

@@ -15,6 +15,12 @@ interface IngestOptions {
      * are never replaced — they surface as a blocking 409 either way. Set via
      * `--force`. */
     force?: boolean;
+    /** Pair this ingest run with the web onboarding step so the user can
+     * watch progress in their browser. Set via `--pair`. If `--pair-code` is
+     * also provided we skip the interactive prompt. */
+    pair?: boolean;
+    /** Pre-supplied pairing code (BD-XXXXX). Implies `--pair`. */
+    pairCode?: string;
 }
 /** Per-file size cap. Any file larger than this is skipped with a warning. */
 export declare const PER_FILE_BYTE_CAP: number;
@@ -105,5 +111,19 @@ export interface EcosystemDetector {
  */
 export declare const DETECTORS: Record<string, EcosystemDetector>;
 export declare const SUPPORTED_TOOLS: readonly string[];
+/**
+ * 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 declare function walkFiles(root: string): string[];
 export declare function ingest(rootPath: string | undefined, options: IngestOptions): Promise<void>;
 export {};