@duckmind/dm-windows-x64 0.60.4 → 0.60.8

package/extensions/greedysearch-dm/extractors/common.mjs

@@ -1,8 +1,127 @@
-import{randomInt as E}from"node:crypto";import{spawn as A}from"node:child_process";import{basename as D}from"node:path";function C(K=process.env,Q=process.execPath){let X=K.GREEDY_SEARCH_NODE||K.NODE_BINARY||K.NODE;if(X?.trim())return X.trim();let Y=D(Q||"").toLowerCase();if(Y==="node"||Y==="node.exe")return Q;return"node"}import{dirname as T,join as w}from"node:path";import{fileURLToPath as B}from"node:url";var R=T(B(import.meta.url)),z=w(R,"..","bin","cdp.mjs"),y=new Set(["list","snap","eval","shot","html","nav","net","click","clickxy","type","loadall","evalraw","browse","stop","--tab"]);function V(K){if(!Array.isArray(K)||K.length===0)throw Error("cdp: args must be a non-empty array");if(K[0]==="test")return K.map((Q,X)=>F(Q,X));if(!y.has(K[0]))throw Error(`cdp: unknown subcommand '${K[0]}'`);return K.map((Q,X)=>F(Q,X))}function F(K,Q){if(typeof K!=="string")throw Error(`cdp: argv[${Q}] must be a string (got ${typeof K})`);if(K.includes("\x00"))throw Error(`cdp: argv[${Q}] contains a null byte`);return K}function O(K,Q=30000){return L(K,null,Q)}function L(K,Q=null,X=30000){let Y=V(K);return new Promise((Z,q)=>{let $=A(C(),[z,...Y],{stdio:[Q==null?"ignore":"pipe","pipe","pipe"]});if(Q!=null)$.stdin.write(Q),$.stdin.end();let J="",W="";$.stdout.on("data",(H)=>J+=H),$.stderr.on("data",(H)=>W+=H);let G=setTimeout(()=>{$.kill(),q(Error(`cdp timeout: ${K[0]}`))},X);$.on("close",(H)=>{if(clearTimeout(G),H===0)Z(J.trim());else q(Error(W.trim()||`cdp exit ${H}`))})})}function m(K,Q){let X=($)=>String($??"").replace(/\s+/g," ").trim(),Y=X(K),Z=X(Q);if(!Z)return!1;if(Y.length<Math.ceil(Z.length*0.8))return!1;let q=Math.min(40,Z.length);return Y.includes(Z.slice(0,q))&&Y.includes(Z.slice(-q))}async function x(K){if(K)return K;let X=(await O(["list"])).split(`
-`)[0]?.slice(0,8);if(!X)throw Error("No Chrome tabs found. Is Chrome running with --remote-debugging-port=9222?");let Y=await O(["evalraw",X,"Target.createTarget",'{"url":"about:blank"}']),Z;try{Z=JSON.parse(Y)}catch(J){throw Error(`Target.createTarget returned invalid JSON: ${J.message}`)}let{targetId:q}=Z;if(!q)throw Error("Target.createTarget did not return a targetId");await O(["list"]);let $=q.slice(0,8);try{await j($)}catch(J){process.stderr.write(`[getOrOpenTab] stealth injection failed: ${J.message}
-`)}return $}async function g(K,Q){let X=`
+import { randomInt } from "node:crypto";
+import { spawn } from "node:child_process";
+import { nodeRuntimeCommand } from "../src/utils/node-runtime.mjs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dir = dirname(fileURLToPath(import.meta.url));
+const CDP = join(__dir, "..", "bin", "cdp.mjs");
+const VALID_CDP_COMMANDS = new Set([
+  "list",
+  "snap",
+  "eval",
+  "shot",
+  "html",
+  "nav",
+  "net",
+  "click",
+  "clickxy",
+  "type",
+  "loadall",
+  "evalraw",
+  "browse",
+  "stop",
+  "--tab"
+]);
+function cdpSafeArgv(args) {
+  if (!Array.isArray(args) || args.length === 0) {
+    throw new Error("cdp: args must be a non-empty array");
+  }
+  if (args[0] === "test")
+    return args.map((v, i) => validateArg(v, i));
+  if (!VALID_CDP_COMMANDS.has(args[0])) {
+    throw new Error(`cdp: unknown subcommand '${args[0]}'`);
+  }
+  return args.map((v, i) => validateArg(v, i));
+}
+function validateArg(value, index) {
+  if (typeof value !== "string") {
+    throw new Error(`cdp: argv[${index}] must be a string (got ${typeof value})`);
+  }
+  if (value.includes("\x00")) {
+    throw new Error(`cdp: argv[${index}] contains a null byte`);
+  }
+  return value;
+}
+export function cdp(args, timeoutMs = 30000) {
+  return cdpWithInput(args, null, timeoutMs);
+}
+export function cdpWithInput(args, input = null, timeoutMs = 30000) {
+  const safeArgs = cdpSafeArgv(args);
+  return new Promise((resolve, reject) => {
+    const proc = spawn(nodeRuntimeCommand(), [CDP, ...safeArgs], {
+      stdio: [input == null ? "ignore" : "pipe", "pipe", "pipe"]
+    });
+    if (input != null) {
+      proc.stdin.write(input);
+      proc.stdin.end();
+    }
+    let out = "";
+    let err = "";
+    proc.stdout.on("data", (d) => out += d);
+    proc.stderr.on("data", (d) => err += d);
+    const timer = setTimeout(() => {
+      proc.kill();
+      reject(new Error(`cdp timeout: ${args[0]}`));
+    }, timeoutMs);
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0)
+        resolve(out.trim());
+      else
+        reject(new Error(err.trim() || `cdp exit ${code}`));
+    });
+  });
+}
+export function verifyInputText(actual, expected) {
+  const normalize = (value) => String(value ?? "").replace(/\s+/g, " ").trim();
+  const actualNormalized = normalize(actual);
+  const expectedNormalized = normalize(expected);
+  if (!expectedNormalized)
+    return false;
+  if (actualNormalized.length < Math.ceil(expectedNormalized.length * 0.8)) {
+    return false;
+  }
+  const sampleLength = Math.min(40, expectedNormalized.length);
+  return actualNormalized.includes(expectedNormalized.slice(0, sampleLength)) && actualNormalized.includes(expectedNormalized.slice(-sampleLength));
+}
+export async function getOrOpenTab(tabPrefix) {
+  if (tabPrefix)
+    return tabPrefix;
+  const list = await cdp(["list"]);
+  const anchor = list.split(`
+`)[0]?.slice(0, 8);
+  if (!anchor)
+    throw new Error("No Chrome tabs found. Is Chrome running with --remote-debugging-port=9222?");
+  const raw = await cdp([
+    "evalraw",
+    anchor,
+    "Target.createTarget",
+    '{"url":"about:blank"}'
+  ]);
+  let createdTarget;
+  try {
+    createdTarget = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Target.createTarget returned invalid JSON: ${error.message}`);
+  }
+  const { targetId } = createdTarget;
+  if (!targetId) {
+    throw new Error("Target.createTarget did not return a targetId");
+  }
+  await cdp(["list"]);
+  const tid = targetId.slice(0, 8);
+  try {
+    await injectHeadlessStealth(tid);
+  } catch (e) {
+    process.stderr.write(`[getOrOpenTab] stealth injection failed: ${e.message}
+`);
+  }
+  return tid;
+}
+export async function injectClipboardInterceptor(tab, globalVar) {
+  const code = `
     (() => {
-      window.${Q} = null;
+      window.${globalVar} = null;
       const _clipboard = navigator.clipboard;
       if (!_clipboard) return;
       const _origWriteText = typeof _clipboard.writeText === 'function'
@@ -13,7 +132,7 @@ import{randomInt as E}from"node:crypto";import{spawn as A}from"node:child_proces
         : null;
 
       _clipboard.writeText = function(text) {
-        window.${Q} = String(text ?? '');
+        window.${globalVar} = String(text ?? '');
         if (!_origWriteText) return Promise.resolve();
         // The OS/browser clipboard write may be denied in automated Chrome or
         // when the tab is not focused. We only need the captured text; returning
@@ -27,7 +146,7 @@ import{randomInt as E}from"node:crypto";import{spawn as A}from"node:child_proces
           for (const item of items || []) {
             if (item.types && item.types.includes('text/plain')) {
               const blob = await item.getType('text/plain');
-              window.${Q} = await blob.text();
+              window.${globalVar} = await blob.text();
               break;
             }
           }
@@ -37,26 +156,36 @@ import{randomInt as E}from"node:crypto";import{spawn as A}from"node:child_proces
         catch (_) { return undefined; }
       };
     })();
-  `;await O(["eval",K,X])}async function p(K,Q,X,Y={}){let{timeoutMs:Z=2600}=Y,q=Y.retryClick!=null?Y.retryClick:Math.floor(Z*0.4),$=String.raw`
+  `;
+  await cdp(["eval", tab, code]);
+}
+export async function clickCopyAndAwaitClipboard(tab, clickExpr, globalVar, options = {}) {
+  const { timeoutMs = 2600 } = options;
+  const retryClick = options.retryClick != null ? options.retryClick : Math.floor(timeoutMs * 0.4);
+  const code = String.raw`
 	new Promise((resolve) => {
-		const _deadline = Date.now() + ${Z};
-		const _retryAt = Date.now() + ${q};
+		const _deadline = Date.now() + ${timeoutMs};
+		const _retryAt = Date.now() + ${retryClick};
 		let _retried = false;
-		function _click() { try { ${Q}; } catch(_) {} }
+		function _click() { try { ${clickExpr}; } catch(_) {} }
 		function _poll() {
-			const val = window.${X};
+			const val = window.${globalVar};
 			if (val) { resolve(val); return; }
 			if (!_retried && Date.now() >= _retryAt) {
 				_retried = true;
 				_click();
 			}
 			if (Date.now() < _deadline) { setTimeout(_poll, 100); }
-			else { resolve(window.${X} || ''); }
+			else { resolve(window.${globalVar} || ''); }
 		}
 		_click();
 		_poll();
 	})
-	`;return await O(["eval",K,$],Z+5000).catch(()=>"")}async function j(K){await O(["evalraw",K,"Page.addScriptToEvaluateOnNewDocument",JSON.stringify({source:`
+	`;
+  return await cdp(["eval", tab, code], timeoutMs + 5000).catch(() => "");
+}
+export async function injectHeadlessStealth(tab) {
+  const code = `
 (function() {
   // ── Runtime.enable / CDP detection masking ──────────────
   try { delete window.__REBROWSER_RUNTIME_ENABLE; } catch(_) {}
@@ -341,22 +470,168 @@ import{randomInt as E}from"node:crypto";import{spawn as A}from"node:child_proces
     };
   } catch(_) {}
 })();
-`})])}function u(K){if(!K)return[];let Q=[],X=0;while(X<K.length&&Q.length<10){let Y=K.indexOf("[",X);if(Y===-1)break;let Z=K.indexOf("](",Y);if(Z===-1)break;let q=Z+2,$=-1;for(let J=q;J<K.length;J++){let W=K[J];if(W===")"){$=J;break}if(/\s/.test(W))break}if($!==-1){let J=K.slice(Y+1,Z),W=K.slice(q,$);if(/^https?:\/\//i.test(W)&&J){if(!Q.some((G)=>G.url===W))Q.push({title:J,url:W})}X=$+1}else X=Y+1}return Q}function N(K){if(!K)return!1;for(let Q=0;Q<K.length;Q++){let X=K.charCodeAt(Q);if(X<48||X>57)return!1}return!0}function d(K){if(!K)return[];let Q=[],X=new Map,Y=/^\[(\d+)\]:\s*(https?:\/\/[^\s"]+)(?:\s+"([^"]*)")?/gm,Z;while((Z=Y.exec(K))!==null){let $=Z[1],J=Z[2],W=Z[3]||"";X.set($,{url:J,title:W})}let q=0;while(q<K.length){let $=K.indexOf("[",q);if($===-1)break;let J=K.indexOf("]",$+1);if(J===-1)break;if(K[J+1]!=="["){q=$+1;continue}let W=K.indexOf("]",J+2);if(W===-1)break;let G=K.slice($+1,J),H=K.slice(J+2,W);if(N(H)){let U=X.get(H);if(U&&!Q.some((_)=>_.url===U.url))Q.push({title:G.trim()||U.title||"",url:U.url})}q=W+1}return Q}var S={postNav:800,postNavSlow:1200,postClick:300,postType:300,inputPoll:400,copyPoll:600,afterVerify:1500};async function c(K,Q,X={}){let{timeout:Y=60000,onPoll:Z}=X;if(!Z){let J=String.raw`
+`;
+  await cdp([
+    "evalraw",
+    tab,
+    "Page.addScriptToEvaluateOnNewDocument",
+    JSON.stringify({ source: code })
+  ]);
+}
+export function parseSourcesFromMarkdown(text) {
+  if (!text)
+    return [];
+  const results = [];
+  let idx = 0;
+  while (idx < text.length && results.length < 10) {
+    const openBracket = text.indexOf("[", idx);
+    if (openBracket === -1)
+      break;
+    const closeBracket = text.indexOf("](", openBracket);
+    if (closeBracket === -1)
+      break;
+    const openParen = closeBracket + 2;
+    let closeParen = -1;
+    for (let p = openParen;p < text.length; p++) {
+      const ch = text[p];
+      if (ch === ")") {
+        closeParen = p;
+        break;
+      }
+      if (/\s/.test(ch))
+        break;
+    }
+    if (closeParen !== -1) {
+      const title = text.slice(openBracket + 1, closeBracket);
+      const url = text.slice(openParen, closeParen);
+      if (/^https?:\/\//i.test(url) && title) {
+        if (!results.some((r) => r.url === url)) {
+          results.push({ title, url });
+        }
+      }
+      idx = closeParen + 1;
+    } else {
+      idx = openBracket + 1;
+    }
+  }
+  return results;
+}
+function isAllDigits(s) {
+  if (!s)
+    return false;
+  for (let k = 0;k < s.length; k++) {
+    const c = s.charCodeAt(k);
+    if (c < 48 || c > 57)
+      return false;
+  }
+  return true;
+}
+export function parseSourcesFromMarkdownRefStyle(text) {
+  if (!text)
+    return [];
+  const results = [];
+  const refMap = new Map;
+  const refRegex = /^\[(\d+)\]:\s*(https?:\/\/[^\s"]+)(?:\s+"([^"]*)")?/gm;
+  let m;
+  while ((m = refRegex.exec(text)) !== null) {
+    const num = m[1];
+    const url = m[2];
+    const title = m[3] || "";
+    refMap.set(num, { url, title });
+  }
+  let cursor = 0;
+  while (cursor < text.length) {
+    const open = text.indexOf("[", cursor);
+    if (open === -1)
+      break;
+    const close = text.indexOf("]", open + 1);
+    if (close === -1)
+      break;
+    if (text[close + 1] !== "[") {
+      cursor = open + 1;
+      continue;
+    }
+    const close2 = text.indexOf("]", close + 2);
+    if (close2 === -1)
+      break;
+    const inner = text.slice(open + 1, close);
+    const numStr = text.slice(close + 2, close2);
+    if (isAllDigits(numStr)) {
+      const ref = refMap.get(numStr);
+      if (ref && !results.some((r) => r.url === ref.url)) {
+        results.push({
+          title: inner.trim() || ref.title || "",
+          url: ref.url
+        });
+      }
+    }
+    cursor = close2 + 1;
+  }
+  return results;
+}
+export const TIMING = {
+  postNav: 800,
+  postNavSlow: 1200,
+  postClick: 300,
+  postType: 300,
+  inputPoll: 400,
+  copyPoll: 600,
+  afterVerify: 1500
+};
+export async function waitForCopyButton(tab, selector, options = {}) {
+  const { timeout = 60000, onPoll } = options;
+  if (!onPoll) {
+    const code = String.raw`
 		new Promise((resolve) => {
-			const _deadline = Date.now() + ${Y};
+			const _deadline = Date.now() + ${timeout};
 			function _poll() {
-				if (document.querySelector('${Q}')) { resolve(true); return; }
+				if (document.querySelector('${selector}')) { resolve(true); return; }
 				if (Date.now() < _deadline) { setTimeout(_poll, 150); }
 				else { resolve(false); }
 			}
 			_poll();
 		})
-		`;if(await O(["eval",K,J],Y+5000).catch(()=>"false")==="true")return;throw Error(`Copy button ('${Q}') did not appear within ${Y}ms`)}let q=Date.now()+Y,$=0;while(Date.now()<q){if(await O(["eval",K,`!!document.querySelector('${Q}')`]).catch(()=>"false")==="true")return;await Z(++$).catch(()=>null),await new Promise((W)=>setTimeout(W,M(S.copyPoll)))}throw Error(`Copy button ('${Q}') did not appear within ${Y}ms`)}function M(K){let Q=K*0.2,X=E(-Math.floor(Q),Math.floor(Q)+1);return Math.max(50,Math.round(K+X))}async function i(K,Q={}){let{timeout:X=20000,interval:Y=600,stableRounds:Z=3,selector:q="document.body",minLength:$=0,isStreamingExpr:J="false"}=Q,W=String.raw`
+		`;
+    const found = await cdp(["eval", tab, code], timeout + 5000).catch(() => "false");
+    if (found === "true")
+      return;
+    throw new Error(`Copy button ('${selector}') did not appear within ${timeout}ms`);
+  }
+  const deadline = Date.now() + timeout;
+  let tick = 0;
+  while (Date.now() < deadline) {
+    const found = await cdp([
+      "eval",
+      tab,
+      `!!document.querySelector('${selector}')`
+    ]).catch(() => "false");
+    if (found === "true")
+      return;
+    await onPoll(++tick).catch(() => null);
+    await new Promise((r) => setTimeout(r, jitter(TIMING.copyPoll)));
+  }
+  throw new Error(`Copy button ('${selector}') did not appear within ${timeout}ms`);
+}
+export function jitter(ms) {
+  const variance = ms * 0.2;
+  const offset = randomInt(-Math.floor(variance), Math.floor(variance) + 1);
+  return Math.max(50, Math.round(ms + offset));
+}
+export async function waitForStreamComplete(tab, options = {}) {
+  const {
+    timeout = 20000,
+    interval = 600,
+    stableRounds = 3,
+    selector = "document.body",
+    minLength = 0,
+    isStreamingExpr = "false"
+  } = options;
+  const code = String.raw`
 	new Promise((resolve, reject) => {
-		const _deadline = Date.now() + ${X};
-		const _baseInterval = ${Y};
-		const _stableRounds = ${Z};
-		const _minLength = ${$};
+		const _deadline = Date.now() + ${timeout};
+		const _baseInterval = ${interval};
+		const _stableRounds = ${stableRounds};
+		const _minLength = ${minLength};
 		let _lastLen = -1;
 		let _stableCount = 0;
 
@@ -367,9 +642,9 @@ import{randomInt as E}from"node:crypto";import{spawn as A}from"node:child_proces
 		function _poll() {
 			try {
 				// Re-query DOM each tick — element may not exist at eval start
-				const el = ${q};
+				const el = ${selector};
 				const cur = el?.textContent?.length ?? 0;
-				const streaming = ${J};
+				const streaming = ${isStreamingExpr};
 				if (streaming) {
 					if (cur !== _lastLen) _lastLen = cur;
 					_stableCount = 0;
@@ -386,17 +661,25 @@ import{randomInt as E}from"node:crypto";import{spawn as A}from"node:child_proces
 					setTimeout(_poll, _jitter(_baseInterval));
 				} else {
 					if (_lastLen >= _minLength && !streaming) { resolve(_lastLen); }
-					else { reject(new Error('Generation did not stabilise within ${X}ms')); }
+					else { reject(new Error('Generation did not stabilise within ${timeout}ms')); }
 				}
 			} catch(e) { reject(e); }
 		}
 
 		_poll();
 	})
-	`,G=await O(["eval",K,W],X+1e4),H=parseInt(G,10)||0;if(H>=$)return H;throw Error(`Generation did not stabilise within ${X}ms`)}async function l(K,Q,X=15000,Y=500){let Z=String.raw`
+	`;
+  const lenStr = await cdp(["eval", tab, code], timeout + 1e4);
+  const currentLen = parseInt(lenStr, 10) || 0;
+  if (currentLen >= minLength)
+    return currentLen;
+  throw new Error(`Generation did not stabilise within ${timeout}ms`);
+}
+export async function waitForSelector(tab, selector, timeoutMs = 15000, interval = 500) {
+  const code = String.raw`
 	new Promise((resolve) => {
-		const _deadline = Date.now() + ${X};
-		const _baseInterval = ${Y};
+		const _deadline = Date.now() + ${timeoutMs};
+		const _baseInterval = ${interval};
 
 		function _jitter(ms) {
 			return Math.max(50, ms + (Math.random() * ms * 0.4 - ms * 0.2));
@@ -404,7 +687,7 @@ import{randomInt as E}from"node:crypto";import{spawn as A}from"node:child_proces
 
 		function _poll() {
 			try {
-				if (document.querySelector('${Q}')) { resolve(true); return; }
+				if (document.querySelector('${selector}')) { resolve(true); return; }
 				if (Date.now() < _deadline) { setTimeout(_poll, _jitter(_baseInterval)); }
 				else { resolve(false); }
 			} catch(_) { resolve(false); }
@@ -412,7 +695,100 @@ import{randomInt as E}from"node:crypto";import{spawn as A}from"node:child_proces
 
 		_poll();
 	})
-	`;return await O(["eval",K,Z],X+5000)==="true"}async function n(K){let Q=K.indexOf("--stdin");if(Q===-1)return K;let X=await new Promise((Z)=>{let q="";process.stdin.setEncoding("utf8"),process.stdin.on("data",($)=>q+=$),process.stdin.on("end",()=>Z(q.trim()))}),Y=[...K];return Y[Q]=X,Y}function s(K){let Q=K.includes("--short"),X=K.filter((W)=>W!=="--short"),Y=X.indexOf("--tab"),Z=Y===-1?null:X[Y+1];if(Y!==-1)X=X.filter((W,G)=>G!==Y&&G!==Y+1);let q=X.indexOf("--locale"),$=q===-1?null:X[q+1];if(q!==-1)X=X.filter((W,G)=>G!==q&&G!==q+1);return{query:X.join(" "),tabPrefix:Z,short:Q,locale:$}}function o(K,Q){if(!K.length||K[0]==="--help")process.stderr.write(Q),process.exit(1)}function r(K,Q,X=300){if(!Q||K.length<=X)return K;let Y=K.slice(0,X),Z=Y.lastIndexOf(" ");return Z>0?`${Y.slice(0,Z)}…`:`${Y}…`}function a(K){process.stdout.write(`${JSON.stringify(K,null,2)}
-`)}function t(K,Q,X=null){if(!K||typeof K!=="object")return;let Y=X?` (+${Date.now()-X}ms)`:"";if(K.lastStage=Q,!Array.isArray(K.stages))K.stages=[];K.stages.push({stage:Q,at:Date.now()});let Z=K.engine||"extractor";console.error(`[${Z}] stage: ${Q}${Y}`)}function e({engine:K,mode:Q="headless",clipboardEmpty:X=null,fallbackUsed:Y=null,blockedBy:Z=null,verificationResult:q=null,inputReady:$=null,durationMs:J=null,lastStage:W=null,stages:G=null}={}){return{engine:K,mode:Q,clipboardEmpty:X,fallbackUsed:Y,blockedBy:Z,verificationResult:q,inputReady:$,durationMs:J,lastStage:W,stages:G}}function KK(K,Q=null){if(Q){let X=JSON.stringify({_envelope:Q,error:K.message});process.stdout.write(`${X}
-`)}process.stderr.write(`Error: ${K.message}
-`),process.exit(1)}export{i as waitForStreamComplete,l as waitForSelector,c as waitForCopyButton,m as verifyInputText,o as validateQuery,n as prepareArgs,d as parseSourcesFromMarkdownRefStyle,u as parseSourcesFromMarkdown,s as parseArgs,a as outputJson,t as logStage,M as jitter,j as injectHeadlessStealth,g as injectClipboardInterceptor,KK as handleError,x as getOrOpenTab,r as formatAnswer,p as clickCopyAndAwaitClipboard,L as cdpWithInput,O as cdp,e as buildEnvelope,S as TIMING};
+	`;
+  const result = await cdp(["eval", tab, code], timeoutMs + 5000);
+  return result === "true";
+}
+export async function prepareArgs(args) {
+  const stdinIdx = args.indexOf("--stdin");
+  if (stdinIdx === -1)
+    return args;
+  const query = await new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => data += chunk);
+    process.stdin.on("end", () => resolve(data.trim()));
+  });
+  const modified = [...args];
+  modified[stdinIdx] = query;
+  return modified;
+}
+export function parseArgs(args) {
+  const short = args.includes("--short");
+  let rest = args.filter((a) => a !== "--short");
+  const tabFlagIdx = rest.indexOf("--tab");
+  const tabPrefix = tabFlagIdx === -1 ? null : rest[tabFlagIdx + 1];
+  if (tabFlagIdx !== -1) {
+    rest = rest.filter((_, i) => i !== tabFlagIdx && i !== tabFlagIdx + 1);
+  }
+  const localeIdx = rest.indexOf("--locale");
+  const locale = localeIdx === -1 ? null : rest[localeIdx + 1];
+  if (localeIdx !== -1) {
+    rest = rest.filter((_, i) => i !== localeIdx && i !== localeIdx + 1);
+  }
+  const query = rest.join(" ");
+  return { query, tabPrefix, short, locale };
+}
+export function validateQuery(args, usage) {
+  if (!args.length || args[0] === "--help") {
+    process.stderr.write(usage);
+    process.exit(1);
+  }
+}
+export function formatAnswer(answer, short, maxLen = 300) {
+  if (!short || answer.length <= maxLen)
+    return answer;
+  const truncated = answer.slice(0, maxLen);
+  const lastSpace = truncated.lastIndexOf(" ");
+  return lastSpace > 0 ? `${truncated.slice(0, lastSpace)}…` : `${truncated}…`;
+}
+export function outputJson(data) {
+  process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+}
+export function logStage(env, stage, startTime = null) {
+  if (!env || typeof env !== "object")
+    return;
+  const elapsed = startTime ? ` (+${Date.now() - startTime}ms)` : "";
+  env.lastStage = stage;
+  if (!Array.isArray(env.stages))
+    env.stages = [];
+  env.stages.push({ stage, at: Date.now() });
+  const engine = env.engine || "extractor";
+  console.error(`[${engine}] stage: ${stage}${elapsed}`);
+}
+export function buildEnvelope({
+  engine,
+  mode = "headless",
+  clipboardEmpty = null,
+  fallbackUsed = null,
+  blockedBy = null,
+  verificationResult = null,
+  inputReady = null,
+  durationMs = null,
+  lastStage = null,
+  stages = null
+} = {}) {
+  return {
+    engine,
+    mode,
+    clipboardEmpty,
+    fallbackUsed,
+    blockedBy,
+    verificationResult,
+    inputReady,
+    durationMs,
+    lastStage,
+    stages
+  };
+}
+export function handleError(error, envelope = null) {
+  if (envelope) {
+    const out = JSON.stringify({ _envelope: envelope, error: error.message });
+    process.stdout.write(`${out}
+`);
+  }
+  process.stderr.write(`Error: ${error.message}
+`);
+  process.exit(1);
+}