@botdocs/cli 0.8.0 → 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;
@@ -471,17 +529,9 @@ async function uploadSkills(skills, options) {
  * sees as a checkbox row in the TUI / a bullet in plain-text output. Adjacent
  * files (scripts/, templates/, etc.) ride along with the root's selection. */
 function isRoot(file) {
-    const cf = file.canonicalFilename;
-    // Nested ecosystems use /SKILL.md or /AGENT.md as the root marker.
-    if (cf.endsWith('/SKILL.md') || cf.endsWith('/AGENT.md'))
-        return true;
-    // Flat ecosystems have no adjacent sweep today, so every file IS a root.
-    // Detect by checking that the canonical filename matches the simple
-    // `<prefix>/<slug>.<ext>` shape with no extra path segment.
-    // (A claude-code-agents single-file would also match here — but we only
-    // produce AGENT.md as the root for nested layouts, so flat .md under
-    // claude-code/agents/ is treated as a root.)
-    return !cf.includes('/scripts/') && !cf.includes('/templates/') && !cf.includes('/reference/');
+    // `isRoot` is set authoritatively at discovery time (rootFile = true,
+    // swept adjacent files = false), so there's no filename guessing here.
+    return file.isRoot;
 }
 /** Filter a discovery file list down to the set the `--auto` / stub filter
  * would actually upload: only ROOT files smaller than the stub threshold are

package/dist/commands/views/ingest-discover-app.js

@@ -3,27 +3,13 @@ import { useMemo, useState } from 'react';
 import { Box, Text, useApp, useInput } from 'ink';
 import { theme } from './theme.js';
 import { ecosystemLabel, formatBytes, STUB_BYTE_THRESHOLD, summaryKey, } from '../../lib/ingest-discover.js';
-/** A file is a "root" — selectable at the skill level — if its canonical
- * filename matches the ecosystem's root pattern. Root files are the only
- * ones surfaced in the TUI; adjacent files (scripts/, templates/) ride
- * along when their skill is toggled. */
+/** A file is a "root" — selectable at the skill level — when discovery marked
+ * it as the skill's primary file. Root files are the only ones surfaced in the
+ * TUI; adjacent files (scripts/, templates/) ride along when their skill is
+ * toggled. The `isRoot` flag is set authoritatively in `discoverSkills`, so
+ * the renderer never has to guess from the filename. */
 function isRootFile(file) {
-    const cf = file.canonicalFilename;
-    // claude/<slug>/SKILL.md or claude-code/agents/<slug>/AGENT.md are nested
-    // root files; everything else is flat (filename matches canonical exactly
-    // and ends with the ecosystem's primary extension).
-    if (cf.endsWith('/SKILL.md'))
-        return true;
-    if (cf.endsWith('/AGENT.md'))
-        return true;
-    // For flat ecosystems (claude-code commands, cursor rules, etc.) there's
-    // no adjacent sweep today, so every discovered file IS a root.
-    if (!cf.endsWith('/SKILL.md') && !cf.endsWith('/AGENT.md')) {
-        // Heuristic: if this file's slug + scope appears exactly once in the
-        // discovery, treat it as the root.
-        return true;
-    }
-    return false;
+    return file.isRoot;
 }
 /** Group files by ecosystem (preserving order) and emit a flat row list with
  * one section header per ecosystem followed by its skill rows. Empty

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/dist/lib/ingest-discover.d.ts

@@ -36,6 +36,13 @@ export interface DiscoveredSkillFile {
     /** Canonical filename for the upload payload — e.g.
      * `claude-code/commands/foo.md`, `claude/<slug>/SKILL.md`, etc. */
     canonicalFilename: string;
+    /** True for the skill's primary file (SKILL.md / AGENT.md / a flat .md),
+     * false for adjacent files swept in from the skill directory
+     * (scripts/, templates/, etc.). Set authoritatively at discovery time —
+     * the TUI and plain-text renderers list ONE row per skill by filtering to
+     * `isRoot`, and adjacent files ride along when their root is selected.
+     * Marking it here avoids fragile filename-suffix guessing downstream. */
+    isRoot: boolean;
 }
 /** Per-skill aggregate stats produced by discovery — surfaced in the TUI and
  * the plain-text fallback so the user can see how big a skill is before

package/dist/lib/ingest-discover.js

@@ -171,6 +171,7 @@ export function discoverSkills(options = {}) {
                 content,
                 mode: safeMode(abs),
                 canonicalFilename: detector.canonicalFilename(slug),
+                isRoot: true,
             };
             files.push(rootFile);
             // Per-skill summary aggregates the root file + any adjacent sweep
@@ -205,6 +206,7 @@ export function discoverSkills(options = {}) {
                         content: adj.content,
                         mode: adj.mode,
                         canonicalFilename: detector.canonicalAdjacentFilename(slug, adj.relPath),
+                        isRoot: false,
                     });
                     summary.totalFiles += 1;
                     summary.totalBytes += adj.sizeBytes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botdocs/cli",
-  "version": "0.8.0",
+  "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",