@monoes/monobrowse 1.0.0 → 1.0.1

package/src/cli.ts

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * monobrowse — standalone CLI entry point
+ * Dispatches to the same command tree used by `monomind browse`
+ */
+
+import { createRequire } from 'module';
+import browseCommand from './cli/commands.js';
+import { output } from './cli/output.js';
+import type { Command, CommandContext, CommandOption, ParsedFlags } from './cli/types.js';
+
+const _require = createRequire(import.meta.url);
+
+// ---------------------------------------------------------------------------
+// Subcommand lookup (supports aliases)
+// ---------------------------------------------------------------------------
+
+function findSub(name: string, subs: Command[]): Command | undefined {
+  return subs.find(s => s.name === name || s.aliases?.includes(name));
+}
+
+// ---------------------------------------------------------------------------
+// Minimal argv parser — resolves short flags from the target subcommand's opts
+// ---------------------------------------------------------------------------
+
+function buildShortMap(cmd: Command | undefined): Record<string, string> {
+  const m: Record<string, string> = {};
+  if (!cmd?.options) return m;
+  for (const opt of cmd.options) {
+    if (opt.short) m[opt.short] = opt.name;
+  }
+  return m;
+}
+
+function isBooleanOpt(name: string, cmd: Command | undefined): boolean {
+  const opt = cmd?.options?.find(o => o.name === name);
+  return opt?.type === 'boolean';
+}
+
+function parseArgv(argv: string[], sub: Command | undefined): { args: string[]; flags: ParsedFlags } {
+  const shortMap = buildShortMap(sub);
+  const flags: ParsedFlags = { _: [] };
+  const positional: string[] = [];
+  let i = 0;
+
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (arg === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+
+    if (arg.startsWith('--')) {
+      const raw = arg.slice(2);
+      if (raw.startsWith('no-')) {
+        flags[raw.slice(3)] = false;
+      } else if (raw.includes('=')) {
+        const eq = raw.indexOf('=');
+        flags[raw.slice(0, eq)] = raw.slice(eq + 1);
+      } else if (isBooleanOpt(raw, sub) || i + 1 >= argv.length || argv[i + 1].startsWith('-')) {
+        flags[raw] = true;
+      } else {
+        flags[raw] = argv[++i];
+      }
+    } else if (arg.startsWith('-') && arg.length >= 2) {
+      const short = arg[1];
+      const long = shortMap[short] ?? short;
+      if (arg.length > 2) {
+        flags[long] = arg.slice(2);
+      } else if (isBooleanOpt(long, sub) || i + 1 >= argv.length || argv[i + 1].startsWith('-')) {
+        flags[long] = true;
+      } else {
+        flags[long] = argv[++i];
+      }
+    } else {
+      positional.push(arg);
+    }
+
+    i++;
+  }
+
+  // Coerce number options
+  for (const opt of (sub?.options ?? [])) {
+    if (opt.type === 'number' && typeof flags[opt.name] === 'string') {
+      flags[opt.name] = Number(flags[opt.name]);
+    }
+  }
+
+  return { args: positional, flags };
+}
+
+// ---------------------------------------------------------------------------
+// Help printer
+// ---------------------------------------------------------------------------
+
+function printHelp(cmd: Command, prefix = 'monobrowse'): void {
+  const usage = cmd.name === 'browse'
+    ? `${prefix} <subcommand> [options]`
+    : `${prefix} ${cmd.name} [subcommand] [options]`;
+  console.log(`\nUsage: ${usage}\n`);
+  console.log(cmd.description + '\n');
+
+  if (cmd.subcommands?.length) {
+    console.log('Subcommands:');
+    for (const s of cmd.subcommands) {
+      if (!s.hidden) console.log(`  ${s.name.padEnd(20)} ${s.description}`);
+    }
+    console.log('');
+  }
+
+  if (cmd.options?.length) {
+    console.log('Options:');
+    for (const o of cmd.options) {
+      const shortPart = o.short ? `-${o.short}, ` : '    ';
+      const defaultPart = o.default !== undefined ? ` (default: ${o.default})` : '';
+      console.log(`  ${shortPart}--${o.name.padEnd(18)} ${o.description}${defaultPart}`);
+    }
+    console.log('');
+  }
+
+  if (cmd.examples?.length) {
+    console.log('Examples:');
+    for (const ex of cmd.examples) {
+      const adjusted = ex.command.replace(/^monomind browse/, prefix);
+      console.log(`  ${adjusted}    ${ex.description}`);
+    }
+    console.log('');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch: find action and build context
+// ---------------------------------------------------------------------------
+
+async function dispatch(cmd: Command, argv: string[]): Promise<void> {
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    printHelp(cmd);
+    return;
+  }
+
+  const subName = argv[0];
+  const rest = argv.slice(1);
+
+  const sub = findSub(subName, cmd.subcommands ?? []);
+  if (!sub) {
+    output.printError(`Unknown subcommand: ${subName}`);
+    output.printInfo('Run `monobrowse --help` to see available subcommands.');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (rest[0] === '--help' || rest[0] === '-h') {
+    printHelp(sub, 'monobrowse');
+    return;
+  }
+
+  // Check if first remaining arg matches a nested subcommand
+  if (sub.subcommands?.length && rest.length > 0 && !rest[0].startsWith('-')) {
+    const nested = findSub(rest[0], sub.subcommands);
+    if (nested?.action) {
+      const { args, flags } = parseArgv(rest.slice(1), nested);
+      const ctx: CommandContext = { args, flags, cwd: process.cwd(), interactive: !!process.stdout.isTTY };
+      const result = await nested.action(ctx);
+      if (result && !result.success) process.exitCode = result.exitCode ?? 1;
+      return;
+    }
+  }
+
+  // No nested match — invoke the subcommand's own action
+  if (!sub.action) {
+    output.printInfo(`Run \`monobrowse ${subName} --help\` for usage.`);
+    return;
+  }
+
+  const { args, flags } = parseArgv(rest, sub);
+  const ctx: CommandContext = { args, flags, cwd: process.cwd(), interactive: !!process.stdout.isTTY };
+  const result = await sub.action(ctx);
+  if (result && !result.success) process.exitCode = result.exitCode ?? 1;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const userArgs = process.argv.slice(2);
+
+  if (userArgs.length === 0 || userArgs[0] === '--help' || userArgs[0] === '-h') {
+    printHelp(browseCommand);
+    return;
+  }
+
+  if (userArgs[0] === '--version' || userArgs[0] === '-V') {
+    const pkg = _require('../package.json') as { version: string };
+    console.log(pkg.version);
+    return;
+  }
+
+  await dispatch(browseCommand, userArgs);
+}
+
+main().then(() => {
+  process.exit(process.exitCode ?? 0);
+}).catch(err => {
+  output.printError(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/index.ts

@@ -1,6 +1,25 @@
+// Re-export the full monoplaybook engine so consumers only need @monoes/monobrowse
+export * from '@monoes/monoplaybook';
+
 export * from './browser/index.js';
-export * from './browser/workflow/index.js';
 export * from './browser/action-builder/analyzer.js';
 export * from './browser/action-builder/types.js';
 export * from './browser/adapters/index.js';
 export { startDashboard, getDashboard } from './browser/dashboard/server.js';
+export { createBuiltinHandlers, createBrowserHandlers } from './browser/playbook/index.js';
+export { readAction } from './browser/playbook/store.js';
+
+// Batteries-included handler factory: service nodes + browser automation + builtins.
+// This is the recommended entry point when using monobrowse as the default executor.
+import { createNodeHandlers } from '@monoes/monoplaybook';
+import { createBrowserHandlers } from './browser/playbook/browser-handlers.js';
+import { createBuiltinHandlers } from './browser/playbook/builtin-handlers.js';
+import type { NodeHandler } from '@monoes/monoplaybook';
+
+export function createDefaultHandlers(): Map<string, NodeHandler> {
+  return new Map<string, NodeHandler>([
+    ...createNodeHandlers(),
+    ...createBrowserHandlers(),
+    ...createBuiltinHandlers(),
+  ]);
+}

package/src/browser/workflow/engine.ts

@@ -1,202 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { resolveExpression, resolveConfig } from './expression.js';
-import { getDashboard } from '../dashboard/server.js';
-import type { WorkflowDef, NodeDef, Item, RunRecord, StepEvent, RunStatus } from './types.js';
-
-export type NodeHandler = (items: Item[], config: Record<string, unknown>) => Promise<Item[]>;
-
-export interface EngineOptions {
-  handlers?: Map<string, NodeHandler>;
-  onEvent?: (event: StepEvent) => void;
-  signal?: AbortSignal;
-  params?: Record<string, string>;
-}
-
-export async function runWorkflow(
-  def: WorkflowDef,
-  options: EngineOptions = {},
-): Promise<RunRecord> {
-  const { handlers = new Map(), onEvent = () => {}, signal, params = {} } = options;
-  const runId = randomUUID();
-  const startedAt = Date.now();
-
-  // Build a unified abort controller that merges the caller's signal with dashboard stop-requests.
-  const controller = new AbortController();
-  if (signal) {
-    if (signal.aborted) {
-      controller.abort();
-    } else {
-      signal.addEventListener('abort', () => controller.abort(), { once: true });
-    }
-  }
-  const dashboard = getDashboard();
-  let stopPollTimer: ReturnType<typeof setInterval> | undefined;
-  if (dashboard) {
-    stopPollTimer = setInterval(() => {
-      if (dashboard.isStopRequested(runId)) controller.abort();
-    }, 500);
-    // Avoid keeping Node.js event loop alive if nothing else is running
-    stopPollTimer.unref?.();
-  }
-
-  const emit = (partial: Omit<StepEvent, 'runId' | 'workflowId' | 'workflowName' | 'timestamp'>) =>
-    onEvent({ runId, workflowId: def.id, workflowName: def.name, timestamp: Date.now(), ...partial });
-
-  emit({ nodeId: '', nodeName: '', eventType: 'run_started' });
-
-  // Build adjacency structures
-  const nodeMap = new Map(def.nodes.map(n => [n.id, n]));
-  const inDegree = new Map<string, number>(def.nodes.map(n => [n.id, 0]));
-  const outEdges = new Map<string, { to: string; handle?: string }[]>();
-  const toEdges = new Map<string, { from: string; handle?: string }[]>();
-
-  for (const conn of def.connections) {
-    inDegree.set(conn.to, (inDegree.get(conn.to) ?? 0) + 1);
-    const edges = outEdges.get(conn.from) ?? [];
-    edges.push({ to: conn.to, handle: conn.handle });
-    outEdges.set(conn.from, edges);
-    const toList = toEdges.get(conn.to) ?? [];
-    toList.push({ from: conn.from, handle: conn.handle });
-    toEdges.set(conn.to, toList);
-  }
-
-  // Kahn's topological sort
-  const queue: string[] = [];
-  const sorted: string[] = [];
-  for (const [id, deg] of inDegree) {
-    if (deg === 0) queue.push(id);
-  }
-  while (queue.length > 0) {
-    const id = queue.shift()!;
-    sorted.push(id);
-    for (const edge of outEdges.get(id) ?? []) {
-      const newDeg = (inDegree.get(edge.to) ?? 0) - 1;
-      inDegree.set(edge.to, newDeg);
-      if (newDeg === 0) queue.push(edge.to);
-    }
-  }
-  if (sorted.length !== def.nodes.length) {
-    throw new Error('Workflow contains a cycle');
-  }
-
-  // Node output accumulator
-  const nodeOutputs = new Map<string, Item[]>();
-  let itemsProcessed = 0;
-  let runStatus: RunStatus = 'completed';
-  let runError: string | undefined;
-
-  try {
-    for (const nodeId of sorted) {
-      if (controller.signal.aborted) {
-        runStatus = 'stopped';
-        emit({ nodeId, nodeName: nodeId, eventType: 'run_stopped' });
-        break;
-      }
-
-      const node = nodeMap.get(nodeId)!;
-      const nodeName = node.name ?? node.id;
-      const t0 = Date.now();
-
-      // Collect inputs from predecessor outputs
-      const inputItems = collectInputs(nodeId, nodeOutputs, toEdges);
-
-      emit({ nodeId, nodeName, eventType: 'step_started', itemTotal: inputItems.length });
-
-      try {
-        const outputs = await executeNode(node, inputItems, handlers, nodeOutputs, params, def.allowEnvAccess);
-        nodeOutputs.set(nodeId, outputs);
-        itemsProcessed += outputs.length;
-        emit({ nodeId, nodeName, eventType: 'step_completed', durationMs: Date.now() - t0, itemTotal: outputs.length });
-      } catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
-        emit({ nodeId, nodeName, eventType: 'step_failed', error, durationMs: Date.now() - t0 });
-        if (node.onError === 'skip') {
-          nodeOutputs.set(nodeId, []);
-        } else {
-          runStatus = 'failed';
-          runError = error;
-          break;
-        }
-      }
-    }
-  } finally {
-    if (stopPollTimer !== undefined) clearInterval(stopPollTimer);
-  }
-
-  const completedAt = Date.now();
-  const record: RunRecord = {
-    id: runId,
-    workflowId: def.id,
-    workflowName: def.name,
-    status: runStatus,
-    startedAt,
-    completedAt,
-    itemsProcessed,
-    itemsTotal: itemsProcessed,
-    error: runError,
-  };
-
-  emit({ nodeId: '', nodeName: '', eventType: runStatus === 'completed' ? 'run_completed' : 'run_stopped', error: runError });
-  return record;
-}
-
-function collectInputs(nodeId: string, nodeOutputs: Map<string, Item[]>, toEdges: Map<string, { from: string; handle?: string }[]>): Item[] {
-  const predecessors = toEdges.get(nodeId) ?? [];
-  if (predecessors.length === 0) return [{ data: {} }];
-  return predecessors.flatMap(({ from, handle }) => {
-    const items = nodeOutputs.get(from) ?? [];
-    if (handle === 'true') return items.filter(item => item.data['__ifResult'] === true);
-    if (handle === 'false') return items.filter(item => item.data['__ifResult'] === false);
-    return items;
-  });
-}
-
-async function executeNode(
-  node: NodeDef,
-  inputs: Item[],
-  handlers: Map<string, NodeHandler>,
-  nodeOutputs: Map<string, Item[]>,
-  params: Record<string, string>,
-  allowEnvAccess?: boolean,
-): Promise<Item[]> {
-  const allOutputs: Record<string, Item[]> = Object.fromEntries(nodeOutputs);
-  const { type, config } = node;
-
-  if (type === 'trigger.manual') {
-    const items = config['items'];
-    if (Array.isArray(items)) return items as Item[];
-    return inputs;
-  }
-
-  if (type === 'core.set') {
-    return inputs.map(item => {
-      const resolved = resolveConfig(config, item, allOutputs, params, allowEnvAccess);
-      return { ...item, data: { ...item.data, ...resolved } };
-    });
-  }
-
-  if (type === 'core.filter') {
-    const predicate = config['expression'] as string;
-    return inputs.filter(item => {
-      try {
-        return Boolean(resolveExpression(predicate, item, allOutputs, params, allowEnvAccess));
-      } catch {
-        return false;
-      }
-    });
-  }
-
-  if (type === 'core.if') {
-    const predicate = config['expression'] as string;
-    return inputs.map(item => {
-      const result = Boolean(resolveExpression(predicate, item, allOutputs, params, allowEnvAccess));
-      return { ...item, data: { ...item.data, __ifResult: result } };
-    });
-  }
-
-  // action.* — delegate to registered handler
-  const handler = handlers.get(type);
-  if (!handler) throw new Error(`No handler registered for node type: ${type}`);
-  const resolvedConfig = resolveConfig(config, inputs[0] ?? { data: {} }, allOutputs, params, allowEnvAccess);
-  return handler(inputs, resolvedConfig);
-}

package/src/browser/workflow/expression.ts

@@ -1,107 +0,0 @@
-import type { Item } from './types.js';
-
-const TEMPLATE_PATTERN = '\\{\\{([^}]+)\\}\\}';
-
-/** Env var names matching this pattern are blocked from $env expressions to prevent secret exfiltration. */
-const ENV_DENYLIST = /(_KEY|_TOKEN|_SECRET|_PASSWORD|_JWT|_API_KEY|_PRIVATE_KEY|_PASS|_PWD|_CERT|_PEM|_CREDENTIAL|_CREDENTIALS|_AUTH)$/i;
-type ParsedTemplate = RegExpMatchArray[];
-const cache = new Map<string, ParsedTemplate>();
-
-function extractTemplates(template: string): ParsedTemplate {
-  if (cache.has(template)) return cache.get(template)!;
-  // LRU eviction: drop the oldest entry rather than clearing all at once (thundering-herd).
-  if (cache.size >= 500) {
-    const oldest = cache.keys().next().value;
-    if (oldest !== undefined) cache.delete(oldest);
-  }
-  const matches = [...template.matchAll(new RegExp(TEMPLATE_PATTERN, 'g'))];
-  cache.set(template, matches);
-  return matches;
-}
-
-export function resolveExpression(
-  template: string,
-  item: Item,
-  nodeOutputs: Record<string, Item[]>,
-  params: Record<string, string>,
-  allowEnvAccess?: boolean,
-): string {
-  const matches = extractTemplates(template);
-  if (matches.length === 0) return template;
-
-  let result = template;
-  for (const match of matches) {
-    const expr = match[1].trim();
-    const value = resolveToken(expr, item, nodeOutputs, params, allowEnvAccess);
-    result = result.split(match[0]).join(String(value));
-  }
-  return result;
-}
-
-function resolveToken(
-  expr: string,
-  item: Item,
-  nodeOutputs: Record<string, Item[]>,
-  params: Record<string, string>,
-  allowEnvAccess?: boolean,
-): unknown {
-  if (expr.startsWith('$json.')) {
-    const key = expr.slice(6);
-    if (!(key in item.data)) throw new Error(`Unresolved: $json.${key} not found in item data`);
-    return item.data[key];
-  }
-  if (expr.startsWith('$env.')) {
-    const key = expr.slice(5);
-    if (!allowEnvAccess && ENV_DENYLIST.test(key)) {
-      throw new Error(
-        `Blocked: env var "${key}" matches secret pattern. Set allowEnvAccess: true in workflow config to override.`,
-      );
-    }
-    const val = process.env[key];
-    if (val === undefined) throw new Error(`Unresolved: $env.${key} not set`);
-    return val;
-  }
-  if (expr.startsWith('params.')) {
-    const key = expr.slice(7);
-    if (!(key in params)) throw new Error(`Unresolved: params.${key} not provided`);
-    return params[key];
-  }
-  if (expr.startsWith('$node.') || expr.startsWith('$node["')) {
-    let nodeId: string;
-    let field: string;
-    if (expr.startsWith('$node["')) {
-      // $node["NodeId"].field
-      const bracketEnd = expr.indexOf('"].');
-      if (bracketEnd === -1) throw new Error(`Unresolved: malformed $node bracket expression: ${expr}`);
-      nodeId = expr.slice(7, bracketEnd);       // slice off '$node["'
-      field = expr.slice(bracketEnd + 3);       // slice off '"].'
-    } else {
-      // $node.NodeId.field
-      const parts = expr.slice(6).split('.');
-      nodeId = parts[0];
-      field = parts.slice(1).join('.');
-    }
-    const items = nodeOutputs[nodeId];
-    if (!items || items.length === 0) throw new Error(`Unresolved: $node.${nodeId} has no output`);
-    const val = items[0].data[field];
-    if (val === undefined) throw new Error(`Unresolved: $node.${nodeId}.${field} not found`);
-    return val;
-  }
-  // Named ref (e.g. {{box}} from a find step) — action executor resolves these using its element handle map
-  return `{{${expr}}}`;
-}
-
-// Note: only resolves top-level string values. Nested objects/arrays are passed through unchanged.
-export function resolveConfig(
-  config: Record<string, unknown>,
-  item: Item,
-  nodeOutputs: Record<string, Item[]>,
-  params: Record<string, string>,
-  allowEnvAccess?: boolean,
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(config)) {
-    result[k] = typeof v === 'string' ? resolveExpression(v, item, nodeOutputs, params, allowEnvAccess) : v;
-  }
-  return result;
-}

package/src/browser/workflow/index.ts

@@ -1,5 +0,0 @@
-export * from './types.js';
-export * from './store.js';
-export * from './engine.js';
-export * from './expression.js';
-export * from './builtin-handlers.js';

package/src/browser/workflow/types.ts

@@ -1,62 +0,0 @@
-export interface WorkflowDef {
-  id: string;
-  name: string;
-  description?: string;
-  params?: Record<string, { type?: string; required?: boolean; default?: unknown; description?: string }>;
-  nodes: NodeDef[];
-  connections: ConnectionDef[];
-  /** Allow $env.* expressions to access env vars that match the secret denylist. Use with caution. */
-  allowEnvAccess?: boolean;
-}
-
-export interface NodeDef {
-  id: string;
-  type: string;
-  name?: string;
-  config: Record<string, unknown>;
-  onError?: 'skip' | 'stop';
-  timeoutMs?: number;
-}
-
-export interface ConnectionDef {
-  from: string;
-  to: string;
-  handle?: string; // port identifier for multi-output nodes (e.g. 'true'/'false' for core.if)
-}
-
-export interface Item {
-  data: Record<string, unknown>;
-  binaryBase64?: string; // base64-encoded binary payload
-}
-
-export type RunStatus = 'running' | 'completed' | 'failed' | 'stopped';
-
-export interface RunRecord {
-  id: string;
-  workflowId: string;
-  workflowName: string;
-  status: RunStatus;
-  startedAt: number;
-  completedAt?: number;
-  itemsProcessed: number;
-  itemsTotal: number;
-  error?: string;
-}
-
-export interface StepEvent {
-  runId: string;
-  workflowId: string;
-  workflowName: string;
-  nodeId: string;
-  nodeName: string;
-  eventType: 'run_started' | 'step_started' | 'step_completed' | 'step_failed' | 'run_completed' | 'run_stopped';
-  itemIndex?: number;
-  itemTotal?: number;
-  durationMs?: number;
-  error?: string;
-  timestamp: number;
-  /** Absolute path of the project directory that emitted this event.
-   *  Clients may subscribe to a specific project by passing `?dir=<path>`.
-   *  Events without a projectDir are delivered to all clients (backward-compatible). */
-  projectDir?: string;
-}