@botdocs/cli 0.5.0 → 0.8.0

package/dist/lib/ingest-discover.js

@@ -0,0 +1,271 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DETECTORS, formatSweepWarnings, sweepSkillRoot, } from '../commands/ingest.js';
+/** Tiny H1 extractor — the same regex `ingest.ts` uses today. Falls back to a
+ * Title-Cased slug when no H1 is present. */
+export function titleFromContent(content, slug) {
+    const m = content.match(/^#\s+(.+)$/m);
+    return m?.[1]?.trim() ?? slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/** Walk up from `start` looking for a `.git` directory. Returns true if any
+ * ancestor is a git repo. Used to gate project-scoped scans (cursor, codex,
+ * copilot, windsurf) which only make sense for repos. */
+export function isGitRepo(start) {
+    let dir = start;
+    // Guard against an infinite loop on platforms where dirname(/) === /
+    for (let i = 0; i < 64; i++) {
+        const candidate = path.join(dir, '.git');
+        try {
+            if (fs.existsSync(candidate))
+                return true;
+        }
+        catch {
+            // Permission denied on some ancestor — treat as not-a-repo and keep walking
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+    return false;
+}
+/** Build the per-row scan table for a given home + cwd by fanning out the
+ * shared `DETECTORS.<ecosystem>.scanPaths()` results. Project rows are
+ * naturally absent when `cwd` is outside a git repo because each project
+ * detector returns `[]` for that case.
+ *
+ * Split out as its own exported function so tests can assert the row shape
+ * without spinning up a fixture tree on disk. */
+export function buildDetectors(homeDir, cwd) {
+    const inRepo = isGitRepo(cwd);
+    const rows = [];
+    for (const [ecosystem, detector] of Object.entries(DETECTORS)) {
+        const paths = detector.scanPaths(homeDir, cwd, inRepo);
+        if (paths.length === 0)
+            continue;
+        // Anything under homeDir is "global"; anything else is "project". This
+        // mirrors how each detector's scanPaths was authored — global paths use
+        // homeDir, project paths use projectRoot.
+        for (const dir of paths) {
+            const kind = dir.startsWith(homeDir) ? 'global' : 'project';
+            rows.push({
+                ecosystem: ecosystem,
+                kind,
+                dir,
+                recursive: detector.nested,
+            });
+        }
+    }
+    return rows;
+}
+/** Recursively walk a directory collecting absolute paths. Returns an empty
+ * list if the directory doesn't exist. Caller decides how to filter results. */
+function walkAll(dir, recursive) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!recursive)
+                continue;
+            // Recurse but skip noisy dirs (node_modules etc. are unlikely under tool
+            // config trees but cheap to defend against).
+            if (entry.name === 'node_modules' || entry.name === '.git')
+                continue;
+            out.push(...walkAll(abs, true));
+        }
+        else if (entry.isFile()) {
+            out.push(abs);
+        }
+    }
+    return out;
+}
+/** For nested ecosystems, the scope is the directory segment immediately
+ * under the scan directory that contains the slug directory. For unscoped
+ * layouts (`<scanDir>/<slug>/SKILL.md`), the parent of the slug dir IS the
+ * scan dir and there's no scope. Returns undefined when no scope applies. */
+function scopeForNested(absPath, scanDir) {
+    // absPath looks like `<scanDir>/.../<scope?>/<slug>/SKILL.md`. The slug dir
+    // is the parent; the scope dir (if any) is the grandparent.
+    const slugDir = path.dirname(absPath);
+    const candidateScopeDir = path.dirname(slugDir);
+    if (candidateScopeDir === scanDir)
+        return undefined;
+    return path.basename(candidateScopeDir);
+}
+/** Key for the per-skill summary map. Stays stable across discoveries so the
+ * TUI can look up a summary by row. */
+export function summaryKey(file) {
+    return `${file.ecosystem}::${file.scope ?? ''}/${file.slug}`;
+}
+/** Stat helper: return st_mode masked to the low 9 perm bits, or 0o644 on
+ * failure. Mirrors the same helper in commands/ingest.ts. */
+function safeMode(absPath) {
+    try {
+        return fs.statSync(absPath).mode & 0o777;
+    }
+    catch {
+        return 0o644;
+    }
+}
+/** Scan all known on-disk locations and return a flat list of discoveries.
+ * Reads file contents synchronously — discovery is one-shot and typically
+ * touches a handful of small files, so the simplicity wins over async sprawl.
+ *
+ * Single source of truth for which ecosystems we know about is the shared
+ * `DETECTORS` table in `commands/ingest.ts`. Each detector's `scanPaths`
+ * decides where to look on disk, `slugFor` extracts the slug, and
+ * `canonicalFilename` produces the upload-shaped filename. */
+export function discoverSkills(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const cwd = options.cwd ?? process.cwd();
+    const rows = buildDetectors(homeDir, cwd);
+    const files = [];
+    const skillSummaries = new Map();
+    const seen = new Set();
+    const empty = new Set();
+    for (const row of rows) {
+        const detector = DETECTORS[row.ecosystem];
+        const candidates = walkAll(row.dir, row.recursive);
+        // Filter to files this detector would accept. We pass the scan dir as the
+        // "root" so `slugFor` can do path-relative work — same convention the
+        // path-based ingest path uses, with `scanDir` standing in for the source
+        // tree root.
+        const matched = candidates.filter((abs) => detector.extensions.some((ext) => abs.endsWith(ext)));
+        if (matched.length === 0) {
+            if (!seen.has(row.ecosystem))
+                empty.add(row.ecosystem);
+            continue;
+        }
+        for (const abs of matched) {
+            const slug = detector.slugFor(abs, row.dir);
+            if (!slug)
+                continue;
+            let content;
+            try {
+                content = fs.readFileSync(abs, 'utf-8');
+            }
+            catch {
+                // Unreadable file — skip silently. Discovery should never throw on
+                // permission errors; users with unusual setups still get the rest.
+                continue;
+            }
+            const scope = detector.nested ? scopeForNested(abs, row.dir) : undefined;
+            const sizeBytes = Buffer.byteLength(content, 'utf-8');
+            const lineCount = content.length === 0 ? 0 : content.split(/\r?\n/).length;
+            const rootFile = {
+                ecosystem: row.ecosystem,
+                sourcePath: abs,
+                slug,
+                scope,
+                title: titleFromContent(content, slug),
+                sizeBytes,
+                lineCount,
+                content,
+                mode: safeMode(abs),
+                canonicalFilename: detector.canonicalFilename(slug),
+            };
+            files.push(rootFile);
+            // Per-skill summary aggregates the root file + any adjacent sweep
+            // outputs below. We seed it now and append adjacent files inline.
+            const sumKey = summaryKey(rootFile);
+            const summary = {
+                ecosystem: row.ecosystem,
+                scope,
+                slug,
+                totalFiles: 1,
+                totalBytes: sizeBytes,
+                warnings: [],
+            };
+            skillSummaries.set(sumKey, summary);
+            // Adjacent-file sweep for detectors that opt in (claude, claude-code-agents).
+            if (detector.includeAdjacent && detector.skillRoot && detector.canonicalAdjacentFilename) {
+                const skillRoot = detector.skillRoot(abs);
+                const sweep = sweepSkillRoot(skillRoot, abs);
+                for (const adj of sweep.files) {
+                    files.push({
+                        ecosystem: row.ecosystem,
+                        sourcePath: adj.absPath,
+                        slug,
+                        scope,
+                        title: rootFile.title,
+                        // sizeBytes / lineCount on adjacent rows describe the adjacent
+                        // file itself — not the skill total. The TUI uses sizeBytes on
+                        // the ROOT row only for the stub filter; per-skill totals come
+                        // from the summary map.
+                        sizeBytes: adj.sizeBytes,
+                        lineCount: adj.content.length === 0 ? 0 : adj.content.split(/\r?\n/).length,
+                        content: adj.content,
+                        mode: adj.mode,
+                        canonicalFilename: detector.canonicalAdjacentFilename(slug, adj.relPath),
+                    });
+                    summary.totalFiles += 1;
+                    summary.totalBytes += adj.sizeBytes;
+                }
+                summary.warnings = sweep.warnings;
+            }
+            seen.add(row.ecosystem);
+            empty.delete(row.ecosystem);
+        }
+    }
+    // Sort stable: by ecosystem, then by display label (scope/slug), then by
+    // canonical filename so adjacent files cluster behind their root file.
+    files.sort((a, b) => {
+        if (a.ecosystem !== b.ecosystem)
+            return a.ecosystem.localeCompare(b.ecosystem);
+        const aLabel = a.scope ? `${a.scope}/${a.slug}` : a.slug;
+        const bLabel = b.scope ? `${b.scope}/${b.slug}` : b.slug;
+        if (aLabel !== bLabel)
+            return aLabel.localeCompare(bLabel);
+        return a.canonicalFilename.localeCompare(b.canonicalFilename);
+    });
+    return {
+        files,
+        skillSummaries,
+        emptyEcosystems: [...empty].sort(),
+        inGitRepo: isGitRepo(cwd),
+    };
+}
+/** Re-export the warning formatter so callers (TUI, plain-text) can share
+ * one rendering. */
+export { formatSweepWarnings };
+/** Human-readable label per ecosystem for the TUI section header. */
+export function ecosystemLabel(ecosystem) {
+    switch (ecosystem) {
+        case 'claude-code':
+            return 'Claude Code';
+        case 'claude-code-agents':
+            return 'Claude Code agents';
+        case 'claude':
+            return 'Claude skills';
+        case 'cursor':
+            return 'Cursor rules';
+        case 'codex':
+            return 'Codex';
+        case 'copilot':
+            return 'GitHub Copilot';
+        case 'windsurf':
+            return 'Windsurf';
+        case 'gemini':
+            return 'Gemini CLI';
+        case 'antigravity':
+            return 'Antigravity';
+        case 'opencode':
+            return 'OpenCode';
+    }
+}
+/** Format a byte count as "0.1 KB" / "2.4 KB" etc. — matches the spec sample.
+ * Single decimal place keeps narrow rows aligned in the TUI. */
+export function formatBytes(n) {
+    return `${(n / 1024).toFixed(1)} KB`;
+}
+/** Files smaller than this are unchecked by default (likely stub files the
+ * user hasn't filled in yet). 100 bytes ≈ a one-line H1 plus a blank line. */
+export const STUB_BYTE_THRESHOLD = 100;

package/dist/lib/ref.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Parse a BotDoc ref like `@user/slug` or `user/slug` into its parts.
+ *
+ * Mirrors the inline `parseRef` already in `commands/install.ts` and
+ * `commands/edit.ts` — kept here for reuse by `publish`/`unpublish`.
+ * The existing duplicates can be folded into this helper in a future
+ * refactor without behavior change.
+ *
+ * Throws on a malformed input so callers can surface a clear message
+ * instead of silently dispatching a malformed API request.
+ */
+export declare function parseRef(raw: string): {
+    username: string;
+    slug: string;
+};
+/**
+ * True when `source` looks like a BotDoc ref (e.g. `@me/my-skill` or
+ * `me/my-skill`), false when it looks like a local filesystem path.
+ *
+ * Used by `botdocs publish <source>` to overload one verb by argument
+ * shape — ref-form dispatches to the publish-toggle API, anything else
+ * goes through the existing file/dir/zip upload flow.
+ *
+ * Heuristic (lean toward "is a ref" only when unambiguous):
+ *
+ * - `@…` → ref. The leading `@` is unambiguous; no filesystem path
+ *   starts with `@`.
+ * - Starts with `./`, `..`, or `/` → path. Absolute and explicit
+ *   relative paths are never refs.
+ * - Contains a `.` (e.g. `foo.md`, `foo.zip`, `dir/file.md`) → path.
+ *   File extensions are the strongest signal we're looking at a file.
+ * - Contains exactly one `/` with non-empty parts on either side → ref.
+ *   `user/slug` and `org/repo`-style.
+ * - Otherwise → path. Bare names like `my-skill` resolve as directory
+ *   paths under the existing upload flow.
+ *
+ * False positives (a real directory named `user/slug` with no `.`) will
+ * surface as a clean "BotDoc not found" 404 from the API — not silent
+ * data loss, just a clearer error than letting the upload flow choke
+ * on a non-existent path.
+ */
+export declare function isRefForm(source: string): boolean;

package/dist/lib/ref.js

@@ -0,0 +1,60 @@
+/**
+ * Parse a BotDoc ref like `@user/slug` or `user/slug` into its parts.
+ *
+ * Mirrors the inline `parseRef` already in `commands/install.ts` and
+ * `commands/edit.ts` — kept here for reuse by `publish`/`unpublish`.
+ * The existing duplicates can be folded into this helper in a future
+ * refactor without behavior change.
+ *
+ * Throws on a malformed input so callers can surface a clear message
+ * instead of silently dispatching a malformed API request.
+ */
+export function parseRef(raw) {
+    const cleaned = raw.startsWith('@') ? raw.slice(1) : raw;
+    const parts = cleaned.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error(`Invalid ref: ${raw} (expected @user/slug)`);
+    }
+    return { username: parts[0], slug: parts[1] };
+}
+/**
+ * True when `source` looks like a BotDoc ref (e.g. `@me/my-skill` or
+ * `me/my-skill`), false when it looks like a local filesystem path.
+ *
+ * Used by `botdocs publish <source>` to overload one verb by argument
+ * shape — ref-form dispatches to the publish-toggle API, anything else
+ * goes through the existing file/dir/zip upload flow.
+ *
+ * Heuristic (lean toward "is a ref" only when unambiguous):
+ *
+ * - `@…` → ref. The leading `@` is unambiguous; no filesystem path
+ *   starts with `@`.
+ * - Starts with `./`, `..`, or `/` → path. Absolute and explicit
+ *   relative paths are never refs.
+ * - Contains a `.` (e.g. `foo.md`, `foo.zip`, `dir/file.md`) → path.
+ *   File extensions are the strongest signal we're looking at a file.
+ * - Contains exactly one `/` with non-empty parts on either side → ref.
+ *   `user/slug` and `org/repo`-style.
+ * - Otherwise → path. Bare names like `my-skill` resolve as directory
+ *   paths under the existing upload flow.
+ *
+ * False positives (a real directory named `user/slug` with no `.`) will
+ * surface as a clean "BotDoc not found" 404 from the API — not silent
+ * data loss, just a clearer error than letting the upload flow choke
+ * on a non-existent path.
+ */
+export function isRefForm(source) {
+    if (!source)
+        return false;
+    if (source.startsWith('@'))
+        return true;
+    if (source.startsWith('./') || source.startsWith('../') || source.startsWith('/')) {
+        return false;
+    }
+    if (source.includes('.'))
+        return false;
+    const parts = source.split('/');
+    if (parts.length !== 2)
+        return false;
+    return Boolean(parts[0] && parts[1]);
+}

package/package.json

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

package/templates/agents.md

@@ -119,7 +119,8 @@ the user and recommend they set one.
 | `init [name]` | Scaffold a new skill directory. |
 | `validate <source>` | Pre-publish structural check. |
 | `search <query>` | Search the registry. |
-| `publish <source>` | Publish from a file, directory, or zip. |
+| `publish <source>` | Publish from a file, directory, or zip — or pass `@user/slug` to mark an existing draft live. |
+| `unpublish <ref>` | Hide a published BotDoc from `/explore` (sets the `draft` flag back; prompts unless `--yes`). |
 | `install <ref>` | Install a skill or bundle (auto-detects destinations). |
 | `sync [ref]` | Apply available updates to installed skills. |
 | `uninstall <ref>` | Remove an installed skill or bundle. |
@@ -129,7 +130,7 @@ the user and recommend they set one.
 | `backups list / restore / diff / clear` | Browse and manage backup runs. |
 | `compile <path>` | Generate per-ecosystem drafts from a canonical source (BYOK). |
 | `edit <ref>` | LLM-assisted revision of a published skill ecosystem file (BYOK). |
-| `ingest <path>` | Walk a directory, detect existing skills across all 10 ecosystems, upload as drafts. Use `--from-tool=<ecosystem>` to ingest from real on-disk locations like `~/.claude/commands/` or `.cursor/rules/`. |
+| `ingest [path]` | Scan your system (zero-arg) or a directory, detect existing skills across all 10 ecosystems, upload as drafts. Use `--from-tool=<ecosystem>` for real on-disk locations like `~/.claude/commands/`; pass `--auto` to skip the interactive selection. |
 | `team list` | List teams you belong to. |
 | `team show <slug>` | Members + pinned skills for a team. |
 | `team push <slug> <ref>` | Pin a skill to a team (WRITE+). |