webhelm 0.0.0-stage → 1.0.1

package/runtime/chrome.mjs

@@ -0,0 +1,125 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import net from 'node:net';
+import { spawn, execFileSync } from 'node:child_process';
+
+import { CONFIG_ROOT, PROFILE_DIR, requireMigratedConfig } from './config-paths.mjs';
+const ROOT = CONFIG_ROOT;
+const PROFILE = PROFILE_DIR;
+const STATE = path.join(ROOT, 'managed-chrome.json');
+const LOCK = path.join(ROOT, 'managed-chrome-node.lock');
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+async function endpointLive(port) {
+  try {
+    const url = `http://127.0.0.1:${port}/json/version`;
+    const response = await fetch(url, { signal: AbortSignal.timeout(650) });
+    if (!response.ok) return false;
+    return Boolean((await response.json()).webSocketDebuggerUrl);
+  } catch { return false; }
+}
+function alive(pid) {
+  try { if(!pid) return false;process.kill(Number(pid), 0);return true; }
+  catch {return false;}
+}
+async function fromState() {
+  let state;
+  try { state=JSON.parse(fs.readFileSync(STATE, 'utf8')); } catch { return null; }
+  if (state?.pid && Number.isInteger(state.port) && alive(state.pid) && await endpointLive(state.port)) return state;
+  return null;
+}
+async function discover() {
+  if (process.platform === 'win32') return null;
+  let output;
+  try { output=execFileSync('ps', ['-axo', 'pid=,command='], {encoding:'utf8'}); }
+  catch { return null; }
+  for(const line of output.split('\n')) {
+    if(!line.includes(`--user-data-dir=${PROFILE}`) || line.includes('--type=')) continue;
+    const match=line.match(/^\s*(\d+)\s+.*?--remote-debugging-port=(\d+)/);
+    if (!match) continue;
+    const [pid,port]=match.slice(1).map(Number);
+    if (!alive(pid) || !await endpointLive(port)) continue;
+    const state={pid,port,profile_dir:PROFILE,chrome_path:line.slice(line.search(/\S/)).replace(/^\d+\s*/, '').split(' --user-data-dir=')[0]};
+    fs.writeFileSync(STATE,JSON.stringify(state,null,2));
+    return state;
+  }
+  return null;
+}
+function browserExecutable(){
+  const override=process.env.WEBHELM_CHROME_PATH||process.env.BROWSER_WORKSPACE_CHROME_PATH;
+  if(override)return override;
+  const candidates=process.platform==='darwin' ? [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  ] : process.platform==='win32' ? [
+    path.join(process.env.LOCALAPPDATA||'', 'Google/Chrome/Application/chrome.exe'),
+    path.join(process.env.PROGRAMFILES||'', 'Google/Chrome/Application/chrome.exe'),
+  ] : ['/usr/bin/google-chrome-stable','/usr/bin/google-chrome','/usr/bin/chromium'];
+  const chosen=candidates.find(candidate=>fs.existsSync(candidate));
+  if(!chosen) throw Error('Chrome not found; set WEBHELM_CHROME_PATH');
+  return chosen;
+}
+function portFree(port) {
+  return new Promise(resolve=>{
+    const server=net.createServer();
+    server.once('error',()=>resolve(false));
+    server.listen(port,'127.0.0.1',()=>server.close(()=>resolve(true)));
+  });
+}
+async function choosePort() {
+  const initial=Number(process.env.BROWSER_WORKSPACE_CDP_PORT||9222);
+  for(let port=initial;port<initial+20;port++) if(await portFree(port))return port;
+  throw Error('No free managed Chrome CDP port');
+}
+async function lockOwnership(fn) {
+  fs.mkdirSync(ROOT,{recursive:true,mode:0o700});
+  let fd;
+  for(let attempt=0;attempt<30;attempt++){
+    try {fd=fs.openSync(LOCK,'wx',0o600);break;}
+    catch (error) {
+      if(error.code!=='EEXIST')throw error;
+      let pid=0;
+      try {pid=Number(fs.readFileSync(LOCK,'utf8'));}catch{}
+      if(pid>0&&!alive(pid)){try{fs.unlinkSync(LOCK);}catch{}}
+      await delay(150);
+    }
+  }
+  if(fd===undefined)throw Error('Managed Chrome lock timed out');
+  fs.writeSync(fd,String(process.pid));
+  try {return await fn();}
+  finally {fs.closeSync(fd);try {fs.unlinkSync(LOCK);}catch{}}
+}
+export async function ensureManagedChrome(){
+  // Explicit CDP endpoints also support hermetic mock-browser tests.
+  const specified=process.env.WEBHELM_CDP_URL;
+  if (specified) return {mode:'override',reused:true,endpoint:specified,profile_dir:PROFILE};
+  requireMigratedConfig();
+  return lockOwnership(async()=>{
+    const existing=await fromState()||await discover();
+    if(existing)return {...existing, mode:'managed',reused:true,endpoint:`http://127.0.0.1:${existing.port}`};
+    // An explicit endpoint takes precedence only when there is no managed instance.
+    const override=process.env.WEBHELM_CDP_URL||process.env.BU_CDP_URL;
+    if(override)return {mode:'override',reused:true,endpoint:override,profile_dir:PROFILE};
+    const port=await choosePort();
+    const chrome=browserExecutable();
+    const log=fs.openSync(path.join(ROOT,'managed-chrome.log'),'a');
+    fs.mkdirSync(PROFILE,{recursive:true});
+    const child=spawn(chrome,[`--user-data-dir=${PROFILE}`,`--remote-debugging-port=${port}`,
+      '--no-first-run','--no-default-browser-check','about:blank'],
+      {detached:true,stdio:['ignore',log,log]});
+    child.unref();
+    fs.closeSync(log);
+    for(let tries=0;tries<100;tries++){
+      if(await endpointLive(port)){
+        const state={chrome_path:chrome,pid:child.pid,port,profile_dir:PROFILE};
+        const temp=`${STATE}.${process.pid}.tmp`;
+        fs.writeFileSync(temp,JSON.stringify(state,null,2));fs.renameSync(temp,STATE);
+        return {...state,mode:'managed',endpoint:`http://127.0.0.1:${port}`,reused:false};
+      }
+      if(!alive(child.pid))throw Error('Managed Chrome exited during launch');
+      await delay(150);
+    }
+    throw Error(`Chrome did not expose CDP port ${port}`);
+  });
+}

package/runtime/cli.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { ensureDaemon, request, handle, SOCKET } from './node-daemon.mjs';
+import { PLATFORMS, listPlatforms, platformProfile, actionPath, validateConfig } from './platforms.mjs';
+import { ACTIONS_DIR, ensureActions, syncActions, publishActions } from './actions-repo.mjs';
+import { migrateConfig } from './migrate.mjs';
+
+const ROOT = path.dirname(fileURLToPath(import.meta.url));
+const emit = value => console.log(JSON.stringify(value));
+const arg = (items, name) => {
+  const i = items.indexOf(name);
+  return i === -1 ? undefined : items[i + 1];
+};
+const has = (items, name) => items.includes(name);
+
+function help() {
+  console.log(`webhelm — browser automation through one Node.js runtime
+
+Usage:
+  webhelm migrate  # after stopping Chrome and the old WebHelm daemon
+  webhelm setup
+  webhelm status
+  webhelm capacity [--workspace NAME]
+  webhelm session start [--url URL]
+  webhelm session list
+  webhelm session exec SESSION_ID [--code-file FILE]   # JavaScript
+  webhelm session stop SESSION_ID|--all
+  webhelm platform list
+  webhelm platform sync
+  webhelm platform publish --message "DESCRIPTION"
+  webhelm platform profile PLATFORM
+  webhelm platform source PLATFORM ACTION
+  webhelm platform run PLATFORM ACTION [--session-id ID | --auto-session] [--config FILE] [--mode async|sync]
+
+Agent workflows should keep their session_id across browser actions and always stop owned sessions.
+`);
+}
+
+function loadConfig(args) {
+  const file = arg(args, '--config');
+  if (!file) return {};
+  const cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) throw Error('platform config must be a JSON object');
+  return cfg;
+}
+
+function validateMode(platform, action, args, config) {
+  const isNewTurn = platform === 'chatgpt' && action === 'new-turn';
+  const override = arg(args, '--mode');
+  if (!isNewTurn && override !== undefined) throw Error('--mode is supported only for chatgpt/new-turn');
+  if (!isNewTurn) return null;
+  if ('sync' in config) throw Error('legacy sync is not supported; use mode: async or sync');
+  if (override !== undefined && 'mode' in config && override !== config.mode) throw Error('--mode conflicts with the new-turn config mode');
+  const mode = override ?? config.mode ?? 'async';
+  if (typeof mode !== 'string' || !['async', 'sync'].includes(mode)) throw Error('mode must be exactly async or sync');
+  if (mode === 'sync' && config.mergeable !== undefined && config.mergeable !== false) {
+    throw Error('mergeable is only supported in async mode');
+  }
+  return mode;
+}
+
+async function runPlatform(args) {
+  const platform = args[2], action = args[3]?.replaceAll('_', '-');
+  if (!platform || !action) throw Error('platform run requires PLATFORM ACTION');
+  await ensureActions();
+  actionPath(platform, action);
+  const config = loadConfig(args);
+  const mode = validateMode(platform, action, args, config);
+  const sid = arg(args, '--session-id');
+  const auto = has(args, '--auto-session');
+  validateConfig(platform, action, config);
+  if (sid && auto) throw Error('--session-id and --auto-session are mutually exclusive');
+  if (platform === 'chatgpt' && action === 'new-turn' && mode === 'async') {
+    if (sid || auto) throw Error('async new-turn cannot use browser session options');
+    if (!config.thread_id || !config.message) throw Error('thread_id and message required');
+    if (typeof config.mergeable !== 'undefined' && typeof config.mergeable !== 'boolean') throw Error('mergeable must be a boolean');
+    const receipt = await request({op:'chatgpt-new-turn-enqueue', config: {...config, idempotency_key: config.idempotency_key || randomUUID(), mode}});
+    if (!receipt.ok || !receipt.queue_id || receipt.thread_id !== String(config.thread_id)) throw Error('ChatGPT queue returned an invalid acceptance receipt');
+    const project = config.project_id || null;
+    const prefix = project ? `/g/${encodeURIComponent(project)}` : '';
+    return {
+      platform, action, session_mode: 'durable_queue', self_heal_capable: false,
+      result: {ok:true, status:'submitted', mode:'new-turn', project_id:project,
+        thread_id:String(config.thread_id), thread_url:`https://chatgpt.com${prefix}/c/${encodeURIComponent(config.thread_id)}`,
+        verified_by:'durable-queue', user_message_id:null, queue_id: receipt.queue_id, state:receipt.state},
+    };
+  }
+  if (mode === 'sync' && (!sid || auto)) throw Error('sync new-turn requires a caller-owned --session-id');
+  if (!sid && !auto) throw Error('platform run requires --session-id; use --auto-session only for one-shot actions');
+  return request({op:'platform-run', platform, action, config: {...config, ...(mode ? {mode} : {})},
+    session_id:sid, auto_session:auto, url:arg(args, '--url')});
+}
+
+async function main(args = process.argv.slice(2)) {
+  const [group, command] = args;
+  if (!group || ['--help', '-h', 'help'].includes(group) || has(args, '--help') || has(args, '-h')) return help();
+  if (group === 'migrate') return emit(await migrateConfig());
+  if (group === 'setup') {
+    const repo=await ensureActions();
+    const chrome=await ensureDaemon();
+    return emit({status:'ready',...repo,daemon_pid:chrome.pid,managed_chrome:chrome.managed_chrome});
+  }
+  if (group === 'status') {
+    const daemon = await ensureDaemon();
+    return emit({version:'1.0.1', platform_dir:PLATFORMS, root:ROOT,
+      cli:fileURLToPath(import.meta.url),
+      admin_helper:process.env.WEBHELM_ADMIN_HELPER || (fs.existsSync(path.join(os.homedir(),'.agents/skills/webhelm/scripts/admin.mjs')) ? path.join(os.homedir(),'.agents/skills/webhelm/scripts/admin.mjs') : path.join(ROOT,'admin.mjs')),
+      managed_chrome:daemon.managed_chrome,
+      daemon:{running:true, pid:daemon.pid, session_count:daemon.session_count, queue_paused:daemon.queue_paused, socket:SOCKET}});
+  }
+  if (group === 'capacity') {
+    const payload={op:'capacity',workspace:arg(args,'--workspace')};
+    try { return emit(await request(payload)); }
+    catch(error) {
+      // Rolling upgrade: query extension metadata directly until a busy old
+      // Node daemon can drain its Sessions and load the new capacity operation.
+      if (!String(error.message).includes('unknown op: capacity')) throw error;
+      emit(await handle(payload));
+      return process.exit(0); // close this CLI's one-off CDP websocket
+    }
+  }
+  if (group === 'session') {
+    if (command === 'start') return emit(await request({op:'start', workspace:arg(args,'--workspace'), url:arg(args,'--url')}));
+    if (command === 'list') return emit(await request({op:'list'}));
+    if (command === 'stop') return emit(await request(has(args,'--all') ? {op:'stop-all'} : {op:'stop',session_id:args[2]}));
+    if (command === 'exec') {
+      if (!args[2]) throw Error('session exec requires SESSION_ID');
+      const file = arg(args, '--code-file');
+      const code = file ? fs.readFileSync(file, 'utf8') : fs.readFileSync(0, 'utf8');
+      const result = await request({op:'exec', session_id:args[2], code});
+      emit(result);
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+  }
+  if (group === 'platform') {
+    if (command === 'sync') return emit(await syncActions());
+    if (command === 'publish') return emit(await publishActions(arg(args, '--message')));
+    await ensureActions();
+    if (command === 'list') return emit(listPlatforms());
+    if (command === 'profile') return emit(platformProfile(args[2]));
+    if (command === 'source') return console.log(fs.readFileSync(actionPath(args[2],args[3]), 'utf8'));
+    if (command === 'run') {
+      const result = await runPlatform(args);
+      // Preserve the legacy caller contract even when a rolling-upgrade daemon
+      // still emits only `result.value`. Do not alter already logged stdout.
+      if(result?.result?.ok===true && result.result.value!==undefined && !String(result.result.stdout||'').trim())
+        result.result.stdout=JSON.stringify(result.result.value);
+      emit(result);
+      if (result?.result?.ok === false) process.exitCode = 1;
+      return;
+    }
+  }
+  throw Error(`unknown command: ${args.join(' ')}`);
+}
+
+main().catch(error => { console.error(JSON.stringify({error:error.message})); process.exitCode=1; });

package/runtime/config-paths.mjs

@@ -0,0 +1,14 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+export const CONFIG_ROOT = path.join(os.homedir(), '.config', 'webhelm');
+export const LEGACY_ROOT = path.join(os.homedir(), '.config', 'browser-workspace');
+export const PROFILE_DIR = path.join(CONFIG_ROOT, 'chrome');
+export const RUNTIME_DIR = path.join(CONFIG_ROOT, 'runtime');
+
+// Avoid starting a second FIFO dispatcher or empty Chrome profile against legacy data.
+export function requireMigratedConfig() {
+  if (fs.existsSync(path.join(LEGACY_ROOT, 'chrome')) && !fs.existsSync(PROFILE_DIR))
+    throw Error(`Legacy Chrome profile exists at ${LEGACY_ROOT}. Stop old Chrome and WebHelm daemon, then run webhelm migrate.`);
+}

package/runtime/migrate.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import net from 'node:net';
+import { CONFIG_ROOT, LEGACY_ROOT } from './config-paths.mjs';
+
+function liveSocket(socketPath) {
+  return new Promise(resolve => {
+    const socket = net.createConnection(socketPath);
+    const finish = result => { socket.destroy(); resolve(result); };
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+    socket.setTimeout(1200, () => finish(true)); // Fail closed if probing hangs.
+  });
+}
+
+export async function migrateConfig({ legacyRoot = LEGACY_ROOT, configRoot = CONFIG_ROOT,
+  processList = () => execFileSync('ps', ['-axo', 'command='], { encoding: 'utf8' }),
+  socketCheck = liveSocket } = {}) {
+  const legacy = path.resolve(legacyRoot);
+  const target = path.resolve(configRoot);
+  if (legacy === target) throw Error('Legacy and new config paths are identical');
+  let oldStat;
+  try { oldStat = fs.lstatSync(legacy); }
+  catch (e) { if (e.code === 'ENOENT') return { status: 'not_needed', config_root: target }; throw e; }
+  if (oldStat.isSymbolicLink()) {
+    if (fs.existsSync(target) && fs.realpathSync(legacy) === fs.realpathSync(target))
+      return { status: 'already_migrated', config_root: target, compatibility_symlink: legacy };
+    throw Error(`Legacy path is a different symlink: ${legacy}`);
+  }
+  if (!oldStat.isDirectory()) throw Error(`Legacy path is not a directory: ${legacy}`);
+  if (fs.existsSync(target)) throw Error(`Target already exists; refusing to overwrite: ${target}`);
+  const running = processList().split('\n').filter(line =>
+    line.includes(`--user-data-dir=${path.join(legacy, 'chrome')}`) ||
+    (line.includes('node-daemon.mjs daemon') && !line.includes('migrate.mjs')));
+  if (running.length) throw Error('Chrome or WebHelm daemon is still running; stop Sessions, daemon and Chrome before migration');
+  const socket = path.join(legacy, 'runtime', 'session-node.sock');
+  if (fs.existsSync(socket) && await socketCheck(socket))
+    throw Error('Legacy daemon socket is active; refusing migration');
+  fs.renameSync(legacy, target); // Same-volume atomic directory move; preserve Chrome data and FIFO WAL.
+  try { fs.symlinkSync(target, legacy, 'dir'); }
+  catch (error) {
+    fs.renameSync(target, legacy);
+    throw error;
+  }
+  return { status: 'migrated', config_root: target, compatibility_symlink: legacy };
+}