@vibemastery/zurf 0.2.3 → 0.3.0

package/dist/lib/config.js

@@ -26,29 +26,56 @@ export function findLocalConfigPath(startDir = process.cwd()) {
     }
     return undefined;
 }
-function readConfigFile(filePath) {
+/**
+ * Detect whether a parsed config object uses the old flat shape (has `apiKey` at root, no `providers` key).
+ */
+function isLegacyConfig(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return false;
+    const obj = raw;
+    return ('apiKey' in obj || 'projectId' in obj) && !('providers' in obj);
+}
+/**
+ * Migrate a legacy flat config to the new nested shape.
+ */
+function migrateLegacyConfig(legacy) {
+    const config = {};
+    if (legacy.apiKey || legacy.projectId) {
+        config.providers = {
+            browserbase: {},
+        };
+        if (legacy.apiKey)
+            config.providers.browserbase.apiKey = legacy.apiKey;
+        if (legacy.projectId)
+            config.providers.browserbase.projectId = legacy.projectId;
+    }
+    if (legacy.format)
+        config.format = legacy.format;
+    return config;
+}
+export function readConfigFile(filePath) {
     try {
         const raw = fs.readFileSync(filePath, 'utf8');
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        if (isLegacyConfig(parsed)) {
+            return migrateLegacyConfig(parsed);
+        }
+        return parsed;
     }
     catch {
         return undefined;
     }
 }
-function readApiKeyFromFile(filePath) {
+function readStringField(filePath, getter) {
     const parsed = readConfigFile(filePath);
     if (!parsed)
         return undefined;
-    const key = typeof parsed.apiKey === 'string' ? parsed.apiKey.trim() : '';
-    return key.length > 0 ? key : undefined;
-}
-function readProjectIdFromFile(filePath) {
-    const parsed = readConfigFile(filePath);
-    if (!parsed)
-        return undefined;
-    const id = typeof parsed.projectId === 'string' ? parsed.projectId.trim() : '';
-    return id.length > 0 ? id : undefined;
+    const val = getter(parsed)?.trim() ?? '';
+    return val.length > 0 ? val : undefined;
 }
+const readBrowserbaseApiKeyFromFile = (f) => readStringField(f, (c) => c.providers?.browserbase?.apiKey);
+const readBrowserbaseProjectIdFromFile = (f) => readStringField(f, (c) => c.providers?.browserbase?.projectId);
+const readPerplexityApiKeyFromFile = (f) => readStringField(f, (c) => c.providers?.perplexity?.apiKey);
 function readFormatFromFile(filePath) {
     const parsed = readConfigFile(filePath);
     if (!parsed)
@@ -85,13 +112,13 @@ export function resolveApiKey(options) {
     }
     const localPath = findLocalConfigPath(cwd);
     if (localPath) {
-        const key = readApiKeyFromFile(localPath);
+        const key = readBrowserbaseApiKeyFromFile(localPath);
         if (key) {
             return { apiKey: key, path: localPath, source: 'local' };
         }
     }
     const gPath = globalConfigFilePath(options.globalConfigDir);
-    const globalKey = readApiKeyFromFile(gPath);
+    const globalKey = readBrowserbaseApiKeyFromFile(gPath);
     if (globalKey) {
         return { apiKey: globalKey, path: gPath, source: 'global' };
     }
@@ -105,20 +132,40 @@ export function resolveProjectId(options) {
     }
     const localPath = findLocalConfigPath(cwd);
     if (localPath) {
-        const id = readProjectIdFromFile(localPath);
+        const id = readBrowserbaseProjectIdFromFile(localPath);
         if (id) {
             return { path: localPath, projectId: id, source: 'local' };
         }
     }
     const gPath = globalConfigFilePath(options.globalConfigDir);
-    const globalId = readProjectIdFromFile(gPath);
+    const globalId = readBrowserbaseProjectIdFromFile(gPath);
     if (globalId) {
         return { path: gPath, projectId: globalId, source: 'global' };
     }
     return { source: 'none' };
 }
+export function resolvePerplexityApiKey(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const envKey = process.env.PERPLEXITY_API_KEY?.trim();
+    if (envKey) {
+        return { apiKey: envKey, source: 'env' };
+    }
+    const localPath = findLocalConfigPath(cwd);
+    if (localPath) {
+        const key = readPerplexityApiKeyFromFile(localPath);
+        if (key) {
+            return { apiKey: key, path: localPath, source: 'local' };
+        }
+    }
+    const gPath = globalConfigFilePath(options.globalConfigDir);
+    const globalKey = readPerplexityApiKeyFromFile(gPath);
+    if (globalKey) {
+        return { apiKey: globalKey, path: gPath, source: 'global' };
+    }
+    return { source: 'none' };
+}
 export async function writeApiKeyConfig(targetPath, apiKey) {
-    await writeConfig(targetPath, { apiKey: apiKey.trim() });
+    await writeConfig(targetPath, { providers: { browserbase: { apiKey: apiKey.trim() } } });
 }
 export async function writeConfig(targetPath, fields) {
     const dir = path.dirname(targetPath);
@@ -126,12 +173,37 @@ export async function writeConfig(targetPath, fields) {
     let existing = {};
     try {
         const raw = await fs.promises.readFile(targetPath, 'utf8');
-        existing = JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        existing = isLegacyConfig(parsed) ? migrateLegacyConfig(parsed) : parsed;
     }
     catch {
         // file doesn't exist yet — start fresh
     }
-    const merged = { ...existing, ...fields };
+    const merged = {
+        ...existing,
+        ...fields,
+        providers: {
+            ...existing.providers,
+            ...fields.providers,
+            browserbase: {
+                ...existing.providers?.browserbase,
+                ...fields.providers?.browserbase,
+            },
+            perplexity: {
+                ...existing.providers?.perplexity,
+                ...fields.providers?.perplexity,
+            },
+        },
+    };
+    if (merged.providers?.browserbase && Object.keys(merged.providers.browserbase).length === 0) {
+        delete merged.providers.browserbase;
+    }
+    if (merged.providers?.perplexity && Object.keys(merged.providers.perplexity).length === 0) {
+        delete merged.providers.perplexity;
+    }
+    if (merged.providers && Object.keys(merged.providers).length === 0) {
+        delete merged.providers;
+    }
     const body = `${JSON.stringify(merged, null, 2)}\n`;
     await fs.promises.writeFile(targetPath, body, { encoding: 'utf8', mode: 0o600 });
 }

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,29 +1,49 @@
 {
   "commands": {
-    "browse": {
+    "ask": {
       "aliases": [],
       "args": {
-        "url": {
-          "description": "URL to browse",
-          "name": "url",
+        "question": {
+          "description": "The question to ask Perplexity",
+          "name": "question",
           "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 init --global` before first use.",
+      "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 %> <%= 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"
+        "<%= 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": {
-        "html": {
-          "description": "Output raw HTML instead of markdown",
-          "env": "ZURF_HTML",
-          "name": "html",
-          "allowNo": false,
+        "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",
@@ -31,81 +51,53 @@
           "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",
+        "recency": {
+          "description": "Filter sources by recency",
+          "name": "recency",
           "hasDynamicHelp": false,
           "multiple": false,
+          "options": [
+            "hour",
+            "day",
+            "week",
+            "month",
+            "year"
+          ],
           "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "browse",
+      "id": "ask",
       "pluginAlias": "@vibemastery/zurf",
       "pluginName": "@vibemastery/zurf",
       "pluginType": "core",
       "strict": true,
-      "summary": "Browse a URL in a cloud browser and return rendered content as markdown",
+      "summary": "Ask a question via Perplexity Sonar",
+      "enableJsonFlag": false,
       "isESM": true,
       "relativePath": [
         "dist",
         "commands",
-        "browse",
+        "ask",
         "index.js"
       ]
     },
-    "config:which": {
+    "browse": {
       "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.",
-      "examples": [
-        "<%= 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"
+      "args": {
+        "url": {
+          "description": "URL to browse",
+          "name": "url",
+          "required": true
         }
       },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "config:which",
-      "pluginAlias": "@vibemastery/zurf",
-      "pluginName": "@vibemastery/zurf",
-      "pluginType": "core",
-      "strict": true,
-      "summary": "Show where the API key is loaded from",
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "config",
-        "which.js"
-      ]
-    },
-    "init": {
-      "aliases": [],
-      "args": {},
-      "description": "Save your Browserbase API key and optional Project ID to global or project config.\nGlobal path follows oclif config (same as `zurf config which`).",
+      "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 %> --global",
-        "<%= config.bin %> <%= command.id %> --local",
-        "<%= config.bin %> <%= command.id %> --global --api-key KEY --project-id PROJ_ID",
-        "printenv BROWSERBASE_API_KEY | <%= config.bin %> <%= command.id %> --global"
+        "<%= 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": {
@@ -122,34 +114,10 @@
           "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"
-        },
-        "project-id": {
-          "description": "Browserbase Project ID (optional; needed for browse, screenshot, pdf commands)",
-          "name": "project-id",
+        "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"
@@ -157,18 +125,17 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "init",
+      "id": "browse",
       "pluginAlias": "@vibemastery/zurf",
       "pluginName": "@vibemastery/zurf",
       "pluginType": "core",
       "strict": true,
-      "summary": "Configure Browserbase API key and Project ID storage",
-      "enableJsonFlag": false,
+      "summary": "Browse a URL in a cloud browser and return rendered content as markdown",
       "isESM": true,
       "relativePath": [
         "dist",
         "commands",
-        "init",
+        "browse",
         "index.js"
       ]
     },
@@ -181,7 +148,7 @@
           "required": true
         }
       },
-      "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 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",
@@ -246,6 +213,47 @@
         "index.js"
       ]
     },
+    "config:which": {
+      "aliases": [],
+      "args": {},
+      "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 %> 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"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "config:which",
+      "pluginAlias": "@vibemastery/zurf",
+      "pluginName": "@vibemastery/zurf",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Show where API keys are loaded from",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "which.js"
+      ]
+    },
     "search": {
       "aliases": [],
       "args": {
@@ -255,7 +263,7 @@
           "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"
@@ -300,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.3"
+  "version": "0.3.0"
 }