@botdocs/cli 0.6.0 → 0.8.1

package/dist/commands/ingest.js

@@ -3,8 +3,181 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { render } from 'ink';
 import { apiFetch } from '../lib/api.js';
-import { discoverSkills, ecosystemLabel, formatBytes, STUB_BYTE_THRESHOLD, titleFromContent, } from '../lib/ingest-discover.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) ----------
+//
+// Caps are tight by design — Claude skills routinely fit well under these.
+// Enforced both here (CLI) and server-side (defense in depth).
+/** Per-file size cap. Any file larger than this is skipped with a warning. */
+export const PER_FILE_BYTE_CAP = 64 * 1024; // 64 KB
+/** Total bytes across all files in a single skill. */
+export const PER_SKILL_BYTE_CAP = 512 * 1024; // 512 KB
+/** Total file count in a single skill. */
+export const PER_SKILL_FILE_CAP = 25;
+/** Directories the sweep recurses INTO. Anything else is silently ignored.
+ * The set is duplicated (not imported) from `walkFiles` so it stays in sync
+ * with what the path-based walker already filters out. */
+const SWEEP_SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.next',
+    '.turbo',
+    '__pycache__',
+    'venv',
+    '.venv',
+]);
+/** Filenames + globs that are uninteresting noise. `.log` and `.lock` are
+ * matched via endsWith, not regex, to keep the check cheap. */
+function isSkippedFileName(name) {
+    if (name === '.DS_Store')
+        return true;
+    if (name.endsWith('.log'))
+        return true;
+    if (name.endsWith('.lock'))
+        return true;
+    return false;
+}
+/** Binary detection: read the first 8 KB and look for a null byte. Matches
+ * the same heuristic git uses. Cheap and good enough — we'd rather refuse a
+ * borderline file than try to base64 it. */
+function looksBinary(absPath) {
+    const buf = Buffer.alloc(8192);
+    let fd = null;
+    try {
+        fd = fs.openSync(absPath, 'r');
+        const bytesRead = fs.readSync(fd, buf, 0, 8192, 0);
+        for (let i = 0; i < bytesRead; i++) {
+            if (buf[i] === 0)
+                return true;
+        }
+        return false;
+    }
+    catch {
+        // Unreadable — treat as binary so we skip it with a warning rather than
+        // crashing the whole ingest.
+        return true;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/**
+ * Walk a skill root recursively and return every non-skipped file the caller
+ * should ingest as an adjacent file. Applies dir-skip, dotfile, binary, and
+ * cap rules. Stops collecting once total caps are exceeded — remaining files
+ * land in `warnings`. The root file (e.g. SKILL.md) is excluded so the caller
+ * can handle it separately.
+ */
+export function sweepSkillRoot(skillRoot, rootFileAbs) {
+    const files = [];
+    const warnings = [];
+    let totalBytes = 0;
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SWEEP_SKIP_DIRS.has(entry.name))
+                    continue;
+                if (entry.name.startsWith('.'))
+                    continue;
+                walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (abs === rootFileAbs)
+                continue;
+            if (entry.name.startsWith('.'))
+                continue;
+            if (isSkippedFileName(entry.name))
+                continue;
+            const relPath = path.relative(skillRoot, abs).split(path.sep).join('/');
+            let stat;
+            try {
+                stat = fs.statSync(abs);
+            }
+            catch {
+                warnings.push({ relPath, reason: 'binary' });
+                continue;
+            }
+            if (stat.size > PER_FILE_BYTE_CAP) {
+                warnings.push({ relPath, reason: 'oversize' });
+                continue;
+            }
+            if (looksBinary(abs)) {
+                warnings.push({ relPath, reason: 'binary' });
+                continue;
+            }
+            // Total-byte cap is checked after the per-file gate so a single huge
+            // file doesn't blow past the skill cap before we've read it.
+            if (totalBytes + stat.size > PER_SKILL_BYTE_CAP) {
+                warnings.push({ relPath, reason: 'cap-total-size' });
+                continue;
+            }
+            // -1 here because we count the root file in the caller's accounting,
+            // but exclude it from this sweep. Cap is "total files per skill".
+            if (files.length + 1 >= PER_SKILL_FILE_CAP) {
+                warnings.push({ relPath, reason: 'cap-file-count' });
+                continue;
+            }
+            let content;
+            try {
+                content = fs.readFileSync(abs, 'utf-8');
+            }
+            catch {
+                warnings.push({ relPath, reason: 'binary' });
+                continue;
+            }
+            files.push({
+                absPath: abs,
+                relPath,
+                content,
+                mode: stat.mode & 0o777,
+                sizeBytes: stat.size,
+            });
+            totalBytes += stat.size;
+        }
+    }
+    walk(skillRoot);
+    return { files, warnings };
+}
+/** Format a sweep warning summary line for a single skill. Empty string when
+ * there are no warnings — caller can use that to suppress the line. */
+export function formatSweepWarnings(slug, warnings) {
+    if (warnings.length === 0)
+        return '';
+    const binary = warnings.filter((w) => w.reason === 'binary').map((w) => w.relPath);
+    const oversize = warnings.filter((w) => w.reason === 'oversize').map((w) => w.relPath);
+    const totalCap = warnings.filter((w) => w.reason === 'cap-total-size').map((w) => w.relPath);
+    const fileCap = warnings.filter((w) => w.reason === 'cap-file-count').map((w) => w.relPath);
+    const parts = [];
+    if (binary.length)
+        parts.push(`${binary.length} binary (${binary.slice(0, 3).join(', ')}${binary.length > 3 ? '…' : ''})`);
+    if (oversize.length)
+        parts.push(`${oversize.length} over 64KB (${oversize.slice(0, 3).join(', ')}${oversize.length > 3 ? '…' : ''})`);
+    if (totalCap.length)
+        parts.push(`${totalCap.length} past 512KB total cap`);
+    if (fileCap.length)
+        parts.push(`${fileCap.length} past 25-file cap`);
+    return `  ⚠ ${slug}: skipped ${warnings.length} file(s) — ${parts.join('; ')}`;
+}
 /**
  * Single source of truth for ecosystem detection. New ecosystems should be
  * added here — both auto-detect mode and future `--from-tool` mode consult
@@ -29,6 +202,11 @@ export const DETECTORS = {
         // Discovery walks ~/.claude/skills recursively — files live one or two
         // segments deep (`<slug>/SKILL.md` or `<scope>/<slug>/SKILL.md`).
         scanPaths: (homeDir) => [path.join(homeDir, '.claude', 'skills')],
+        // Marquee case for adjacent-file sweep: real Claude skills bundle
+        // scripts/, templates/, and reference markdown next to SKILL.md.
+        includeAdjacent: true,
+        skillRoot: (abs) => path.dirname(abs),
+        canonicalAdjacentFilename: (slug, relPath) => `claude/${slug}/${relPath}`,
     },
     'claude-code': {
         pathPrefix: 'claude-code/commands/',
@@ -44,6 +222,44 @@ export const DETECTORS = {
                 paths.push(path.join(projectRoot, '.claude', 'commands'));
             return paths;
         },
+        // Commands are FLAT today — every .md in ~/.claude/commands/ is its own
+        // skill, with no enclosing directory. That means there's no meaningful
+        // "skill root" to sweep: the dirname of a command is shared with all
+        // other commands, and walking it would produce false-positive adjacent
+        // files. If Anthropic ever adds a directory layout for commands we'll
+        // flip this back to `true` and add the appropriate skillRoot logic.
+        includeAdjacent: false,
+    },
+    'claude-code-agents': {
+        // Anthropic's convention today is single-file agents at
+        // `.claude/agents/<name>.md`. For BotDocs multi-file agents we expect a
+        // directory: `.claude/agents/<name>/AGENT.md` + adjacent files. The
+        // detector matches `**/AGENT.md` under `claude-code/agents/`; the slug
+        // is the parent dir of AGENT.md.
+        pathPrefix: 'claude-code/agents/',
+        extensions: ['/AGENT.md'],
+        nested: true,
+        slugFor: (abs, root) => {
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if (!rel.endsWith('/AGENT.md'))
+                return null;
+            const parts = rel.split('/');
+            if (parts.length < 2)
+                return null;
+            return parts[parts.length - 2] ?? null;
+        },
+        canonicalFilename: (slug) => `claude-code/agents/${slug}/AGENT.md`,
+        // Mirror claude-code commands: global ~/.claude/agents always, project
+        // .claude/agents only inside a git repo.
+        scanPaths: (homeDir, projectRoot, isGitRepo) => {
+            const paths = [path.join(homeDir, '.claude', 'agents')];
+            if (isGitRepo)
+                paths.push(path.join(projectRoot, '.claude', 'agents'));
+            return paths;
+        },
+        includeAdjacent: true,
+        skillRoot: (abs) => path.dirname(abs),
+        canonicalAdjacentFilename: (slug, relPath) => `claude-code/agents/${slug}/${relPath}`,
     },
     cursor: {
         pathPrefix: 'cursor/rules/',
@@ -113,13 +329,12 @@ export const DETECTORS = {
     },
 };
 export const SUPPORTED_TOOLS = Object.keys(DETECTORS);
-const IGNORED_DIRS = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.turbo']);
 function walkFiles(root) {
     const out = [];
     function walk(dir) {
         for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
             if (entry.isDirectory()) {
-                if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                if (SWEEP_SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))
                     continue;
                 walk(path.join(dir, entry.name));
             }
@@ -131,6 +346,16 @@ function walkFiles(root) {
     walk(root);
     return out;
 }
+/** Stat helper that masks mode to the low 9 bits (rwx for owner/group/other).
+ * Falls back to 0o644 on error so we never block ingest on a stat failure. */
+function safeMode(absPath) {
+    try {
+        return fs.statSync(absPath).mode & 0o777;
+    }
+    catch {
+        return 0o644;
+    }
+}
 /** Does the filename end with any of the detector's declared extensions? */
 function matchesExtension(absPath, detector) {
     return detector.extensions.some((ext) => absPath.endsWith(ext));
@@ -154,6 +379,7 @@ function detectAuto(absPath, root, content) {
             content,
             ecosystem,
             slug,
+            mode: safeMode(absPath),
         };
     }
     return null;
@@ -179,8 +405,29 @@ function detectFromTool(absPath, root, content, ecosystem) {
         content,
         ecosystem,
         slug,
+        mode: safeMode(absPath),
     };
 }
+/**
+ * Sweep adjacent files when a detector opts in. Returns a list of
+ * `DetectedFile` for each non-skipped sibling file, plus warnings the caller
+ * surfaces inline. The root file itself is excluded — caller already has it.
+ */
+function adjacentFilesFor(detector, ecosystem, slug, rootFileAbs) {
+    if (!detector.includeAdjacent || !detector.skillRoot || !detector.canonicalAdjacentFilename) {
+        return { files: [], warnings: [] };
+    }
+    const root = detector.skillRoot(rootFileAbs);
+    const result = sweepSkillRoot(root, rootFileAbs);
+    const files = result.files.map((f) => ({
+        filename: detector.canonicalAdjacentFilename(slug, f.relPath),
+        content: f.content,
+        ecosystem,
+        slug,
+        mode: f.mode,
+    }));
+    return { files, warnings: result.warnings };
+}
 /** Group a list of discovered files into the `DetectedSkill[]` shape the
  * `/api/cli/ingest` endpoint expects. Multiple discoveries with the same slug
  * collapse into one logical skill with multiple files — same convention as
@@ -200,6 +447,7 @@ function groupDiscoveredIntoSkills(discovered) {
         grouped.get(f.slug).files.push({
             filename: f.canonicalFilename,
             content: f.content,
+            mode: f.mode,
         });
     }
     return [...grouped.values()];
@@ -219,24 +467,58 @@ async function uploadSkills(skills, options) {
     }
     console.log(`\n  ✓ Drafts created. Review at:\n    https://botdocs.ai${result.reviewUrl}\n`);
 }
+/** Returns true if this file is the "root" for its skill — the file the user
+ * 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) {
+    // `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
+ * dropped. Adjacent files ride along when their root is eligible. */
+function applyStubFilter(files) {
+    const eligibleKeys = new Set();
+    for (const f of files) {
+        if (!isRoot(f))
+            continue;
+        if (f.sizeBytes >= STUB_BYTE_THRESHOLD)
+            eligibleKeys.add(summaryKey(f));
+    }
+    return files.filter((f) => eligibleKeys.has(summaryKey(f)));
+}
 /** Render a sectioned plain-text listing of discoveries. Reused for both
- * `--dry-run` output and the non-TTY fallback. */
-function printDiscoveryPlainText(discovered) {
+ * `--dry-run` output and the non-TTY fallback. Adjacent files are not listed
+ * row-by-row — the per-skill aggregate `(SKILL.md + N)` is enough signal. */
+function printDiscoveryPlainText(discovered, skillSummaries) {
+    const rootFiles = discovered.filter(isRoot);
     const byEcosystem = new Map();
-    for (const d of discovered) {
+    for (const d of rootFiles) {
         const list = byEcosystem.get(d.ecosystem) ?? [];
         list.push(d);
         byEcosystem.set(d.ecosystem, list);
     }
     console.log('');
-    console.log(`  Found ${discovered.length} skill(s) across ${byEcosystem.size} tool(s):`);
+    console.log(`  Found ${rootFiles.length} skill(s) across ${byEcosystem.size} tool(s):`);
     for (const [eco, list] of byEcosystem) {
         console.log('');
         console.log(`  ${ecosystemLabel(eco)}:`);
         for (const f of list) {
             const label = f.scope ? `${f.scope}/${f.slug}` : f.slug;
             const stub = f.sizeBytes < STUB_BYTE_THRESHOLD ? ' (stub — excluded by default)' : '';
-            console.log(`    • ${label}   ${formatBytes(f.sizeBytes)} · ${f.lineCount} lines${stub}`);
+            const summary = skillSummaries?.get(summaryKey(f));
+            const details = summary && summary.totalFiles > 1
+                ? `${formatBytes(summary.totalBytes)} · ${summary.totalFiles} files`
+                : `${formatBytes(f.sizeBytes)} · ${f.lineCount} lines`;
+            console.log(`    • ${label}   ${details}${stub}`);
+            // Render any sweep warnings as a sub-bullet under the skill — keeps
+            // the per-ecosystem section readable.
+            if (summary && summary.warnings.length > 0) {
+                const line = formatSweepWarnings(label, summary.warnings);
+                if (line)
+                    console.log(`    ${line.trimStart()}`);
+            }
         }
     }
     console.log('');
@@ -254,16 +536,26 @@ async function ingestDiscover(options) {
     // consume it. Includes per-file metadata; content is omitted to keep the
     // payload small — callers can re-run with a path to actually upload.
     if (options.json) {
-        const payload = discovery.files.map((f) => ({
-            ecosystem: f.ecosystem,
-            slug: f.slug,
-            scope: f.scope,
-            title: f.title,
-            sourcePath: f.sourcePath,
-            sizeBytes: f.sizeBytes,
-            lineCount: f.lineCount,
-            canonicalFilename: f.canonicalFilename,
-        }));
+        // Only emit root files (one per skill). Adjacent files are aggregated
+        // into `totalFiles` / `totalBytes` so the JSON consumer sees the same
+        // shape the TUI shows.
+        const payload = discovery.files
+            .filter(isRoot)
+            .map((f) => {
+            const summary = discovery.skillSummaries.get(summaryKey(f));
+            return {
+                ecosystem: f.ecosystem,
+                slug: f.slug,
+                scope: f.scope,
+                title: f.title,
+                sourcePath: f.sourcePath,
+                sizeBytes: f.sizeBytes,
+                lineCount: f.lineCount,
+                canonicalFilename: f.canonicalFilename,
+                totalFiles: summary?.totalFiles ?? 1,
+                totalBytes: summary?.totalBytes ?? f.sizeBytes,
+            };
+        });
         console.log(JSON.stringify({ discovered: payload, emptyEcosystems: discovery.emptyEcosystems }));
         return;
     }
@@ -271,22 +563,24 @@ async function ingestDiscover(options) {
     // (stubs excluded). Helps the user verify before re-running without
     // --dry-run.
     if (options.dryRun && options.auto) {
-        const eligible = discovery.files.filter((f) => f.sizeBytes >= STUB_BYTE_THRESHOLD);
-        printDiscoveryPlainText(eligible);
+        const eligible = applyStubFilter(discovery.files);
+        printDiscoveryPlainText(eligible, discovery.skillSummaries);
         console.log('  --dry-run --auto: would upload the above (stubs excluded). Not uploading.\n');
         return;
     }
     // --dry-run alone: list ALL discoveries in plain text, never upload, never
     // TUI. Stubs are marked inline so the user knows they'd be excluded.
     if (options.dryRun) {
-        printDiscoveryPlainText(discovery.files);
+        printDiscoveryPlainText(discovery.files, discovery.skillSummaries);
         console.log('  --dry-run: not uploading.\n');
         return;
     }
     // --auto: skip the TUI and upload everything matching the defaults (stubs
-    // < STUB_BYTE_THRESHOLD bytes excluded — same rule the TUI uses).
+    // < STUB_BYTE_THRESHOLD bytes excluded — same rule the TUI uses). The
+    // stub filter looks at the root file only; adjacent files always ride
+    // along when their root is selected.
     if (options.auto) {
-        const eligible = discovery.files.filter((f) => f.sizeBytes >= STUB_BYTE_THRESHOLD);
+        const eligible = applyStubFilter(discovery.files);
         if (eligible.length === 0) {
             console.log('\n  No skills found (all discovered files are < 100-byte stubs). Inspect with `--dry-run`.\n');
             return;
@@ -295,6 +589,15 @@ async function ingestDiscover(options) {
         console.log(`\n  ✓ Uploading ${skills.length} skill(s) found by discovery (--auto):`);
         for (const s of skills)
             console.log(`    • ${s.slug} (${s.files.length} file(s))`);
+        // Surface any sweep warnings inline so the user knows what got dropped.
+        for (const [, summary] of discovery.skillSummaries) {
+            if (summary.warnings.length === 0)
+                continue;
+            const label = summary.scope ? `${summary.scope}/${summary.slug}` : summary.slug;
+            const line = formatSweepWarnings(label, summary.warnings);
+            if (line)
+                console.log(line);
+        }
         await uploadSkills(skills, options);
         return;
     }
@@ -304,7 +607,7 @@ async function ingestDiscover(options) {
         // do NOT upload silently here — interactive consent matters. The user
         // can re-run with `--json` for machine-readable output or with `--auto`
         // for one-shot mode.
-        printDiscoveryPlainText(discovery.files);
+        printDiscoveryPlainText(discovery.files, discovery.skillSummaries);
         console.log('  Run with --json for machine-readable output, or in a real terminal for interactive selection.\n');
         return;
     }
@@ -317,6 +620,7 @@ async function ingestDiscover(options) {
     };
     const instance = render(React.createElement(IngestDiscoverApp, {
         files: discovery.files,
+        skillSummaries: discovery.skillSummaries,
         emptyEcosystems: discovery.emptyEcosystems,
         onDone: (r) => {
             resultHolder.value = r;
@@ -357,13 +661,24 @@ export async function ingest(rootPath, options) {
         return;
     }
     const detected = [];
+    const sweepWarnings = [];
     for (const filePath of walkFiles(root)) {
         const content = fs.readFileSync(filePath, 'utf-8');
         const d = options.fromTool
             ? detectFromTool(filePath, root, content, options.fromTool)
             : detectAuto(filePath, root, content);
-        if (d)
-            detected.push(d);
+        if (!d)
+            continue;
+        detected.push(d);
+        // Sweep adjacent files when the detector opts in (claude SKILL.md, the
+        // new claude-code-agents AGENT.md). The root file we already pushed —
+        // this catches scripts/, templates/, reference docs, etc.
+        const detector = DETECTORS[d.ecosystem];
+        const { files: adjacent, warnings } = adjacentFilesFor(detector, d.ecosystem, d.slug, filePath);
+        detected.push(...adjacent);
+        const warningLine = formatSweepWarnings(d.slug, warnings);
+        if (warningLine)
+            sweepWarnings.push(warningLine);
     }
     if (detected.length === 0) {
         if (options.fromTool) {
@@ -388,13 +703,15 @@ export async function ingest(rootPath, options) {
                 files: [],
             });
         }
-        grouped.get(f.slug).files.push({ filename: f.filename, content: f.content });
+        grouped.get(f.slug).files.push({ filename: f.filename, content: f.content, mode: f.mode });
     }
     const skills = [...grouped.values()];
     console.log(`\n  ✓ Found ${skills.length} skill(s):`);
     for (const s of skills) {
         console.log(`    • ${s.slug} (${s.files.length} file(s))`);
     }
+    for (const line of sweepWarnings)
+        console.log(line);
     if (options.dryRun) {
         console.log('\n  --dry-run: not uploading.\n');
         return;

package/dist/commands/install.js

@@ -55,6 +55,17 @@ async function downloadAndWrite(file, dest, options, projectDir) {
     }
     ensureDir(dest);
     fs.writeFileSync(dest, content, 'utf-8');
+    // Restore the file mode the author shipped. Defaults to 0o644 when the
+    // manifest omits `mode` (older server, pre-mode-column row, etc.). We
+    // explicitly chmod even when the value is 0o644 so a previously-executable
+    // file at the dest gets re-normalized to non-executable on update.
+    try {
+        fs.chmodSync(dest, file.mode ?? 0o644);
+    }
+    catch {
+        // chmod can fail on Windows / network mounts. Don't fail the install
+        // over a permission cosmetic — the file still got written.
+    }
     return { src: file.filename, dest, fingerprint: fingerprintFile(dest) };
 }
 async function installSkill(ref, manifest, options, scope) {

package/dist/commands/publish.d.ts

@@ -6,6 +6,34 @@ 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. */
+    yes?: boolean;
 }
 export declare function publish(source: string, options: PublishOptions): Promise<void>;
-export {};
+/**
+ * Toggle an existing BotDoc from draft → published via the API.
+ *
+ * Called from `publish()` when the source argument looks like a ref
+ * (`@user/slug` or `user/slug`) instead of a local path. Strips the
+ * `draft` and `ingest:<id>` tags server-side. No prompt — moving from
+ * draft to published is the natural progression, and unpublishing a
+ * mistake is one CLI call away.
+ */
+declare function publishRef(rawRef: string, options: PublishOptions): Promise<void>;
+/**
+ * Map an `ApiError` from a publish/unpublish call to a friendly,
+ * actionable message. Shared by both verbs so the wording stays in sync.
+ *
+ * 401: most likely the user isn't logged in (or their saved token is
+ * stale). The api lib already produces a helpful "run `botdocs login`"
+ * hint — pass it through.
+ *
+ * 403: authenticated as someone who doesn't own this BotDoc.
+ *
+ * 404: BotDoc doesn't exist (or is owned by a different user — the API
+ * returns 404 rather than 403 to avoid leaking existence to non-authors).
+ */
+declare function handlePublishToggleError(err: unknown, refLabel: string, options: PublishOptions): void;
+export { publishRef, handlePublishToggleError };

package/dist/commands/publish.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import AdmZip from 'adm-zip';
-import { apiFetch } from '../lib/api.js';
+import { ApiError, apiFetch } from '../lib/api.js';
 import { parseManifest } from '../lib/manifest.js';
 import { compile } from './compile.js';
 import { ecosystemDestination } from '../lib/canonical.js';
+import { isRefForm, parseRef } from '../lib/ref.js';
 const VALID_CATEGORIES = [
     'KNOWLEDGE_MANAGEMENT',
     'DEV_WORKFLOW',
@@ -15,6 +16,16 @@ const VALID_CATEGORIES = [
 ];
 const VALID_LICENSES = ['MIT', 'CC_BY_4_0', 'CC_BY_SA_4_0', 'CC0', 'ALL_RIGHTS_RESERVED'];
 export async function publish(source, options) {
+    // Ref-form (e.g. "@user/slug" or "user/slug") → toggle the published
+    // flag via the API. Path-form continues to the existing upload flow
+    // below. Overloading by argument shape (rather than introducing
+    // `botdocs publish-ref` or a `--ref` flag) keeps the verb intuitive:
+    // a user typing `botdocs publish @me/foo` doesn't have to know it's a
+    // different code path under the hood.
+    if (isRefForm(source)) {
+        await publishRef(source, options);
+        return;
+    }
     const resolved = path.resolve(source);
     if (!fs.existsSync(resolved)) {
         console.error(`Source not found: ${source}`);
@@ -92,6 +103,79 @@ export async function publish(source, options) {
         console.log(`\nPublished: ${result.url}`);
     }
 }
+/**
+ * Toggle an existing BotDoc from draft → published via the API.
+ *
+ * Called from `publish()` when the source argument looks like a ref
+ * (`@user/slug` or `user/slug`) instead of a local path. Strips the
+ * `draft` and `ingest:<id>` tags server-side. No prompt — moving from
+ * draft to published is the natural progression, and unpublishing a
+ * mistake is one CLI call away.
+ */
+async function publishRef(rawRef, options) {
+    let parsed;
+    try {
+        parsed = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    const { username, slug } = parsed;
+    const refLabel = `@${username}/${slug}`;
+    try {
+        await apiFetch(`/api/botdocs/${username}/${slug}/publish`, {
+            method: 'POST',
+            auth: true,
+        });
+    }
+    catch (err) {
+        handlePublishToggleError(err, refLabel, options);
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'published' }));
+    }
+    else {
+        console.log(`✓ Published ${refLabel} — visible at https://botdocs.ai/${refLabel}`);
+    }
+}
+/**
+ * Map an `ApiError` from a publish/unpublish call to a friendly,
+ * actionable message. Shared by both verbs so the wording stays in sync.
+ *
+ * 401: most likely the user isn't logged in (or their saved token is
+ * stale). The api lib already produces a helpful "run `botdocs login`"
+ * hint — pass it through.
+ *
+ * 403: authenticated as someone who doesn't own this BotDoc.
+ *
+ * 404: BotDoc doesn't exist (or is owned by a different user — the API
+ * returns 404 rather than 403 to avoid leaking existence to non-authors).
+ */
+function handlePublishToggleError(err, refLabel, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, ref: refLabel, status: err.status, error: err.message }));
+        process.exit(1);
+    }
+    if (err.status === 401) {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    else if (err.status === 403) {
+        console.error(`\n  ✗ You don't own ${refLabel}.\n`);
+    }
+    else if (err.status === 404) {
+        console.error(`\n  ✗ BotDoc not found: ${refLabel}\n`);
+    }
+    else {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    process.exit(1);
+}
+export { publishRef, handlePublishToggleError };
 function readManifest(source) {
     const manifestPath = path.join(source, 'botdocs.json');
     if (!fs.existsSync(manifestPath))