@prave/cli 1.3.0 → 1.4.0

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/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,6 +6,7 @@ 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';
@@ -16,6 +17,7 @@ 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';
@@ -167,6 +169,26 @@ 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')
@@ -215,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.3.0",
+  "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": [
@@ -51,11 +51,13 @@
     "commander": "^12.1.0",
     "open": "^10.1.0",
     "ora": "^8.0.1",
+    "tar": "^7.4.3",
     "undici": "^6.18.0",
-    "@prave/shared": "1.3.0"
+    "@prave/shared": "1.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",
+    "@types/tar": "^6.1.13",
     "tsx": "^4.11.0",
     "typescript": "^5.4.5"
   },