@botdocs/cli 0.8.1 → 0.9.0

package/dist/commands/ingest.d.ts

@@ -11,6 +11,10 @@ interface IngestOptions {
     /** Force the plain-text rendering path — disables the Ink TUI. Mirrors the
      * `--no-ink` flag on `login` and `sync`. */
     noInk?: boolean;
+    /** Replace existing *draft* skills that collide on slug. Published skills
+     * are never replaced — they surface as a blocking 409 either way. Set via
+     * `--force`. */
+    force?: boolean;
 }
 /** Per-file size cap. Any file larger than this is skipped with a warning. */
 export declare const PER_FILE_BYTE_CAP: number;

package/dist/commands/ingest.js

@@ -2,7 +2,8 @@ import React from 'react';
 import fs from 'node:fs';
 import path from 'node:path';
 import { render } from 'ink';
-import { apiFetch } from '../lib/api.js';
+import { ApiError, apiFetch } from '../lib/api.js';
+import { loadAuth } from '../lib/config.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) ----------
@@ -452,15 +453,72 @@ function groupDiscoveredIntoSkills(discovered) {
     }
     return [...grouped.values()];
 }
+/** Narrow an unknown ApiError body to the ingest 409 `{ conflicts }` shape. */
+function parseConflicts(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const conflicts = body.conflicts;
+    if (typeof conflicts !== 'object' || conflicts === null)
+        return null;
+    const { replaceable, blocking } = conflicts;
+    if (!Array.isArray(replaceable) || !Array.isArray(blocking))
+        return null;
+    return {
+        replaceable: replaceable.filter((s) => typeof s === 'string'),
+        blocking: blocking.filter((s) => typeof s === 'string'),
+    };
+}
+/** Render the delete-hint ref for a slug. Uses the logged-in username when
+ * it's readily available (so the user can copy-paste `botdocs delete
+ * @me/slug`); falls back to the bare slug otherwise. */
+function deleteRef(slug) {
+    const username = loadAuth()?.username;
+    return username ? `@${username}/${slug}` : slug;
+}
+/** Print an actionable 409 message and exit non-zero. Honors `--json` by
+ * emitting the structured `{ ok: false, conflicts }` shape instead of prose. */
+function reportConflicts(conflicts, options) {
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, conflicts }));
+        process.exit(1);
+    }
+    if (conflicts.blocking.length > 0) {
+        const refs = conflicts.blocking.map((s) => `botdocs delete ${deleteRef(s)}`).join(', ');
+        console.error(`\n  ✗ These skills are already published and won't be replaced: ${conflicts.blocking.join(', ')}. ` +
+            `Unpublish or delete them first (${refs}), then re-ingest.`);
+    }
+    if (conflicts.replaceable.length > 0) {
+        console.error(`\n  ✗ These skills already exist as drafts: ${conflicts.replaceable.join(', ')}. ` +
+            `Re-run with --force to replace them, or delete them first.`);
+    }
+    console.error('');
+    process.exit(1);
+}
 /** POST the grouped skills to the ingest endpoint. Honors `--json` (emit raw
- * response) and the default human-friendly "drafts created" line. Returns
- * nothing on success. */
+ * 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) {
-    const result = await apiFetch('/api/cli/ingest', {
-        method: 'POST',
-        auth: true,
-        body: { skills, bundle: options.bundle ? { name: options.bundle } : undefined },
-    });
+    let result;
+    try {
+        result = await apiFetch('/api/cli/ingest', {
+            method: 'POST',
+            auth: true,
+            body: {
+                skills,
+                bundle: options.bundle ? { name: options.bundle } : undefined,
+                force: options.force,
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 409) {
+            const conflicts = parseConflicts(err.body);
+            if (conflicts)
+                reportConflicts(conflicts, options);
+        }
+        throw err;
+    }
     if (options.json) {
         console.log(JSON.stringify(result));
         return;

package/dist/index.js

@@ -160,6 +160,7 @@ program
     .option('--dry-run', 'Show what would be ingested without uploading')
     .option('--from-tool <ecosystem>', `Treat every file in the path as belonging to a single ecosystem (one of: ${INGEST_SUPPORTED_TOOLS.join(', ')}). Useful when ingesting directly from ~/.claude/commands/, .cursor/rules/, etc.`)
     .option('--auto', 'Skip the interactive selection and ingest everything discovery finds (zero-arg mode only)')
+    .option('--force', 'Replace existing draft skills with the same name (won\'t touch published skills)')
     .option('--no-ink', 'Disable the interactive TUI; use plain output (zero-arg mode only)')
     .action(async (sourcePath, opts) => {
     // Commander's --no-ink convention sets opts.ink = false; flip to noInk

package/dist/lib/api.d.ts

@@ -1,10 +1,17 @@
 export declare function getApiUrl(): string;
 /** Thrown by apiFetch when the server returns a non-2xx response. Carries the
  * status code and the server-provided message so callers can branch on
- * different HTTP error codes (404 vs 403 vs 5xx) with friendly hints. */
+ * different HTTP error codes (404 vs 403 vs 5xx) with friendly hints.
+ *
+ * `body` holds the parsed JSON error payload when the server returned one
+ * (e.g. ingest's `{ error, conflicts }`). It's `undefined` when the response
+ * body wasn't JSON. Callers that need structured fields (not just the
+ * `message` string) read it — most callers ignore it and the existing
+ * `status` + `message` branching keeps working unchanged. */
 export declare class ApiError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    readonly body?: unknown;
+    constructor(status: number, message: string, body?: unknown);
 }
 interface FetchOptions {
     method?: string;

package/dist/lib/api.js

@@ -5,13 +5,21 @@ export function getApiUrl() {
 }
 /** Thrown by apiFetch when the server returns a non-2xx response. Carries the
  * status code and the server-provided message so callers can branch on
- * different HTTP error codes (404 vs 403 vs 5xx) with friendly hints. */
+ * different HTTP error codes (404 vs 403 vs 5xx) with friendly hints.
+ *
+ * `body` holds the parsed JSON error payload when the server returned one
+ * (e.g. ingest's `{ error, conflicts }`). It's `undefined` when the response
+ * body wasn't JSON. Callers that need structured fields (not just the
+ * `message` string) read it — most callers ignore it and the existing
+ * `status` + `message` branching keeps working unchanged. */
 export class ApiError extends Error {
     status;
-    constructor(status, message) {
+    body;
+    constructor(status, message, body) {
         super(message);
         this.name = 'ApiError';
         this.status = status;
+        this.body = body;
     }
 }
 export async function apiFetch(path, options = {}) {
@@ -42,8 +50,13 @@ export async function apiFetch(path, options = {}) {
     if (!response.ok) {
         const text = await response.text();
         let message;
+        // `parsedBody` is the structured error payload when the server sent JSON
+        // (e.g. ingest's `{ error, conflicts }`). Left undefined for non-JSON
+        // bodies so callers can distinguish "no structured data" from "{}".
+        let parsedBody;
         try {
             const json = JSON.parse(text);
+            parsedBody = json;
             message = json.error || text;
         }
         catch {
@@ -54,7 +67,7 @@ export async function apiFetch(path, options = {}) {
         if (response.status === 401 && auth) {
             message = 'Authentication failed. Run `botdocs login` to sign in again.';
         }
-        throw new ApiError(response.status, message);
+        throw new ApiError(response.status, message, parsedBody);
     }
     const contentType = response.headers.get('content-type') || '';
     if (contentType.includes('application/json')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botdocs/cli",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "CLI for BotDocs — author, publish, install, and sync agent skills across Claude, Claude Code, Cursor, Codex, ChatGPT, Windsurf, Copilot, Gemini, Antigravity, and OpenCode.",
   "keywords": [
     "botdocs",