@docyrus/docyrus 0.0.56 → 0.0.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",
@@ -23,8 +23,8 @@
     "@repomix/tree-sitter-wasms": "^0.1.16",
     "@sinclair/typebox": "^0.34.48",
     "@xterm/headless": "^5.5.0",
-    "diff": "^8.0.4",
-    "hono": "^4.12.12",
+    "diff": "^9.0.0",
+    "hono": "^4.12.14",
     "ignore-walk": "^8.0.0",
     "incur": "^0.1.6",
     "jsdom": "^29.0.1",

package/resources/browser-tools/browser-connect.js

@@ -0,0 +1,172 @@
+/**
+ * Shared browser connection module.
+ *
+ * Reads `.docyrus/browser.json` (or DOCYRUS_BROWSER_SANDBOX env) to decide
+ * between local Chrome on :9222 and a remote Cloudflare Browser Rendering
+ * session. Remote sessions are cached in `.docyrus/browser-session.json` and
+ * reused until they expire.
+ *
+ * Exports:
+ *   connectBrowser()  → { browser, mode, session }
+ *   isSandboxMode()   → boolean
+ *   getSessionInfo()  → cached session object | null
+ */
+
+import puppeteer from "puppeteer-core";
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const DOCYRUS_DIR = ".docyrus";
+const BROWSER_CONFIG_FILE = "browser.json";
+const BROWSER_SESSION_FILE = "browser-session.json";
+const LOCAL_TIMEOUT_MS = 5_000;
+const REMOTE_TIMEOUT_MS = 30_000;
+const SESSION_EXPIRY_BUFFER_MS = 30_000;
+
+function resolveDocyrusDir() {
+  return join(process.cwd(), DOCYRUS_DIR);
+}
+
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonFile(filePath, data) {
+  const dir = join(filePath, "..");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+}
+
+function readBrowserConfig() {
+  return readJsonFile(join(resolveDocyrusDir(), BROWSER_CONFIG_FILE));
+}
+
+function readCachedSession() {
+  return readJsonFile(join(resolveDocyrusDir(), BROWSER_SESSION_FILE));
+}
+
+function writeCachedSession(session) {
+  writeJsonFile(join(resolveDocyrusDir(), BROWSER_SESSION_FILE), session);
+}
+
+export function isSandboxMode() {
+  if (process.env.DOCYRUS_BROWSER_SANDBOX === "1") {
+    return true;
+  }
+  const config = readBrowserConfig();
+  return config?.mode === "sandbox";
+}
+
+export function getSessionInfo() {
+  if (!isSandboxMode()) {
+    return null;
+  }
+  const cached = readCachedSession();
+  if (!cached?.expiresAt) {
+    return null;
+  }
+  if (new Date(cached.expiresAt).getTime() - SESSION_EXPIRY_BUFFER_MS <= Date.now()) {
+    return null;
+  }
+  return cached;
+}
+
+function resolveAppId() {
+  const config = readBrowserConfig();
+  return config?.appId || process.env.DOCYRUS_SANDBOX_APP_ID || null;
+}
+
+function createRemoteSession(appId) {
+  const result = spawnSync("docyrus", [
+    "curl", "-X", "POST",
+    `/api/v1/ai/sandbox/app/${appId}/createBrowserSession`,
+    "--format", "json",
+  ], {
+    encoding: "utf8",
+    env: { ...process.env },
+  });
+
+  if (result.status !== 0) {
+    const msg = result.stderr?.trim() || "unknown error";
+    console.error(`✗ Failed to create browser session: ${msg}`);
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(result.stdout);
+  } catch (e) {
+    console.error("✗ Invalid session response:", e.message);
+    process.exit(1);
+  }
+
+  const now = Date.now();
+  const session = {
+    ...data,
+    createdAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + (data.keepAliveMs || 600_000)).toISOString(),
+  };
+
+  writeCachedSession(session);
+  return session;
+}
+
+async function connectRemote(session) {
+  const browser = await Promise.race([
+    puppeteer.connect({
+      browserWSEndpoint: session.browserWSEndpoint,
+      headers: { Authorization: session.authHeader },
+    }),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error("Timed out connecting to remote browser")), REMOTE_TIMEOUT_MS),
+    ),
+  ]);
+  return browser;
+}
+
+async function connectLocal() {
+  const browser = await Promise.race([
+    puppeteer.connect({
+      browserURL: "http://localhost:9222",
+      defaultViewport: null,
+    }),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error("timeout")), LOCAL_TIMEOUT_MS),
+    ),
+  ]).catch((e) => {
+    console.error("✗ Could not connect to browser:", e.message);
+    console.error("  Run: docyrus browser start");
+    process.exit(1);
+  });
+  return browser;
+}
+
+export async function connectBrowser() {
+  if (isSandboxMode()) {
+    const appId = resolveAppId();
+    if (!appId) {
+      console.error("✗ Sandbox mode active but no app ID found.");
+      console.error("  Set DOCYRUS_SANDBOX_APP_ID or configure .docyrus/browser.json");
+      process.exit(1);
+    }
+
+    let session = getSessionInfo();
+    if (!session) {
+      session = createRemoteSession(appId);
+    }
+
+    const browser = await connectRemote(session);
+    return { browser, mode: "remote", session };
+  }
+
+  const browser = await connectLocal();
+  return { browser, mode: "local", session: null };
+}

package/resources/{chrome-tools → browser-tools}/browser-content.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
-import puppeteer from "puppeteer-core";
 import { Readability } from "@mozilla/readability";
 import { JSDOM } from "jsdom";
 import TurndownService from "turndown";
 import { gfm } from "turndown-plugin-gfm";
+import { connectBrowser } from "./browser-connect.js";
 
 // Global timeout - exit if script takes too long
 const TIMEOUT = 30000;
-const timeoutId = setTimeout(() => {
+setTimeout(() => {
   console.error("✗ Timeout after 30s");
   process.exit(1);
 }, TIMEOUT).unref();
@@ -24,17 +24,7 @@ if (!url) {
   process.exit(1);
 }
 
-const b = await Promise.race([
-  puppeteer.connect({
-    browserURL: "http://localhost:9222",
-    defaultViewport: null,
-  }),
-  new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 5000)),
-]).catch((e) => {
-  console.error("✗ Could not connect to browser:", e.message);
-  console.error("  Run: browser-start.js");
-  process.exit(1);
-});
+const { browser: b, mode, session } = await connectBrowser();
 
 const p = (await b.pages()).at(-1);
 if (!p) {
@@ -82,7 +72,7 @@ let content;
 if (article && article.content) {
   content = htmlToMarkdown(article.content);
 } else {
-	// Fallback
+  // Fallback
   const fallbackDoc = new JSDOM(outerHTML, { url: finalUrl });
   const fallbackBody = fallbackDoc.window.document;
   fallbackBody.querySelectorAll("script, style, noscript, nav, header, footer, aside").forEach((el) => el.remove());
@@ -95,8 +85,14 @@ if (article && article.content) {
   }
 }
 
+// Content command outputs markdown directly (not wrapped in JSON) since
+// the extracted text is the primary payload and is consumed as plain text.
 console.log(`URL: ${finalUrl}`);
 if (article?.title) {console.log(`Title: ${article.title}`);}
+if (mode === "remote" && session?.devtoolsFrontendUrl) {
+  console.log(`DevTools: ${session.devtoolsFrontendUrl}`);
+}
+console.log(`Mode: ${mode}`);
 console.log("");
 console.log(content);
 

package/resources/browser-tools/browser-cookies.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import { connectBrowser } from "./browser-connect.js";
+
+const { browser: b, mode, session } = await connectBrowser();
+
+const p = (await b.pages()).at(-1);
+
+if (!p) {
+  console.error("✗ No active tab found");
+  process.exit(1);
+}
+
+const cookies = await p.cookies();
+
+const result = { mode, cookies };
+if (session?.devtoolsFrontendUrl) {
+  result.devtoolsFrontendUrl = session.devtoolsFrontendUrl;
+}
+console.log(JSON.stringify(result));
+
+await b.disconnect();

package/resources/browser-tools/browser-eval.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { connectBrowser } from "./browser-connect.js";
+
+const code = process.argv.slice(2).join(" ");
+if (!code) {
+  console.log("Usage: browser-eval.js 'code'");
+  console.log("\nExamples:");
+  console.log('  browser-eval.js "document.title"');
+  console.log('  browser-eval.js "document.querySelectorAll(\'a\').length"');
+  process.exit(1);
+}
+
+const { browser: b, mode, session } = await connectBrowser();
+
+const p = (await b.pages()).at(-1);
+
+if (!p) {
+  console.error("✗ No active tab found");
+  process.exit(1);
+}
+
+const evalResult = await p.evaluate((c) => {
+  const AsyncFunction = (async() => {}).constructor;
+  return new AsyncFunction(`return (${c})`)();
+}, code);
+
+const output = { mode, result: evalResult };
+if (session?.devtoolsFrontendUrl) {
+  output.devtoolsFrontendUrl = session.devtoolsFrontendUrl;
+}
+console.log(JSON.stringify(output));
+
+await b.disconnect();

package/resources/{chrome-tools → browser-tools}/browser-nav.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import puppeteer from "puppeteer-core";
+import { connectBrowser } from "./browser-connect.js";
 
 const args = process.argv.slice(2);
 const newTab = args.includes("--new");
@@ -16,29 +16,23 @@ if (!url) {
   process.exit(1);
 }
 
-const b = await Promise.race([
-  puppeteer.connect({
-    browserURL: "http://localhost:9222",
-    defaultViewport: null,
-  }),
-  new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 5000)),
-]).catch((e) => {
-  console.error("✗ Could not connect to browser:", e.message);
-  console.error("  Run: browser-start.js");
-  process.exit(1);
-});
+const { browser: b, mode, session } = await connectBrowser();
 
 if (newTab) {
   const p = await b.newPage();
   await p.goto(url, { waitUntil: "domcontentloaded" });
-  console.log("✓ Opened:", url);
 } else {
   const p = (await b.pages()).at(-1);
   await p.goto(url, { waitUntil: "domcontentloaded" });
   if (reload) {
     await p.reload({ waitUntil: "domcontentloaded" });
   }
-  console.log("✓ Navigated to:", url);
 }
 
+const result = { mode, url };
+if (session?.devtoolsFrontendUrl) {
+  result.devtoolsFrontendUrl = session.devtoolsFrontendUrl;
+}
+console.log(JSON.stringify(result));
+
 await b.disconnect();

package/resources/{chrome-tools → browser-tools}/browser-pick.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import puppeteer from "puppeteer-core";
+import { connectBrowser } from "./browser-connect.js";
 
 const message = process.argv.slice(2).join(" ");
 if (!message) {
@@ -10,17 +10,7 @@ if (!message) {
   process.exit(1);
 }
 
-const b = await Promise.race([
-  puppeteer.connect({
-    browserURL: "http://localhost:9222",
-    defaultViewport: null,
-  }),
-  new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 5000)),
-]).catch((e) => {
-  console.error("✗ Could not connect to browser:", e.message);
-  console.error("  Run: browser-start.js");
-  process.exit(1);
-});
+const { browser: b, mode, session } = await connectBrowser();
 
 const p = (await b.pages()).at(-1);
 
@@ -142,21 +132,12 @@ await p.evaluate(() => {
   }
 });
 
-const result = await p.evaluate((msg) => window.pick(msg), message);
+const selection = await p.evaluate((msg) => window.pick(msg), message);
 
-if (Array.isArray(result)) {
-  for (let i = 0; i < result.length; i++) {
-    if (i > 0) {console.log("");}
-    for (const [key, value] of Object.entries(result[i])) {
-      console.log(`${key}: ${value}`);
-    }
-  }
-} else if (typeof result === "object" && result !== null) {
-  for (const [key, value] of Object.entries(result)) {
-    console.log(`${key}: ${value}`);
-  }
-} else {
-  console.log(result);
+const output = { mode, selection };
+if (session?.devtoolsFrontendUrl) {
+  output.devtoolsFrontendUrl = session.devtoolsFrontendUrl;
 }
+console.log(JSON.stringify(output));
 
 await b.disconnect();

package/resources/browser-tools/browser-run-script.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * Run a user-supplied CDP script on the active browser session.
+ *
+ * Usage: node browser-run-script.js <script> [--appId <id>] [--appSlug <slug>]
+ *
+ * The script file receives `browser` (Puppeteer Browser) and `page` (first Page)
+ * as function arguments. Whatever the script returns is printed as JSON to stdout.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { connectBrowser } from "./browser-connect.js";
+
+const args = process.argv.slice(2);
+
+const scriptPath = args.find((a) => !a.startsWith("--") && args[args.indexOf(a) - 1]?.startsWith("--") === false) ?? args[0];
+
+if (!scriptPath || scriptPath.startsWith("--")) {
+  console.error("Usage: browser-run-script.js <script.js> [--appId <id>] [--appSlug <slug>]");
+  console.error("\nThe script receives `browser` and `page` as arguments.");
+  console.error("\nExample script:");
+  console.error('  await page.goto("https://example.com");');
+  console.error("  return { title: await page.title() };");
+  process.exit(1);
+}
+
+const { browser, mode, session } = await connectBrowser();
+
+try {
+  const page = await browser.newPage();
+
+  const userCode = readFileSync(resolve(scriptPath), "utf8");
+  const AsyncFunction = (async() => {}).constructor;
+  const fn = new AsyncFunction("browser", "page", userCode);
+  const scriptResult = await fn(browser, page);
+
+  const output = { mode, result: scriptResult ?? { ok: true } };
+  if (session?.devtoolsFrontendUrl) {
+    output.devtoolsFrontendUrl = session.devtoolsFrontendUrl;
+  }
+  console.log(JSON.stringify(output, null, 2));
+} catch (e) {
+  console.error("✗ CDP script failed:", e.message);
+  process.exit(1);
+} finally {
+  try {
+    await browser.disconnect();
+  } catch {
+    // Session may have already expired.
+  }
+}

package/resources/{chrome-tools → browser-tools}/browser-screenshot.js

@@ -2,19 +2,9 @@
 
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import puppeteer from "puppeteer-core";
-
-const b = await Promise.race([
-  puppeteer.connect({
-    browserURL: "http://localhost:9222",
-    defaultViewport: null,
-  }),
-  new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 5000)),
-]).catch((e) => {
-  console.error("✗ Could not connect to browser:", e.message);
-  console.error("  Run: browser-start.js");
-  process.exit(1);
-});
+import { connectBrowser } from "./browser-connect.js";
+
+const { browser: b, mode, session } = await connectBrowser();
 
 const p = (await b.pages()).at(-1);
 
@@ -29,6 +19,10 @@ const filepath = join(tmpdir(), filename);
 
 await p.screenshot({ path: filepath });
 
-console.log(filepath);
+const result = { mode, path: filepath };
+if (session?.devtoolsFrontendUrl) {
+  result.devtoolsFrontendUrl = session.devtoolsFrontendUrl;
+}
+console.log(JSON.stringify(result));
 
 await b.disconnect();

package/resources/{chrome-tools → browser-tools}/browser-start.js

@@ -2,16 +2,33 @@
 
 import { spawn, execSync } from "node:child_process";
 import puppeteer from "puppeteer-core";
+import { isSandboxMode, connectBrowser } from "./browser-connect.js";
 
 const useProfile = process.argv[2] === "--profile";
 
 if (process.argv[2] && process.argv[2] !== "--profile") {
   console.log("Usage: browser-start.js [--profile]");
   console.log("\nOptions:");
-  console.log("  --profile  Copy your default Chrome profile (cookies, logins)");
+  console.log("  --profile  Copy your default Chrome profile (cookies, logins) — local mode only");
   process.exit(1);
 }
 
+// Sandbox mode: create a remote Cloudflare Browser Rendering session
+if (isSandboxMode()) {
+  const { session } = await connectBrowser();
+
+  const result = {
+    mode: "remote",
+    sessionId: session.sessionId,
+    tabUrl: session.tabUrl,
+    devtoolsFrontendUrl: session.devtoolsFrontendUrl,
+  };
+  console.log(JSON.stringify(result));
+  process.exit(0);
+}
+
+// Local mode: start Chrome on :9222
+// Note: execSync calls below use only hardcoded paths, not user input.
 const SCRAPING_DIR = `${process.env.HOME}/.cache/browser-tools`;
 
 // Check if already running on :9222
@@ -21,7 +38,7 @@ try {
     defaultViewport: null,
   });
   await browser.disconnect();
-  console.log("✓ Chrome already running on :9222");
+  console.log(JSON.stringify({ mode: "local", status: "already_running" }));
   process.exit(0);
 } catch {}
 
@@ -34,7 +51,7 @@ try {
 } catch {}
 
 if (useProfile) {
-  console.log("Syncing profile...");
+  console.error("Syncing profile...");
   execSync(
     `rsync -a --delete \
 			--exclude='SingletonLock' \
@@ -83,4 +100,4 @@ if (!connected) {
   process.exit(1);
 }
 
-console.log(`✓ Chrome started on :9222${useProfile ? " with your profile" : ""}`);
+console.log(JSON.stringify({ mode: "local", status: "started", profile: useProfile }));

package/resources/pi-agent/extensions/docyrus-web-browser.ts

@@ -1,9 +1,9 @@
 import { isToolCallEventType, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { buildDocyrusWebBrowserProtocolInstructions } from "../shared/docyrusWebBrowserProtocol";
 
-const DOCYRUS_CHROME_COMMAND_PATTERN = /\bdocyrus\b(?:\s+-g|\s+--global)?\s+chrome\b/;
-const DOCYRUS_CHROME_BLOCK_REASON =
-  "Docyrus Server sessions must use the docyrus-web-browser preview tools instead of `docyrus chrome`.";
+const DOCYRUS_BROWSER_COMMAND_PATTERN = /\bdocyrus\b(?:\s+-g|\s+--global)?\s+(?:browser|chrome)\b/;
+const DOCYRUS_BROWSER_BLOCK_REASON =
+  "Docyrus Server sessions must use the docyrus-web-browser preview tools instead of `docyrus browser`.";
 
 export default function docyrusWebBrowserExtension(pi: ExtensionAPI) {
   pi.on("before_agent_start", async(event) => {
@@ -19,13 +19,13 @@ export default function docyrusWebBrowserExtension(pi: ExtensionAPI) {
     }
 
     const command = typeof event.input.command === "string" ? event.input.command.trim() : "";
-    if (!command || !DOCYRUS_CHROME_COMMAND_PATTERN.test(command)) {
+    if (!command || !DOCYRUS_BROWSER_COMMAND_PATTERN.test(command)) {
       return;
     }
 
     return {
       block: true,
-      reason: DOCYRUS_CHROME_BLOCK_REASON,
+      reason: DOCYRUS_BROWSER_BLOCK_REASON,
     };
   });
 }

package/resources/pi-agent/shared/docyrusWebBrowserProtocol.ts

@@ -141,7 +141,7 @@ export function parseDocyrusWebBrowserRequestFromText(text: string): IDocyrusWeb
 export function buildDocyrusWebBrowserProtocolInstructions(): string {
   return [
     "When you need to inspect or automate the Docyrus web preview in server-backed sessions, use the docyrus-web-browser client tools.",
-    "Do not use `docyrus chrome` or any visible Chrome DevTools workflow in this environment.",
+    "Do not use `docyrus browser` or any visible Chrome DevTools workflow in this environment.",
     `Instead, output only a single ${DOCYRUS_WEB_BROWSER_OPEN}...${DOCYRUS_WEB_BROWSER_CLOSE} block and nothing else in the assistant message.`,
     "Inside that block, emit strict JSON with this shape:",
     "{\"tool\":\"web_preview_context\",\"input\":{\"includeSnapshot\":true}}",