@prave/cli 1.2.2 → 1.4.0

package/dist/commands/deploy.js

@@ -3,7 +3,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import chalk from 'chalk';
 import ora from 'ora';
-import { AGENT_REGISTRY } from '@prave/shared';
+import { AGENT_REGISTRY, compileSkill } from '@prave/shared';
 import { track } from '../lib/analytics.js';
 import { api, ApiError } from '../lib/api.js';
 import { requireAuth } from '../lib/credentials.js';
@@ -41,34 +41,30 @@ async function fetchRemoteSkill(slug) {
     }
     return data.content;
 }
-function describeContentForCursor(content, slug) {
-    // Has frontmatter? best-effort rename triggers: → globs:
-    const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?/);
-    if (fmMatch && fmMatch[1] !== undefined) {
-        const body = content.slice(fmMatch[0].length);
-        const fmInner = fmMatch[1].replace(/(^|\n)triggers:/g, '$1globs:');
-        return `---\n${fmInner}\n---\n${body}`;
-    }
-    // No frontmatter — synthesize
-    const trimmed = content.trim().replace(/\s+/g, ' ').slice(0, 200);
-    return `---\nname: ${slug}\ndescription: ${trimmed}\n---\n${content}`;
-}
-function buildDestPath(agent, basePath, os, slug) {
+/**
+ * Build the on-disk write path for the given agent + slug. The
+ * `compileSkill()` import from `@prave/shared` decides the *content*
+ * transform (e.g. Cursor `.mdc` frontmatter rewrite); this function
+ * only resolves the absolute filesystem location by combining the
+ * agent's `basePath` from user settings with the relative path the
+ * shared compiler returned.
+ */
+function buildDestPath(agent, basePath, os, slug, relPath) {
     const expanded = expandHome(basePath, os);
-    if (agent === 'cursor') {
-        // .cursor/rules/<slug>.mdc — the basePath already points at .cursor/rules
-        return {
-            dir: expanded,
-            file: join(expanded, `${slug}.mdc`),
-            converted: true,
-            display: `${basePath.replace(/[\\/]+$/, '')}/${slug}.mdc`,
-        };
-    }
+    // The shared compiler returns POSIX-style relPaths
+    // (e.g. `<slug>/SKILL.md` or `.cursor/rules/<slug>.mdc`). For
+    // Cursor specifically the user's `basePath` already points at
+    // `.cursor/rules/`, so we collapse the leading `.cursor/rules/`
+    // to avoid the path duplicating to `.cursor/rules/.cursor/rules/`.
+    const collapsed = agent === 'cursor' && relPath.startsWith('.cursor/rules/')
+        ? relPath.slice('.cursor/rules/'.length)
+        : relPath;
+    const file = join(expanded, ...collapsed.split('/'));
+    const dir = file.slice(0, file.length - collapsed.split('/').slice(-1)[0].length - 1);
     return {
-        dir: join(expanded, slug),
-        file: join(expanded, slug, 'SKILL.md'),
-        converted: false,
-        display: `${basePath.replace(/[\\/]+$/, '')}/${slug}/SKILL.md`,
+        dir,
+        file,
+        display: `${basePath.replace(/[\\/]+$/, '')}/${collapsed}`,
     };
 }
 export async function deployCommand(skillName, opts = {}) {
@@ -146,10 +142,12 @@ export async function deployCommand(skillName, opts = {}) {
         const meta = AGENT_REGISTRY[agent];
         const paths = settings.skill_paths[agent] ?? meta.defaultPath;
         const basePath = os === 'windows' ? paths.windows : paths.mac;
-        const dest = buildDestPath(agent, basePath, os, skillName);
-        const content = dest.converted
-            ? describeContentForCursor(source, skillName)
-            : source;
+        // Shared compileSkill() is the single source of truth — same
+        // function the SaaS /dashboard/compile page calls, so the CLI
+        // and the web zip produce byte-identical output for the same
+        // SKILL.md.
+        const artifact = compileSkill(source, skillName, agent);
+        const dest = buildDestPath(agent, basePath, os, skillName, artifact.path);
         spinner.text = `→ ${meta.label}`;
         if (opts.dryRun) {
             okCount += 1;
@@ -157,7 +155,7 @@ export async function deployCommand(skillName, opts = {}) {
         }
         try {
             await mkdir(dest.dir, { recursive: true });
-            await writeFile(dest.file, content, 'utf8');
+            await writeFile(dest.file, artifact.content, 'utf8');
             okCount += 1;
         }
         catch (err) {
@@ -169,8 +167,9 @@ export async function deployCommand(skillName, opts = {}) {
         const meta = AGENT_REGISTRY[agent];
         const paths = settings.skill_paths[agent] ?? meta.defaultPath;
         const basePath = os === 'windows' ? paths.windows : paths.mac;
-        const dest = buildDestPath(agent, basePath, os, skillName);
-        const tag = dest.converted ? chalk.dim(' (converted)') : '';
+        const artifact = compileSkill(source, skillName, agent);
+        const dest = buildDestPath(agent, basePath, os, skillName, artifact.path);
+        const tag = artifact.converted ? chalk.dim(' (converted)') : '';
         console.log(`${chalk.green('✓')} ${meta.label.padEnd(14)} → ${dest.display}${tag}`);
     }
     const elapsed = ((Date.now() - start) / 1000).toFixed(1);

package/dist/commands/docs.js

@@ -0,0 +1,32 @@
+import chalk from 'chalk';
+import open from 'open';
+import { CONFIG } from '../lib/config.js';
+/**
+ * `prave docs [slug]` — open the docs in the user's browser.
+ *
+ * No `slug` → opens https://prave.app/docs
+ * Slug given → opens https://prave.app/docs/<slug>
+ *
+ * No auth needed — the docs are public. The command exists purely so
+ * users don't have to alt-tab to a browser, type a URL, and hunt for
+ * the right section. From the terminal:
+ *
+ *   prave docs              # docs home
+ *   prave docs cli/run      # the Runs CLI reference
+ *   prave docs web/runs     # the Runs dashboard guide
+ *   prave docs pricing      # the plans page
+ */
+export async function docsCommand(slug) {
+    const cleaned = (slug ?? '').replace(/^\/+|\/+$/g, '').trim();
+    // CONFIG.webUrl points at the SPA host (https://prave.app in prod,
+    // http://localhost:5173 in dev). Docs always live under /docs.
+    const base = CONFIG.webUrl?.replace(/\/$/, '') ?? 'https://prave.app';
+    const url = cleaned ? `${base}/docs/${cleaned}` : `${base}/docs`;
+    console.log(`${chalk.dim('Opening')} ${chalk.cyan(url)}`);
+    try {
+        await open(url);
+    }
+    catch {
+        console.log(chalk.dim('(your browser did not open — copy the URL above)'));
+    }
+}

package/dist/commands/mcp-install.js

@@ -0,0 +1,197 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile, stat } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import chalk from 'chalk';
+import { track } from '../lib/analytics.js';
+import { log } from '../utils/logger.js';
+const ENTRY_NPX = {
+    command: 'npx',
+    args: ['-y', '@prave/cli', 'mcp-server'],
+};
+const ENTRY_GLOBAL = {
+    command: 'prave',
+    args: ['mcp-server'],
+};
+export async function mcpInstallCommand() {
+    track('cli_mcp_install');
+    const target = resolveClaudeDesktopConfigPath();
+    if (!target) {
+        log.error(`This OS (${platform()}) isn't supported by Claude Desktop yet. Use the manual JSON snippet from /dashboard/settings/mcp instead.`);
+        process.exitCode = 1;
+        return;
+    }
+    // Prefer the global `prave` binary when it's on PATH — it's faster
+    // (no npx resolution at every Claude Desktop launch), version-pinned
+    // by the user (no surprise updates mid-session), and the config
+    // entry is two tokens shorter. Fall back to the npx form when the
+    // user is on a one-shot `npx @prave/cli mcp install` path.
+    const hasGlobalPrave = await detectGlobalPrave();
+    const PRAVE_ENTRY = hasGlobalPrave ? ENTRY_GLOBAL : ENTRY_NPX;
+    // Read existing config, tolerate the "file doesn't exist yet" case
+    // — Claude Desktop creates the file on first launch, but users often
+    // run our setup BEFORE opening the app for the first time.
+    let existing = {};
+    let fileExisted = false;
+    try {
+        const raw = await readFile(target, 'utf8');
+        fileExisted = true;
+        try {
+            existing = JSON.parse(raw);
+        }
+        catch (err) {
+            log.error(`Couldn't parse ${target} as JSON (${err.message}). Fix it manually or delete it and re-run.`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            log.error(`Couldn't read ${target}: ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // Idempotency check — if a `prave` entry with our exact command +
+    // args already exists, don't churn the file.
+    const current = existing.mcpServers?.prave;
+    if (current &&
+        current.command === PRAVE_ENTRY.command &&
+        JSON.stringify(current.args ?? []) === JSON.stringify(PRAVE_ENTRY.args ?? [])) {
+        log.success('Prave MCP server is already wired into Claude Desktop.');
+        log.dim(`Config: ${target}`);
+        log.dim('Restart Claude Desktop if you haven\'t since the last edit.');
+        return;
+    }
+    // Backup before mutating. Only when the file existed — there's
+    // nothing to back up otherwise.
+    if (fileExisted) {
+        try {
+            const raw = await readFile(target, 'utf8');
+            await writeFile(`${target}.bak`, raw, 'utf8');
+        }
+        catch (err) {
+            log.warn(`Couldn't write ${target}.bak — proceeding anyway: ${err.message}`);
+        }
+    }
+    // Merge our entry, preserving everything else (including any other
+    // MCP servers the user has configured).
+    const nextConfig = {
+        ...existing,
+        mcpServers: {
+            ...(existing.mcpServers ?? {}),
+            prave: PRAVE_ENTRY,
+        },
+    };
+    try {
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, JSON.stringify(nextConfig, null, 2) + '\n', 'utf8');
+    }
+    catch (err) {
+        log.error(`Couldn't write ${target}: ${err.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    log.success('Prave MCP server installed for Claude Desktop.');
+    console.log();
+    console.log(`  ${chalk.dim('Config:')}  ${target}`);
+    if (fileExisted) {
+        console.log(`  ${chalk.dim('Backup:')}  ${target}.bak`);
+    }
+    else {
+        console.log(`  ${chalk.dim('Note:')}    New config file created.`);
+    }
+    console.log(`  ${chalk.dim('Mode:')}    ${hasGlobalPrave
+        ? 'global `prave` binary (fast, no npx hop)'
+        : 'npx (no global install needed)'}`);
+    console.log();
+    log.info('Next:');
+    log.dim('  1. Restart Claude Desktop.');
+    log.dim('  2. Prave\'s tools appear in the MCP panel.');
+    log.dim('  3. Try: "Find me a skill for React testing".');
+    if (!hasGlobalPrave) {
+        console.log();
+        log.dim(`Tip: ${chalk.bold('npm i -g @prave/cli')} once, and Claude Desktop boots Prave a second faster (no npx resolution).`);
+    }
+    // Ping the heartbeat so the SaaS Settings → MCP card shows
+    // "Connection wired" even before the user fires the first real
+    // tool call. Best-effort; failure swallowed.
+    void pingHeartbeatBestEffort();
+}
+/* ─── internals ─────────────────────────────────────────────────── */
+function resolveClaudeDesktopConfigPath() {
+    const home = homedir();
+    switch (platform()) {
+        case 'darwin':
+            return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+        case 'win32': {
+            const appData = process.env.APPDATA;
+            if (!appData)
+                return null;
+            return join(appData, 'Claude', 'claude_desktop_config.json');
+        }
+        case 'linux':
+            return join(home, '.config', 'Claude', 'claude_desktop_config.json');
+        default:
+            return null;
+    }
+}
+async function pingHeartbeatBestEffort() {
+    try {
+        const { api } = await import('../lib/api.js');
+        await api.post('/api/v1/me/mcp-heartbeat', {}, true);
+    }
+    catch {
+        // No creds yet, or API unreachable — fine. The first real tool
+        // call from Claude Desktop will set the heartbeat anyway.
+    }
+}
+/**
+ * Is the `prave` binary globally installed and on PATH?
+ *
+ * Uses `which` (POSIX) / `where` (Windows) to probe. Returns true only
+ * when the resolved path is NOT inside an npx temp directory — that
+ * way running this command via `npx @prave/cli mcp install` doesn't
+ * fool the detector into thinking the user has a permanent install
+ * (the resolved binary in that case is in `~/.npm/_npx/...`).
+ *
+ * Timeout: 1s. If `which` hangs (shouldn't ever, but networked
+ * filesystems are weird), we fall back to the npx form. Worst case
+ * is one extra npx hop per Claude Desktop launch — not a correctness
+ * issue.
+ */
+async function detectGlobalPrave() {
+    return new Promise((resolve) => {
+        const cmd = platform() === 'win32' ? 'where' : 'which';
+        const child = spawn(cmd, ['prave'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        let output = '';
+        const timer = setTimeout(() => {
+            child.kill();
+            resolve(false);
+        }, 1_000);
+        child.stdout?.on('data', (chunk) => {
+            output += chunk.toString('utf8');
+        });
+        child.on('error', () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (code !== 0 || !output.trim()) {
+                resolve(false);
+                return;
+            }
+            // Filter out npx-temp paths so an in-flight `npx @prave/cli` run
+            // doesn't get mistaken for a global install.
+            const firstLine = output.split('\n')[0]?.trim() ?? '';
+            const looksLikeNpxTemp = /[/\\](_npx|\.npm[/\\]_npx|npm-cache[/\\]_npx)[/\\]/i.test(firstLine);
+            resolve(!looksLikeNpxTemp);
+        });
+    });
+}
+// Silences the unused-import lint when no other branch reads `stat`.
+// The function is kept here intentionally for future expansion (e.g.
+// staleness check on `.bak` files) without re-adding the import.
+void stat;

package/dist/commands/mcp-server.js

@@ -0,0 +1,211 @@
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { api, ApiError } from '../lib/api.js';
+import { loadCredentials } from '../lib/credentials.js';
+const TOOLS = [
+    {
+        name: 'prave_search_skills',
+        description: 'Search the public Prave catalogue of Claude Skills. Returns up to 20 results. Use this when the user is exploring which Skill to install, or asking what Skills exist for a domain.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Keyword or phrase to search. Searches name + description + tags.',
+                },
+                category: {
+                    type: 'string',
+                    description: 'Optional category filter (e.g. "testing", "design", "deployment"). See the Discover page for the full list.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 20,
+                    default: 10,
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'prave_whatdoes',
+        description: 'Look up one Skill by slug. Returns the canonical name, description, tags, install count, and rating. Useful as a confirmation step before `prave_install_skill`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: { type: 'string', description: 'Skill slug, e.g. "vercel-labs-agent-skills-react-best-practices".' },
+            },
+            required: ['slug'],
+        },
+    },
+    {
+        name: 'prave_my_skills',
+        description: 'List Skills the signed-in user has installed locally or authored. Useful when the user asks "what Skills do I already have?".',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'prave_audit_library',
+        description: 'Return the Skill Intelligence overview for the signed-in user: total Skill count, library token footprint, trigger count over the last 30 days, conflicts detected, and the 5 token-heaviest Skills. Use this when the user asks about token cost, performance, or which Skills to trim.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'prave_install_skill',
+        description: 'Install a Skill from the catalogue into the user\'s local agent directory (~/.claude/skills/). Spawns the `prave install <slug>` CLI subprocess and streams its output back. Use only after confirming the slug with `prave_whatdoes`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: { type: 'string', description: 'Skill slug to install.' },
+            },
+            required: ['slug'],
+        },
+    },
+];
+export async function mcpServerCommand() {
+    // Auth check up-front. If the user runs `prave mcp-server` without
+    // logging in, the MCP frame would otherwise look healthy but every
+    // tool call would fail with 401 — confusing. Emit a clear stderr
+    // message and exit, so Claude Desktop's MCP UI surfaces a bad-config
+    // error instead of letting the user wonder.
+    const creds = await loadCredentials();
+    if (!creds) {
+        process.stderr.write('prave mcp-server: not logged in. Run `prave login` first.\n');
+        process.exit(1);
+    }
+    const server = new Server({ name: 'prave-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args = {} } = req.params;
+        // Best-effort heartbeat — every successful tool call pings the
+        // server so the Settings → MCP card knows the user is wired in.
+        // Fired-and-forgotten; failures don't break the tool response.
+        void pingHeartbeat();
+        try {
+            switch (name) {
+                case 'prave_search_skills':
+                    return await handleSearch(args);
+                case 'prave_whatdoes':
+                    return await handleWhatdoes(args);
+                case 'prave_my_skills':
+                    return await handleMySkills();
+                case 'prave_audit_library':
+                    return await handleAuditLibrary();
+                case 'prave_install_skill':
+                    return await handleInstallSkill(args);
+                default:
+                    return mcpError(`Unknown tool: ${name}`);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof ApiError ? err.message : err.message;
+            return mcpError(msg);
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Block forever — the transport keeps the event loop alive while
+    // stdio is open. Process exits cleanly when the parent (Claude
+    // Desktop) closes the pipe.
+}
+/* ─── tool handlers ────────────────────────────────────────────── */
+async function handleSearch(args) {
+    const params = new URLSearchParams();
+    params.set('q', args.query);
+    if (args.category)
+        params.set('category', args.category);
+    params.set('limit', String(Math.min(20, Math.max(1, args.limit ?? 10))));
+    const { data } = await api.get(`/api/v1/skills?${params.toString()}`, true);
+    const items = data.items ?? [];
+    const lines = items.map((s) => `• ${s.name} (${s.slug}) — ${s.description ?? 'no description'} · ↓${s.install_count}`);
+    return mcpText(lines.length
+        ? `Found ${lines.length} Skill${lines.length === 1 ? '' : 's'}:\n\n${lines.join('\n')}`
+        : `No Skills matched "${args.query}".`);
+}
+async function handleWhatdoes(args) {
+    const { data } = await api.get(`/api/v1/skills/${encodeURIComponent(args.slug)}`, true);
+    return mcpText([
+        `${data.name} (${data.slug})`,
+        data.description ?? '(no description)',
+        '',
+        `Tags: ${data.tags.length ? data.tags.join(', ') : '(none)'}`,
+        `Installs: ${data.install_count}`,
+        data.rating != null ? `Rating: ${data.rating.toFixed(1)}/5` : '',
+    ]
+        .filter(Boolean)
+        .join('\n'));
+}
+async function handleMySkills() {
+    const { data } = await api.get('/api/v1/me/skills', true);
+    const items = data.items ?? [];
+    if (items.length === 0) {
+        return mcpText('You haven\'t installed or authored any Skills yet. Try `prave_search_skills` to browse the catalogue.');
+    }
+    const lines = items.map((s) => `• ${s.name} (${s.slug})`);
+    return mcpText(`You have ${items.length} Skill${items.length === 1 ? '' : 's'}:\n\n${lines.join('\n')}`);
+}
+async function handleAuditLibrary() {
+    const { data } = await api.get('/api/v1/intelligence/overview', true);
+    const heaviestLines = data.heaviest
+        .slice(0, 5)
+        .map((s) => `  • ${s.name ?? s.slug ?? '(unnamed)'} — ${s.estimated_tokens.toLocaleString()} tokens`);
+    return mcpText([
+        `Skill Intelligence overview`,
+        ``,
+        `Total Skills indexed: ${data.total_skills}`,
+        `Library token footprint: ${data.total_estimated_tokens.toLocaleString()} tokens`,
+        `Triggered in last 30 days: ${data.triggered_30d}`,
+        `Conflicts detected: ${data.conflict_count}`,
+        ``,
+        `Top 5 token-heaviest:`,
+        ...(heaviestLines.length ? heaviestLines : ['  (none indexed yet — run `prave sync`)']),
+    ].join('\n'));
+}
+async function handleInstallSkill(args) {
+    // Run the existing CLI install command as a subprocess. Identical
+    // behavior to a user typing `prave install <slug>` — same plan
+    // checks, same dependency resolution, same on-disk effects. Tail
+    // the output for the MCP response.
+    return await new Promise((resolve) => {
+        const child = spawn(process.argv[0] ?? 'node', [process.argv[1] ?? '', 'install', args.slug], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => {
+            resolve(mcpError(`Failed to spawn install: ${err.message}`));
+        });
+        child.on('close', (code) => {
+            const output = (stdout + (stderr ? `\n${stderr}` : '')).trim() ||
+                (code === 0 ? `Installed ${args.slug}.` : `Install exited with code ${code}.`);
+            resolve(code === 0
+                ? mcpText(output)
+                : mcpError(output));
+        });
+    });
+}
+/* ─── helpers ──────────────────────────────────────────────────── */
+function mcpText(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function mcpError(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+async function pingHeartbeat() {
+    try {
+        await api.post('/api/v1/me/mcp-heartbeat', {}, true);
+    }
+    catch {
+        // Heartbeat is fire-and-forget. The MCP tool still works even
+        // when the heartbeat endpoint is unreachable (e.g. brief API
+        // outage); the SaaS Settings card just won't update its
+        // last-seen timestamp.
+    }
+}

package/dist/commands/run.js

@@ -0,0 +1,301 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { resolve, relative, basename, sep } from 'node:path';
+import { Buffer } from 'node:buffer';
+import chalk from 'chalk';
+import open from 'open';
+import ora from 'ora';
+import * as tar from 'tar';
+import { request } from 'undici';
+import { isLikelyTextPath, scanForSecrets, } from '@prave/shared';
+import { api, ApiError } from '../lib/api.js';
+import { CONFIG } from '../lib/config.js';
+import { loadCredentials, requireAuth } from '../lib/credentials.js';
+import { log } from '../utils/logger.js';
+/**
+ * `prave run` — scheduled server-side skill executions on Prave's
+ * infrastructure.
+ *
+ *   prave run deploy [path]       # bundle dir → upload → open wizard
+ *   prave run list                # list my deployed runs
+ *   prave run logs <slug>         # tail the most recent execution logs
+ *
+ * `deploy` is the headline action — the rest just expose the same data
+ * the dashboard already shows. The wizard handles schedule + agent
+ * selection in the browser because picking from an agent dropdown
+ * filtered to "which API keys do I have" is way clearer in a UI than
+ * an interactive prompt.
+ */
+// Sane-default ignore list for `tar.create` — none of these belong in
+// a deployable bundle and dragging them up adds noise to the scan +
+// bloats storage.
+const TAR_IGNORE = new Set([
+    '.git',
+    '.github',
+    '.next',
+    '.turbo',
+    '.svelte-kit',
+    '.cache',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.venv',
+    'venv',
+    '__pycache__',
+    '.DS_Store',
+]);
+const MAX_BUNDLE_BYTES = 20 * 1024 * 1024; // matches API + Supabase Storage cap
+const MAX_FILES = 200;
+export async function runDeployCommand(pathArg) {
+    const root = resolve(pathArg ?? process.cwd());
+    const rootStat = await stat(root).catch(() => null);
+    if (!rootStat?.isDirectory()) {
+        log.error(`Not a directory: ${root}`);
+        process.exit(1);
+    }
+    // Sanity check — the dir should *look* like a skill project. We don't
+    // hard-reject; we just warn if there's no SKILL.md anywhere.
+    const skillMd = await findSkillMd(root);
+    if (!skillMd) {
+        log.warn('No SKILL.md found in this directory. Deploys still work without it, but the runner will not have skill-shaped context for the agent.');
+    }
+    const creds0 = await requireAuth('prave run');
+    if (!creds0)
+        return;
+    // 1. Local secret-scan BEFORE we ship anything. Cheap defence in
+    // depth — even though the API scans again, surfacing the finding
+    // pre-upload saves the user a round-trip and avoids briefly storing
+    // a secret-bearing tarball in our bucket.
+    const localFindings = await preflightScan(root);
+    if (localFindings.length > 0) {
+        log.error('Bundle contains files that look like secrets:');
+        for (const f of localFindings.slice(0, 10)) {
+            console.error(`  ${chalk.red('•')} ${f.rule}  ${chalk.dim(f.path)}${f.line ? `:${f.line}` : ''}`);
+        }
+        console.error(chalk.dim('\nRemove these files (or scrub the values) and re-run.\n' +
+            'For env vars, ship a .env.example template instead — Prave\n' +
+            'will prompt you for the real values during the wizard.'));
+        process.exit(1);
+    }
+    // 2. Mint the deploy session
+    const initSpinner = ora('Opening deploy session…').start();
+    let session;
+    try {
+        const { data } = await api.post('/api/v1/deploy/init', {}, true);
+        session = data.session;
+        initSpinner.succeed('Session opened');
+    }
+    catch (err) {
+        initSpinner.fail(`Could not open deploy session: ${err.message}`);
+        process.exit(1);
+    }
+    // 3. Pack the directory into a gzipped tar in memory. tar.create's
+    // `cwd` option is critical — paths inside the archive must be
+    // RELATIVE to the project root, not absolute.
+    const packSpinner = ora('Bundling project…').start();
+    let tarball;
+    try {
+        tarball = await packDirectory(root);
+        packSpinner.succeed(`Bundled ${formatBytes(tarball.length)}`);
+    }
+    catch (err) {
+        packSpinner.fail(`Bundle failed: ${err.message}`);
+        process.exit(1);
+    }
+    if (tarball.length > MAX_BUNDLE_BYTES) {
+        log.error(`Bundle is ${formatBytes(tarball.length)}, cap is ${formatBytes(MAX_BUNDLE_BYTES)}. ` +
+            'Add large files to .gitignore-style noise (or place them in node_modules / .git which we already skip).');
+        process.exit(1);
+    }
+    // 4. Stream the tarball to /deploy/upload. We use undici directly
+    // because api.ts only does JSON.
+    const uploadSpinner = ora('Uploading to Prave…').start();
+    const creds = await loadCredentials();
+    if (!creds) {
+        uploadSpinner.fail('Credentials expired mid-flight — please re-login.');
+        process.exit(1);
+    }
+    const uploadUrl = `${CONFIG.apiUrl}/api/v1/deploy/upload?session=${encodeURIComponent(session.session_id)}`;
+    try {
+        const { statusCode, body } = await request(uploadUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/gzip',
+                Authorization: `Bearer ${creds.access_token}`,
+            },
+            body: tarball,
+        });
+        const text = await body.text();
+        if (statusCode >= 400) {
+            const parsed = safeJson(text);
+            const msg = parsed?.error ?? `HTTP ${statusCode}`;
+            uploadSpinner.fail(`Upload rejected: ${msg}`);
+            process.exit(1);
+        }
+        uploadSpinner.succeed('Upload complete');
+    }
+    catch (err) {
+        uploadSpinner.fail(`Upload failed: ${err.message}`);
+        process.exit(1);
+    }
+    // 5. Open the browser at the wizard
+    console.log();
+    console.log(chalk.bold('Finish in the browser:'));
+    console.log(chalk.cyan('  ' + session.wizard_url));
+    try {
+        await open(session.wizard_url);
+    }
+    catch {
+        /* user can copy the URL manually */
+    }
+}
+export async function runListCommand() {
+    if (!(await requireAuth('prave run list')))
+        return;
+    const spinner = ora('Fetching runs…').start();
+    try {
+        const { data } = await api.get('/api/v1/runs', true);
+        spinner.stop();
+        if (!data.runs.length) {
+            console.log(chalk.dim('No runs yet. `prave run deploy` to schedule your first one.'));
+            return;
+        }
+        for (const r of data.runs) {
+            const nextRun = r.next_run_at
+                ? new Date(r.next_run_at).toLocaleString()
+                : chalk.dim('paused');
+            const status = r.status === 'active'
+                ? chalk.green('active')
+                : r.status === 'paused'
+                    ? chalk.yellow('paused')
+                    : chalk.red(r.status);
+            console.log(`  ${chalk.bold(r.name)}  ${chalk.dim(r.slug)}\n` +
+                `    ${chalk.dim(`agent=${r.agent}  schedule=${r.schedule_kind}  status=${status}  next=${nextRun}`)}`);
+        }
+    }
+    catch (err) {
+        spinner.fail(err.message);
+        process.exit(err instanceof ApiError ? 1 : 1);
+    }
+}
+export async function runLogsCommand(slug) {
+    if (!(await requireAuth('prave run logs')))
+        return;
+    const spinner = ora(`Fetching logs for ${slug}…`).start();
+    try {
+        const { data } = await api.get(`/api/v1/runs/${encodeURIComponent(slug)}/executions?limit=10`, true);
+        spinner.stop();
+        if (!data.executions.length) {
+            console.log(chalk.dim('No executions yet. The first one will appear after the next scheduled fire.'));
+            return;
+        }
+        const latest = data.executions[0];
+        const status = latest.status === 'success'
+            ? chalk.green(latest.status)
+            : latest.status === 'running'
+                ? chalk.cyan(latest.status)
+                : chalk.red(latest.status);
+        console.log(`${chalk.bold(slug)}  ${chalk.dim(latest.started_at)}  ${status}` +
+            (latest.duration_ms !== null ? chalk.dim(`  (${latest.duration_ms}ms)`) : ''));
+        console.log();
+        console.log(latest.log_text ?? chalk.dim('(no log captured)'));
+        if (latest.error_message) {
+            console.log();
+            console.log(chalk.red('Error: ') + latest.error_message);
+        }
+    }
+    catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+// ── helpers ──────────────────────────────────────────────────────────
+async function findSkillMd(root) {
+    // Top-level only — most skill projects ship SKILL.md at the root.
+    // Deeper search would be wasted work for the warning we'd print.
+    try {
+        const entries = await readdir(root);
+        return entries.find((n) => n.toLowerCase() === 'skill.md') ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function preflightScan(root) {
+    const inputs = [];
+    let files = 0;
+    let bytes = 0;
+    const visit = async (dir) => {
+        if (files >= MAX_FILES)
+            return;
+        if (bytes >= MAX_BUNDLE_BYTES)
+            return;
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (TAR_IGNORE.has(entry.name))
+                continue;
+            if (entry.name.startsWith('._'))
+                continue;
+            const abs = `${dir}${sep}${entry.name}`;
+            if (entry.isDirectory()) {
+                await visit(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            files++;
+            const rel = relative(root, abs).split(sep).join('/');
+            if (!isLikelyTextPath(rel)) {
+                inputs.push({ path: rel });
+                continue;
+            }
+            try {
+                const content = await readFile(abs, 'utf8');
+                bytes += content.length;
+                inputs.push({ path: rel, content });
+            }
+            catch {
+                inputs.push({ path: rel });
+            }
+        }
+    };
+    await visit(root);
+    return scanForSecrets(inputs).findings;
+}
+async function packDirectory(root) {
+    // Top-level entries only — tar.create resolves them against `cwd`.
+    const entries = (await readdir(root)).filter((n) => !TAR_IGNORE.has(n));
+    if (entries.length === 0) {
+        throw new Error('Project directory is empty.');
+    }
+    const stream = tar.create({
+        gzip: true,
+        cwd: root,
+        portable: true,
+        // Prefix all paths with the project's basename so the runner
+        // gets a `<project>/SKILL.md` shape, not a flat dump at the
+        // archive root.
+        prefix: basename(root),
+        filter: (_path) => true,
+    }, entries);
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n}B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)}KB`;
+    return `${(n / 1024 / 1024).toFixed(2)}MB`;
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.js

@@ -6,14 +6,18 @@ import { Command } from 'commander';
 import { conflictsCommand } from './commands/conflicts.js';
 import { deployCommand } from './commands/deploy.js';
 import { diffCommand } from './commands/diff.js';
+import { docsCommand } from './commands/docs.js';
 import { exportCommand } from './commands/export.js';
 import { importCommand } from './commands/import.js';
 import { installCommand } from './commands/install.js';
 import { listCommand } from './commands/list.js';
 import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
+import { mcpInstallCommand } from './commands/mcp-install.js';
+import { mcpServerCommand } from './commands/mcp-server.js';
 import { optimizeCommand } from './commands/optimize.js';
 import { overviewCommand } from './commands/overview.js';
+import { runDeployCommand, runListCommand, runLogsCommand, } from './commands/run.js';
 import { searchCommand } from './commands/search.js';
 import { settingsCommand } from './commands/settings.js';
 import { syncCommand } from './commands/sync.js';
@@ -161,6 +165,35 @@ program
     .option('--agent <agent>', 'restrict deploy to a single agent (claude-code | codex | cursor | gemini | cline | amp)')
     .option('--dry-run', 'log every destination path but write nothing — preview before committing')
     .action(deployCommand);
+program
+    .command('mcp-server')
+    .description('Run the Prave MCP server over stdio. Wire into Claude Desktop / Cursor MCP / Continue.dev via { "command": "npx", "args": ["-y", "@prave/cli", "mcp-server"] }. Exposes search, install, audit, my-skills, whatdoes as MCP tools.')
+    .action(mcpServerCommand);
+program
+    .command('docs [slug]')
+    .description('Open the docs in your browser. Bare `prave docs` lands on the home page; `prave docs cli/run` or `prave docs web/runs` jumps straight to a section.')
+    .action((slug) => docsCommand(slug));
+// ─── prave run — scheduled server-side executions (Runs) ──────────
+const run = program
+    .command('run')
+    .description('Schedule a skill to fire on a cron, executed by your chosen AI agent on Prave\'s sandbox. Bring the whole project — SKILL.md, scripts, .env.');
+run
+    .command('deploy [path]')
+    .description('Bundle the current directory (or `path`), upload it to Prave, and open the browser wizard to pick the schedule + agent.')
+    .action((path) => runDeployCommand(path));
+run
+    .command('list')
+    .description('List your scheduled runs with next-fire time + last status.')
+    .action(runListCommand);
+run
+    .command('logs <slug>')
+    .description('Print the latest execution log for a scheduled run.')
+    .action(runLogsCommand);
+program
+    .command('mcp install')
+    .alias('mcp-install')
+    .description('One-command setup: patches Claude Desktop\'s config to wire the Prave MCP server. Idempotent, takes a `.bak` of any existing config, preserves other mcpServers entries. Restart Claude Desktop after running.')
+    .action(mcpInstallCommand);
 // ─── Help command — full quick-reference ───────────────────────────
 program
     .command('cheat')
@@ -204,6 +237,15 @@ program
         'Settings',
         '  prave settings                     # configure agents + paths',
         '',
+        'Runs (scheduled cron on Prave)',
+        '  prave run deploy                   # bundle cwd, upload, open wizard',
+        '  prave run list                     # your scheduled runs',
+        '  prave run logs <slug>              # tail latest execution log',
+        '',
+        'Docs',
+        '  prave docs                         # open the docs in your browser',
+        '  prave docs <slug>                  # jump to a section, e.g. cli/run',
+        '',
         'Telemetry',
         '  PRAVE_TELEMETRY=0                  # opt out of CLI usage analytics',
         '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "Prave CLI — discover, install, version, test, and ship Claude Skills. The developer platform for the complete Skill lifecycle.",
   "type": "module",
   "keywords": [
@@ -46,15 +46,18 @@
     "dist"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "open": "^10.1.0",
     "ora": "^8.0.1",
+    "tar": "^7.4.3",
     "undici": "^6.18.0",
-    "@prave/shared": "1.2.2"
+    "@prave/shared": "1.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",
+    "@types/tar": "^6.1.13",
     "tsx": "^4.11.0",
     "typescript": "^5.4.5"
   },