@botdocs/cli 0.10.2 → 0.11.0

package/dist/commands/install.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { ApiError, apiFetch, fetchRawContent } from '../lib/api.js';
+import { ApiError, apiFetch, fetchRawContent, friendlyApiErrorDetail } from '../lib/api.js';
 import { detectDestination } from '../lib/auto-detect.js';
 import { SUPPORTED_ECOSYSTEMS } from '../lib/canonical.js';
 import { convertSkillToEcosystem, parseFrontmatter, stripFrontmatter, } from '../lib/convert.js';
@@ -96,10 +96,19 @@ async function installSkill(ref, manifest, options, scope) {
         if (detection.kind === 'skip')
             continue;
         if (detection.kind === 'manual') {
-            // Print for user paste (ChatGPT case). Suppressed under --json so output stays parseable.
+            // Print for user paste (ChatGPT/Gemini case). Suppressed under --json so
+            // output stays parseable. We also surface the per-ecosystem instruction
+            // from MANUAL_INSTRUCTIONS so a non-dev knows what to DO with the dumped
+            // text (paste into Custom GPT, add to GEMINI.md, etc.) rather than
+            // seeing a wall of markdown followed by "✓ Installed".
             if (!options.json) {
                 const content = await fetchRawContent(file.rawUrl);
-                console.log(`\n  Manual paste required for ${file.filename}:\n${content}\n`);
+                const ecosystem = file.filename.split('/')[0];
+                const instr = MANUAL_INSTRUCTIONS[ecosystem];
+                console.log(`\n  Manual paste required for ${ecosystem}:${instr ? ` ${instr}` : ''}`);
+                console.log('  ---');
+                console.log(content);
+                console.log('  ---\n');
             }
             // A manual paste prompt counts as "we surfaced this file to the user",
             // so don't trigger the no-installable-files warning below.
@@ -340,8 +349,97 @@ async function crossInstall(refStr, manifest, options, scope) {
     console.log('');
     await syncLibrary();
 }
+/** Compare a prior install entry against an incoming SKILL manifest. Returns
+ * true only when nothing has drifted: same version, same set of manifest
+ * filenames, and every tracked file still on disk with a matching
+ * fingerprint. Any local edit (fingerprint mismatch), missing file, or
+ * upstream-added file makes the install non-idempotent and we fall through
+ * to the normal install path. */
+function isInstallUpToDate(prior, manifest) {
+    if (prior.version !== manifest.version)
+        return false;
+    // Resolve each manifest filename to the destination the prior install
+    // recorded for it. If the manifest adds a file the prior install didn't
+    // have (or vice versa), we're not up-to-date.
+    const priorBySrc = new Map(prior.files.map((f) => [f.src, f]));
+    for (const manifestFile of manifest.files) {
+        const tracked = priorBySrc.get(manifestFile.filename);
+        if (!tracked)
+            return false;
+        if (!fs.existsSync(tracked.dest))
+            return false;
+        if (fingerprintFile(tracked.dest) !== tracked.fingerprint)
+            return false;
+    }
+    // Allow prior to have MORE files than the manifest (skipped detections)
+    // only when the extras aren't in the manifest. The loop above already
+    // confirmed every manifest file is tracked; check there are no manifest
+    // entries the prior install dropped.
+    if (manifest.files.length !== prior.files.filter((f) => priorBySrc.has(f.src)).length) {
+        // Shouldn't be possible given the map construction, but defend against
+        // future schema drift.
+        return false;
+    }
+    return true;
+}
+/** Compute the Levenshtein edit distance between two short strings. Used by
+ * the "did you mean?" suggester to filter search hits that are too far from
+ * the user's typo to be useful. Implementation is the textbook two-row DP —
+ * O(n*m) time, O(min(n,m)) space. Both inputs are slug-sized (≤ ~64 chars),
+ * so the constant factor doesn't matter. */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
+/** On a 404, query the search endpoint for the user's slug fragment and
+ * return the top result as a `@user/slug` string when its slug is within
+ * Levenshtein distance 2 of the requested slug. Returns null when the
+ * search returns no results, when the top result is too far, or when
+ * `requestedRef` already equals the top match (defensive). Never throws —
+ * callers wrap in catch and treat any failure as "no suggestion". */
+async function suggestClosestRef(requestedSlug, requestedRef) {
+    const encoded = encodeURIComponent(requestedSlug);
+    const resp = await apiFetch(`/api/search?q=${encoded}`);
+    const top = resp.results[0];
+    if (!top)
+        return null;
+    if (levenshtein(top.slug.toLowerCase(), requestedSlug.toLowerCase()) > 2)
+        return null;
+    const candidate = `@${top.author}/${top.slug}`;
+    if (candidate === requestedRef)
+        return null;
+    return candidate;
+}
 export async function install(rawRef, options) {
-    const ref = parseRef(rawRef);
+    let ref;
+    try {
+        ref = parseRef(rawRef);
+    }
+    catch {
+        // parseRef throws `Error: Invalid ref: foo (expected @user/slug)` on
+        // malformed input — uncaught it stack-trips through commander. Catch it
+        // here and surface the same `✗ ` formatting other CLI errors use so a
+        // typo like `botdocs install foo` lands at one clean line, not a stack.
+        console.error(`\n  ✗ Invalid ref: ${rawRef} — expected @user/slug (e.g. @yourname/my-skill)\n`);
+        process.exit(1);
+    }
     const refStr = `@${ref.username}/${ref.slug}`;
     if (options.clean) {
         const lf = loadLockfile();
@@ -371,11 +469,49 @@ export async function install(rawRef, options) {
     }
     catch (err) {
         if (err instanceof ApiError && err.status === 404) {
-            console.error(`\n  ✗ Skill or bundle not found: ${refStr}\n`);
+            // 404 dead-ends are common when users mistype a slug. Ask the search
+            // endpoint for the slug-fragment and surface the top close match
+            // (Levenshtein distance ≤ 2) so the user can quickly correct.
+            // Network errors from the suggestion lookup are swallowed — the 404
+            // itself is the primary signal and we shouldn't gate it on the
+            // suggestion call succeeding.
+            const suggestion = await suggestClosestRef(ref.slug, refStr).catch(() => null);
+            const suffix = suggestion ? `\n    Did you mean: ${suggestion}?\n` : '\n';
+            console.error(`\n  ✗ Skill or bundle not found: ${refStr}${suffix}`);
+            process.exit(1);
+        }
+        // 410 Gone = author soft-deleted the skill upstream. Distinct from 404
+        // ("never existed") so users know they had it installed and can clean up.
+        if (err instanceof ApiError && err.status === 410) {
+            console.error(`\n  ⌀ ${refStr}: removed by author — run \`botdocs uninstall ${refStr}\` to clean up local files.\n`);
+            process.exit(1);
+        }
+        // Generic 403/429/5xx — route through the shared friendly-detail helper
+        // so the error vocabulary stays consistent across commands instead of
+        // leaking a raw ApiError stack to stderr.
+        if (err instanceof ApiError) {
+            console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
             process.exit(1);
         }
         throw err;
     }
+    // Already-at-version short-circuit. Re-running install on a skill at the
+    // current version with all file fingerprints matching does nothing visible
+    // today — the user can't tell whether anything changed. Compare the
+    // manifest version + each tracked file's fingerprint to the lockfile entry;
+    // when nothing has drifted, print a clear no-op line and skip the work.
+    // Skipped under --json and --clean (both want the full path), and only
+    // applies when a prior install exists. Bundles re-resolve per-skill so
+    // the short-circuit fires at the skill level inside the loop below.
+    if (!options.clean && !options.json && !options.to && manifest.type === 'SKILL') {
+        const lf = loadLockfile();
+        const prior = lf.installs.find((i) => i.ref === refStr);
+        if (prior && isInstallUpToDate(prior, manifest)) {
+            console.log(`\n  ✓ ${refStr} already at v${manifest.version} (no changes)\n`);
+            await syncLibrary();
+            return;
+        }
+    }
     // `--to`: cross-install into a different ecosystem (deterministic, no LLM).
     if (options.to) {
         await crossInstall(refStr, manifest, options, ref.username);
@@ -417,6 +553,11 @@ export async function install(rawRef, options) {
             continue;
         console.log(`    ${entry.ref}: ${entry.files.length} file(s)`);
     }
+    // Dim sync hint — only on the success path, not on errors. Suppressed when
+    // --json is set (JSON mode is for scripting and shouldn't carry banner
+    // noise). ANSI dim (\x1b[2m) degrades to plain text on terminals that
+    // don't support it; harmless when redirected to a file.
+    console.log('\x1b[2m  → Updates? Run `botdocs sync` (or `botdocs install-instructions --shell-hook` for auto-notify)\x1b[0m');
     console.log('');
     await syncLibrary();
 }

package/dist/commands/list.js

@@ -1,6 +1,68 @@
 import { loadLockfile } from '../lib/lockfile.js';
+import { fetchUpdates } from './check-updates.js';
+/** Filter the lockfile down to the subset that has an available update or has
+ * been removed upstream, per the cached check-updates result. Returns the
+ * (refs, result) tuple so the caller can render a structured summary that
+ * distinguishes "outdated" from "gone". */
+function filterOutdated(installs, result) {
+    const updateMap = new Map();
+    for (const u of result.updates)
+        updateMap.set(u.ref, { from: u.from, to: u.to });
+    const removedRefs = new Set(result.removed.map((r) => r.ref));
+    const outdated = installs.filter((i) => updateMap.has(i.ref) || removedRefs.has(i.ref));
+    return { outdated, removedRefs, updateMap };
+}
 export async function list(options) {
     const lf = loadLockfile();
+    if (options.outdated) {
+        // Empty lockfile short-circuit — no point hitting the server when there's
+        // nothing to compare against.
+        if (lf.installs.length === 0) {
+            if (options.json) {
+                console.log(JSON.stringify({ outdated: [], removed: [] }));
+                return;
+            }
+            console.log('\n  nothing installed yet — try `botdocs install @user/slug`\n');
+            return;
+        }
+        const result = await fetchUpdates();
+        const { outdated, removedRefs, updateMap } = filterOutdated(lf.installs, result);
+        if (options.json) {
+            // Emit a structured shape: every outdated install with its delta + a
+            // boolean flag for the removed-upstream case. Easier for scripts than
+            // re-correlating against the raw check-updates output.
+            const shaped = outdated.map((i) => {
+                const update = updateMap.get(i.ref);
+                return {
+                    ref: i.ref,
+                    type: i.type,
+                    version: i.version,
+                    latest: update?.to ?? null,
+                    removed: removedRefs.has(i.ref),
+                };
+            });
+            console.log(JSON.stringify({ outdated: shaped }));
+            return;
+        }
+        if (outdated.length === 0) {
+            console.log('\n  Everything is up to date.\n');
+            return;
+        }
+        console.log('');
+        for (const entry of outdated) {
+            const update = updateMap.get(entry.ref);
+            if (update) {
+                console.log(`  ▸ ${entry.ref}: ${update.from} → ${update.to}`);
+            }
+            else {
+                // Removed upstream — surface the same ⌀ glyph check-updates uses so
+                // users learn one visual language for "gone".
+                console.log(`  ⌀ ${entry.ref}: removed upstream`);
+            }
+        }
+        console.log('');
+        return;
+    }
     if (options.json) {
         console.log(JSON.stringify({ installs: lf.installs }));
         return;

package/dist/commands/login.js

@@ -75,6 +75,30 @@ async function initLoginState(baseUrl) {
     if (!initRes.ok) {
         throw new Error(`Failed to start login (HTTP ${initRes.status}).`);
     }
+    // P3 #14 (DOCUMENTATION-ONLY trade-off, not a code fix in this PR):
+    //
+    // The `state` value rides in the query string on the browser-side
+    // authorize URL. Query-string parameters land in:
+    //   - the browser's address bar (visible to anyone over the user's
+    //     shoulder + saved in browser history)
+    //   - any Referer header on links the user clicks from /cli-auth
+    //   - server-side access logs at every proxy between the user and the
+    //     Vercel edge
+    //
+    // The cli-auth state IS effectively a single-use, time-boxed (10 min)
+    // bearer for the device-grant flow. Leaking it would let an observer
+    // race the user to call /grant. We accept this exposure today because:
+    //   1. The /cli-auth page strips Referer on the click that ultimately
+    //      lands the grant (the button submits a POST, not an <a href>),
+    //      so the worst leak is the address bar + browser history.
+    //   2. The state is single-use and short-lived; replay is bounded.
+    //   3. The CLI binds the state to the polling channel — an attacker
+    //      who steals it would need to win a poll race with our own CLI.
+    //
+    // A future revision should switch this to a POST-based handoff with the
+    // state carried in the URL hash fragment (#state=...), which browsers
+    // never send to the server and never write to history. That refactor is
+    // out of scope for the P3 bucket — tracked as a separate item.
     return {
         state,
         authUrl: `${baseUrl}/cli-auth?state=${state}`,
@@ -210,14 +234,44 @@ async function loginPlainInteractive(syncLibrary) {
     printSyncLibraryHint(syncLibrary);
 }
 /** Polls the server with exponential backoff. Returns the granted payload on
- * success or null if the loop ran out of budget (matching the server's TTL). */
+ * success or null if the loop ran out of budget (matching the server's TTL).
+ *
+ * Network errors (DNS hiccup, WiFi blip, server briefly unreachable) are
+ * caught and treated the same as transient HTTP 5xx: we keep polling. An
+ * uncaught throw here would crash Ink mid-render and leave the terminal in
+ * raw mode. We surface a single dimmed "retrying…" hint after three
+ * consecutive failures so the user knows their network is the bottleneck
+ * rather than assuming the CLI hung. */
 async function pollUntilGranted(baseUrl, state) {
     const deadline = Date.now() + POLL_TIMEOUT_MS;
     let delay = POLL_INITIAL_DELAY_MS;
+    let consecutiveFailures = 0;
     while (Date.now() < deadline) {
         await sleep(delay);
         delay = Math.min(delay * POLL_BACKOFF_FACTOR, POLL_MAX_DELAY_MS);
-        const res = await fetch(`${baseUrl}/api/cli/auth/poll?state=${encodeURIComponent(state)}`, { headers: { Accept: 'application/json' } });
+        let res;
+        try {
+            // P3 #14: the poll endpoint also carries `state` in the query string.
+            // See the comment in `initLoginState` for the full trade-off rationale
+            // and the planned migration to a hash-fragment + POST handoff.
+            res = await fetch(`${baseUrl}/api/cli/auth/poll?state=${encodeURIComponent(state)}`, { headers: { Accept: 'application/json' } });
+        }
+        catch {
+            // Network-level failure — same disposition as a 5xx: keep polling
+            // within the 10-minute budget. Note we intentionally don't surface a
+            // visible error to Ink to avoid mid-render churn; the deadline check
+            // remains the source of truth for "give up and exit".
+            consecutiveFailures += 1;
+            if (consecutiveFailures >= 3 && process.stderr.isTTY) {
+                // Dimmed retry hint goes to stderr so it doesn't disturb Ink's
+                // stdout-rendered frame buffer. Only printed once per streak.
+                if (consecutiveFailures === 3) {
+                    process.stderr.write('\n  (network hiccup, retrying…)\n');
+                }
+            }
+            continue;
+        }
+        consecutiveFailures = 0;
         if (res.status === 410) {
             return null;
         }

package/dist/commands/publish.d.ts

@@ -6,10 +6,22 @@ interface PublishOptions {
     license?: string;
     json?: boolean;
     noCompile?: boolean;
-    /** Skip confirmation prompts. Reserved for future use — publish on a
-     * ref currently doesn't prompt, but the flag is accepted so users
-     * developing scripts get a consistent surface across publish/unpublish. */
+    /** Skip the pre-POST y/N confirmation prompt. First-time authors don't
+     * always realize `publish` is immediate, so the path-form publish asks
+     * "Publish to public registry as @<user>/<slug>? [y/N]" by default.
+     * `--yes` bypasses it for scripted runs; `--json` skips it implicitly
+     * because JSON mode is for non-interactive consumers. */
     yes?: boolean;
+    /** Build the payload, print what would be published, exit 0 without POSTing.
+     * Lets authors preview title/description/file list + total size before they
+     * commit to publishing. Skipped entirely on ref-form publish (toggling a
+     * draft → published flag is already cheap and reversible via `unpublish`). */
+    dryRun?: boolean;
+}
+interface FileEntry {
+    filename: string;
+    content: string;
+    sortOrder: number;
 }
 export declare function publish(source: string, options: PublishOptions): Promise<void>;
 /**
@@ -37,3 +49,18 @@ declare function publishRef(rawRef: string, options: PublishOptions): Promise<vo
  */
 declare function handlePublishToggleError(err: unknown, refLabel: string, options: PublishOptions): void;
 export { publishRef, handlePublishToggleError };
+/**
+ * Recursively collect publishable markdown files under `currentDir`.
+ *
+ * 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 silently upload that file's contents as a public skill. We use
+ * `withFileTypes: true` so the `Dirent` reports the entry's own type (NOT
+ * the target's), then gate on `isFile()` / `isDirectory()` explicitly so
+ * anything else (symlinks, sockets, FIFOs, character/block devices) is
+ * dropped. Mirrors `walkAll` in `src/lib/ingest-discover.ts`.
+ *
+ * Exported only for unit testing — production callers should go through
+ * `collectFromDirectory`.
+ */
+export declare function walkDirectory(rootDir: string, currentDir: string, out: FileEntry[]): void;