@botdocs/cli 0.5.0 → 0.8.0

package/README.md

@@ -55,12 +55,14 @@ botdocs publish my-skill/
 | `edit <ref>` | LLM-assisted revision of a published skill ecosystem file (BYOK). |
 | `validate <source>` | Pre-publish structural check on a directory or file. |
 | `search <query>` | Search the public registry. |
-| `publish <source>` | Publish from a file, directory, or zip archive. |
+| `publish <source>` | Publish from a file, directory, or zip archive — or pass `@user/slug` to mark an existing draft live. |
+| `unpublish <ref>` | Hide a published BotDoc from `/explore` (sets the `draft` flag back). |
+| `delete <ref>` | Delete a BotDoc. Drafts are hard-deleted (row + all children); published BotDocs are soft-deleted (hidden, version history preserved). |
 | `install <ref>` | Install a skill or bundle (auto-detects destinations). |
 | `sync [ref]` | Check installed skills/bundles for updates and apply. |
 | `uninstall <ref>` | Remove an installed skill or bundle. |
 | `list` | Show installed skills and bundles. |
-| `ingest <path>` | Walk a directory, detect existing skills, upload as drafts. |
+| `ingest [path]` | Scan your system (or a directory), detect existing skills, upload as drafts. |
 | `team list` / `show` / `create` / `add` / `remove` / `push` / `unpush` | Manage teams: shared skill libraries for your org. |
 | `undo` | Restore the most recent backup run (reversible). |
 | `backups list` / `restore` / `diff` / `clear` | Browse, restore, diff, and prune backup runs. |
@@ -290,10 +292,28 @@ ambiguously (e.g. paths containing `_`).
 
 Authors who want to share their existing collection of skills run
 `botdocs ingest <path>` — the CLI walks the directory, detects each
-skill across all 10 supported ecosystems (claude, claude-code, cursor,
-chatgpt, codex, copilot, windsurf, gemini, antigravity, opencode), and
-uploads them as drafts in your BotDocs account for review before
-publishing.
+skill across all 11 supported ecosystems (claude, claude-code,
+claude-code-agents, cursor, chatgpt, codex, copilot, windsurf, gemini,
+antigravity, opencode), and uploads them as drafts in your BotDocs
+account for review before publishing.
+
+For nested ecosystems (claude SKILL.md, claude-code-agents AGENT.md),
+ingest also sweeps adjacent files inside the skill directory —
+`scripts/*.sh`, `templates/*`, reference docs — and uploads them with
+their original POSIX file mode so the executable bit on helper scripts
+survives the round-trip. `botdocs install` restores the mode on disk.
+
+Per-skill size limits (enforced both client- and server-side):
+
+- 64 KB per file
+- 512 KB total per skill
+- 25 files per skill
+
+Binary files are detected by a null-byte sniff on the first 8 KB and
+skipped with an inline warning. Cap violations warn and skip without
+failing the ingest. Skipped dirs: `node_modules/`, `.git/`, `dist/`,
+`build/`, `.next/`, `.turbo/`, `__pycache__/`, `venv/`, `.venv/`, plus
+all dotfiles, `.DS_Store`, `*.log`, `*.lock`.
 
 By default `ingest` expects the canonical BotDocs layout (e.g.
 `claude-code/commands/<slug>.md`, `cursor/rules/<slug>.mdc`). If your
@@ -316,6 +336,114 @@ The upload always uses the canonical BotDocs filename, so when someone
 else `botdocs install`s the resulting skill it lands in the right
 on-disk location.
 
+### Publishing drafts (and taking them back down)
+
+`botdocs ingest` and `botdocs edit` both create drafts — hidden from
+`/explore`, 404 for everyone but the author. To flip a draft live:
+
+```bash
+botdocs publish @me/my-skill      # → ✓ Published @me/my-skill
+botdocs publish @me/my-skill --json
+# → {"ok":true,"ref":"@me/my-skill","status":"published"}
+```
+
+`botdocs publish` is overloaded by argument shape: a local path
+(`./my-skill/`) runs the existing upload flow unchanged; a
+`@user/slug` ref toggles the publish flag via the API.
+
+To hide a published BotDoc again (e.g. you want to revise it without
+the in-progress version visible publicly):
+
+```bash
+botdocs unpublish @me/my-skill          # prompts to confirm
+botdocs unpublish @me/my-skill --yes    # skip the prompt (scripts/CI)
+botdocs unpublish @me/my-skill --json   # implies --yes, emits JSON
+```
+
+Unpublishing sets the `draft` flag back; the URL 404s for non-authors
+and the BotDoc disappears from `/explore`. It's idempotent — calling
+it on something already a draft is a no-op.
+
+To delete a BotDoc entirely:
+
+```bash
+botdocs delete @me/my-skill             # state-aware confirm prompt
+botdocs delete @me/my-skill --yes       # skip the prompt (scripts/CI)
+botdocs delete @me/my-skill --json      # implies --yes, emits JSON
+```
+
+`delete` behaves differently depending on what's there:
+
+- **Draft** → *hard delete*. The row and all children (files, version
+  history, bundle pins, team pins) are removed. The confirm prompt is a
+  single yes/no.
+- **Published** → *soft delete*. Sets `deletedAt`; the BotDoc disappears
+  from `/explore` and the public URL 404s, but version history is kept.
+  The confirm prompt requires typing the full ref (`@user/slug`) so a
+  fat-finger doesn't strand bookmarks at a 404.
+
+JSON output is `{ok, ref, mode}` where `mode` is `"hard"` or `"soft"`,
+mirroring the server's decision.
+
+### Zero-argument discovery mode
+
+Run `botdocs ingest` (no path) and the CLI scans your machine across
+every known on-disk location for the ten supported ecosystems:
+
+- `~/.claude/commands/` and `<repo>/.claude/commands/` (Claude Code)
+- `~/.claude/agents/**/AGENT.md` and `<repo>/.claude/agents/**/AGENT.md`
+  (Claude Code agents, multi-file)
+- `~/.claude/skills/**/SKILL.md` (Claude skills, nested by scope)
+- `<repo>/.cursor/rules/` (Cursor)
+- `<repo>/.codex/skills/` (Codex)
+- `<repo>/.github/instructions/` (GitHub Copilot)
+- `<repo>/.codeium/windsurf-rules/` (Windsurf)
+- `~/.gemini/instructions/` (Gemini CLI)
+- `~/.gemini/antigravity/skills/` (Antigravity)
+- `~/.config/opencode/instructions/` (OpenCode)
+
+Project-scoped scans (Cursor, Codex, Copilot, Windsurf, the project
+flavor of Claude Code) only run when the current directory is inside
+a git repo.
+
+A scan opens an interactive Ink TUI sectioned by ecosystem. Multi-file
+skills show their aggregate size + file count instead of per-file lines:
+
+```text
+BotDocs ingest
+Found 7 skills across 4 tools:
+
+  Claude Code:
+    [x] scx-pr-craft           2.1 KB · 67 lines
+    [x] pr-review-craft        1.8 KB · 54 lines
+    [ ] generic-test-cmd       0.1 KB · 4 lines    ← unchecked (< 100 bytes)
+
+  Claude skills:
+    [x] code-review            12.4 KB · 4 files    ← SKILL.md + 3 adjacent
+
+  Cursor rules:
+    [x] typescript-strict      0.8 KB · 25 lines
+
+  Gemini CLI:
+    [x] research-protocol      2.4 KB · 81 lines
+
+  ↑/↓ navigate · space toggle · a select all · n select none · enter confirm · q cancel
+```
+
+Useful flags:
+
+- `--auto` — skip the TUI and upload everything discovery finds
+  (with the < 100-byte stub filter applied).
+- `--dry-run` — list what discovery found in plain text; don't upload.
+- `--json` — emit the discovery as JSON; don't upload.
+- `--no-ink` — disable the TUI on TTYs (for screen readers or simple
+  terminals). Falls back to plain-text listing without uploading;
+  combine with `--auto` if you want one-shot ingestion.
+
+When the discovery returns nothing the CLI prints a hint pointing at
+`botdocs init` (to scaffold a new skill) or `botdocs ingest <dir>`
+(to ingest from a specific path).
+
 ## Development
 
 ```bash

package/dist/commands/delete.d.ts

@@ -0,0 +1,23 @@
+interface DeleteOptions {
+    yes?: boolean;
+    json?: boolean;
+}
+/**
+ * Delete a BotDoc by ref. Behavior split (decided server-side):
+ *
+ * - Draft → hard delete with cascade. The row and all children (files,
+ *   versions, version files, bundle pins, team pins) go away.
+ * - Published → soft delete (sets `deletedAt`). Hidden from /explore;
+ *   the public URL 404s; version history is preserved.
+ *
+ * Prompts unless `--yes` (or `--json`, which implies `--yes`). Draft
+ * deletes get a single yes/no confirm; published deletes require typing
+ * the ref exactly because the effect is visible to anyone who had the
+ * URL bookmarked. The CLI does a preflight GET to know which prompt to
+ * show before the user commits.
+ *
+ * Errors flow through the shared `handlePublishToggleError` so 401/403/
+ * 404 messages stay in sync with publish/unpublish.
+ */
+export declare function delete_(rawRef: string, options: DeleteOptions): Promise<void>;
+export {};

package/dist/commands/delete.js

@@ -0,0 +1,106 @@
+import * as p from '@clack/prompts';
+import { apiFetch } from '../lib/api.js';
+import { parseRef } from '../lib/ref.js';
+import { handlePublishToggleError } from './publish.js';
+/**
+ * Delete a BotDoc by ref. Behavior split (decided server-side):
+ *
+ * - Draft → hard delete with cascade. The row and all children (files,
+ *   versions, version files, bundle pins, team pins) go away.
+ * - Published → soft delete (sets `deletedAt`). Hidden from /explore;
+ *   the public URL 404s; version history is preserved.
+ *
+ * Prompts unless `--yes` (or `--json`, which implies `--yes`). Draft
+ * deletes get a single yes/no confirm; published deletes require typing
+ * the ref exactly because the effect is visible to anyone who had the
+ * URL bookmarked. The CLI does a preflight GET to know which prompt to
+ * show before the user commits.
+ *
+ * Errors flow through the shared `handlePublishToggleError` so 401/403/
+ * 404 messages stay in sync with publish/unpublish.
+ */
+export async function delete_(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}`;
+    // Preflight to determine state — we need to know draft vs published so
+    // we can show the right confirm prompt. Skip the network round-trip
+    // when prompts are disabled (`--yes`/`--json`): the server returns the
+    // resolved mode in the DELETE response anyway, and skipping the GET
+    // avoids a double-fail if the user has a stale token.
+    if (!options.yes && !options.json) {
+        let info;
+        try {
+            info = await apiFetch(`/api/botdocs/${username}/${slug}`, {
+                method: 'GET',
+                auth: true,
+            });
+        }
+        catch (err) {
+            handlePublishToggleError(err, refLabel, options);
+            return;
+        }
+        const confirmed = await promptConfirm(refLabel, info.isDraft);
+        if (!confirmed) {
+            console.log('  Cancelled.\n');
+            process.exit(1);
+        }
+    }
+    let result;
+    try {
+        result = await apiFetch(`/api/botdocs/${username}/${slug}`, {
+            method: 'DELETE',
+            auth: true,
+        });
+    }
+    catch (err) {
+        handlePublishToggleError(err, refLabel, options);
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, ref: refLabel, mode: result.mode }));
+        return;
+    }
+    if (result.mode === 'hard') {
+        console.log(`✓ Deleted draft ${refLabel}.`);
+    }
+    else {
+        console.log(`✓ Deleted ${refLabel} — hidden from /explore (version history preserved).`);
+    }
+}
+/**
+ * Show the appropriate confirm prompt for the BotDoc's state.
+ *
+ * Draft → simple yes/no confirm.
+ * Published → type-the-ref. We don't accept anything else — a fat-finger
+ * on a soft delete still strands public bookmarks at a 404.
+ *
+ * Returns `false` for any non-positive outcome (ctrl-C, no, wrong text).
+ */
+async function promptConfirm(refLabel, isDraft) {
+    if (isDraft) {
+        const confirmed = await p.confirm({
+            message: `Delete draft ${refLabel}? This can't be undone.`,
+            initialValue: false,
+        });
+        if (p.isCancel(confirmed))
+            return false;
+        return confirmed === true;
+    }
+    const typed = await p.text({
+        message: `Delete ${refLabel}? This hides it from /explore (version history is kept). ` +
+            `Bookmarks will 404. Confirm by typing the ref:`,
+        placeholder: refLabel,
+        validate: (v) => (v === refLabel ? undefined : `Must match ${refLabel} exactly`),
+    });
+    if (p.isCancel(typed))
+        return false;
+    return typed === refLabel;
+}

package/dist/commands/ingest.d.ts

@@ -2,8 +2,104 @@ interface IngestOptions {
     bundle?: string;
     dryRun?: boolean;
     json?: boolean;
+    /** Force every file in the path to belong to a single ecosystem, instead of
+     * relying on the canonical-layout auto-detect. Set via `--from-tool=<x>`. */
     fromTool?: string;
+    /** Skip the TUI and ingest everything discovery finds (with the default
+     * stub filter applied). Set via `--auto`. */
+    auto?: boolean;
+    /** Force the plain-text rendering path — disables the Ink TUI. Mirrors the
+     * `--no-ink` flag on `login` and `sync`. */
+    noInk?: boolean;
 }
+/** Per-file size cap. Any file larger than this is skipped with a warning. */
+export declare const PER_FILE_BYTE_CAP: number;
+/** Total bytes across all files in a single skill. */
+export declare const PER_SKILL_BYTE_CAP: number;
+/** Total file count in a single skill. */
+export declare const PER_SKILL_FILE_CAP = 25;
+export interface AdjacentSweepFile {
+    /** Absolute path on disk. */
+    absPath: string;
+    /** Path relative to the skill root, forward-slashed (`scripts/helper.sh`). */
+    relPath: string;
+    /** File contents (text). Binary files are skipped before this is read. */
+    content: string;
+    /** Low 9 bits of st_mode, captured before reading. */
+    mode: number;
+    /** Size in bytes. */
+    sizeBytes: number;
+}
+export interface AdjacentSweepWarning {
+    relPath: string;
+    reason: 'binary' | 'oversize' | 'cap-total-size' | 'cap-file-count';
+}
+export interface AdjacentSweepResult {
+    files: AdjacentSweepFile[];
+    warnings: AdjacentSweepWarning[];
+}
+/**
+ * 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 declare function sweepSkillRoot(skillRoot: string, rootFileAbs: string): AdjacentSweepResult;
+/** 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 declare function formatSweepWarnings(slug: string, warnings: AdjacentSweepWarning[]): string;
+export interface EcosystemDetector {
+    /** Path prefix the file's root-relative path must start with for auto-detect mode. */
+    pathPrefix: string;
+    /** Extension suffixes the filename must match. Tested via endsWith. */
+    extensions: string[];
+    /** Whether this ecosystem uses a nested SKILL.md layout (claude) vs flat.
+     * Discovery uses this to decide whether to recurse the scan directories. */
+    nested: boolean;
+    /**
+     * Given an absolute file path and the source root, return the slug or null
+     * if the file doesn't match this ecosystem's layout (e.g. wrong nesting).
+     */
+    slugFor: (absPath: string, root: string) => string | null;
+    /** Canonical filename inside a BotDoc directory, given the slug. */
+    canonicalFilename: (slug: string) => string;
+    /**
+     * Absolute directories to scan during zero-arg discovery mode. Receives the
+     * user's home dir, the current project root (cwd), and whether the project
+     * root is inside a git repo. Project-scoped paths should return `[]` when
+     * `isGitRepo` is false. Return `[]` for ecosystems that have no canonical
+     * on-disk location (e.g. chatgpt — manual-paste only).
+     */
+    scanPaths: (homeDir: string, projectRoot: string, isGitRepo: boolean) => string[];
+    /**
+     * When true, ingest sweeps the skill directory and uploads adjacent files
+     * (scripts/, templates/, etc.) alongside the root file. Today this is only
+     * meaningful for `claude` and `claude-code-agents` — flat-file ecosystems
+     * leave it false. `claude-code` (commands) keeps it as `true` for forward-
+     * compat but is a no-op since commands have no enclosing directory.
+     */
+    includeAdjacent?: boolean;
+    /**
+     * Given the absolute path to a matched root file, return the directory that
+     * counts as the "skill root" — everything below it is eligible for the
+     * adjacent-file sweep. For nested ecosystems this is the parent dir of the
+     * root file. Only invoked when `includeAdjacent` is true.
+     */
+    skillRoot?: (absPath: string) => string;
+    /**
+     * Build the canonical filename for an adjacent file given its skill slug
+     * and the path relative to the skill root (e.g. `scripts/helper.sh`). Only
+     * invoked when `includeAdjacent` is true.
+     */
+    canonicalAdjacentFilename?: (slug: string, relPath: string) => string;
+}
+/**
+ * Single source of truth for ecosystem detection. New ecosystems should be
+ * added here — both auto-detect mode and future `--from-tool` mode consult
+ * this table.
+ */
+export declare const DETECTORS: Record<string, EcosystemDetector>;
 export declare const SUPPORTED_TOOLS: readonly string[];
-export declare function ingest(rootPath: string, options: IngestOptions): Promise<void>;
+export declare function ingest(rootPath: string | undefined, options: IngestOptions): Promise<void>;
 export {};