unbrowse 3.1.0-experiments.995f8bb → 3.1.0-experiments.9cbcb13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/dist/cli.js +79 -33
  2. package/dist/index.js +2 -6
  3. package/dist/mcp.js +73 -22
  4. package/dist/server.js +25994 -0
  5. package/package.json +1 -2
  6. package/vendor/kuri/manifest.json +1 -1
  7. package/runtime-src/agent-outcome.ts +0 -166
  8. package/runtime-src/analytics-session.ts +0 -55
  9. package/runtime-src/api/browse-index.ts +0 -343
  10. package/runtime-src/api/browse-session.ts +0 -572
  11. package/runtime-src/api/browse-submit-prereqs.ts +0 -48
  12. package/runtime-src/api/browse-submit.ts +0 -1184
  13. package/runtime-src/api/routes.ts +0 -1833
  14. package/runtime-src/auth/browser-cookies.ts +0 -423
  15. package/runtime-src/auth/index.ts +0 -535
  16. package/runtime-src/auth/runtime.ts +0 -116
  17. package/runtime-src/browser/index.ts +0 -659
  18. package/runtime-src/browser/types.ts +0 -41
  19. package/runtime-src/build-info.generated.ts +0 -6
  20. package/runtime-src/capture/index.ts +0 -1929
  21. package/runtime-src/capture/prefetch.ts +0 -95
  22. package/runtime-src/capture/rsc.ts +0 -45
  23. package/runtime-src/cli/shortcuts.ts +0 -273
  24. package/runtime-src/cli.ts +0 -1734
  25. package/runtime-src/client/graph-client.ts +0 -100
  26. package/runtime-src/client/index.ts +0 -1425
  27. package/runtime-src/debug-trace.ts +0 -18
  28. package/runtime-src/domain.ts +0 -38
  29. package/runtime-src/execution/index.ts +0 -3407
  30. package/runtime-src/execution/retry.ts +0 -46
  31. package/runtime-src/execution/robots.ts +0 -167
  32. package/runtime-src/execution/search-forms.ts +0 -188
  33. package/runtime-src/execution/token-resolver.ts +0 -135
  34. package/runtime-src/extraction/index.ts +0 -1507
  35. package/runtime-src/foundry/publish-bundle.ts +0 -392
  36. package/runtime-src/graph/agent-augment.ts +0 -315
  37. package/runtime-src/graph/index.ts +0 -1532
  38. package/runtime-src/graph/local-fixtures.ts +0 -393
  39. package/runtime-src/graph/local-harness.ts +0 -646
  40. package/runtime-src/graph/planner.ts +0 -411
  41. package/runtime-src/graph/session.ts +0 -294
  42. package/runtime-src/graph/trace-store.ts +0 -136
  43. package/runtime-src/impact-log.ts +0 -227
  44. package/runtime-src/index.ts +0 -24
  45. package/runtime-src/indexer/index.ts +0 -465
  46. package/runtime-src/intent-match.ts +0 -1515
  47. package/runtime-src/kuri/client.ts +0 -1839
  48. package/runtime-src/logger.ts +0 -30
  49. package/runtime-src/marketplace/index.ts +0 -111
  50. package/runtime-src/mcp.ts +0 -1911
  51. package/runtime-src/orchestrator/browser-agent.ts +0 -374
  52. package/runtime-src/orchestrator/dag-advisor.ts +0 -59
  53. package/runtime-src/orchestrator/dag-feedback.ts +0 -257
  54. package/runtime-src/orchestrator/first-pass-action.ts +0 -403
  55. package/runtime-src/orchestrator/index.ts +0 -4480
  56. package/runtime-src/orchestrator/passive-publish.ts +0 -187
  57. package/runtime-src/orchestrator/timing-economics.ts +0 -80
  58. package/runtime-src/payments/cascade.ts +0 -137
  59. package/runtime-src/payments/index.ts +0 -270
  60. package/runtime-src/payments/lobster-pay.ts +0 -182
  61. package/runtime-src/payments/wallet.ts +0 -98
  62. package/runtime-src/publish/review-context.ts +0 -93
  63. package/runtime-src/publish/sanitize.ts +0 -197
  64. package/runtime-src/publish/schema-review.ts +0 -192
  65. package/runtime-src/publish-admission.ts +0 -388
  66. package/runtime-src/ratelimit/index.ts +0 -23
  67. package/runtime-src/reverse-engineer/bundle-scanner.ts +0 -127
  68. package/runtime-src/reverse-engineer/description-prompt.ts +0 -213
  69. package/runtime-src/reverse-engineer/index.ts +0 -1551
  70. package/runtime-src/reverse-engineer/token-sources.ts +0 -379
  71. package/runtime-src/router.ts +0 -17
  72. package/runtime-src/routing-telemetry.ts +0 -395
  73. package/runtime-src/runtime/browser-access.ts +0 -11
  74. package/runtime-src/runtime/browser-auth.ts +0 -12
  75. package/runtime-src/runtime/browser-host.ts +0 -48
  76. package/runtime-src/runtime/lifecycle.ts +0 -17
  77. package/runtime-src/runtime/local-server.ts +0 -311
  78. package/runtime-src/runtime/paths.ts +0 -99
  79. package/runtime-src/runtime/setup.ts +0 -251
  80. package/runtime-src/runtime/supervisor.ts +0 -69
  81. package/runtime-src/runtime/update-hints.ts +0 -351
  82. package/runtime-src/server.ts +0 -100
  83. package/runtime-src/session-logs.ts +0 -142
  84. package/runtime-src/settings.ts +0 -221
  85. package/runtime-src/single-binary.ts +0 -143
  86. package/runtime-src/site-policy.ts +0 -54
  87. package/runtime-src/stale-cleanup-runner.ts +0 -144
  88. package/runtime-src/stale-cleanup.ts +0 -133
  89. package/runtime-src/telemetry-attribution.ts +0 -120
  90. package/runtime-src/telemetry.ts +0 -253
  91. package/runtime-src/template-params.ts +0 -141
  92. package/runtime-src/transform/drift.ts +0 -60
  93. package/runtime-src/transform/index.ts +0 -277
  94. package/runtime-src/types/index.ts +0 -1
  95. package/runtime-src/types/skill.ts +0 -931
  96. package/runtime-src/vault/index.ts +0 -196
  97. package/runtime-src/verification/auth-gate.ts +0 -8
  98. package/runtime-src/verification/candidates.ts +0 -27
  99. package/runtime-src/verification/index.ts +0 -120
  100. package/runtime-src/verification/matrix.ts +0 -30
  101. package/runtime-src/version.ts +0 -148
  102. package/runtime-src/workflow/artifact.ts +0 -161
  103. package/runtime-src/workflow/compile.ts +0 -808
  104. package/runtime-src/workflow/publish.ts +0 -225
  105. package/runtime-src/workflow/runtime.ts +0 -213
@@ -1,1734 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * Unbrowse CLI — shell-safe wrapper for the local API.
4
- * Eliminates curl + jq escaping issues. All JSON is constructed
5
- * and parsed in TypeScript, never through shell interpolation.
6
- *
7
- * Usage: unbrowse <command> [flags]
8
- */
9
-
10
- import { config as loadEnv } from "dotenv";
11
- import { spawn } from "node:child_process";
12
- import {
13
- detectTelemetryHostType,
14
- ensureCliInstallTracked,
15
- ensureRegistered,
16
- getAgentId,
17
- getApiKey,
18
- getCreatorEarnings,
19
- getMyProfile,
20
- getTransactionHistory,
21
- recordFunnelTelemetryEvent,
22
- recordInstallTelemetryEvent,
23
- } from "./client/index.js";
24
- import { appendImpact, getImpactLogPath, impactFromResult, readImpactSummary } from "./impact-log.js";
25
- import { findSitePack, findTask, allSitePacks, buildDepsGraph, planExecution, buildDepsMetadata, type SitePack } from "./cli/shortcuts.js";
26
- import { ensureLocalServer, checkServerVersion, stopServer, restartServer } from "./runtime/local-server.js";
27
- import { isBundledVirtualEntrypoint, isMainModule, resolveSiblingEntrypoint, runtimeArgsForEntrypoint } from "./runtime/paths.js";
28
- import { drainPendingIndexJobs } from "./indexer/index.js";
29
- import { drainPendingPassivePublishes } from "./orchestrator/passive-publish.js";
30
- import { runSetup, type SetupReport, type SetupScope } from "./runtime/setup.js";
31
- import { checkForUpdates, recordUpdateHint } from "./runtime/update-hints.js";
32
-
33
- loadEnv({ quiet: true });
34
- loadEnv({ path: ".env.runtime", quiet: true });
35
-
36
- const BASE_URL = process.env.UNBROWSE_URL || "http://localhost:6969";
37
- const CLI_CLIENT_ID = process.env.UNBROWSE_CLIENT_ID || `cli-${process.ppid || process.pid}`;
38
- let walletNudgeShown = false;
39
-
40
- // ---------------------------------------------------------------------------
41
- // Arg parser
42
- // ---------------------------------------------------------------------------
43
-
44
- export function parseArgs(argv: string[]): { command: string; args: string[]; flags: Record<string, string | boolean> } {
45
- const raw = argv.slice(2); // skip runtime + script
46
- const command = raw[0] && !raw[0].startsWith("--") ? raw[0] : "help";
47
- const rest = command === "help" ? raw : raw.slice(1);
48
- const positional: string[] = [];
49
- const flags: Record<string, string | boolean> = {};
50
- for (let i = 0; i < rest.length; i++) {
51
- const a = rest[i];
52
- if (a.startsWith("--")) {
53
- const key = a.slice(2);
54
- const next = rest[i + 1];
55
- if (!next || next.startsWith("--")) {
56
- flags[key] = true;
57
- } else {
58
- flags[key] = next;
59
- i++;
60
- }
61
- } else {
62
- positional.push(a);
63
- }
64
- }
65
- return { command, args: positional, flags };
66
- }
67
-
68
- // ---------------------------------------------------------------------------
69
- // HTTP helpers
70
- // ---------------------------------------------------------------------------
71
-
72
- async function api(method: string, path: string, body?: unknown): Promise<unknown> {
73
- let target = `${BASE_URL}${path}`;
74
- let requestBody = body;
75
- if (method === "GET" && body && typeof body === "object") {
76
- const params = new URLSearchParams();
77
- for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
78
- if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
79
- params.set(key, String(value));
80
- }
81
- }
82
- const query = params.toString();
83
- if (query) target += `${target.includes("?") ? "&" : "?"}${query}`;
84
- requestBody = undefined;
85
- }
86
- const res = await fetch(target, {
87
- method,
88
- headers: {
89
- ...(requestBody ? { "Content-Type": "application/json" } : {}),
90
- "x-unbrowse-client-id": CLI_CLIENT_ID,
91
- },
92
- body: requestBody ? JSON.stringify(requestBody) : undefined,
93
- });
94
- if (!res.ok && res.headers.get("content-type")?.includes("json")) {
95
- return res.json();
96
- }
97
- if (!res.ok) {
98
- return { error: `HTTP ${res.status}: ${await res.text()}` };
99
- }
100
- return res.json();
101
- }
102
-
103
- function output(data: unknown, pretty = false): void {
104
- process.stdout.write((pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data)) + "\n");
105
- }
106
-
107
- function die(msg: string): never {
108
- output({ error: msg });
109
- process.exit(1);
110
- }
111
-
112
- function info(msg: string): void {
113
- process.stderr.write(`[unbrowse] ${msg}\n`);
114
- }
115
-
116
- function resolveResultError(result: Record<string, unknown>): string | undefined {
117
- return (result.result as Record<string, unknown> | undefined)?.error as string | undefined
118
- ?? result.error as string | undefined;
119
- }
120
-
121
- function resolveLoginUrl(result: Record<string, unknown>, fallbackUrl?: string): string {
122
- return (result.result as Record<string, unknown> | undefined)?.login_url as string
123
- ?? fallbackUrl
124
- ?? "";
125
- }
126
-
127
- function isResolveSuccessResult(result: Record<string, unknown>): boolean {
128
- if (resolveResultError(result)) return false;
129
- return !!result.result || Array.isArray(result.available_endpoints);
130
- }
131
-
132
- async function withPendingNotice<T>(promise: Promise<T>, message: string, delayMs = 3_000): Promise<T> {
133
- let done = false;
134
- const timer = setTimeout(() => {
135
- if (!done) info(message);
136
- }, delayMs);
137
- try {
138
- return await promise;
139
- } finally {
140
- done = true;
141
- clearTimeout(timer);
142
- }
143
- }
144
-
145
- function normalizeSetupScope(value: string | boolean | undefined): SetupScope {
146
- if (value === true || value == null) return "auto";
147
- const normalized = String(value).trim().toLowerCase();
148
- if (normalized === "global" || normalized === "project" || normalized === "off") return normalized;
149
- return "auto";
150
- }
151
-
152
- // ---------------------------------------------------------------------------
153
- // Slim output — keep only essential trace metadata + result
154
- // ---------------------------------------------------------------------------
155
-
156
- function slimTrace(obj: Record<string, unknown>): Record<string, unknown> {
157
- const trace = obj.trace as Record<string, unknown> | undefined;
158
- const out: Record<string, unknown> = {
159
- trace: trace
160
- ? {
161
- trace_id: trace.trace_id,
162
- skill_id: trace.skill_id,
163
- endpoint_id: trace.endpoint_id,
164
- success: trace.success,
165
- status_code: trace.status_code,
166
- trace_version: trace.trace_version,
167
- ...(trace.schema_backfilled ? { schema_backfilled: true } : {}),
168
- }
169
- : undefined,
170
- };
171
- if (typeof obj.error === "string") out.error = obj.error;
172
- if (typeof obj.message === "string") out.message = obj.message;
173
- if (typeof obj.hint === "string") out.hint = obj.hint;
174
- if (typeof obj.login_url === "string") out.login_url = obj.login_url;
175
- if (typeof obj.provider === "string") out.provider = obj.provider;
176
- if ("result" in obj) out.result = obj.result;
177
- if (obj.available_endpoints) out.available_endpoints = obj.available_endpoints;
178
- if (obj.impact) out.impact = obj.impact;
179
- if (obj.next_actions) out.next_actions = obj.next_actions;
180
- if (obj.next_step) out.next_step = obj.next_step;
181
- if (obj.source) out.source = obj.source;
182
- if (obj.skill) out.skill = obj.skill;
183
- return out;
184
- }
185
-
186
- function formatSavedDuration(ms: number): string {
187
- if (ms >= 60_000) return `${(ms / 60_000).toFixed(1)}m`;
188
- if (ms >= 10_000) return `${Math.round(ms / 1000)}s`;
189
- if (ms >= 1000) return `${(ms / 1000).toFixed(1)}s`;
190
- return `${ms}ms`;
191
- }
192
-
193
- function formatCostUsd(uc: number): string {
194
- // uc = micro-USD (1e-6 USD). 1M uc = $1.
195
- const usd = uc / 1_000_000;
196
- if (usd >= 1) return `$${usd.toFixed(2)}`;
197
- if (usd >= 0.01) return `$${usd.toFixed(3)}`;
198
- return `$${usd.toFixed(4)}`;
199
- }
200
-
201
- function emitImpactSummary(result: Record<string, unknown>): void {
202
- const impact = result.impact as Record<string, unknown> | undefined;
203
- if (!impact) return;
204
-
205
- const timeSavedMs = typeof impact.time_saved_ms === "number" ? impact.time_saved_ms : 0;
206
- const tokensSaved = typeof impact.tokens_saved === "number" ? impact.tokens_saved : 0;
207
- const timeSavedPct = typeof impact.time_saved_pct === "number" ? impact.time_saved_pct : 0;
208
- const tokensSavedPct = typeof impact.tokens_saved_pct === "number" ? impact.tokens_saved_pct : 0;
209
- const costSavedUc = typeof impact.cost_saved_uc === "number" ? impact.cost_saved_uc : 0;
210
- const browserAvoided = impact.browser_avoided === true;
211
- if (timeSavedMs <= 0 && tokensSaved <= 0 && costSavedUc <= 0 && !browserAvoided) return;
212
-
213
- const parts: string[] = [];
214
- if (timeSavedMs > 0) parts.push(`${formatSavedDuration(timeSavedMs)} saved (${timeSavedPct}% faster)`);
215
- if (tokensSaved > 0) parts.push(`${tokensSaved.toLocaleString("en-US")} tokens saved (${tokensSavedPct}% less context)`);
216
- if (costSavedUc > 0) parts.push(`${formatCostUsd(costSavedUc)} saved`);
217
- if (browserAvoided) parts.push("browser avoided");
218
- info(parts.join(" • "));
219
- }
220
-
221
- function emitNextActionSummary(result: Record<string, unknown>): void {
222
- const nextActions = Array.isArray(result.next_actions)
223
- ? result.next_actions as Array<Record<string, unknown>>
224
- : [];
225
- if (nextActions.length === 0) return;
226
- info("Likely next actions:");
227
- for (const action of nextActions.slice(0, 3)) {
228
- const command = typeof action.command === "string" ? action.command : "";
229
- const title = typeof action.title === "string" ? action.title : (action.endpoint_id as string | undefined) ?? "next step";
230
- const why = typeof action.why === "string" ? action.why : "";
231
- info(` ${command || title}${why ? ` # ${why}` : ""}`);
232
- }
233
- }
234
-
235
-
236
- async function cmdHealth(flags: Record<string, string | boolean>): Promise<void> {
237
- output(await api("GET", "/health"), !!flags.pretty);
238
- }
239
-
240
- function telemetryDomainFromInput(domain?: string, url?: string): string | null {
241
- if (domain?.trim()) return domain.trim().replace(/^www\./, "");
242
- if (!url?.trim()) return null;
243
- try {
244
- return new URL(url).hostname.replace(/^www\./, "");
245
- } catch {
246
- return null;
247
- }
248
- }
249
-
250
- async function cmdResolve(flags: Record<string, string | boolean>): Promise<void> {
251
- const intent = flags.intent as string;
252
- if (!intent) die("--intent is required");
253
- const hostType = detectTelemetryHostType();
254
- await ensureCliInstallTracked(hostType);
255
- await recordFunnelTelemetryEvent("cli_invoked", {
256
- source: "cli",
257
- hostType,
258
- properties: { command: "resolve" },
259
- });
260
- await recordFunnelTelemetryEvent("resolve_started", {
261
- source: "cli",
262
- hostType,
263
- properties: {
264
- command: "resolve",
265
- intent,
266
- domain: telemetryDomainFromInput(flags.domain as string | undefined, flags.url as string | undefined),
267
- url: typeof flags.url === "string" ? flags.url : null,
268
- has_url: typeof flags.url === "string",
269
- has_domain: typeof flags.domain === "string",
270
- auto_execute: !!flags.execute,
271
- },
272
- });
273
-
274
- try {
275
- const body: Record<string, unknown> = { intent };
276
- const url = flags.url as string | undefined;
277
- const domain = flags.domain as string | undefined;
278
- const explicitEndpointId = flags["endpoint-id"] as string | undefined;
279
- const autoExecute = !!flags.execute;
280
- const extraParams = flags.params ? JSON.parse(flags.params as string) : {};
281
-
282
- if (url) {
283
- body.params = { url };
284
- body.context = { url };
285
- }
286
- if (domain) {
287
- body.context = { ...(body.context as Record<string, unknown> ?? {}), domain };
288
- }
289
- if (explicitEndpointId) {
290
- body.params = { ...(body.params as Record<string, unknown> ?? {}), endpoint_id: explicitEndpointId };
291
- }
292
- if (flags.params) {
293
- body.params = { ...(body.params as Record<string, unknown> ?? {}), ...extraParams };
294
- }
295
- if (flags["dry-run"]) body.dry_run = true;
296
- if (flags["confirm-third-party-terms"]) body.confirm_third_party_terms = true;
297
- if (flags["force-capture"]) body.force_capture = true;
298
- body.projection = { raw: true };
299
-
300
- function execBody(endpointId: string): Record<string, unknown> {
301
- return {
302
- params: { endpoint_id: endpointId, ...extraParams },
303
- intent,
304
- projection: { raw: true },
305
- ...(flags["confirm-third-party-terms"] ? { confirm_third_party_terms: true } : {}),
306
- };
307
- }
308
-
309
- function endpointNeedsThirdPartyTermsConfirmation(endpoint: Record<string, unknown>): boolean {
310
- return endpoint.requires_third_party_terms_confirmation === true;
311
- }
312
-
313
- function resolveSkillId(): string | undefined {
314
- return (result.skill as Record<string, unknown>)?.skill_id as string
315
- ?? (result as Record<string, unknown>).skill_id as string;
316
- }
317
-
318
- const startedAt = Date.now();
319
- async function resolveOnce(message = "Still working. Searching cached routes..."): Promise<Record<string, unknown>> {
320
- return withPendingNotice(
321
- api("POST", "/v1/intent/resolve", body) as Promise<Record<string, unknown>>,
322
- message,
323
- );
324
- }
325
-
326
- let result = await resolveOnce();
327
- const resultError = resolveResultError(result);
328
- if (resultError === "auth_required") {
329
- const loginUrl = resolveLoginUrl(result, url);
330
- if (loginUrl) info(`Authentication required. Run: unbrowse login --url "${loginUrl}"`);
331
- }
332
-
333
- // When agent explicitly picked an endpoint but resolve deferred, execute it directly
334
- if (explicitEndpointId && result.available_endpoints) {
335
- const skillId = resolveSkillId();
336
- if (skillId) {
337
- result = await withPendingNotice(
338
- api("POST", `/v1/skills/${skillId}/execute`, execBody(explicitEndpointId)) as Promise<Record<string, unknown>>,
339
- "Executing selected endpoint...",
340
- );
341
- }
342
- }
343
-
344
- // --execute: auto-pick best endpoint and return data in one step
345
- if (autoExecute && result.available_endpoints && !result.result) {
346
- const endpoints = result.available_endpoints as Array<Record<string, unknown>>;
347
- const skillId = resolveSkillId();
348
- if (skillId && endpoints.length > 0) {
349
- const bestEndpoint = endpoints[0];
350
- if (endpointNeedsThirdPartyTermsConfirmation(bestEndpoint) && !flags["confirm-third-party-terms"]) {
351
- info(
352
- `Auto-execute skipped: ${bestEndpoint.description ?? bestEndpoint.endpoint_id} requires explicit third-party terms confirmation`
353
- + (typeof bestEndpoint.third_party_terms_policy_domain === "string" ? ` for ${bestEndpoint.third_party_terms_policy_domain}` : "")
354
- + ". Re-run with --confirm-third-party-terms only after the user explicitly confirms.",
355
- );
356
- output(result, !!flags.pretty);
357
- return;
358
- }
359
- info(`Auto-executing endpoint: ${bestEndpoint.description ?? bestEndpoint.endpoint_id}`);
360
- result = await withPendingNotice(
361
- api("POST", `/v1/skills/${skillId}/execute`, execBody(bestEndpoint.endpoint_id as string)) as Promise<Record<string, unknown>>,
362
- "Executing best endpoint...",
363
- );
364
- }
365
- }
366
-
367
- if (Date.now() - startedAt > 3_000 && result.source === "live-capture") {
368
- info("Live capture finished. Future runs against this site should be much faster.");
369
- }
370
-
371
- if (isResolveSuccessResult(result)) {
372
- await recordFunnelTelemetryEvent("resolve_completed", {
373
- source: "cli",
374
- hostType,
375
- properties: {
376
- command: "resolve",
377
- intent,
378
- domain: telemetryDomainFromInput(domain, url),
379
- url: url ?? null,
380
- source: result.source,
381
- auto_execute: autoExecute,
382
- explicit_endpoint: explicitEndpointId ?? null,
383
- },
384
- });
385
- }
386
-
387
- result = slimTrace(result);
388
- emitImpactSummary(result);
389
- {
390
- const entry = impactFromResult("resolve", result, { intent, domain, });
391
- if (entry) appendImpact(entry);
392
- }
393
- emitNextActionSummary(result);
394
-
395
- const skill = result.skill as Record<string, unknown> | undefined;
396
- const trace = result.trace as Record<string, unknown> | undefined;
397
-
398
- // Nudge wallet setup after successful resolve that indexed routes
399
- if (trace?.success && !walletNudgeShown) {
400
- try {
401
- const { checkWalletConfigured } = await import("./payments/wallet.js");
402
- const wallet = checkWalletConfigured();
403
- if (!wallet.configured) {
404
- info("You're indexing routes but have no payout wallet. Run: npx @crossmint/lobster-cli setup");
405
- walletNudgeShown = true;
406
- }
407
- } catch (_e) { /* non-fatal */ }
408
- }
409
-
410
- if (skill?.skill_id && trace) {
411
- (result as Record<string, unknown>)._feedback = `unbrowse feedback --skill ${skill.skill_id} --endpoint ${trace.endpoint_id || "?"} --rating <1-5>`;
412
- }
413
-
414
- output(result, !!flags.pretty);
415
- } catch (error) {
416
- const message = error instanceof Error ? error.message : String(error);
417
- await recordFunnelTelemetryEvent("resolve_failed", {
418
- source: "cli",
419
- hostType,
420
- properties: {
421
- command: "resolve",
422
- intent,
423
- domain: telemetryDomainFromInput(flags.domain as string | undefined, flags.url as string | undefined),
424
- url: typeof flags.url === "string" ? flags.url : null,
425
- failure_stage: "resolve",
426
- failure_reason: message,
427
- },
428
- });
429
- throw error;
430
- }
431
- }
432
-
433
- // ---------------------------------------------------------------------------
434
- // Post-processing helpers for --path, --extract, --limit, --schema
435
- // ---------------------------------------------------------------------------
436
-
437
- /** Drill into a value using a dot-path like "data.items[].name".
438
- * `[]` flattens arrays at that level so nested arrays become flat collections. */
439
- function drillPath(data: unknown, path: string): unknown {
440
- const segments = path.split(/\./).flatMap((s) => {
441
- // "items[]" → ["items", "[]"]
442
- const m = s.match(/^(.+)\[\]$/);
443
- return m ? [m[1], "[]"] : [s];
444
- });
445
- // Work with an array of "current values" to handle multi-level flattening
446
- let values: unknown[] = [data];
447
- for (const seg of segments) {
448
- if (values.length === 0) return [];
449
- if (seg === "[]") {
450
- // Flatten: each value that is an array gets its elements spread out
451
- values = values.flatMap((v) => (Array.isArray(v) ? v : [v]));
452
- continue;
453
- }
454
- // Drill into each value
455
- values = values.flatMap((v) => {
456
- if (v == null) return [];
457
- if (Array.isArray(v)) {
458
- // Auto-flatten arrays even without explicit []
459
- return v.map((item) => (item as Record<string, unknown>)?.[seg]).filter((x) => x !== undefined);
460
- }
461
- if (typeof v === "object") {
462
- const val = (v as Record<string, unknown>)[seg];
463
- return val !== undefined ? [val] : [];
464
- }
465
- return [];
466
- });
467
- }
468
- return values;
469
- }
470
-
471
- /** Resolve a dot-path on a single object, e.g. "core.user_results.result.core.screen_name" */
472
- function resolveDotPath(obj: unknown, path: string): unknown {
473
- let cur = obj;
474
- for (const key of path.split(".")) {
475
- if (cur == null || typeof cur !== "object") return undefined;
476
- cur = (cur as Record<string, unknown>)[key];
477
- }
478
- return cur;
479
- }
480
-
481
- /** Apply --extract field spec: "alias:deep.path,field2,alias2:path" */
482
- function applyExtract(items: unknown[], extractSpec: string): unknown[] {
483
- const fields = extractSpec.split(",").map((f) => {
484
- const colon = f.indexOf(":");
485
- if (colon > 0) return { alias: f.slice(0, colon), path: f.slice(colon + 1) };
486
- return { alias: f, path: f };
487
- });
488
- return items
489
- .map((item) => {
490
- const row: Record<string, unknown> = {};
491
- let hasValue = false;
492
- for (const { alias, path } of fields) {
493
- const val = resolveDotPath(item, path);
494
- row[alias] = val ?? null;
495
- if (val != null) hasValue = true;
496
- }
497
- return hasValue ? row : null;
498
- })
499
- .filter((row): row is Record<string, unknown> => row !== null);
500
- }
501
-
502
- /** Build a compact schema tree from a value (depth-limited). */
503
- function schemaOf(value: unknown, depth = 4): unknown {
504
- if (value == null) return "null";
505
- if (Array.isArray(value)) {
506
- if (value.length === 0) return ["unknown"];
507
- return [schemaOf(value[0], depth - 1)];
508
- }
509
- if (typeof value === "object") {
510
- if (depth <= 0) return "object";
511
- const out: Record<string, unknown> = {};
512
- for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
513
- out[k] = schemaOf(v, depth - 1);
514
- }
515
- return out;
516
- }
517
- return typeof value;
518
- }
519
-
520
- async function cmdExecute(flags: Record<string, string | boolean>): Promise<void> {
521
- const skillId = flags.skill as string;
522
- if (!skillId) die("--skill is required");
523
- const hostType = detectTelemetryHostType();
524
- await ensureCliInstallTracked(hostType);
525
- await recordFunnelTelemetryEvent("cli_invoked", {
526
- source: "cli",
527
- hostType,
528
- properties: { command: "execute" },
529
- });
530
- await recordFunnelTelemetryEvent("resolve_started", {
531
- source: "cli",
532
- hostType,
533
- properties: {
534
- command: "execute",
535
- intent: typeof flags.intent === "string" ? flags.intent : null,
536
- domain: telemetryDomainFromInput(undefined, flags.url as string | undefined),
537
- url: typeof flags.url === "string" ? flags.url : null,
538
- skill_id: skillId,
539
- endpoint_id: typeof flags.endpoint === "string" ? flags.endpoint : null,
540
- },
541
- });
542
-
543
- try {
544
- const body: Record<string, unknown> = { params: {} };
545
- if (flags.endpoint) {
546
- (body.params as Record<string, unknown>).endpoint_id = flags.endpoint;
547
- }
548
- if (flags.params) {
549
- body.params = { ...(body.params as Record<string, unknown>), ...JSON.parse(flags.params as string) };
550
- }
551
- if (flags.url) {
552
- body.context_url = flags.url;
553
- (body.params as Record<string, unknown>).url = flags.url;
554
- }
555
- if (flags.intent) body.intent = flags.intent;
556
- if (flags["dry-run"]) body.dry_run = true;
557
- if (flags["confirm-unsafe"]) body.confirm_unsafe = true;
558
- if (flags["confirm-third-party-terms"]) body.confirm_third_party_terms = true;
559
- body.projection = { raw: true };
560
-
561
- let result = await withPendingNotice(
562
- api("POST", `/v1/skills/${skillId}/execute`, body) as Promise<Record<string, unknown>>,
563
- "Still working. This endpoint may require browser replay or first-time auth/capture setup.",
564
- );
565
-
566
- if (isResolveSuccessResult(result)) {
567
- await recordFunnelTelemetryEvent("resolve_completed", {
568
- source: "cli",
569
- hostType,
570
- properties: {
571
- command: "execute",
572
- intent: typeof flags.intent === "string" ? flags.intent : null,
573
- domain: telemetryDomainFromInput(undefined, flags.url as string | undefined),
574
- url: typeof flags.url === "string" ? flags.url : null,
575
- skill_id: skillId,
576
- endpoint_id: typeof flags.endpoint === "string" ? flags.endpoint : null,
577
- },
578
- });
579
- }
580
-
581
- // Strip metadata bloat
582
- result = slimTrace(result);
583
- emitImpactSummary(result);
584
- {
585
- const entry = impactFromResult("execute", result, {
586
- skill_id: skillId,
587
- endpoint_id: typeof flags.endpoint === "string" ? flags.endpoint : undefined,
588
- });
589
- if (entry) appendImpact(entry);
590
- }
591
- emitNextActionSummary(result);
592
-
593
- const pathFlag = flags.path as string | undefined;
594
- const extractFlag = flags.extract as string | undefined;
595
- const limitFlag = flags.limit ? Number(flags.limit) : undefined;
596
- const schemaFlag = !!flags.schema;
597
- const rawFlag = !!flags.raw;
598
-
599
- // --schema: show response structure without data
600
- if (schemaFlag && !rawFlag) {
601
- const data = result.result;
602
- output({
603
- trace: result.trace,
604
- schema: schemaOf(data),
605
- ...(result.impact ? { impact: result.impact } : {}),
606
- ...(result.next_actions ? { next_actions: result.next_actions } : {}),
607
- }, !!flags.pretty);
608
- return;
609
- }
610
-
611
- // Apply --path, --extract, --limit when not --raw
612
- if (!rawFlag && (pathFlag || extractFlag || limitFlag)) {
613
- const data = pathFlag ? drillPath(result.result, pathFlag) : result.result;
614
-
615
- // Ensure array for extract/limit
616
- const items = Array.isArray(data) ? data : data != null ? [data] : [];
617
-
618
- // Apply --extract
619
- const extracted = extractFlag ? applyExtract(items, extractFlag) : items;
620
-
621
- // Apply --limit
622
- const limited = limitFlag ? extracted.slice(0, limitFlag) : extracted;
623
-
624
- const trace = result.trace as Record<string, unknown> | undefined;
625
- const out: Record<string, unknown> = {
626
- trace: result.trace,
627
- data: limited,
628
- count: limited.length,
629
- ...(result.impact ? { impact: result.impact } : {}),
630
- ...(result.next_actions ? { next_actions: result.next_actions } : {}),
631
- };
632
-
633
- // Prompt agent to review when this is likely a first-time execute
634
- if (trace?.skill_id && trace?.endpoint_id && limited.length > 0) {
635
- out._review_hint =
636
- `After presenting results, review this endpoint's contract: description plus request/response schema notes where needed. Example: unbrowse review --skill ${trace.skill_id} --endpoints '[{"endpoint_id":"${trace.endpoint_id}","description":"DESCRIBE WHAT THIS RETURNS AND ANY IMPORTANT CONSTRAINTS","action_kind":"ACTION","resource_kind":"RESOURCE","parameter_reviews":[{"location":"query","name":"q","description":"Search query text","type":"string","required":true}],"response_reviews":[{"path":"items[].url","description":"Canonical result URL","type":"string"}]}]'`;
637
- }
638
-
639
- output(out, !!flags.pretty);
640
- return;
641
- }
642
-
643
- // Auto-wrap large responses with extraction_hints when no flags given
644
- if (!rawFlag && !pathFlag && !extractFlag && !schemaFlag) {
645
- const raw = JSON.stringify(result.result);
646
- if (raw && raw.length > 2048) {
647
- const schema = schemaOf(result.result);
648
- output({
649
- trace: result.trace,
650
- ...(result.impact ? { impact: result.impact } : {}),
651
- ...(result.next_actions ? { next_actions: result.next_actions } : {}),
652
- extraction_hints: {
653
- message: "Response is large. Use --path/--extract/--limit to filter, or --schema to see structure, or --raw for full response.",
654
- schema_tree: schema,
655
- response_bytes: raw.length,
656
- },
657
- }, !!flags.pretty);
658
- return;
659
- }
660
- }
661
-
662
- output(result, !!flags.pretty);
663
- } catch (error) {
664
- const message = error instanceof Error ? error.message : String(error);
665
- await recordFunnelTelemetryEvent("resolve_failed", {
666
- source: "cli",
667
- hostType,
668
- properties: {
669
- command: "execute",
670
- intent: typeof flags.intent === "string" ? flags.intent : null,
671
- domain: telemetryDomainFromInput(undefined, flags.url as string | undefined),
672
- url: typeof flags.url === "string" ? flags.url : null,
673
- skill_id: skillId,
674
- failure_stage: "execute",
675
- failure_reason: message,
676
- },
677
- });
678
- throw error;
679
- }
680
- }
681
-
682
- async function cmdFeedback(flags: Record<string, string | boolean>): Promise<void> {
683
- const skillId = flags.skill as string;
684
- const endpointId = flags.endpoint as string;
685
- const rating = Number(flags.rating);
686
- if (!skillId || !endpointId || !rating) die("--skill, --endpoint, and --rating are required");
687
-
688
- const body: Record<string, unknown> = {
689
- skill_id: skillId,
690
- endpoint_id: endpointId,
691
- rating,
692
- };
693
- if (flags.outcome) body.outcome = flags.outcome;
694
- if (flags.diagnostics) body.diagnostics = JSON.parse(flags.diagnostics as string);
695
-
696
- output(await api("POST", "/v1/feedback", body), !!flags.pretty);
697
- }
698
-
699
- async function cmdReview(flags: Record<string, string | boolean>): Promise<void> {
700
- const skillId = flags.skill as string;
701
- if (!skillId) die("--skill is required");
702
- const endpointsJson = flags.endpoints as string;
703
- if (!endpointsJson) die("--endpoints is required (JSON array of {endpoint_id, description?, action_kind?, resource_kind?, parameter_reviews?, response_reviews?})");
704
- const endpoints = JSON.parse(endpointsJson) as Array<Record<string, unknown>>;
705
- if (!Array.isArray(endpoints) || endpoints.length === 0) die("--endpoints must be a non-empty JSON array");
706
- output(await api("POST", `/v1/skills/${skillId}/review`, { endpoints }), !!flags.pretty);
707
- }
708
-
709
- function parseCsvFlag(value: string | boolean | undefined): string[] | undefined {
710
- if (typeof value !== "string") return undefined;
711
- const parts = value
712
- .split(",")
713
- .map((entry) => entry.trim())
714
- .filter(Boolean);
715
- return parts.length > 0 ? parts : [];
716
- }
717
-
718
- async function cmdIndex(flags: Record<string, string | boolean>): Promise<void> {
719
- const skillId = flags.skill as string;
720
- if (!skillId) die("--skill is required");
721
- output(await api("POST", `/v1/skills/${skillId}/index`, {}), !!flags.pretty);
722
- }
723
-
724
- async function cmdPublish(flags: Record<string, string | boolean>): Promise<void> {
725
- const skillId = flags.skill as string;
726
- if (!skillId) die("--skill is required");
727
- const endpointsJson = flags.endpoints as string | undefined;
728
- const confirmPublish = flags["confirm-publish"] === true;
729
- if (endpointsJson) {
730
- // Phase 2: merge descriptions + publish
731
- const endpoints = JSON.parse(endpointsJson) as Array<Record<string, unknown>>;
732
- if (!Array.isArray(endpoints) || endpoints.length === 0) die("--endpoints must be a non-empty JSON array");
733
- output(await api("POST", `/v1/skills/${skillId}/publish`, {
734
- endpoints,
735
- ...(confirmPublish ? { confirm_publish: true } : {}),
736
- }), !!flags.pretty);
737
- } else {
738
- // Phase 1: return endpoints needing descriptions
739
- output(await api("POST", `/v1/skills/${skillId}/publish`, {
740
- ...(confirmPublish ? { confirm_publish: true } : {}),
741
- }), !!flags.pretty);
742
- }
743
- }
744
-
745
- async function cmdPublishBundle(flags: Record<string, string | boolean>): Promise<void> {
746
- const presetPath = flags.preset as string;
747
- if (!presetPath) die("--preset is required");
748
- const hosts = typeof flags.hosts === "string"
749
- ? flags.hosts.split(",").map((host) => host.trim()).filter(Boolean)
750
- : undefined;
751
- output(await api("POST", "/v1/foundry/publish-bundle", {
752
- preset_path: presetPath,
753
- ...(typeof flags["site-url"] === "string" ? { site_url: flags["site-url"] } : {}),
754
- ...(hosts?.length ? { hosts } : {}),
755
- }), !!flags.pretty);
756
- }
757
-
758
- async function cmdSettings(flags: Record<string, string | boolean>): Promise<void> {
759
- const body: Record<string, unknown> = {};
760
- if (typeof flags["auto-publish"] === "string") {
761
- const normalized = String(flags["auto-publish"]).trim().toLowerCase();
762
- if (normalized !== "on" && normalized !== "off") die("--auto-publish must be on or off");
763
- body.auto_publish_checkpoints = normalized === "on";
764
- }
765
-
766
- const blacklist = parseCsvFlag(flags["publish-blacklist"]);
767
- if (blacklist) body.publish_domain_blacklist = blacklist;
768
- const promptlist = parseCsvFlag(flags["publish-promptlist"]);
769
- if (promptlist) body.publish_domain_promptlist = promptlist;
770
- if (flags["clear-publish-blacklist"] === true) body.clear_publish_domain_blacklist = true;
771
- if (flags["clear-publish-promptlist"] === true) body.clear_publish_domain_promptlist = true;
772
-
773
- const hasMutation = Object.keys(body).length > 0;
774
- output(
775
- await api(hasMutation ? "POST" : "GET", "/v1/settings", hasMutation ? body : undefined),
776
- !!flags.pretty,
777
- );
778
- }
779
-
780
- async function cmdLogin(flags: Record<string, string | boolean>): Promise<void> {
781
- const url = flags.url as string;
782
- if (!url) die("--url is required");
783
- output(await api("POST", "/v1/auth/login", { url }), !!flags.pretty);
784
- }
785
-
786
- async function cmdSkills(flags: Record<string, string | boolean>): Promise<void> {
787
- output(await api("GET", "/v1/skills"), !!flags.pretty);
788
- }
789
-
790
- async function cmdSkill(args: string[], flags: Record<string, string | boolean>): Promise<void> {
791
- const id = args[0] ?? flags.id as string;
792
- if (!id) die("skill <id> or --id required");
793
- output(await api("GET", `/v1/skills/${id}`), !!flags.pretty);
794
- }
795
-
796
- async function cmdCleanupStale(flags: Record<string, string | boolean>): Promise<void> {
797
- const body: Record<string, unknown> = {};
798
- if (typeof flags.skill === "string") body.skill_id = flags.skill;
799
- if (typeof flags.domain === "string") body.domain = flags.domain;
800
- if (typeof flags.limit === "string") body.limit = Number(flags.limit);
801
- output(
802
- await withPendingNotice(api("POST", "/v1/stale/cleanup", body), "Cleaning stale endpoints..."),
803
- !!flags.pretty,
804
- );
805
- }
806
-
807
- async function cmdSearch(flags: Record<string, string | boolean>): Promise<void> {
808
- await cmdResolve(flags);
809
- }
810
-
811
- async function cmdSessions(flags: Record<string, string | boolean>): Promise<void> {
812
- const domain = flags.domain as string;
813
- if (!domain) die("--domain is required");
814
- const limit = flags.limit ?? "10";
815
- output(await api("GET", `/v1/sessions/${domain}?limit=${limit}`), !!flags.pretty);
816
- }
817
-
818
- async function cmdSetup(flags: Record<string, string | boolean>): Promise<void> {
819
- const hostType = detectTelemetryHostType();
820
- await ensureCliInstallTracked(hostType);
821
- await recordFunnelTelemetryEvent("cli_invoked", {
822
- source: "setup",
823
- hostType,
824
- properties: { command: "setup" },
825
- });
826
- info("Running setup checks");
827
- const report = await runSetup({
828
- cwd: process.cwd(),
829
- opencode: normalizeSetupScope(flags.opencode),
830
- installBrowser: !flags["skip-browser"],
831
- }) as SetupReport & {
832
- server?: {
833
- started: boolean;
834
- skipped?: boolean;
835
- base_url?: string;
836
- error?: string;
837
- };
838
- };
839
-
840
- if (report.browser_engine.action === "failed") {
841
- info("Browser engine install failed");
842
- } else if (report.browser_engine.action === "installed") {
843
- info("Browser engine installed");
844
- }
845
-
846
- if (report.opencode.action === "installed" || report.opencode.action === "updated") {
847
- info(`Open Code command installed at ${report.opencode.command_file}`);
848
- }
849
- for (const hook of report.update_hints) {
850
- if (hook.action === "installed" || hook.action === "updated") {
851
- info(`${hook.host} update hint hook ${hook.action} at ${hook.config_file}`);
852
- }
853
- }
854
-
855
- // Wallet status — tell the user if they're missing payout config
856
- if (report.wallet.configured) {
857
- info(`Wallet configured (${report.wallet.provider}): ${(report.wallet as Record<string, unknown>).wallet_address ?? "linked"}`);
858
- } else if ((report.wallet as Record<string, unknown>).lobster_installed) {
859
- info("Wallet not paired — your indexed routes won't earn payouts.");
860
- info("Run: npx @crossmint/lobster-cli setup");
861
- } else {
862
- info("No wallet configured — you're indexing routes for free.");
863
- info("Set up a wallet so you earn when agents use your routes:");
864
- info(" npx @crossmint/lobster-cli setup");
865
- }
866
-
867
- await recordInstallTelemetryEvent("setup", {
868
- hostType,
869
- status: report.browser_engine.action === "failed" ? "failed" : "installed",
870
- properties: {
871
- browser_engine_action: report.browser_engine.action,
872
- opencode_action: report.opencode.action,
873
- no_start: !!flags["no-start"],
874
- skip_browser: !!flags["skip-browser"],
875
- },
876
- });
877
- await recordFunnelTelemetryEvent("setup_completed", {
878
- source: "setup",
879
- hostType,
880
- properties: {
881
- browser_engine_action: report.browser_engine.action,
882
- opencode_action: report.opencode.action,
883
- no_start: !!flags["no-start"],
884
- },
885
- });
886
-
887
- if (flags["no-start"]) {
888
- report.server = { started: false, skipped: true, base_url: BASE_URL };
889
- output(report, true);
890
- if (report.browser_engine.action === "failed") process.exit(1);
891
- return;
892
- }
893
-
894
- if (!getApiKey()) {
895
- await ensureRegistered({ promptForEmail: true });
896
- }
897
-
898
- try {
899
- await ensureLocalServer(BASE_URL, false, import.meta.url);
900
- report.server = { started: true, base_url: BASE_URL };
901
- await recordFunnelTelemetryEvent("server_autostart_succeeded", {
902
- source: "setup",
903
- hostType,
904
- properties: {
905
- base_url: BASE_URL,
906
- },
907
- });
908
- } catch (error) {
909
- const message = error instanceof Error ? error.message : String(error);
910
- await recordFunnelTelemetryEvent("server_autostart_failed", {
911
- source: "setup",
912
- hostType,
913
- properties: {
914
- failure_stage: "server_autostart",
915
- failure_reason: message,
916
- },
917
- });
918
- report.server = { started: false, error: message, base_url: BASE_URL };
919
- output(report, true);
920
- process.exit(1);
921
- }
922
-
923
- output(report, true);
924
- if (report.browser_engine.action === "failed") process.exit(1);
925
- }
926
-
927
- // ---------------------------------------------------------------------------
928
- // CLI Reference — single source of truth for help text AND SKILL.md
929
- // ---------------------------------------------------------------------------
930
-
931
- export const CLI_REFERENCE = {
932
- commands: [
933
- { name: "health", usage: "", desc: "Server health check" },
934
- { name: "mcp", usage: "[--no-auto-start]", desc: "Run the stdio MCP server" },
935
- { name: "setup", usage: "[--opencode auto|global|project|off] [--no-start]", desc: "Bootstrap browser deps + Open Code command" },
936
- { name: "upgrade", usage: "", desc: "Check latest release and print the right upgrade command" },
937
- { name: "resolve", usage: '--intent "..." [--domain "..."] [--url "..."] [opts]', desc: "Search cached indexed/published routes and optionally execute the top trusted endpoint" },
938
- { name: "execute", usage: "--skill ID --endpoint ID [opts]", desc: "Execute a specific endpoint" },
939
- { name: "feedback", usage: "--skill ID --endpoint ID --rating N", desc: "Submit feedback (mandatory after resolve)" },
940
- { name: "review", usage: "--skill ID --endpoints '[...]'", desc: "Push reviewed descriptions/schema metadata back to a captured skill before publish" },
941
- { name: "index", usage: "--skill ID", desc: "Recompute local graph/contracts/export from cached skill state only" },
942
- { name: "publish", usage: "--skill ID [--confirm-publish] [--endpoints '[...]']", desc: "Re-index locally, inspect publish-review metadata, then publish/share from cached skill state" },
943
- { name: "publish-bundle", usage: "--preset path [--hosts codex,claude,openclaw] [--site-url https://www.unbrowse.ai]", desc: "Derive foundry bundle/share/host artifacts from one preset and write the public share manifest" },
944
- { name: "settings", usage: "[--auto-publish on|off] [--publish-blacklist domains] [--publish-promptlist domains]", desc: "Show or update local capture/publish policy settings" },
945
- { name: "login", usage: '--url "..."', desc: "Interactive browser login" },
946
- { name: "skills", usage: "", desc: "List all skills" },
947
- { name: "skill", usage: "<id>", desc: "Get skill details" },
948
- { name: "cleanup-stale", usage: "[--skill ID] [--domain host] [--limit N]", desc: "Verify skills and evict stale cached endpoints" },
949
- { name: "sessions", usage: '--domain "..." [--limit N]', desc: "Debug session logs" },
950
- { name: "go", usage: '<url> [--session id]', desc: "Open a fresh Kuri browser tab, or reuse explicit --session" },
951
- { name: "submit", usage: "[--session id] [--form-selector sel] [--submit-selector sel] [--wait-for hint] [--assist-site-state]", desc: "Submit current form. Thin browser-native proxy by default; site-state assist and same-origin rehydrate are explicit opt-ins" },
952
- { name: "snap", usage: "[--session id] [--filter interactive]", desc: "A11y snapshot with @eN refs" },
953
- { name: "click", usage: "[--session id] <ref>", desc: "Click element by ref (e.g. e5)" },
954
- { name: "fill", usage: "[--session id] <ref> <value>", desc: "Fill input by ref" },
955
- { name: "type", usage: "<text>", desc: "Type text with key events" },
956
- { name: "press", usage: "<key>", desc: "Press key (Enter, Tab, Escape)" },
957
- { name: "select", usage: "<ref> <value>", desc: "Select option by ref" },
958
- { name: "scroll", usage: "[up|down|left|right]", desc: "Scroll the page" },
959
- { name: "screenshot", usage: "[--session id]", desc: "Capture screenshot (base64 PNG)" },
960
- { name: "text", usage: "[--session id]", desc: "Get page text content" },
961
- { name: "markdown", usage: "[--session id]", desc: "Get page as Markdown" },
962
- { name: "cookies", usage: "[--session id]", desc: "Get page cookies" },
963
- { name: "eval", usage: "[--session id] <expression>", desc: "Evaluate JavaScript" },
964
- { name: "back", usage: "[--session id]", desc: "Navigate back" },
965
- { name: "forward", usage: "[--session id]", desc: "Navigate forward" },
966
- { name: "sync", usage: "[--session id]", desc: "Checkpoint current capture, keep tab open, queue background index + publish, then inspect via skill/publish review" },
967
- { name: "close", usage: "[--session id]", desc: "Checkpoint capture, queue background index + publish, close browse session, then inspect via skill/publish review" },
968
- { name: "stats", usage: "[--json] [--pretty]", desc: "Show lifetime time/tokens/cost saved and marketplace earnings/spending" },
969
- ],
970
- globalFlags: [
971
- { flag: "--pretty", desc: "Indented JSON output" },
972
- { flag: "--no-auto-start", desc: "Don't auto-start server" },
973
- { flag: "--raw", desc: "Return raw response data (skip server-side projection)" },
974
- { flag: "--skip-browser", desc: "setup: skip browser-engine install" },
975
- { flag: "--opencode auto|global|project|off", desc: "setup: install /unbrowse command for Open Code" },
976
- ],
977
- resolveExecuteFlags: [
978
- { flag: "--execute", desc: "Auto-execute the top trusted endpoint from resolve" },
979
- { flag: "--schema", desc: "Show response schema + extraction hints only (no data)" },
980
- { flag: '--path "data.items[]"', desc: "Drill into result before extract/output" },
981
- { flag: '--extract "field1,alias:deep.path.to.val"', desc: "Pick specific fields (no piping needed)" },
982
- { flag: "--limit N", desc: "Cap array output to N items" },
983
- { flag: "--endpoint-id ID", desc: "Pick a specific endpoint" },
984
- { flag: "--dry-run", desc: "Preview mutations" },
985
- { flag: "--params '{...}'", desc: "Extra params as JSON" },
986
- ],
987
- examples: [
988
- "unbrowse setup",
989
- "unbrowse mcp",
990
- 'unbrowse resolve --intent "top stories" --domain "news.ycombinator.com" --url "https://news.ycombinator.com" --execute',
991
- 'unbrowse resolve --intent "get timeline" --url "https://x.com"',
992
- 'unbrowse go "https://www.mandai.com/en/ticketing/admission-and-rides/parks-selection.html"',
993
- 'unbrowse snap --filter interactive',
994
- 'unbrowse submit --wait-for "/time-selection.html"',
995
- 'unbrowse sync',
996
- "unbrowse execute --skill abc --endpoint def --pretty",
997
- "unbrowse execute --skill abc --endpoint def --schema --pretty",
998
- 'unbrowse execute --skill abc --endpoint def --path "data.items[]" --extract "name,url" --limit 10 --pretty',
999
- "unbrowse feedback --skill abc --endpoint def --rating 5",
1000
- 'unbrowse review --skill abc --endpoints \'[{"endpoint_id":"def","description":"...","parameter_reviews":[{"location":"query","name":"q","description":"Search query","type":"string","required":true}],"response_reviews":[{"path":"items[].title","description":"Listing title","type":"string"}]}]\'',
1001
- "unbrowse index --skill abc --pretty",
1002
- "unbrowse publish --skill abc --pretty",
1003
- "unbrowse publish --skill abc --confirm-publish --pretty",
1004
- "unbrowse publish-bundle --preset skills/x-account-operator/foundry-preset.json --pretty",
1005
- 'unbrowse settings --auto-publish off --publish-blacklist "linkedin.com,x.com" --publish-promptlist "github.com" --pretty',
1006
- 'unbrowse publish --skill abc --endpoints \'[{"endpoint_id":"def","description":"Search court judgments by keywords","action_kind":"search","resource_kind":"judgment"}]\'',
1007
- ],
1008
- };
1009
-
1010
-
1011
- // ---------------------------------------------------------------------------
1012
- // stats — show lifetime impact (savings + earnings) for the current agent
1013
- // ---------------------------------------------------------------------------
1014
-
1015
- function formatTotalDuration(ms: number): string {
1016
- if (ms >= 3_600_000) return `${(ms / 3_600_000).toFixed(1)}h`;
1017
- if (ms >= 60_000) return `${(ms / 60_000).toFixed(1)}m`;
1018
- if (ms >= 1000) return `${(ms / 1000).toFixed(1)}s`;
1019
- return `${ms}ms`;
1020
- }
1021
-
1022
- async function cmdStats(flags: Record<string, string | boolean>): Promise<void> {
1023
- const pretty = !!flags.pretty;
1024
- const jsonOnly = !!flags.json;
1025
- const local = readImpactSummary();
1026
- const agentId = getAgentId();
1027
-
1028
- type EarningsLedger = { total_earned_uc: number; total_earned_usd: number; transaction_count: number; last_transaction_at?: string } | null;
1029
- type SpendingLedger = { total_spent_uc: number; total_spent_usd: number; transaction_count: number; last_transaction_at?: string } | null;
1030
-
1031
- let profile: Awaited<ReturnType<typeof getMyProfile>> | null = null;
1032
- let earnings: { ledger: EarningsLedger; transactions: unknown[] } | null = null;
1033
- let spending: { ledger: SpendingLedger; transactions: unknown[] } | null = null;
1034
- const remoteErrors: Record<string, string> = {};
1035
-
1036
- if (agentId) {
1037
- const results = await Promise.allSettled([
1038
- getMyProfile(),
1039
- getCreatorEarnings(agentId),
1040
- getTransactionHistory(agentId),
1041
- ]);
1042
- if (results[0].status === "fulfilled") profile = results[0].value;
1043
- else remoteErrors.profile = (results[0].reason as Error)?.message ?? String(results[0].reason);
1044
- if (results[1].status === "fulfilled") earnings = results[1].value as { ledger: EarningsLedger; transactions: unknown[] };
1045
- else remoteErrors.earnings = (results[1].reason as Error)?.message ?? String(results[1].reason);
1046
- if (results[2].status === "fulfilled") spending = results[2].value as { ledger: SpendingLedger; transactions: unknown[] };
1047
- else remoteErrors.spending = (results[2].reason as Error)?.message ?? String(results[2].reason);
1048
- } else {
1049
- remoteErrors.profile = "No agent_id in local config. Run `unbrowse setup` to register.";
1050
- }
1051
-
1052
- const earnedUsd = earnings?.ledger?.total_earned_usd ?? 0;
1053
- const spentUsd = spending?.ledger?.total_spent_usd ?? 0;
1054
- const netUsd = earnedUsd - spentUsd;
1055
- const savedUsd = local.total_cost_saved_uc / 1_000_000;
1056
-
1057
- const payload = {
1058
- agent_id: agentId,
1059
- profile,
1060
- impact: {
1061
- total_runs: local.total_runs,
1062
- successful_runs: local.successful_runs,
1063
- browser_avoided_runs: local.browser_avoided_runs,
1064
- total_time_saved_ms: local.total_time_saved_ms,
1065
- total_time_saved_human: formatTotalDuration(local.total_time_saved_ms),
1066
- total_tokens_saved: local.total_tokens_saved,
1067
- total_cost_saved_usd: Number(savedUsd.toFixed(6)),
1068
- avg_time_saved_pct: local.avg_time_saved_pct,
1069
- avg_tokens_saved_pct: local.avg_tokens_saved_pct,
1070
- by_source: local.by_source,
1071
- first_entry_at: local.first_entry_at,
1072
- last_entry_at: local.last_entry_at,
1073
- log_path: getImpactLogPath(),
1074
- },
1075
- earnings: {
1076
- total_earned_usd: earnedUsd,
1077
- total_earned_uc: earnings?.ledger?.total_earned_uc ?? 0,
1078
- transaction_count: earnings?.ledger?.transaction_count ?? 0,
1079
- last_transaction_at: earnings?.ledger?.last_transaction_at ?? null,
1080
- },
1081
- spending: {
1082
- total_spent_usd: spentUsd,
1083
- total_spent_uc: spending?.ledger?.total_spent_uc ?? 0,
1084
- transaction_count: spending?.ledger?.transaction_count ?? 0,
1085
- last_transaction_at: spending?.ledger?.last_transaction_at ?? null,
1086
- },
1087
- net_usd: netUsd,
1088
- ...(Object.keys(remoteErrors).length > 0 ? { remote_errors: remoteErrors } : {}),
1089
- };
1090
-
1091
- if (jsonOnly) {
1092
- output(payload, pretty);
1093
- return;
1094
- }
1095
-
1096
- // Human-readable view (to stderr like other info) + JSON to stdout for piping.
1097
- const lines: string[] = [];
1098
- lines.push("Unbrowse stats");
1099
- lines.push(` agent_id: ${agentId ?? "(not registered — run `unbrowse setup`)"}`);
1100
- if (profile?.name) lines.push(` name: ${profile.name}`);
1101
- lines.push("");
1102
- lines.push("Impact (local, this machine):");
1103
- if (local.total_runs === 0) {
1104
- lines.push(" No resolve/execute runs recorded yet.");
1105
- lines.push(` Log file: ${getImpactLogPath()}`);
1106
- } else {
1107
- lines.push(` Runs: ${local.total_runs} (${local.successful_runs} successful, ${local.browser_avoided_runs} browser-avoided)`);
1108
- if (local.total_time_saved_ms > 0) {
1109
- lines.push(` Time saved: ${formatTotalDuration(local.total_time_saved_ms)} (avg ${local.avg_time_saved_pct}% faster)`);
1110
- }
1111
- if (local.total_tokens_saved > 0) {
1112
- lines.push(` Tokens saved: ${local.total_tokens_saved.toLocaleString("en-US")} (avg ${local.avg_tokens_saved_pct}% less context)`);
1113
- }
1114
- if (savedUsd > 0) {
1115
- lines.push(` Cost saved: ${formatCostUsd(local.total_cost_saved_uc)}`);
1116
- }
1117
- if (Object.keys(local.by_source).length > 0) {
1118
- const topSources = Object.entries(local.by_source)
1119
- .sort((a, b) => b[1] - a[1])
1120
- .slice(0, 5)
1121
- .map(([k, v]) => `${k}=${v}`)
1122
- .join(", ");
1123
- lines.push(` By source: ${topSources}`);
1124
- }
1125
- }
1126
- lines.push("");
1127
- lines.push("Money (backend ledger):");
1128
- if (!agentId) {
1129
- lines.push(" (not registered — earnings/spending unavailable)");
1130
- } else if (remoteErrors.earnings || remoteErrors.spending) {
1131
- if (remoteErrors.earnings) lines.push(` earnings: error — ${remoteErrors.earnings}`);
1132
- if (remoteErrors.spending) lines.push(` spending: error — ${remoteErrors.spending}`);
1133
- } else {
1134
- lines.push(` Earned: $${earnedUsd.toFixed(4)} (${earnings?.ledger?.transaction_count ?? 0} payouts)`);
1135
- lines.push(` Spent: $${spentUsd.toFixed(4)} (${spending?.ledger?.transaction_count ?? 0} payments)`);
1136
- lines.push(` Net: ${netUsd >= 0 ? "+" : ""}$${netUsd.toFixed(4)}`);
1137
- }
1138
- lines.push("");
1139
- info(lines.join("\n"));
1140
- output(payload, pretty);
1141
- }
1142
-
1143
- function printHelp(): void {
1144
- const r = CLI_REFERENCE;
1145
- const lines: string[] = ["unbrowse \u2014 shell-safe CLI for the local API", ""];
1146
-
1147
- // Commands
1148
- lines.push("Commands:");
1149
- const cmdPad = Math.max(...r.commands.map((c) => ` ${c.name} ${c.usage}`.length)) + 2;
1150
- for (const c of r.commands) {
1151
- const left = ` ${c.name} ${c.usage}`;
1152
- lines.push(left.padEnd(cmdPad) + c.desc);
1153
- }
1154
-
1155
- // Global flags
1156
- lines.push("", "Global flags:");
1157
- const gPad = Math.max(...r.globalFlags.map((f) => ` ${f.flag}`.length)) + 2;
1158
- for (const f of r.globalFlags) {
1159
- lines.push(` ${f.flag}`.padEnd(gPad) + f.desc);
1160
- }
1161
-
1162
- // resolve/execute flags
1163
- lines.push("", "resolve/execute flags:");
1164
- const rPad = Math.max(...r.resolveExecuteFlags.map((f) => ` ${f.flag}`.length)) + 2;
1165
- for (const f of r.resolveExecuteFlags) {
1166
- lines.push(` ${f.flag}`.padEnd(rPad) + f.desc);
1167
- }
1168
-
1169
- // Examples
1170
- lines.push("", "Examples:");
1171
- for (const e of r.examples) {
1172
- lines.push(` ${e}`);
1173
- }
1174
-
1175
- lines.push(
1176
- "",
1177
- "Browser workflow:",
1178
- " 1. go -> open the live tab you want to work in",
1179
- " 2. snap -> inspect refs and confirm the page state",
1180
- " 3. click/fill/eval -> set real page state",
1181
- " 4. submit -> prefer DOM submit; keep traversal browser-native; opt into same-origin rehydrate only for explicit replay/recovery debugging",
1182
- " 5. sync -> checkpoint the current step and queue background index + publish",
1183
- " 6. close -> final checkpoint + queue background index + publish, then close the session",
1184
- " 7. skill/publish --pretty -> inspect the fresh captured endpoints and review context",
1185
- " 8. review/publish -> annotate and share the contract; resolve is for later reuse, not first-pass capture validation",
1186
- );
1187
-
1188
- lines.push(
1189
- "",
1190
- "JS-heavy forms:",
1191
- " Prefer real calendar/time clicks before submit.",
1192
- " If the UI is flaky, inspect hidden inputs/cookies with eval, then submit the real form.",
1193
- );
1194
-
1195
- lines.push("");
1196
- process.stderr.write(lines.join("\n"));
1197
- }
1198
-
1199
- // ---------------------------------------------------------------------------
1200
- // Server lifecycle commands
1201
- // ---------------------------------------------------------------------------
1202
-
1203
- async function cmdStatus(flags: Record<string, string | boolean>): Promise<void> {
1204
- const healthy = await fetch(`${BASE_URL}/health`, { signal: AbortSignal.timeout(2_000) })
1205
- .then((r) => r.ok).catch(() => false);
1206
- const versionInfo = checkServerVersion(BASE_URL, import.meta.url);
1207
- output({
1208
- server: healthy ? "running" : "stopped",
1209
- url: BASE_URL,
1210
- ...(versionInfo ?? {}),
1211
- }, !!flags.pretty);
1212
- }
1213
-
1214
- async function cmdRestart(flags: Record<string, string | boolean>): Promise<void> {
1215
- info("Restarting server...");
1216
- await restartServer(BASE_URL, import.meta.url);
1217
- info("Server restarted.");
1218
- await cmdStatus(flags);
1219
- }
1220
-
1221
- function cmdStop(flags: Record<string, string | boolean>): void {
1222
- const stopped = stopServer(BASE_URL);
1223
- if (stopped) info("Server stopped.");
1224
- else info("No server running.");
1225
- }
1226
-
1227
- async function cmdUpgrade(flags: Record<string, string | boolean>): Promise<void> {
1228
- const hintOnly = !!flags["hint-only"];
1229
- if (!hintOnly) info("Checking for updates...");
1230
-
1231
- try {
1232
- const result = await checkForUpdates(import.meta.url, { force: !hintOnly });
1233
- if (!result.latest) {
1234
- if (!hintOnly) info("Could not check for updates right now.");
1235
- return;
1236
- }
1237
-
1238
- if (!result.has_update) {
1239
- if (!hintOnly) info(`Already at latest version: ${result.installed}`);
1240
- return;
1241
- }
1242
-
1243
- info(`Update available: ${result.installed} -> ${result.latest}`);
1244
- info(`Run: ${result.command}`);
1245
- if (!hintOnly) {
1246
- info("Tip: `unbrowse setup` now installs session-start update hints for Codex and Claude when those hosts are present.");
1247
- }
1248
- recordUpdateHint(result.latest);
1249
- } catch (err) {
1250
- if (!hintOnly) info(`Could not check for updates: ${(err as Error).message}`);
1251
- }
1252
- }
1253
-
1254
- async function cmdMcp(flags: Record<string, string | boolean>): Promise<void> {
1255
- const entrypoint = resolveSiblingEntrypoint(import.meta.url, "mcp");
1256
- const childArgs = isBundledVirtualEntrypoint(entrypoint)
1257
- ? ["mcp-serve", ...(flags["no-auto-start"] ? ["--no-auto-start"] : [])]
1258
- : [...runtimeArgsForEntrypoint(import.meta.url, entrypoint), ...(flags["no-auto-start"] ? ["--no-auto-start"] : [])];
1259
- const child = spawn(
1260
- process.execPath,
1261
- childArgs,
1262
- {
1263
- cwd: process.cwd(),
1264
- stdio: "inherit",
1265
- env: {
1266
- ...process.env,
1267
- MCP_SERVER_MODE: "1",
1268
- },
1269
- },
1270
- );
1271
-
1272
- const code = await new Promise<number>((resolve, reject) => {
1273
- child.once("error", reject);
1274
- child.once("exit", (exitCode, signal) => {
1275
- if (signal) {
1276
- process.kill(process.pid, signal);
1277
- return;
1278
- }
1279
- resolve(exitCode ?? 1);
1280
- });
1281
- });
1282
-
1283
- if (code !== 0) process.exit(code);
1284
- }
1285
-
1286
- // ---------------------------------------------------------------------------
1287
- // Site/task shortcut commands
1288
- // ---------------------------------------------------------------------------
1289
-
1290
- async function cmdSiteHelp(pack: SitePack, flags: Record<string, string | boolean>): Promise<void> {
1291
- // --deps: return dependency graph as JSON
1292
- if (flags.deps) {
1293
- const graph = buildDepsGraph(pack);
1294
- output({ site: pack.site, tasks: graph }, !!flags.pretty);
1295
- return;
1296
- }
1297
- // --plan: return execution plan for a set of tasks
1298
- if (flags.plan) {
1299
- const taskNames = (flags.plan as string).split(",").map((s) => s.trim());
1300
- const waves = planExecution(pack, taskNames);
1301
- output({ site: pack.site, waves }, !!flags.pretty);
1302
- return;
1303
- }
1304
- // Default: human-readable help
1305
- const lines: string[] = [
1306
- `unbrowse ${pack.site} — ${pack.description}`,
1307
- "",
1308
- "Tasks:",
1309
- ];
1310
- for (const t of pack.tasks) {
1311
- const aliases = t.match.length > 1 ? ` (${t.match.slice(1).join(", ")})` : "";
1312
- const auth = t.needs_auth ? " [auth]" : "";
1313
- lines.push(` ${t.match[0]}${aliases}${auth} ${t.description}`);
1314
- }
1315
- lines.push(
1316
- "",
1317
- "Examples:",
1318
- ` unbrowse ${pack.site} login`,
1319
- ` unbrowse ${pack.site} ${pack.tasks.find((t) => t.match[0] !== "login")?.match[0] || "help"} --pretty`,
1320
- ` unbrowse ${pack.site} --batch ${pack.tasks.filter((t) => t.parallel_safe).map((t) => t.match[0]).join(",")}`,
1321
- ` unbrowse ${pack.site} help --deps`,
1322
- ` unbrowse ${pack.site} help --plan feed,notifications`,
1323
- "",
1324
- "Flags: --pretty --raw --path --extract --limit --force-capture --dry-run --batch --deps --plan",
1325
- );
1326
- process.stderr.write(lines.join("\n") + "\n");
1327
- }
1328
-
1329
- async function cmdSiteLogin(pack: SitePack, flags: Record<string, string | boolean>): Promise<void> {
1330
- const result = await api("POST", "/v1/auth/login", { url: pack.login_url });
1331
- const deps = buildDepsMetadata(pack, "login");
1332
- output({ ...result as Record<string, unknown>, _deps: deps, _shortcut: `${pack.site} login` }, !!flags.pretty);
1333
- }
1334
-
1335
- async function cmdSiteTask(pack: SitePack, taskName: string, flags: Record<string, string | boolean>): Promise<void> {
1336
- const task = findTask(pack, taskName);
1337
- if (!task) {
1338
- info(`Unknown task "${taskName}" for ${pack.site}. Run: unbrowse ${pack.site} help`);
1339
- process.exit(1);
1340
- }
1341
-
1342
- // Compile to resolve call
1343
- const body: Record<string, unknown> = {
1344
- intent: task.intent,
1345
- params: { url: task.url },
1346
- context: { url: task.url },
1347
- };
1348
- if (flags.params) {
1349
- body.params = { ...(body.params as Record<string, unknown>), ...JSON.parse(flags.params as string) };
1350
- }
1351
- if (flags["dry-run"]) body.dry_run = true;
1352
- if (flags["force-capture"]) body.force_capture = true;
1353
- body.projection = { raw: true };
1354
-
1355
- const startedAt = Date.now();
1356
- let result = await withPendingNotice(
1357
- api("POST", "/v1/intent/resolve", body) as Promise<Record<string, unknown>>,
1358
- "Still working. First-time capture/indexing for a site can take 20-80s.",
1359
- );
1360
-
1361
- // Check for auth-required response
1362
- if (result && typeof result === "object" && (result as Record<string, unknown>).error === "auth_required") {
1363
- info(`Authentication required. Run: unbrowse ${pack.site} login`);
1364
- const deps = buildDepsMetadata(pack, taskName);
1365
- output({ ...(result as Record<string, unknown>), _deps: { ...deps, requires: ["login"] }, _next: [`unbrowse ${pack.site} login`] }, !!flags.pretty);
1366
- process.exit(2);
1367
- }
1368
-
1369
- // Strip metadata bloat
1370
- result = slimTrace(result);
1371
-
1372
- const deps = buildDepsMetadata(pack, taskName);
1373
- (result as Record<string, unknown>)._deps = deps;
1374
- (result as Record<string, unknown>)._shortcut = `${pack.site} ${taskName}`;
1375
-
1376
- if (Date.now() - startedAt > 3_000 && result.source === "live-capture") {
1377
- info("Live capture finished. Future runs should be much faster.");
1378
- }
1379
-
1380
- output(result, !!flags.pretty);
1381
- }
1382
-
1383
- async function cmdSiteBatch(pack: SitePack, batchArg: string, flags: Record<string, string | boolean>): Promise<void> {
1384
- const taskNames = batchArg.split(",").map((s) => s.trim());
1385
- const waves = planExecution(pack, taskNames);
1386
- const results: Record<string, unknown> = { site: pack.site, waves: [], _deps: { parallel_safe: true } };
1387
- const waveResults: unknown[] = [];
1388
-
1389
- for (const wave of waves) {
1390
- const waveStart = Date.now();
1391
- const promises = wave.commands.map(async (cmd) => {
1392
- const parts = cmd.split(" ");
1393
- const task = parts[parts.length - 1];
1394
- const taskDef = findTask(pack, task);
1395
- if (!taskDef) return { task, error: "unknown task" };
1396
-
1397
- if (task === "login") {
1398
- return { task, result: await api("POST", "/v1/auth/login", { url: pack.login_url }) };
1399
- }
1400
- const body: Record<string, unknown> = {
1401
- intent: taskDef.intent,
1402
- params: { url: taskDef.url },
1403
- context: { url: taskDef.url },
1404
- };
1405
- if (flags["force-capture"]) body.force_capture = true;
1406
- body.projection = { raw: true };
1407
- const res = await api("POST", "/v1/intent/resolve", body) as Record<string, unknown>;
1408
- return { task, result: slimTrace(res) };
1409
- });
1410
-
1411
- const waveResult = await Promise.all(promises);
1412
- waveResults.push({
1413
- wave: wave.wave,
1414
- reason: wave.reason,
1415
- elapsed_ms: Date.now() - waveStart,
1416
- tasks: waveResult,
1417
- });
1418
- }
1419
-
1420
- (results as Record<string, unknown>).waves = waveResults;
1421
- output(results, !!flags.pretty);
1422
- }
1423
-
1424
- // ---------------------------------------------------------------------------
1425
- // Main
1426
- // ---------------------------------------------------------------------------
1427
-
1428
- // ---------------------------------------------------------------------------
1429
- // Browse commands — Kuri browser actions with passive indexing via server
1430
- // ---------------------------------------------------------------------------
1431
-
1432
- async function cmdGo(args: string[], flags: Record<string, string | boolean>): Promise<void> {
1433
- const url = args[0] ?? flags.url as string;
1434
- if (!url) die("Usage: unbrowse go <url>");
1435
- output(await api("POST", "/v1/browse/go", {
1436
- url,
1437
- ...(typeof flags.session === "string" ? { session_id: flags.session } : {}),
1438
- }), !!flags.pretty);
1439
- }
1440
-
1441
- async function cmdSubmit(flags: Record<string, string | boolean>): Promise<void> {
1442
- const body: Record<string, unknown> = {};
1443
- if (typeof flags.session === "string") body.session_id = flags.session;
1444
- if (typeof flags["form-selector"] === "string") body.form_selector = flags["form-selector"];
1445
- if (typeof flags["submit-selector"] === "string") body.submit_selector = flags["submit-selector"];
1446
- if (typeof flags["wait-for"] === "string") body.wait_for = flags["wait-for"];
1447
- if (typeof flags["timeout-ms"] === "string") body.timeout_ms = Number(flags["timeout-ms"]);
1448
- if (flags["assist-site-state"] !== undefined) {
1449
- body.assist_site_state = flags["assist-site-state"] !== "false";
1450
- }
1451
- if (flags["same-origin-fetch-fallback"] !== undefined) {
1452
- body.same_origin_fetch_fallback = flags["same-origin-fetch-fallback"] !== "false";
1453
- }
1454
- output(await api("POST", "/v1/browse/submit", body), !!flags.pretty);
1455
- }
1456
-
1457
- async function cmdSnap(flags: Record<string, string | boolean>): Promise<void> {
1458
- const filter = flags.filter as string | undefined;
1459
- const result = await api("POST", "/v1/browse/snap", {
1460
- ...(filter ? { filter } : {}),
1461
- ...(typeof flags.session === "string" ? { session_id: flags.session } : {}),
1462
- }) as { snapshot?: string };
1463
- if (result.snapshot && !flags.pretty) {
1464
- console.log(result.snapshot);
1465
- } else {
1466
- output(result, !!flags.pretty);
1467
- }
1468
- }
1469
-
1470
- async function cmdClick(args: string[], flags: Record<string, string | boolean>): Promise<void> {
1471
- const ref = args[0];
1472
- if (!ref) die("Usage: unbrowse click <ref>");
1473
- output(await api("POST", "/v1/browse/click", {
1474
- ref,
1475
- ...(typeof flags.session === "string" ? { session_id: flags.session } : {}),
1476
- }), false);
1477
- }
1478
-
1479
- async function cmdFill(args: string[], flags: Record<string, string | boolean>): Promise<void> {
1480
- const ref = args[0];
1481
- const value = args.slice(1).join(" ");
1482
- if (!ref || !value) die("Usage: unbrowse fill <ref> <value>");
1483
- output(await api("POST", "/v1/browse/fill", {
1484
- ref,
1485
- value,
1486
- ...(typeof flags.session === "string" ? { session_id: flags.session } : {}),
1487
- }), false);
1488
- }
1489
-
1490
- async function cmdType(args: string[], flags: Record<string, string | boolean>): Promise<void> {
1491
- const text = args.join(" ");
1492
- if (!text) die("Usage: unbrowse type <text>");
1493
- output(await api("POST", "/v1/browse/type", {
1494
- text,
1495
- ...(typeof flags.session === "string" ? { session_id: flags.session } : {}),
1496
- }), false);
1497
- }
1498
-
1499
- async function cmdPress(args: string[], flags: Record<string, string | boolean>): Promise<void> {
1500
- const key = args[0];
1501
- if (!key) die("Usage: unbrowse press <key>");
1502
- output(await api("POST", "/v1/browse/press", {
1503
- key,
1504
- ...(typeof flags.session === "string" ? { session_id: flags.session } : {}),
1505
- }), false);
1506
- }
1507
-
1508
- async function cmdSelect(args: string[], flags: Record<string, string | boolean>): Promise<void> {
1509
- const ref = args[0];
1510
- const value = args.slice(1).join(" ");
1511
- if (!ref || !value) die("Usage: unbrowse select <ref> <value>");
1512
- output(await api("POST", "/v1/browse/select", {
1513
- ref,
1514
- value,
1515
- ...(typeof flags.session === "string" ? { session_id: flags.session } : {}),
1516
- }), false);
1517
- }
1518
-
1519
- async function cmdScroll(args: string[], flags: Record<string, string | boolean>): Promise<void> {
1520
- const direction = args[0] ?? "down";
1521
- output(await api("POST", "/v1/browse/scroll", {
1522
- direction,
1523
- ...(typeof flags.session === "string" ? { session_id: flags.session } : {}),
1524
- }), false);
1525
- }
1526
-
1527
- async function cmdScreenshot(flags: Record<string, string | boolean>): Promise<void> {
1528
- output(await api("GET", "/v1/browse/screenshot", typeof flags.session === "string" ? { session_id: flags.session } : undefined), !!flags.pretty);
1529
- }
1530
-
1531
- async function cmdText(flags: Record<string, string | boolean>): Promise<void> {
1532
- const result = await api("GET", "/v1/browse/text", typeof flags.session === "string" ? { session_id: flags.session } : undefined) as { text?: string };
1533
- if (result.text && !flags.pretty) {
1534
- console.log(result.text);
1535
- } else {
1536
- output(result, !!flags.pretty);
1537
- }
1538
- }
1539
-
1540
- async function cmdMarkdown(flags: Record<string, string | boolean>): Promise<void> {
1541
- const result = await api("GET", "/v1/browse/markdown", typeof flags.session === "string" ? { session_id: flags.session } : undefined) as { markdown?: string };
1542
- if (result.markdown && !flags.pretty) {
1543
- console.log(result.markdown);
1544
- } else {
1545
- output(result, !!flags.pretty);
1546
- }
1547
- }
1548
-
1549
- async function cmdCookies(flags: Record<string, string | boolean>): Promise<void> {
1550
- output(await api("GET", "/v1/browse/cookies", typeof flags.session === "string" ? { session_id: flags.session } : undefined), !!flags.pretty);
1551
- }
1552
-
1553
- async function cmdEval(args: string[], flags: Record<string, string | boolean>): Promise<void> {
1554
- const expression = args.join(" ");
1555
- if (!expression) die("Usage: unbrowse eval <expression>");
1556
- output(await api("POST", "/v1/browse/eval", {
1557
- expression,
1558
- ...(typeof flags.session === "string" ? { session_id: flags.session } : {}),
1559
- }), !!flags.pretty);
1560
- }
1561
-
1562
- async function cmdBack(flags: Record<string, string | boolean>): Promise<void> {
1563
- output(await api("POST", "/v1/browse/back", typeof flags.session === "string" ? { session_id: flags.session } : undefined), false);
1564
- }
1565
-
1566
- async function cmdForward(flags: Record<string, string | boolean>): Promise<void> {
1567
- output(await api("POST", "/v1/browse/forward", typeof flags.session === "string" ? { session_id: flags.session } : undefined), false);
1568
- }
1569
-
1570
- async function cmdSync(flags: Record<string, string | boolean>): Promise<void> {
1571
- output(await api("POST", "/v1/browse/sync", typeof flags.session === "string" ? { session_id: flags.session } : undefined), !!flags.pretty);
1572
- }
1573
-
1574
- async function cmdClose(flags: Record<string, string | boolean>): Promise<void> {
1575
- output(await api("POST", "/v1/browse/close", typeof flags.session === "string" ? { session_id: flags.session } : undefined), false);
1576
- }
1577
-
1578
- async function cmdConnectChrome(): Promise<void> {
1579
- const { execSync, spawn: spawnProc } = require("child_process");
1580
-
1581
- // Check if Chrome already has CDP
1582
- try {
1583
- const res = await fetch("http://127.0.0.1:9222/json/version", { signal: AbortSignal.timeout(1000) });
1584
- if (res.ok) {
1585
- const data = await res.json() as { "User-Agent"?: string };
1586
- if (!data["User-Agent"]?.includes("Headless")) {
1587
- console.log("Your Chrome is already connected with CDP on port 9222.");
1588
- console.log("Browse commands will use your real browser with all your sessions.");
1589
- return;
1590
- }
1591
- }
1592
- } catch { /* not running */ }
1593
-
1594
- // Kill any Kuri-managed Chrome
1595
- try { execSync("pkill -f kuri/chrome-profile", { stdio: "ignore" }); } catch {}
1596
-
1597
- // Quit Chrome fully — can't add debugging port to running instance
1598
- console.log("Quitting Chrome to relaunch with remote debugging...");
1599
- if (process.platform === "darwin") {
1600
- try { execSync('osascript -e "quit app \\"Google Chrome\\""', { stdio: "ignore", timeout: 5000 }); } catch {}
1601
- } else {
1602
- try { execSync("pkill -f chrome", { stdio: "ignore" }); } catch {}
1603
- }
1604
- await new Promise(r => setTimeout(r, 2000));
1605
-
1606
- console.log("Launching Chrome with remote debugging on port 9222...");
1607
- if (process.platform === "darwin") {
1608
- spawnProc("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
1609
- ["--remote-debugging-port=9222", "--no-first-run", "--no-default-browser-check"],
1610
- { stdio: "ignore", detached: true }).unref();
1611
- } else {
1612
- spawnProc("google-chrome", ["--remote-debugging-port=9222"], { stdio: "ignore", detached: true }).unref();
1613
- }
1614
-
1615
- // Wait for CDP
1616
- const deadline = Date.now() + 15000;
1617
- while (Date.now() < deadline) {
1618
- try {
1619
- const res = await fetch("http://127.0.0.1:9222/json/version", { signal: AbortSignal.timeout(500) });
1620
- if (res.ok) {
1621
- console.log("Connected. Your real Chrome is now available for browse commands.");
1622
- console.log("All your logged-in sessions (LinkedIn, X, etc.) will work.");
1623
- console.log('Run: unbrowse go "https://linkedin.com/feed/"');
1624
- return;
1625
- }
1626
- } catch {}
1627
- await new Promise(r => setTimeout(r, 500));
1628
- }
1629
- console.error("Could not connect to Chrome. Make sure all Chrome windows are closed and try again.");
1630
- }
1631
- async function main(): Promise<void> {
1632
- const { command, args, flags } = parseArgs(process.argv);
1633
- const noAutoStart = !!flags["no-auto-start"];
1634
-
1635
- if (command === "help" || flags.help) {
1636
- printHelp();
1637
- process.exit(0);
1638
- }
1639
-
1640
- if (command === "setup") {
1641
- await cmdSetup(flags);
1642
- return;
1643
- }
1644
-
1645
- // Server lifecycle commands (don't need ensureLocalServer)
1646
- if (command === "mcp") return cmdMcp(flags);
1647
- if (command === "status") return cmdStatus(flags);
1648
- if (command === "stop") { cmdStop(flags); return; }
1649
- if (command === "restart") return cmdRestart(flags);
1650
- if (command === "upgrade" || command === "update") return cmdUpgrade(flags);
1651
- if (command === "connect-chrome") return cmdConnectChrome();
1652
- if (command === "stats") return cmdStats(flags);
1653
-
1654
- // --- Shortcut resolution: unbrowse <site> [task] [flags] ---
1655
- const KNOWN_COMMANDS = new Set([
1656
- "health", "mcp", "setup", "resolve", "execute", "exec",
1657
- "feedback", "fb", "review", "index", "publish", "publish-bundle", "settings", "login", "skills", "skill", "cleanup-stale", "search", "sessions",
1658
- "status", "stop", "restart", "upgrade", "update",
1659
- "go", "submit", "snap", "click", "fill", "type", "press", "select", "scroll",
1660
- "screenshot", "text", "markdown", "cookies", "eval", "back", "forward", "sync", "close",
1661
- "connect-chrome", "stats",
1662
- ]);
1663
-
1664
- if (!KNOWN_COMMANDS.has(command)) {
1665
- const pack = findSitePack(command);
1666
- if (pack) {
1667
- await ensureLocalServer(BASE_URL, noAutoStart, import.meta.url);
1668
- const taskName = args[0];
1669
- if (!taskName || taskName === "help") {
1670
- return cmdSiteHelp(pack, flags);
1671
- }
1672
- if (taskName === "login") {
1673
- return cmdSiteLogin(pack, flags);
1674
- }
1675
- const batchArg = flags.batch as string | undefined;
1676
- if (batchArg) {
1677
- return cmdSiteBatch(pack, batchArg, flags);
1678
- }
1679
- return cmdSiteTask(pack, taskName, flags);
1680
- }
1681
- }
1682
-
1683
- await ensureLocalServer(BASE_URL, noAutoStart, import.meta.url);
1684
-
1685
- switch (command) {
1686
- case "health": return cmdHealth(flags);
1687
- case "mcp": return cmdMcp(flags);
1688
- case "setup": return cmdSetup(flags);
1689
- case "resolve": return cmdResolve(flags);
1690
- case "execute": case "exec": return cmdExecute(flags);
1691
- case "feedback": case "fb": return cmdFeedback(flags);
1692
- case "review": return cmdReview(flags);
1693
- case "index": return cmdIndex(flags);
1694
- case "publish": return cmdPublish(flags);
1695
- case "publish-bundle": return cmdPublishBundle(flags);
1696
- case "settings": return cmdSettings(flags);
1697
- case "login": return cmdLogin(flags);
1698
- case "skills": return cmdSkills(flags);
1699
- case "skill": return cmdSkill(args, flags);
1700
- case "cleanup-stale": return cmdCleanupStale(flags);
1701
- case "search": return cmdSearch(flags);
1702
- case "sessions": return cmdSessions(flags);
1703
- // Browse commands — Kuri browser actions with passive indexing
1704
- case "go": return cmdGo(args, flags);
1705
- case "submit": return cmdSubmit(flags);
1706
- case "snap": return cmdSnap(flags);
1707
- case "click": return cmdClick(args, flags);
1708
- case "fill": return cmdFill(args, flags);
1709
- case "type": return cmdType(args, flags);
1710
- case "press": return cmdPress(args, flags);
1711
- case "select": return cmdSelect(args, flags);
1712
- case "scroll": return cmdScroll(args, flags);
1713
- case "screenshot": return cmdScreenshot(flags);
1714
- case "text": return cmdText(flags);
1715
- case "markdown": return cmdMarkdown(flags);
1716
- case "cookies": return cmdCookies(flags);
1717
- case "eval": return cmdEval(args, flags);
1718
- case "back": return cmdBack(flags);
1719
- case "forward": return cmdForward(flags);
1720
- case "sync": return cmdSync(flags);
1721
- case "close": return cmdClose(flags);
1722
- case "connect-chrome": return cmdConnectChrome();
1723
- case "stats": return cmdStats(flags);
1724
- default: info(`Unknown command: ${command}`); printHelp(); process.exit(1);
1725
- }
1726
- }
1727
-
1728
- if (isMainModule(import.meta.url)) {
1729
- main()
1730
- .then(() => Promise.all([drainPendingIndexJobs(), drainPendingPassivePublishes()]))
1731
- .catch((err) => {
1732
- die((err as Error).message);
1733
- });
1734
- }