@omega.js/desktop 0.1.0

package/dist/build.js

@@ -0,0 +1,249 @@
+// Libraries
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const fs = require('fs');
+const JSON5 = require('json5');
+const { force, execute } = require('node-powertools');
+
+// argv is parsed lazily — yargs is ESM-only and can't be `require()`'d in older Node runtimes.
+let _argv = null;
+function getArgv() {
+  if (_argv) return _argv;
+  _argv = require('yargs')(process.argv.slice(2)).parseSync();
+  return _argv;
+}
+
+// Class
+function Manager() {
+  const self = this;
+
+  // Properties
+  self._logger = null;
+
+  // Return
+  return self;
+}
+
+// Initialize (build-time hook)
+Manager.prototype.initialize = function () {
+  console.log('initialize:');
+};
+
+// Logger
+Manager.prototype.logger = function (name) {
+  // Static-style call
+  if (!(this instanceof Manager)) {
+    return new (require('./lib/logger'))(name);
+  }
+
+  // Cache one logger per Manager instance
+  if (!this._logger) {
+    this._logger = new (require('./lib/logger'))(name);
+  }
+
+  return this._logger;
+};
+
+// argv (yargs is loaded on first call so the runtime build.js doesn't pull in ESM-only deps)
+Manager.getArguments = function () {
+  const options = getArgv() || {};
+
+  options._ = options._ || [];
+  options.debug = force(options.debug === undefined ? false : options.debug, 'boolean');
+
+  return options;
+};
+Manager.prototype.getArguments = Manager.getArguments;
+
+// Report build errors with notification (parity with BXM)
+Manager.reportBuildError = function (error, callback) {
+  const logger = new (require('./lib/logger'))('build-error');
+  const errorMessage = error.message || error.toString() || 'Unknown error';
+  const errorPlugin = error.plugin || 'Build';
+
+  logger.error(`[${errorPlugin}] ${errorMessage}`);
+
+  if (callback) {
+    return callback(error);
+  }
+
+  return (cb) => cb ? cb(error) : error;
+};
+Manager.prototype.reportBuildError = Manager.reportBuildError;
+
+// Mode flags
+Manager.isBuildMode = function () {
+  return process.env.OMEGA_BUILD_MODE === 'true';
+};
+Manager.prototype.isBuildMode = Manager.isBuildMode;
+
+Manager.isPublishMode = function () {
+  return process.env.OMEGA_IS_PUBLISH === 'true';
+};
+Manager.prototype.isPublishMode = Manager.isPublishMode;
+
+Manager.isServerMode = function () {
+  return process.env.OMEGA_IS_SERVER === 'true';
+};
+Manager.prototype.isServerMode = Manager.isServerMode;
+
+Manager.actLikeProduction = function () {
+  return Boolean(Manager.isBuildMode() || process.env.OMEGA_AUDIT_FORCE === 'true');
+};
+Manager.prototype.actLikeProduction = Manager.actLikeProduction;
+
+// getEnvironment() is the SINGLE SOURCE OF TRUTH and lives in src/utils/mode-helpers.js
+// (alongside isDevelopment/isProduction/isTesting — the natural environment-helper family).
+// It's mixed into ALL FOUR @omega.js/desktop Manager entry points (main / renderer / preload / build) via
+// the mode-helpers attachTo() call at the bottom of each, so every context resolves the
+// environment identically. (@omega.js/desktop has four separate Manager constructors that share code only
+// through these mixins — unlike UJM/BXM, where one build.js Manager serves every context.)
+
+Manager.getMode = function () {
+  return {
+    build:   Manager.isBuildMode(),
+    publish: Manager.isPublishMode(),
+    server:  Manager.isServerMode(),
+    environment: Manager.getEnvironment(),
+  };
+};
+Manager.prototype.getMode = Manager.getMode;
+
+// Config — the consumer's config/omega.json5 resolved for the desktop target via
+// @omega.js/config: shared sections (brand, cloud, analytics, payment, monitoring,
+// theme) at the top level, targets.desktop overlaid onto them (so app/platforms/startup/
+// releases/... land at the top level here), and in a brand monorepo the brand root's
+// config merges underneath the target's. Then @omega.js/desktop's derived defaults:
+//   app.appId       ← reverse-domain of brand.url (`https://foo.example.com` →
+//                     `com.example.foo`), else `app.${brand.id}` — the BRAND
+//                     owns the identity, never a hardcoded company (friction #18)
+//   app.productName ← brand.name if not set
+// These keep the consumer's config minimal: setting `brand: { id: 'foo', name: 'Foo',
+// url: 'https://foo.com' }` is enough; appId/productName flow through automatically.
+Manager.getConfig = function () {
+  const { hasOmegaConfig, loadConfig } = require('./vendor/config/index.js');
+
+  // No config at all (fresh dir, non-consumer cwd) → seeded empty shape below; the
+  // schema validation in audit/boot reports what's actually missing.
+  const cwd = process.cwd();
+  const config = hasOmegaConfig(cwd) ? loadConfig(cwd, 'desktop').config : {};
+
+  // Apply derived defaults. Always seed `brand` + `app` so callers can deref
+  // `config.brand.X` / `config.app.X` without optional-chaining at every callsite.
+  config.brand = config.brand || {};
+  config.app   = config.app   || {};
+  if (!config.app.appId) {
+    const host = String(config.brand.url || '').replace(/^https?:\/\//, '').replace(/^www\./, '').split('/')[0];
+    if (host) {
+      config.app.appId = host.split('.').reverse().join('.');
+    } else if (config.brand.id) {
+      config.app.appId = `app.${config.brand.id}`;
+    }
+  }
+  if (!config.app.productName && config.brand.name) config.app.productName = config.brand.name;
+
+  return config;
+};
+Manager.prototype.getConfig = Manager.getConfig;
+
+// package.json
+Manager.getPackage = function (type) {
+  const basePath = type === 'project'
+    ? process.cwd()
+    : path.resolve(__dirname, '..');
+
+  const pkgPath = path.join(basePath, 'package.json');
+  const raw = jetpack.read(pkgPath);
+
+  if (!raw) {
+    return {};
+  }
+
+  return JSON5.parse(raw);
+};
+Manager.prototype.getPackage = Manager.getPackage;
+
+// Root path
+Manager.getRootPath = function (type) {
+  return type === 'project'
+    ? process.cwd()
+    : path.resolve(__dirname, '..');
+};
+Manager.prototype.getRootPath = Manager.getRootPath;
+
+// Live reload port
+Manager.getLiveReloadPort = function () {
+  process.env.OMEGA_LIVERELOAD_PORT = process.env.OMEGA_LIVERELOAD_PORT || 35729;
+  return parseInt(process.env.OMEGA_LIVERELOAD_PORT, 10);
+};
+Manager.prototype.getLiveReloadPort = Manager.getLiveReloadPort;
+
+// Windows signing strategy. Config-only — `platforms.win.signing.strategy`
+// (targets.desktop.platforms.win in the raw omega.json5). Default 'self-hosted'.
+Manager.getWindowsSignStrategy = function () {
+  const config = Manager.getConfig();
+  return config?.platforms?.win?.signing?.strategy || 'self-hosted';
+};
+Manager.prototype.getWindowsSignStrategy = Manager.getWindowsSignStrategy;
+
+// Touch files to trigger a rebuild watcher
+Manager.triggerRebuild = function (files, logger) {
+  logger = this?._logger || logger || console;
+
+  if (typeof files === 'string') {
+    files = [files];
+  } else if (Array.isArray(files)) {
+    // already an array
+  } else if (typeof files === 'object' && files !== null) {
+    files = Object.keys(files);
+  } else {
+    logger.error('Invalid files for triggerRebuild()');
+    return;
+  }
+
+  const now = new Date();
+
+  files.forEach((file) => {
+    try {
+      fs.utimesSync(file, now, now);
+      logger.log(`Triggered build: ${file}`);
+    } catch (e) {
+      logger.error(`Failed to trigger build ${file}`, e);
+    }
+  });
+};
+Manager.prototype.triggerRebuild = Manager.triggerRebuild;
+
+// Generic require passthrough (lets gulp tasks dynamically load lib modules).
+// Only ever called from gulp tasks (release / package / bundle), which run
+// un-bundled — so plain require is fine.
+Manager.require = function (p) {
+  return require(p);
+};
+Manager.prototype.require = Manager.require;
+
+// Memory usage
+Manager.getMemoryUsage = function () {
+  const used = process.memoryUsage();
+  return {
+    rss:       Math.round(used.rss / 1024 / 1024),
+    heapTotal: Math.round(used.heapTotal / 1024 / 1024),
+    heapUsed:  Math.round(used.heapUsed / 1024 / 1024),
+    external:  Math.round(used.external / 1024 / 1024),
+  };
+};
+Manager.prototype.getMemoryUsage = Manager.getMemoryUsage;
+
+Manager.logMemory = function (logger, label) {
+  const mem = Manager.getMemoryUsage();
+  logger.log(`[Memory ${label}] RSS: ${mem.rss}MB | Heap Used: ${mem.heapUsed}MB / ${mem.heapTotal}MB | External: ${mem.external}MB`);
+};
+Manager.prototype.logMemory = Manager.logMemory;
+
+// Mix in shared cross-context helpers — same code path used in main, renderer, preload.
+// All four contexts share the exact same implementation.
+require('./utils/mode-helpers.js').attachTo(Manager);
+require('./utils/url-helpers.js').attachTo(Manager);
+
+// Export
+module.exports = Manager;

package/dist/cli-run.js

@@ -0,0 +1,34 @@
+/**
+ * run() — the omega-desktop bin body, shared by bin/omega-desktop (via
+ * dist/omega-bin.js) and cross-framework dispatch ('@omega.js/desktop/cli').
+ */
+async function run() {
+  // Local-dist freshness guard: a stale locally-linked dist rebuilds and the
+  // invocation re-execs once, so no command ever runs stale framework code
+  require('./vendor/devkit/local.js').freshnessBoot({ packageName: '@omega.js/desktop' });
+
+  // Strip ELECTRON_RUN_AS_NODE — it leaks into our env from common parent processes
+  // (e.g. VS Code's Claude Code extension) and makes every Electron binary we shell
+  // to silently run as plain Node. Strip once at the CLI boundary.
+  delete process.env.ELECTRON_RUN_AS_NODE;
+
+  // Value-less flags must be declared boolean — otherwise yargs treats the next
+  // positional as the flag's VALUE. Mirrors the same fix in @omega.js/backend's CLI.
+  // yargs' built-in --version/--help are disabled so both route through the
+  // alias table / the router's built-in help (the built-ins printed an empty
+  // stub and version "0.0.0" — yargs can't resolve our package version here).
+  const argv = require('yargs')(process.argv.slice(2))
+    .boolean(['extended', 'local', 'quick', 'q'])
+    .version(false)
+    .help(false)
+    .parseSync();
+  const cli = new (require('./cli.js'))(argv);
+
+  try {
+    await cli.process(argv);
+  } catch (e) {
+    process.exit(1);
+  }
+}
+
+module.exports = { run };

package/dist/cli.js

@@ -0,0 +1,49 @@
+// Libraries
+const path = require('path');
+const { createCliRouter } = require('./vendor/devkit/cli-router.js');
+const { isBoxVerbArgv } = require('./vendor/devkit/omega-bin.js');
+
+// Resolve the .env cascade from the project root
+// (shell > local .env > brand .env > company .env). The target name delivers
+// the schema's `deliverAs` renames into process.env (#678) — the brand's
+// GOOGLE_ANALYTICS_SECRET_DESKTOP arrives as GOOGLE_ANALYTICS_SECRET.
+//
+// …for every verb but the signing box's. `runner` and `sign-windows` belong to
+// a MACHINE, not a project: they read the shell and `<runner home>\.env` and
+// nothing else, so a brand's GH_TOKEN can never register the box's runners or
+// hand its release token to a config walk ([#337](https://github.com/Omega-JS-Stack/omega/issues/337)).
+// Which invocations those are is the dispatcher's own answer, imported: one
+// reading of it, covering the bare verb and its `--` flag spelling alike.
+if (!isBoxVerbArgv(process.argv.slice(2))) {
+  require('./vendor/config/index.js').loadEnv(process.cwd(), { target: 'desktop' });
+}
+
+// Main class — dispatch (positional/flag alias resolution, command loading,
+// error surfacing) is the shared devkit router; this file owns only the alias
+// table and the commands directory. (ELECTRON_RUN_AS_NODE stripping stays in
+// the bin — it must happen before anything Electron-adjacent loads.)
+//
+// A bare `omega` prints help: setup is retired and every verb runs the local
+// scaffold itself ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+module.exports = createCliRouter({
+  commandsDir: path.join(__dirname, 'commands'),
+  defaultCommand: 'help',
+  aliases: {
+    clean:            ['-c', '--clean'],
+    install:          ['-i', 'i', '--install'],
+    version:          ['-v', '--version'],
+    build:            ['-b', '--build'],
+    deploy:           ['-d', '--deploy'],
+    publish:          ['-p', '--publish'],
+    release:          ['-r', '--release'],
+    test:             ['-t', '--test'],
+    update:           ['-u', '--update', 'outdated', 'out'],
+    logs:             ['--logs', 'log'],
+    'validate-certs': ['certs', '--validate-certs'],
+    'sign-windows':   ['--sign-windows'],
+    'push-secrets':   ['secrets', '--push-secrets'],
+    'finalize-release': ['finalize', '--finalize-release'],
+    runner:           ['--runner'],
+    launch:           ['open', '--launch'],
+  },
+});

package/dist/commands/build.js

@@ -0,0 +1,32 @@
+// Libraries
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('build');
+const { runPipeline } = require('../utils/build-pipeline.js');
+const { ensureTarget } = require('./lib/ensure-target.js');
+
+// The consumer's `build` script is `omega build` — this verb owns the
+// pipeline and the build-mode flag; it must never shell back to that script.
+// `certs` delivers the Apple artifacts first (#678).
+function plan() {
+  return {
+    env: { OMEGA_BUILD_MODE: 'true' },
+    steps: [
+      { type: 'clean' },
+      { type: 'certs' },
+      { type: 'gulp', task: 'build' },
+    ],
+  };
+}
+
+module.exports = async function (options) {
+  logger.log('Running production build...');
+
+  // The local scaffold BEFORE the pipeline (#675): the gulp `defaults` task
+  // ensures too, but gulp itself is one of the peer deps the ensure installs,
+  // so a fresh consumer outside any node_modules hoist never reaches it.
+  await ensureTarget({ log: (line) => logger.log(line), warn: (line) => logger.warn(line) });
+
+  await runPipeline(plan(options), options);
+};
+
+module.exports.plan = plan;

package/dist/commands/cdp/capture.js

@@ -0,0 +1,91 @@
+// `npx omega cdp capture <out.png>` — composited window capture: what the user
+// ACTUALLY sees (the BrowserWindow document + every WebContentsView stacked by
+// the window server), normalized to sRGB.
+//
+//   npx omega cdp capture <out.png> [--window-id <CGWindowID>]
+//   npx omega cdp capture --find-window-id
+//
+// Default path: raises the app (System Events), reads the window rect over
+// CDP, region-captures it. Anything overlapping that region after the raise
+// (e.g. an always-on-top window) would be captured too — for an
+// occlusion-proof capture pass `--window-id` (find it with --find-window-id;
+// it's stable for the window's lifetime, so cache it per app launch).
+//
+// WHY the sips step: macOS embeds the MONITOR's ICC profile in screenshot
+// PNGs; many viewers (including image previews in tooling) misrender it
+// dramatically (a dark panel can read near-white). Converting to sRGB makes
+// the file portable. Raw pixel VALUES in the PNG are correct either way.
+//
+// macOS only (screencapture / sips / osascript).
+
+const { execFileSync } = require('child_process');
+const client = require('./client');
+
+const Manager = new (require('../../build.js'))();
+
+const SRGB_PROFILE = '/System/Library/ColorSync/Profiles/sRGB Profile.icc';
+
+// Dev runs under the Electron binary's name; packaged builds under the
+// product name — try each until one raises.
+function raiseApp(names) {
+  let lastError = null;
+  for (const name of names) {
+    try {
+      execFileSync('osascript', ['-e', `tell application "System Events" to set frontmost of (first process whose name contains "${name}") to true`]);
+      return;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw new Error(`could not raise the app (tried: ${names.join(', ')}): ${lastError.message}`);
+}
+
+// CGWindowID lookup via a Swift snippet — slow (~2-4s compile) but dependable.
+// (JXA's CoreGraphics bridge segfaults on CGWindowListCopyWindowInfo.)
+function findWindowIds(names) {
+  const matchExpr = names.map((n) => `owner.contains("${n}") || name.contains("${n}")`).join(' || ');
+  const swift = `
+import CoreGraphics
+import Foundation
+let opts = CGWindowListOption([.optionOnScreenOnly, .excludeDesktopElements])
+guard let list = CGWindowListCopyWindowInfo(opts, kCGNullWindowID) as? [[String: Any]] else { exit(1) }
+for w in list {
+    let owner = w["kCGWindowOwnerName"] as? String ?? ""
+    let name = w["kCGWindowName"] as? String ?? ""
+    if ${matchExpr} {
+        print("\\(w["kCGWindowNumber"] ?? 0) | \\(owner) | \\(name)")
+    }
+}
+`;
+  return execFileSync('swift', ['-'], { input: swift, encoding: 'utf8' }).trim();
+}
+
+module.exports = async function (options) {
+  if (process.platform !== 'darwin') {
+    throw new Error('mgr cdp capture is macOS-only (screencapture/sips/osascript)');
+  }
+
+  const names = client.appNames(Manager.getConfig());
+
+  if (options['find-window-id'] || options.findWindowId) {
+    console.log(findWindowIds(names) || `no windows found (tried: ${names.join(', ')})`);
+    return;
+  }
+
+  const outPath = options._[2];
+  if (!outPath) {
+    throw new Error('Usage: npx omega cdp capture <out.png> [--window-id <id>] | --find-window-id');
+  }
+
+  const windowId = options['window-id'] || options.windowId;
+  if (windowId) {
+    execFileSync('screencapture', ['-x', '-o', '-l', String(windowId), outPath]);
+  } else {
+    raiseApp(names);
+    const rect = await client.evaluate(client.MAIN_VIEW, '({ x: window.screenX, y: window.screenY, w: window.outerWidth, h: window.outerHeight })');
+    execFileSync('screencapture', ['-x', `-R${rect.x},${rect.y},${rect.w},${rect.h}`, outPath]);
+  }
+
+  execFileSync('sips', ['-m', SRGB_PROFILE, outPath, '--out', outPath], { stdio: 'ignore' });
+  console.log(`captured ${outPath}`);
+};

package/dist/commands/cdp/client.js

@@ -0,0 +1,140 @@
+// Shared CDP plumbing for the `mgr cdp` toolkit — zero dependencies (Node 22+
+// global fetch + WebSocket). Talks to the RUNNING dev app's DevTools endpoint
+// (launch with `OMEGA_CDP_PORT=9222 npm start`, or `npx omega cdp relaunch`).
+//
+// @omega.js/desktop apps are MULTI-TARGET — one debuggable page per webContents (every
+// BrowserWindow and WebContentsView). Every helper takes a URL-substring
+// matcher instead of a "selected page"; the main window's document is always
+// at `dist/views/main/` (the MAIN_VIEW default matcher).
+//
+// See docs/cdp-debugging.md for the full toolkit reference.
+
+// The main window's view path — @omega.js/desktop's templating convention, so it holds for
+// every consumer. Subcommands that need "the app's main renderer" (status,
+// theme, capture geometry) default to this matcher.
+const MAIN_VIEW = '/views/main/';
+
+function port() {
+  return Number(process.env.OMEGA_CDP_PORT || 9222);
+}
+
+// List the app's debuggable pages (type === 'page' targets only).
+async function targets() {
+  const response = await fetch(`http://127.0.0.1:${port()}/json`).catch(() => null);
+  if (!response || !response.ok) {
+    throw new Error(`No CDP endpoint on port ${port()} — is the app running? (OMEGA_CDP_PORT=${port()} npm start, or npx omega cdp relaunch)`);
+  }
+  const list = await response.json();
+  return list.filter((t) => t.type === 'page');
+}
+
+// Pure matcher — pick the first page target whose URL contains `matcher`.
+// (Build-layer tested; keep it free of IO.)
+function pickTarget(pages, matcher) {
+  if (!matcher) {
+    return null;
+  }
+  return pages.find((t) => t.type === 'page' && (t.url || '').includes(matcher)) || null;
+}
+
+async function requireTarget(matcher) {
+  const pages = await targets();
+  const target = pickTarget(pages, matcher);
+  if (!target) {
+    throw new Error(`No target matching "${matcher}". Targets:\n${pages.map((t) => `  ${t.url}`).join('\n')}`);
+  }
+  return target;
+}
+
+// Open a CDP WebSocket to a target and return a send(method, params) function.
+async function connect(target) {
+  const ws = new WebSocket(target.webSocketDebuggerUrl);
+  await new Promise((resolve, reject) => {
+    ws.onopen = resolve;
+    ws.onerror = () => reject(new Error('WebSocket connection failed'));
+  });
+
+  let nextId = 1;
+  const pending = new Map();
+  ws.onmessage = (evt) => {
+    const msg = JSON.parse(evt.data);
+    if (pending.has(msg.id)) {
+      pending.get(msg.id)(msg);
+      pending.delete(msg.id);
+    }
+  };
+
+  const send = (method, params = {}) => new Promise((resolve, reject) => {
+    const id = nextId++;
+    pending.set(id, resolve);
+    ws.send(JSON.stringify({ id, method, params }));
+    setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`CDP timeout: ${method}`));
+    }, 15000);
+  });
+
+  return { send, close: () => ws.close() };
+}
+
+// Evaluate a JS expression in the matched target; returns the JSON value.
+// Throws (with the exception text) when the expression throws.
+async function evaluate(matcher, expression) {
+  const target = await requireTarget(matcher);
+  const { send, close } = await connect(target);
+  try {
+    const result = await send('Runtime.evaluate', {
+      expression,
+      returnByValue: true,
+      awaitPromise: true,
+      userGesture: true,
+    });
+    if (result.result?.exceptionDetails) {
+      throw new Error(`Expression threw in ${target.url}: ${JSON.stringify(result.result.exceptionDetails.exception?.description || result.result.exceptionDetails)}`);
+    }
+    return result.result?.result?.value;
+  } finally {
+    close();
+  }
+}
+
+// Per-renderer screenshot (that webContents' own pixels — NOT the composited
+// window; use `mgr cdp capture` for what the user actually sees).
+async function screenshot(matcher, outPath) {
+  const fs = require('fs');
+  const target = await requireTarget(matcher);
+  const { send, close } = await connect(target);
+  try {
+    await send('Page.enable');
+    const shot = await send('Page.captureScreenshot', { format: 'png', fromSurface: true });
+    if (!shot.result?.data) {
+      throw new Error(`captureScreenshot failed: ${JSON.stringify(shot.error || shot)}`);
+    }
+    fs.writeFileSync(outPath, Buffer.from(shot.result.data, 'base64'));
+    return outPath;
+  } finally {
+    close();
+  }
+}
+
+// ── Pure config resolvers (build-layer tested) ─────────────────────────────
+
+// Process names the app may run under: 'Electron' in dev (the node_modules
+// binary), the productName when packaged.
+function appNames(config) {
+  const names = ['Electron'];
+  if (config?.app?.productName) {
+    names.push(config.app.productName);
+  }
+  return names;
+}
+
+// The boot-complete signal for `mgr cdp relaunch` — a URL substring that must
+// match a CDP page target. Default: the main window's document. Consumers
+// whose boot finishes later than first paint override via config
+// `cdp.readySignal` (e.g. an overlay view created last in the boot sequence).
+function readyMatcher(config) {
+  return config?.cdp?.readySignal || MAIN_VIEW;
+}
+
+module.exports = { MAIN_VIEW, port, targets, pickTarget, requireTarget, connect, evaluate, screenshot, appNames, readyMatcher };

package/dist/commands/cdp/eval.js

@@ -0,0 +1,20 @@
+// `npx omega cdp eval <target-match> '<expression>'` — evaluate JS inside any
+// of the app's webContents:
+//
+//   npx omega cdp eval "/views/main/" 'document.title'                 # the main window
+//   npx omega cdp eval "example.com" 'getComputedStyle(document.body).background'
+//
+// Promises are awaited; the result prints as JSON. The expression runs with
+// a user gesture, so focus()/clipboard-ish APIs behave like real input.
+
+const client = require('./client');
+
+module.exports = async function (options) {
+  const [, , matcher, expression] = options._;
+  if (!matcher || !expression) {
+    throw new Error("Usage: npx omega cdp eval <target-match> '<expression>'");
+  }
+
+  const value = await client.evaluate(String(matcher), String(expression));
+  console.log(JSON.stringify(value, null, 2));
+};