@vibemastery/zurf 0.1.0

package/dist/lib/init-input.js

@@ -0,0 +1,26 @@
+import * as readline from 'node:readline';
+export async function readStdinIfPiped() {
+    if (process.stdin.isTTY) {
+        return undefined;
+    }
+    try {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+        }
+        const s = Buffer.concat(chunks).toString('utf8').trim();
+        return s.length > 0 ? s : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function promptLine(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}

package/dist/lib/json-output.d.ts

@@ -0,0 +1,3 @@
+export declare function printJson(value: unknown): void;
+/** JSON errors use stdout on purpose so `--json` callers get a single stream for piping/parsing. */
+export declare function printErrorJson(message: string, code?: number | string): void;

package/dist/lib/json-output.js

@@ -0,0 +1,11 @@
+export function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+/** JSON errors use stdout on purpose so `--json` callers get a single stream for piping/parsing. */
+export function printErrorJson(message, code) {
+    const payload = { error: { message } };
+    if (code !== undefined) {
+        payload.error.code = code;
+    }
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}

package/dist/lib/search-output.d.ts

@@ -0,0 +1,16 @@
+export type SearchResultRow = {
+    author?: string;
+    title: string;
+    url: string;
+};
+export type SearchResponseForDisplay = {
+    query: string;
+    requestId: string;
+    results: SearchResultRow[];
+};
+export declare function buildSearchJsonPayload(response: SearchResponseForDisplay): {
+    query: string;
+    requestId: string;
+    results: SearchResultRow[];
+};
+export declare function linesForHumanSearch(response: SearchResponseForDisplay): string[];

package/dist/lib/search-output.js

@@ -0,0 +1,20 @@
+export function buildSearchJsonPayload(response) {
+    return {
+        query: response.query,
+        requestId: response.requestId,
+        results: response.results,
+    };
+}
+export function linesForHumanSearch(response) {
+    const lines = [`requestId: ${response.requestId}`, ''];
+    for (const [i, r] of response.results.entries()) {
+        const block = [
+            `${i + 1}. ${r.title}`,
+            `   ${r.url}`,
+            ...(r.author ? [`   author: ${r.author}`] : []),
+            '',
+        ];
+        lines.push(...block);
+    }
+    return lines;
+}

package/dist/lib/zurf-browserbase-command.d.ts

@@ -0,0 +1,8 @@
+import type { Browserbase } from '@browserbasehq/sdk';
+import { Command } from '@oclif/core';
+/** Shared behavior for commands that call Browserbase: client resolution, optional spinner, unified API error handling. */
+export declare abstract class ZurfBrowserbaseCommand extends Command {
+    protected runWithBrowserbase(flags: {
+        json: boolean;
+    }, spinnerLabel: string, work: (client: Browserbase) => Promise<void>): Promise<void>;
+}

package/dist/lib/zurf-browserbase-command.js

@@ -0,0 +1,36 @@
+import { Command, ux } from '@oclif/core';
+import { getBrowserbaseClientOrExit } from './browserbase-command.js';
+import { cliError, errorMessage, errorStatus } from './cli-errors.js';
+/** Shared behavior for commands that call Browserbase: client resolution, optional spinner, unified API error handling. */
+export class ZurfBrowserbaseCommand extends Command {
+    async runWithBrowserbase(flags, spinnerLabel, work) {
+        const { client } = await getBrowserbaseClientOrExit(this, flags, {
+            globalConfigDir: this.config.configDir,
+        });
+        const run = async () => {
+            try {
+                await work(client);
+            }
+            catch (error) {
+                cliError({
+                    command: this,
+                    exitCode: 1,
+                    json: flags.json,
+                    message: errorMessage(error),
+                    statusCode: errorStatus(error),
+                });
+            }
+        };
+        if (flags.json) {
+            await run();
+            return;
+        }
+        ux.action.start(spinnerLabel);
+        try {
+            await run();
+        }
+        finally {
+            ux.action.stop();
+        }
+    }
+}

package/oclif.manifest.json

@@ -0,0 +1,213 @@
+{
+  "commands": {
+    "config:which": {
+      "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": {
+        "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 the API key is loaded from",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "which.js"
+      ]
+    },
+    "fetch": {
+      "aliases": [],
+      "args": {
+        "url": {
+          "description": "URL to fetch",
+          "name": "url",
+          "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.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> https://example.com",
+        "<%= config.bin %> <%= command.id %> https://example.com --json",
+        "<%= config.bin %> <%= command.id %> https://example.com -o page.html --proxies"
+      ],
+      "flags": {
+        "json": {
+          "description": "Print machine-readable JSON to stdout",
+          "env": "ZURF_JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "allow-insecure-ssl": {
+          "description": "Disable TLS certificate verification (use only if you trust the target)",
+          "name": "allow-insecure-ssl",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "allow-redirects": {
+          "description": "Follow HTTP redirects",
+          "name": "allow-redirects",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "output": {
+          "char": "o",
+          "description": "Write response body to this file (full content); otherwise human mode prints a truncated preview to stdout",
+          "name": "output",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "proxies": {
+          "description": "Route through Browserbase proxies (helps with some blocked sites)",
+          "name": "proxies",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "fetch",
+      "pluginAlias": "@vibemastery/zurf",
+      "pluginName": "@vibemastery/zurf",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Fetch a URL via Browserbase",
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "fetch",
+        "index.js"
+      ]
+    },
+    "search": {
+      "aliases": [],
+      "args": {
+        "query": {
+          "description": "Search query, max 200 characters (quote for multiple words)",
+          "name": "query",
+          "required": true
+        }
+      },
+      "description": "Search the web via Browserbase (Exa-powered).\nRequires authentication. Run `zurf init --global` 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": {
+        "json": {
+          "description": "Print machine-readable JSON to stdout",
+          "env": "ZURF_JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "num-results": {
+          "char": "n",
+          "description": "Number of results (1–25)",
+          "name": "num-results",
+          "default": 10,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "search",
+      "pluginAlias": "@vibemastery/zurf",
+      "pluginName": "@vibemastery/zurf",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Search the web via Browserbase",
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "search",
+        "index.js"
+      ]
+    },
+    "init": {
+      "aliases": [],
+      "args": {},
+      "description": "Save your Browserbase API key to global or project config.\nGlobal path follows oclif config (same as `zurf config which`).",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --global",
+        "<%= config.bin %> <%= command.id %> --local",
+        "printenv BROWSERBASE_API_KEY | <%= config.bin %> <%= command.id %> --global"
+      ],
+      "flags": {
+        "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",
+      "pluginAlias": "@vibemastery/zurf",
+      "pluginName": "@vibemastery/zurf",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Configure Browserbase API key storage",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "init",
+        "index.js"
+      ]
+    }
+  },
+  "version": "0.1.0"
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@vibemastery/zurf",
+  "description": "A lightweight CLI for searching and fetching web pages, powered by Browserbase.",
+  "version": "0.1.0",
+  "author": "Luis Güette",
+  "bin": {
+    "zurf": "./bin/run.js"
+  },
+  "bugs": "https://github.com/vibemastery/zurf/issues",
+  "dependencies": {
+    "@browserbasehq/sdk": "^2.9.0",
+    "@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"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^1",
+    "@oclif/prettier-config": "^0.2.1",
+    "@oclif/test": "^4",
+    "@types/chai": "^4",
+    "@types/mocha": "^10",
+    "@types/node": "^18",
+    "chai": "^4",
+    "eslint": "^9",
+    "eslint-config-oclif": "^6",
+    "eslint-config-prettier": "^10",
+    "mocha": "^11",
+    "oclif": "^4",
+    "shx": "^0.3.3",
+    "ts-node": "^10",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "./bin",
+    "./dist",
+    "./oclif.manifest.json"
+  ],
+  "homepage": "https://github.com/vibemastery/zurf",
+  "keywords": [
+    "oclif",
+    "browserbase",
+    "web-search",
+    "cli"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "type": "module",
+  "oclif": {
+    "bin": "zurf",
+    "dirname": "zurf",
+    "commands": "./dist/commands",
+    "plugins": [
+      "@oclif/plugin-autocomplete",
+      "@oclif/plugin-help",
+      "@oclif/plugin-not-found",
+      "@oclif/plugin-plugins",
+      "@oclif/plugin-warn-if-update-available"
+    ],
+    "macos": {
+      "identifier": "ai.vibemastery.zurf"
+    },
+    "topicSeparator": " ",
+    "topics": {
+      "config": {
+        "description": "Inspect zurf configuration"
+      },
+      "init": {
+        "description": "Configure Browserbase API key storage"
+      }
+    }
+  },
+  "repository": "vibemastery/zurf",
+  "scripts": {
+    "build": "shx rm -rf dist && tsc -b",
+    "lint": "eslint",
+    "postpack": "shx rm -f oclif.manifest.json",
+    "posttest": "pnpm run lint",
+    "prepack": "oclif manifest && oclif readme",
+    "pretest": "pnpm run build",
+    "test": "mocha --forbid-only \"test/**/*.test.ts\"",
+    "version": "oclif readme && git add README.md"
+  },
+  "types": "dist/index.d.ts"
+}