@botdocs/cli 0.10.3 → 0.12.0

package/dist/commands/publish.js

@@ -1,11 +1,51 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import AdmZip from 'adm-zip';
-import { ApiError, apiFetch } from '../lib/api.js';
+import * as p from '@clack/prompts';
+import { ApiError, apiFetch, getApiUrl, friendlyApiErrorDetail } 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';
+import { loadAuth } from '../lib/config.js';
+/** Bail out early when the user isn't logged in. Without this, publish runs
+ * through file collection, manifest parsing, and the description prompt
+ * before the POST hits a 401 — wasting input and surfacing a confusing
+ * "Authentication failed" message at the end. Mirror whoami.ts's preflight:
+ * one friendly line, exit 1. JSON-mode emits the same structured payload
+ * other publish auth errors do so scripts can branch on it. */
+function requireAuth(options) {
+    if (loadAuth())
+        return;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, error: 'not logged in', hint: 'Run `botdocs login` first.' }));
+    }
+    else {
+        console.error('\n  ✗ Not logged in. Run `botdocs login` first.\n');
+    }
+    process.exit(1);
+}
+/** Canonical-skill primary-file heuristic — mirrors the server-side
+ * `pickPrimaryFile` in `apps/web/src/app/api/cli/ingest/route.ts`. Used to
+ * answer "does this multi-file payload have something we can publish?"
+ * without requiring a literal `index.md`. */
+function hasPublishablePrimary(files) {
+    if (files.length === 0)
+        return false;
+    const basename = (filename) => {
+        const idx = filename.lastIndexOf('/');
+        return idx === -1 ? filename : filename.slice(idx + 1);
+    };
+    if (files.some((f) => /\/(SKILL|AGENT)\.md$/.test(f.filename)))
+        return true;
+    if (files.some((f) => basename(f.filename) === 'SKILL.md' || basename(f.filename) === 'AGENT.md'))
+        return true;
+    if (files.some((f) => f.filename === 'index.md'))
+        return true;
+    if (files.some((f) => f.filename.endsWith('.md') || f.filename.endsWith('.mdc')))
+        return true;
+    return false;
+}
 const VALID_CATEGORIES = [
     'KNOWLEDGE_MANAGEMENT',
     'DEV_WORKFLOW',
@@ -16,6 +56,10 @@ 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) {
+    // Preflight: bail before any file reading / description prompting if the
+    // user isn't logged in. The 401 would otherwise only surface after the POST,
+    // making large publishes feel slow and confusing.
+    requireAuth(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
@@ -31,7 +75,19 @@ export async function publish(source, options) {
         console.error(`Source not found: ${source}`);
         process.exit(1);
     }
-    // Determine source type and collect files
+    // Determine source type and collect files. `lstatSync` reports the path's
+    // OWN type rather than its target's, so we can refuse a symlinked entry
+    // point. Without this, `botdocs publish ./leak.md` where `leak.md` is a
+    // symlink to e.g. `~/.ssh/id_rsa` would read the target into the publish
+    // payload — the same exfil class the walker fix closes for nested
+    // entries. We reject (fatal) rather than warn-and-skip: the user
+    // explicitly named this path, so silently doing nothing would be more
+    // confusing than the error.
+    const lstat = fs.lstatSync(resolved);
+    if (lstat.isSymbolicLink()) {
+        console.error(`Refusing to publish from a symlink: ${source}. Pass the resolved real path instead.`);
+        process.exit(1);
+    }
     let files;
     const stat = fs.statSync(resolved);
     if (stat.isDirectory()) {
@@ -49,21 +105,32 @@ export async function publish(source, options) {
         console.error('No markdown files found.');
         process.exit(1);
     }
-    // Ensure index.md exists
-    const hasIndex = files.some((f) => f.filename === 'index.md');
-    if (!hasIndex) {
-        // For single file, rename to index.md
+    // Canonical skill layouts (`claude/SKILL.md`, `claude-code/commands/<slug>.md`,
+    // top-level `<slug>.md`/`.mdc`) don't have a literal `index.md`. Require
+    // "at least one publishable markdown file" instead — matching the
+    // server-side `pickPrimaryFile` heuristic and the repo CLAUDE.md guidance.
+    if (!hasPublishablePrimary(files)) {
         if (files.length === 1) {
+            // Single file with an unusual extension — rename it so the server
+            // can still resolve a primary file. Preserves the old single-file
+            // ergonomics without re-introducing the hard `index.md` requirement.
             files[0].filename = 'index.md';
         }
         else {
-            console.error('Multi-file BotDocs must include an index.md file.');
+            console.error('No publishable markdown found (expected SKILL.md, AGENT.md, <slug>.md/.mdc, index.md, or any .md).');
             process.exit(1);
         }
     }
+    // Pull type + sourceEcosystem from botdocs.json so the server stores
+    // the row as a SKILL/BUNDLE (instead of defaulting to SPEC).
+    const manifest = stat.isDirectory() ? readManifest(resolved) : null;
     // Resolve metadata from flags
     const title = options.title || deriveTitle(source, files);
-    const description = options.description || '';
+    // Description resolution: --description flag > botdocs.json `description` >
+    // empty. The manifest fallback lets `botdocs publish .` work without
+    // forcing the author to repeat the flag every time once they've put the
+    // description in their manifest.
+    const description = options.description || manifest?.description || '';
     const category = resolveCategory(options.category);
     const tags = options.tags
         ? options.tags
@@ -72,37 +139,168 @@ export async function publish(source, options) {
             .filter(Boolean)
         : [];
     const license = resolveLicense(options.license);
+    const botdocType = manifest?.type ?? 'SPEC';
+    const sourceEcosystem = manifest?.sourceEcosystem ?? null;
+    // --dry-run: print what would be published and exit. Validates everything
+    // up to (but not including) the POST so authors can sanity-check the
+    // payload — title resolution, description fallback, file list, total size
+    // vs cap — before committing. Mirrors the file/total caps in
+    // apps/web/src/lib/skill-caps.ts (64KB per file, 512KB total) so the
+    // preview reflects what the server would enforce.
+    //
+    // Description is intentionally NOT required in dry-run: authors run
+    // `--dry-run` to preview the payload BEFORE filling in metadata. Surface
+    // the missing field as a placeholder in the preview rather than aborting.
+    if (options.dryRun) {
+        const previewDescription = description || '<missing — fill in before publishing>';
+        printDryRun({ title, description: previewDescription, files, sourceEcosystem, source }, options);
+        return;
+    }
     if (!description) {
-        console.error('Description is required. Use --description "..."');
+        console.error('Description is required. Use --description "..." or set "description" in botdocs.json.');
         process.exit(1);
     }
-    // Pull type + sourceEcosystem from botdocs.json so the server stores
-    // the row as a SKILL/BUNDLE (instead of defaulting to SPEC).
-    const manifest = stat.isDirectory() ? readManifest(resolved) : null;
-    const botdocType = manifest?.type ?? 'SPEC';
-    const sourceEcosystem = manifest?.sourceEcosystem ?? null;
+    // Pre-POST confirmation. Publish is immediate and pushes the skill to the
+    // public registry — first-time authors don't always know that, so we ask
+    // y/N (defaulting to N) before sending. Skipped under --yes (scripted
+    // runs that opt in) and --json (non-interactive consumers, which also
+    // gives back-compat for callers that don't have a TTY).
+    if (!options.yes && !options.json) {
+        const auth = loadAuth();
+        // requireAuth() ran first, so auth is non-null here. The fallback is
+        // defensive in case of a future refactor.
+        const username = auth?.username ?? 'me';
+        const slugGuess = derivePublishSlug(source);
+        const confirmed = await p.confirm({
+            message: `Publish to public registry as @${username}/${slugGuess}?`,
+            initialValue: false,
+        });
+        if (p.isCancel(confirmed) || confirmed !== true) {
+            console.log('  Publish cancelled.');
+            return;
+        }
+    }
     console.log(`Publishing "${title}" (${files.length} file(s))...`);
-    const result = await apiFetch('/api/botdocs', {
-        method: 'POST',
-        auth: true,
-        body: {
-            title,
-            description,
-            category,
-            tags,
-            license,
-            files,
-            botdocType,
-            sourceEcosystem,
-        },
-    });
+    let result;
+    try {
+        result = await apiFetch('/api/botdocs', {
+            method: 'POST',
+            auth: true,
+            body: {
+                title,
+                description,
+                category,
+                tags,
+                license,
+                files,
+                botdocType,
+                sourceEcosystem,
+            },
+        });
+    }
+    catch (err) {
+        handlePathPublishError(err, options);
+        return;
+    }
+    // Belt-and-suspenders: older server responses (or any path that slips
+    // through with a relative URL) become clickable links here. Newer
+    // servers return an absolute URL already, in which case this is a
+    // no-op.
+    const absoluteUrl = result.url.startsWith('/') ? `${getApiUrl()}${result.url}` : result.url;
     if (options.json) {
-        console.log(JSON.stringify(result));
+        console.log(JSON.stringify({ ...result, url: absoluteUrl }));
     }
     else {
-        console.log(`\nPublished: ${result.url}`);
+        console.log(`\nPublished: ${absoluteUrl}`);
     }
 }
+/** Translate path-publish API errors into actionable CLI messages.
+ *
+ * 409 ALREADY_EXISTS — the slug exists live for this author. The server
+ * suggests using the ref-form publish or the edit UI; pass that through.
+ *
+ * 409 ARCHIVED_SLUG — the slug exists but was soft-deleted. The server
+ * suggests restoring via the web UI; pass that through. (We don't auto-revive
+ * here because the user might genuinely want to start fresh on a different
+ * skill that happens to share the title — surfacing the conflict and letting
+ * them decide is safer.)
+ *
+ * 413 (payload too large) — the server's `validateSkillCaps` returns a
+ * structured `detail` body ("file foo/bar.md is 71 KB, cap is 64 KB"). We
+ * print `detail` instead of the generic ApiError message so authors know
+ * exactly which file to trim.
+ *
+ * Everything else falls back to the generic ApiError message.
+ */
+function handlePathPublishError(err, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    // The 413 body now ships structured `detail: { ..., message }`. Older
+    // server versions sent `detail: string`; we accept both shapes here so a
+    // freshly-deployed CLI keeps working against a not-yet-deployed server,
+    // and vice versa.
+    const body = err.body;
+    const code = body?.code;
+    const hint = body?.hint;
+    const detailMessage = extractDetailMessage(body?.detail);
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: false,
+            status: err.status,
+            error: err.message,
+            code: code ?? null,
+            hint: hint ?? null,
+            // Pass through the raw detail (string OR object) so scripted
+            // consumers can still read the structured fields. JSON.stringify
+            // handles both shapes cleanly.
+            detail: body?.detail ?? null,
+        }));
+        process.exit(1);
+    }
+    if (err.status === 409 && code === 'ALREADY_EXISTS') {
+        console.error(`\n  ✗ ${err.message}`);
+        if (hint)
+            console.error(`    ${hint}`);
+        console.error('');
+    }
+    else if (err.status === 409 && code === 'ARCHIVED_SLUG') {
+        console.error(`\n  ✗ ${err.message}`);
+        if (hint)
+            console.error(`    ${hint}`);
+        console.error('');
+    }
+    else if (err.status === 413) {
+        // Prefer the server-rendered `detail.message` ("file foo.md is 71 KB,
+        // cap is 64 KB") because the server knows the per-branch context. Fall
+        // back to:
+        //   1. a string-form `detail` (older servers)
+        //   2. the generic `err.message`
+        // so we always print something user-actionable instead of the previous
+        // `[object Object]` regression.
+        console.error(`\n  ✗ ${detailMessage ?? err.message}\n`);
+    }
+    else if (err.status === 401) {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    else {
+        // Generic 403/429/5xx — route through the shared helper so the
+        // wording matches sync/install/edit instead of leaking ApiError's raw
+        // `message` (which is often the server's error string verbatim).
+        console.error(`\n  ✗ ${friendlyApiErrorDetail(err)}\n`);
+    }
+    process.exit(1);
+}
+/** Pull a printable line out of the 413 `detail` field, accepting both the
+ * new structured shape (`{ message: '…' }`) and the legacy string form. */
+function extractDetailMessage(detail) {
+    if (typeof detail === 'string')
+        return detail;
+    if (detail && typeof detail.message === 'string' && detail.message.length > 0) {
+        return detail.message;
+    }
+    return undefined;
+}
 /**
  * Toggle an existing BotDoc from draft → published via the API.
  *
@@ -113,6 +311,11 @@ export async function publish(source, options) {
  * mistake is one CLI call away.
  */
 async function publishRef(rawRef, options) {
+    // Preflight: same as the path-form publish. publish() already called
+    // requireAuth before dispatching here, but publishRef is also exported
+    // (and re-used by tests/other commands) — keep the guard local so the
+    // contract holds regardless of caller.
+    requireAuth(options);
     let parsed;
     try {
         parsed = parseRef(rawRef);
@@ -165,13 +368,17 @@ function handlePublishToggleError(err, refLabel, options) {
         console.error(`\n  ✗ ${err.message}\n`);
     }
     else if (err.status === 403) {
+        // Ownership check is command-specific — keep the explicit "you don't
+        // own this" wording instead of the generic team-membership-lost line.
         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`);
+        // 429/5xx — use the shared friendly helper for consistent wording
+        // across commands.
+        console.error(`\n  ✗ ${friendlyApiErrorDetail(err)}\n`);
     }
     process.exit(1);
 }
@@ -220,9 +427,38 @@ async function maybeAutoCompile(source, options) {
         return !fs.existsSync(dest) || fs.statSync(dest).mtimeMs < sourceMtime;
     });
     if (stale) {
-        console.log('  Auto-compiling stale ecosystem files…');
+        if (!options.json)
+            console.log('  Auto-compiling stale ecosystem files…');
         await compile(source, {});
     }
+    else if (!options.json) {
+        // Previously silent — users couldn't tell whether auto-compile ran or
+        // was skipped. Print a clear no-op line so the author knows their
+        // ecosystem files are already in sync with the source.
+        console.log('  Ecosystems up-to-date — skipping compile.');
+    }
+}
+/** Best-effort slug derivation for the publish confirmation prompt. Mirrors
+ * the slug logic in `printDryRun` so the y/N message and the dry-run preview
+ * agree. Falls back to the source path's basename for non-directory sources.
+ *
+ * Edge case: `botdocs publish .` (or `..`, or an empty string) used to derive
+ * an empty slug, so the confirm prompt and dry-run preview both said
+ * `@user/` — confusing for first-time authors. When the literal basename is
+ * `.`/`..`/empty, fall back to the resolved-path basename so the cwd name
+ * shows up instead. Cross-platform note: `path.basename('.')` returns `'.'`
+ * on POSIX and Windows alike (verified empirically); the resolved fallback
+ * is what gives us the real directory name. */
+function derivePublishSlug(source) {
+    const trimmed = source.trim();
+    const rawBase = path.basename(trimmed, path.extname(trimmed));
+    const base = rawBase === '' || rawBase === '.' || rawBase === '..'
+        ? path.basename(path.resolve(trimmed))
+        : rawBase;
+    return base
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
 }
 function collectFromFile(filePath) {
     const content = fs.readFileSync(filePath, 'utf-8');
@@ -235,20 +471,38 @@ function collectFromDirectory(dirPath) {
     files.sort((a, b) => a.sortOrder - b.sortOrder);
     return files;
 }
-function walkDirectory(rootDir, currentDir, out) {
-    const entries = fs.readdirSync(currentDir);
+/**
+ * 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 function walkDirectory(rootDir, currentDir, out) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
     for (const entry of entries) {
-        if (entry.startsWith('.'))
+        if (entry.name.startsWith('.'))
+            continue;
+        const fullPath = path.join(currentDir, entry.name);
+        if (entry.isSymbolicLink()) {
+            const rel = path.relative(rootDir, fullPath).split(path.sep).join('/');
+            console.warn(`Skipping symlink: ${rel}`);
             continue;
-        const fullPath = path.join(currentDir, entry);
-        const stat = fs.statSync(fullPath);
-        if (stat.isDirectory()) {
+        }
+        if (entry.isDirectory()) {
             walkDirectory(rootDir, fullPath, out);
             continue;
         }
-        if (!stat.isFile())
+        if (!entry.isFile())
             continue;
-        if (!entry.endsWith('.md') && !entry.endsWith('.markdown'))
+        if (!entry.name.endsWith('.md') && !entry.name.endsWith('.markdown'))
             continue;
         // POSIX-style relative path so the install-time prefix check
         // (e.g. `claude/SKILL.md`) works on every platform.
@@ -328,3 +582,62 @@ function resolveLicense(input) {
     };
     return aliases[upper] ?? 'MIT';
 }
+/** Mirror of `apps/web/src/lib/skill-caps.ts` — kept inlined here so the CLI's
+ * dry-run preview can reflect the same per-file and per-skill caps the server
+ * will enforce, without dragging the web app into the CLI's dep graph. */
+const PER_FILE_BYTE_CAP_PREVIEW = 64 * 1024;
+const PER_SKILL_BYTE_CAP_PREVIEW = 512 * 1024;
+/** Render N bytes as a short human string (`12 KB`, `512 KB`). KB only — the
+ * dry-run preview is bounded by PER_SKILL_BYTE_CAP_PREVIEW (512KB) so MB
+ * never comes up. */
+function formatKb(bytes) {
+    const kb = bytes / 1024;
+    if (kb < 10)
+        return `${kb.toFixed(1)} KB`;
+    return `${Math.round(kb)} KB`;
+}
+/** Print a dry-run preview of what `publish` would upload, then exit. Suppressed
+ * under --json (emits a structured payload instead) so scripts can branch on
+ * the same shape they'd get from a real publish. */
+function printDryRun(payload, options) {
+    const auth = loadAuth();
+    // requireAuth() ran first, so auth is non-null here. Default to a sentinel
+    // so the preview still renders cleanly if someone calls printDryRun without
+    // the preflight (e.g. a future refactor).
+    const username = auth?.username ?? 'me';
+    // Slug derivation mirrors the server: lowercase the title and collapse
+    // non-alphanumerics. The actual server-side slug is authoritative, but this
+    // gives users a close-enough preview ("am I publishing to the right
+    // place?") without an extra round-trip. Shared with the confirmation
+    // prompt's `derivePublishSlug` so both surfaces agree.
+    const slugPreview = derivePublishSlug(payload.source);
+    const fileSizes = payload.files.map((f) => ({
+        name: f.filename,
+        bytes: Buffer.byteLength(f.content, 'utf-8'),
+    }));
+    const totalBytes = fileSizes.reduce((sum, f) => sum + f.bytes, 0);
+    if (options.json) {
+        console.log(JSON.stringify({
+            dryRun: true,
+            title: payload.title,
+            description: payload.description,
+            slug: `@${username}/${slugPreview}`,
+            sourceEcosystem: payload.sourceEcosystem,
+            files: fileSizes.map((f) => ({ filename: f.name, bytes: f.bytes })),
+            totalBytes,
+            perFileCap: PER_FILE_BYTE_CAP_PREVIEW,
+            perSkillCap: PER_SKILL_BYTE_CAP_PREVIEW,
+        }));
+        return;
+    }
+    console.log('\n[dry-run] Would publish:');
+    console.log(`  Title:       ${payload.title}`);
+    console.log(`  Description: ${payload.description}`);
+    console.log(`  Slug:        @${username}/${slugPreview}`);
+    console.log(`  Files:       ${payload.files.length}`);
+    for (const f of fileSizes) {
+        console.log(`    - ${f.name}   (${formatKb(f.bytes)})`);
+    }
+    console.log(`  Total size:  ${formatKb(totalBytes)} / cap ${formatKb(PER_SKILL_BYTE_CAP_PREVIEW)}`);
+    console.log('\nNothing was sent. Re-run without --dry-run to publish.\n');
+}