@vibemastery/zurf 0.2.2 → 0.3.0

package/dist/lib/html-to-markdown.d.ts

@@ -0,0 +1 @@
+export declare function htmlToMarkdown(html: string): Promise<string>;

package/dist/lib/html-to-markdown.js

@@ -0,0 +1,21 @@
+let cached;
+async function getService() {
+    if (cached)
+        return cached;
+    const { default: Turndown } = await import('turndown');
+    const service = new Turndown({
+        codeBlockStyle: 'fenced',
+        headingStyle: 'atx',
+    });
+    service.remove(['script', 'style', 'iframe', 'noscript']);
+    service.addRule('remove-svg', {
+        filter: (node) => node.nodeName.toLowerCase() === 'svg',
+        replacement: () => '',
+    });
+    cached = service;
+    return service;
+}
+export async function htmlToMarkdown(html) {
+    const service = await getService();
+    return service.turndown(html);
+}

package/dist/lib/perplexity-client.d.ts

@@ -0,0 +1,33 @@
+import { resolvePerplexityApiKey } from './config.js';
+export type PerplexityDepth = 'deep' | 'quick';
+export type PerplexityRecency = 'day' | 'hour' | 'month' | 'week' | 'year';
+export interface PerplexityAskOptions {
+    depth?: PerplexityDepth;
+    domains?: string[];
+    question: string;
+    recency?: PerplexityRecency;
+}
+export interface PerplexityAskResult {
+    answer: string;
+    citations: string[];
+    model: string;
+}
+export declare class PerplexityClient {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    ask(options: PerplexityAskOptions): Promise<PerplexityAskResult>;
+}
+export declare class MissingPerplexityKeyError extends Error {
+    code: string;
+    suggestions: string[];
+    constructor();
+}
+export declare function createPerplexityClient(options: {
+    cwd?: string;
+    globalConfigDir: string;
+}): {
+    client: PerplexityClient;
+    resolution: Extract<ReturnType<typeof resolvePerplexityApiKey>, {
+        apiKey: string;
+    }>;
+};

package/dist/lib/perplexity-client.js

@@ -0,0 +1,59 @@
+import { resolvePerplexityApiKey } from './config.js';
+function buildRequestBody(options) {
+    const model = options.depth === 'deep' ? 'sonar-pro' : 'sonar';
+    const body = {
+        messages: [{ content: options.question, role: 'user' }],
+        model,
+    };
+    if (options.recency) {
+        body.search_recency_filter = options.recency; // eslint-disable-line camelcase
+    }
+    if (options.domains && options.domains.length > 0) {
+        body.search_domain_filter = options.domains; // eslint-disable-line camelcase
+    }
+    return body;
+}
+export class PerplexityClient {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async ask(options) {
+        const body = buildRequestBody(options);
+        const response = await fetch('https://api.perplexity.ai/chat/completions', {
+            body: JSON.stringify(body),
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            method: 'POST',
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`Perplexity API error (${response.status}): ${text || response.statusText}`);
+        }
+        const data = (await response.json());
+        const answer = data.choices?.[0]?.message?.content ?? '';
+        const citations = data.citations ?? [];
+        return { answer, citations, model: data.model };
+    }
+}
+export class MissingPerplexityKeyError extends Error {
+    code = 'MISSING_PERPLEXITY_KEY';
+    suggestions = [
+        'Run `zurf setup` to configure your Perplexity API key',
+        'Or set the PERPLEXITY_API_KEY environment variable',
+    ];
+    constructor() {
+        super('No Perplexity API key found.');
+        this.name = 'MissingPerplexityKeyError';
+    }
+}
+export function createPerplexityClient(options) {
+    const resolution = resolvePerplexityApiKey({ cwd: options.cwd, globalConfigDir: options.globalConfigDir });
+    if (resolution.source === 'none') {
+        throw new MissingPerplexityKeyError();
+    }
+    const client = new PerplexityClient(resolution.apiKey);
+    return { client, resolution };
+}

package/dist/lib/setup-prompts.d.ts

@@ -0,0 +1,10 @@
+export type ConfigScope = 'global' | 'local';
+export interface ProviderChoice {
+    configured: boolean;
+    name: string;
+    value: string;
+}
+export declare function selectScope(): Promise<ConfigScope>;
+export declare function selectProviders(providers: ProviderChoice[]): Promise<string[]>;
+export declare function promptApiKey(label: string): Promise<string>;
+export declare function promptProjectId(): Promise<string>;

package/dist/lib/setup-prompts.js

@@ -0,0 +1,34 @@
+import { checkbox, input, password, select } from '@inquirer/prompts';
+export async function selectScope() {
+    return select({
+        choices: [
+            { name: 'Global (user-wide, recommended)', value: 'global' },
+            { name: 'Local (this project only)', value: 'local' },
+        ],
+        message: 'Where should zurf store your config?',
+    });
+}
+export async function selectProviders(providers) {
+    const choices = providers.map((p) => ({
+        checked: p.configured,
+        name: p.configured ? `${p.name} [configured]` : p.name,
+        value: p.value,
+    }));
+    return checkbox({
+        choices,
+        message: 'Which providers do you want to configure?',
+        required: true,
+    });
+}
+export async function promptApiKey(label) {
+    return password({
+        mask: '*',
+        message: `${label} API key:`,
+        validate: (value) => (value.trim().length > 0 ? true : 'API key cannot be empty'),
+    });
+}
+export async function promptProjectId() {
+    return input({
+        message: 'Browserbase Project ID (optional, press Enter to skip):',
+    });
+}

package/oclif.manifest.json

@@ -1,37 +1,142 @@
 {
   "commands": {
-    "config:which": {
+    "ask": {
       "aliases": [],
-      "args": {},
-      "description": "Show where the Browserbase API key would be loaded from (no secret printed).\nResolution order: BROWSERBASE_API_KEY, then project .zurf/config.json (walk-up), then global config in the CLI config directory.",
+      "args": {
+        "question": {
+          "description": "The question to ask Perplexity",
+          "name": "question",
+          "required": true
+        }
+      },
+      "description": "Ask a question and get an AI-powered answer with web citations via Perplexity Sonar.\nReturns an answer with inline citations and a sources list. Use --depth deep for more thorough research.",
       "examples": [
-        "<%= config.bin %> config which",
-        "<%= config.bin %> config which --json"
+        "<%= config.bin %> <%= command.id %> \"What is Browserbase?\"",
+        "<%= config.bin %> <%= command.id %> \"latest tech news\" --recency day",
+        "<%= config.bin %> <%= command.id %> \"search reddit for best CLI tools\" --domains reddit.com",
+        "<%= config.bin %> <%= command.id %> \"explain quantum computing\" --depth deep",
+        "<%= config.bin %> <%= command.id %> \"What is Node.js?\" --json",
+        "<%= config.bin %> <%= command.id %> \"What is oclif?\" --no-citations"
       ],
       "flags": {
+        "citations": {
+          "description": "Show sources list after the answer (use --no-citations to hide)",
+          "name": "citations",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "depth": {
+          "description": "Search depth: quick (sonar) or deep (sonar-pro)",
+          "name": "depth",
+          "default": "quick",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "quick",
+            "deep"
+          ],
+          "type": "option"
+        },
+        "domains": {
+          "description": "Restrict search to these domains (comma-separated)",
+          "name": "domains",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "json": {
           "description": "Print machine-readable JSON to stdout",
           "env": "ZURF_JSON",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
+        },
+        "recency": {
+          "description": "Filter sources by recency",
+          "name": "recency",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "hour",
+            "day",
+            "week",
+            "month",
+            "year"
+          ],
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "config:which",
+      "id": "ask",
       "pluginAlias": "@vibemastery/zurf",
       "pluginName": "@vibemastery/zurf",
       "pluginType": "core",
       "strict": true,
-      "summary": "Show where the API key is loaded from",
+      "summary": "Ask a question via Perplexity Sonar",
       "enableJsonFlag": false,
       "isESM": true,
       "relativePath": [
         "dist",
         "commands",
-        "config",
-        "which.js"
+        "ask",
+        "index.js"
+      ]
+    },
+    "browse": {
+      "aliases": [],
+      "args": {
+        "url": {
+          "description": "URL to browse",
+          "name": "url",
+          "required": true
+        }
+      },
+      "description": "Browse a URL in a cloud browser and return the rendered content as markdown (default) or raw HTML.\nUses a real Chromium browser via Browserbase, so JavaScript-heavy pages are fully rendered.\nRequires authentication and a Project ID. Run `zurf setup` before first use.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> https://example.com",
+        "<%= config.bin %> <%= command.id %> https://example.com --html",
+        "<%= config.bin %> <%= command.id %> https://example.com --json",
+        "<%= config.bin %> <%= command.id %> https://example.com -o page.md"
+      ],
+      "flags": {
+        "html": {
+          "description": "Output raw HTML instead of markdown",
+          "env": "ZURF_HTML",
+          "name": "html",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "json": {
+          "description": "Print machine-readable JSON to stdout",
+          "env": "ZURF_JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "output": {
+          "char": "o",
+          "description": "Write rendered content to this file (full content); otherwise human mode prints a truncated preview to stdout",
+          "name": "output",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "browse",
+      "pluginAlias": "@vibemastery/zurf",
+      "pluginName": "@vibemastery/zurf",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Browse a URL in a cloud browser and return rendered content as markdown",
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "browse",
+        "index.js"
       ]
     },
     "fetch": {
@@ -43,13 +148,21 @@
           "required": true
         }
       },
-      "description": "Fetch a URL via Browserbase (no browser session; static HTML, 1 MB max).\nRequires authentication. Run `zurf init --global` or use a project key before first use.",
+      "description": "Fetch a URL via Browserbase and return content as markdown (default) or raw HTML (no browser session; static HTML, 1 MB max).\nRequires authentication. Run `zurf setup` or use a project key before first use.",
       "examples": [
         "<%= config.bin %> <%= command.id %> https://example.com",
+        "<%= config.bin %> <%= command.id %> https://example.com --html",
         "<%= config.bin %> <%= command.id %> https://example.com --json",
-        "<%= config.bin %> <%= command.id %> https://example.com -o page.html --proxies"
+        "<%= config.bin %> <%= command.id %> https://example.com -o page.md --proxies"
       ],
       "flags": {
+        "html": {
+          "description": "Output raw HTML instead of markdown",
+          "env": "ZURF_HTML",
+          "name": "html",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "json": {
           "description": "Print machine-readable JSON to stdout",
           "env": "ZURF_JSON",
@@ -91,7 +204,7 @@
       "pluginName": "@vibemastery/zurf",
       "pluginType": "core",
       "strict": true,
-      "summary": "Fetch a URL via Browserbase",
+      "summary": "Fetch a URL via Browserbase and return content as markdown",
       "isESM": true,
       "relativePath": [
         "dist",
@@ -100,64 +213,45 @@
         "index.js"
       ]
     },
-    "init": {
+    "config:which": {
       "aliases": [],
       "args": {},
-      "description": "Save your Browserbase API key to global or project config.\nGlobal path follows oclif config (same as `zurf config which`).",
+      "description": "Show where API keys would be loaded from (no secrets printed).\nResolution order: env var → project .zurf/config.json (walk-up) → global config.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --global",
-        "<%= config.bin %> <%= command.id %> --local",
-        "printenv BROWSERBASE_API_KEY | <%= config.bin %> <%= command.id %> --global"
+        "<%= config.bin %> config which",
+        "<%= config.bin %> config which --json"
       ],
       "flags": {
+        "html": {
+          "description": "Output raw HTML instead of markdown",
+          "env": "ZURF_HTML",
+          "name": "html",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "json": {
           "description": "Print machine-readable JSON to stdout",
           "env": "ZURF_JSON",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
-        },
-        "api-key": {
-          "description": "API key for non-interactive use. Prefer piping stdin or using a TTY prompt — values on the command line are visible in shell history and process listings.",
-          "name": "api-key",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "gitignore": {
-          "description": "Append .zurf/ to ./.gitignore if that entry is missing",
-          "name": "gitignore",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "global": {
-          "description": "Store API key in user config (oclif config dir for this CLI)",
-          "name": "global",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "local": {
-          "description": "Store API key in ./.zurf/config.json for this directory",
-          "name": "local",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "init",
+      "id": "config:which",
       "pluginAlias": "@vibemastery/zurf",
       "pluginName": "@vibemastery/zurf",
       "pluginType": "core",
       "strict": true,
-      "summary": "Configure Browserbase API key storage",
+      "summary": "Show where API keys are loaded from",
       "enableJsonFlag": false,
       "isESM": true,
       "relativePath": [
         "dist",
         "commands",
-        "init",
-        "index.js"
+        "config",
+        "which.js"
       ]
     },
     "search": {
@@ -169,12 +263,19 @@
           "required": true
         }
       },
-      "description": "Search the web via Browserbase (Exa-powered).\nRequires authentication. Run `zurf init --global` or use a project key before first use.",
+      "description": "Search the web via Browserbase (Exa-powered).\nRequires authentication. Run `zurf setup` or use a project key before first use.",
       "examples": [
         "<%= config.bin %> <%= command.id %> \"browserbase documentation\"",
         "<%= config.bin %> <%= command.id %> \"laravel inertia\" --num-results 5 --json"
       ],
       "flags": {
+        "html": {
+          "description": "Output raw HTML instead of markdown",
+          "env": "ZURF_HTML",
+          "name": "html",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "json": {
           "description": "Print machine-readable JSON to stdout",
           "env": "ZURF_JSON",
@@ -207,7 +308,54 @@
         "search",
         "index.js"
       ]
+    },
+    "setup": {
+      "aliases": [],
+      "args": {},
+      "description": "Interactive setup wizard for configuring API keys for all providers (Browserbase, Perplexity).\nStores keys in global or local config. Re-run to update or add providers.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --global",
+        "<%= config.bin %> <%= command.id %> --local"
+      ],
+      "flags": {
+        "global": {
+          "description": "Store config in user config directory (skip scope prompt)",
+          "name": "global",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "json": {
+          "description": "Print machine-readable JSON to stdout",
+          "env": "ZURF_JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "local": {
+          "description": "Store config in .zurf/config.json in the current directory (skip scope prompt)",
+          "name": "local",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "setup",
+      "pluginAlias": "@vibemastery/zurf",
+      "pluginName": "@vibemastery/zurf",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Configure API keys for Browserbase and Perplexity",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "setup",
+        "index.js"
+      ]
     }
   },
-  "version": "0.2.2"
+  "version": "0.3.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vibemastery/zurf",
   "description": "A lightweight CLI for searching and fetching web pages, powered by Browserbase.",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "author": "Luis Güette",
   "bin": {
     "zurf": "./bin/run.js"
@@ -9,12 +9,15 @@
   "bugs": "https://github.com/vibemastery/zurf/issues",
   "dependencies": {
     "@browserbasehq/sdk": "^2.9.0",
+    "@inquirer/prompts": "^8.3.2",
     "@oclif/core": "^4",
     "@oclif/plugin-autocomplete": "^3.2.42",
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-not-found": "^3.2.77",
     "@oclif/plugin-plugins": "^5",
-    "@oclif/plugin-warn-if-update-available": "^3.1.57"
+    "@oclif/plugin-warn-if-update-available": "^3.1.57",
+    "playwright-core": "^1.58.2",
+    "turndown": "^7.2.2"
   },
   "devDependencies": {
     "@eslint/compat": "^1",
@@ -23,6 +26,7 @@
     "@types/chai": "^4",
     "@types/mocha": "^10",
     "@types/node": "^18",
+    "@types/turndown": "^5.0.6",
     "chai": "^4",
     "eslint": "^9",
     "eslint-config-oclif": "^6",
@@ -70,8 +74,8 @@
       "config": {
         "description": "Inspect zurf configuration"
       },
-      "init": {
-        "description": "Configure Browserbase API key storage"
+      "setup": {
+        "description": "Configure API keys for Browserbase and Perplexity"
       }
     }
   },

package/dist/commands/init/index.js

@@ -1,95 +0,0 @@
-import { Command, Flags } from '@oclif/core';
-import * as fs from 'node:fs/promises';
-import { cliError, errorMessage } from '../../lib/cli-errors.js';
-import { globalConfigFilePath, localConfigPathForCwd, writeApiKeyConfig } from '../../lib/config.js';
-import { zurfBaseFlags } from '../../lib/flags.js';
-import { dotGitignoreMentionsZurf, ensureZurfGitignoreEntry, gitignorePathForCwd, } from '../../lib/gitignore-zurf.js';
-import { promptLine, readStdinIfPiped } from '../../lib/init-input.js';
-import { printJson } from '../../lib/json-output.js';
-export default class Init extends Command {
-    static description = `Save your Browserbase API key to global or project config.
-Global path follows oclif config (same as \`zurf config which\`).`;
-    static examples = [
-        '<%= config.bin %> <%= command.id %> --global',
-        '<%= config.bin %> <%= command.id %> --local',
-        'printenv BROWSERBASE_API_KEY | <%= config.bin %> <%= command.id %> --global',
-    ];
-    static flags = {
-        ...zurfBaseFlags,
-        'api-key': Flags.string({
-            description: 'API key for non-interactive use. Prefer piping stdin or using a TTY prompt — values on the command line are visible in shell history and process listings.',
-        }),
-        gitignore: Flags.boolean({
-            description: 'Append .zurf/ to ./.gitignore if that entry is missing',
-        }),
-        global: Flags.boolean({
-            description: 'Store API key in user config (oclif config dir for this CLI)',
-            exactlyOne: ['global', 'local'],
-        }),
-        local: Flags.boolean({
-            description: 'Store API key in ./.zurf/config.json for this directory',
-            exactlyOne: ['global', 'local'],
-        }),
-    };
-    static summary = 'Configure Browserbase API key storage';
-    async run() {
-        const { flags } = await this.parse(Init);
-        const apiKey = await this.readApiKeyForInit(flags);
-        const targetPath = flags.global
-            ? globalConfigFilePath(this.config.configDir)
-            : localConfigPathForCwd();
-        try {
-            await writeApiKeyConfig(targetPath, apiKey);
-        }
-        catch (error) {
-            cliError({ command: this, exitCode: 1, json: flags.json, message: errorMessage(error) });
-        }
-        if (flags.gitignore) {
-            try {
-                await ensureZurfGitignoreEntry(gitignorePathForCwd());
-            }
-            catch (error) {
-                cliError({ command: this, exitCode: 1, json: flags.json, message: errorMessage(error) });
-            }
-        }
-        if (flags.json) {
-            printJson({ ok: true, path: targetPath, scope: flags.global ? 'global' : 'local' });
-        }
-        else {
-            this.log(`Saved API key to ${targetPath}`);
-            if (flags.local) {
-                let showTip = true;
-                try {
-                    const gi = await fs.readFile(gitignorePathForCwd(), 'utf8');
-                    if (dotGitignoreMentionsZurf(gi)) {
-                        showTip = false;
-                    }
-                }
-                catch {
-                    // no .gitignore yet
-                }
-                if (showTip) {
-                    this.log('Tip: add .zurf/ to .gitignore so the key is not committed (or run with --gitignore).');
-                }
-            }
-        }
-    }
-    async readApiKeyForInit(flags) {
-        let apiKey = flags['api-key']?.trim();
-        if (!apiKey) {
-            apiKey = await readStdinIfPiped();
-        }
-        if (!apiKey && process.stdin.isTTY) {
-            apiKey = await promptLine('Browserbase API key: ');
-        }
-        if (!apiKey) {
-            cliError({
-                command: this,
-                exitCode: 2,
-                json: flags.json,
-                message: 'No API key provided. Pipe stdin, use --api-key, or run interactively in a TTY.',
-            });
-        }
-        return apiKey;
-    }
-}